Referencia de la API Graph

Información general

La API Graph para Workplace es una forma de introducir y extraer datos en Workplace mediante programación. Se trata de una API basada en HTTP de bajo nivel que puedes utilizar para consultar datos sobre objetos en un gráfico de Workplace.

La API Graph recibe el nombre de la idea de un modelo de datos gráfico, donde los objetos se representan mediante nodos y se unen en los perímetros. En un nivel de API, las aplicaciones acceden así a la información de Workplace. La API Graph para Workplace permite un subconjunto de funcionalidades de la API Graph. Estas funcionalidades se limitan a interacciones con una comunidad de Workplace y pueden presentar diferencias en algunos casos para obtener mejor rendimiento o facilidad de uso.

A continuación, puedes encontrar más información sobre cómo usar la API Graph para Workplace:

Crear aplicaciones Crear bots Permisos Ejemplos

Objetos de la API Graph para Workplace

Es posible acceder a los siguientes nodos mediante la API Graph para Workplace. Se debe utilizar un identificador de acceso de integración personalizado para acceder a todos los nodos.

Comunidad

Una comunidad de Workplace. El grupo raíz de las llamadas a la API Graph para Workplace.

Grupos

Un grupo de Workplace.

Publicaciones

Una publicación realizada en un grupo o en el perfil de un miembro.

Miembros

Una cuenta de un usuario específico de Workplace.

Para ver ejemplos de la combinación de llamadas a la API Graph a fin de resolver problemas específicos, puedes consultar la lista de aplicaciones de muestra.

Uso de la API Graph

Objetos de la API Graph

La API Graph es una representación de la información de Workplace y se compone de los siguientes elementos:

Nodos: objetos, como un usuario, una foto, una publicación o un comentario.
Perímetros: las conexiones entre esos "objetos", como el archivo de una publicación o los comentarios de una foto.
Campos: metadatos sobre los objetos, como el nombre de una persona o la privacidad de un grupo.

Cada elemento del gráfico de Workplace se representa mediante un identificador único. Los grupos, los miembros, las publicaciones e incluso los comentarios tienen sus propios identificadores, que se pueden usar para recuperar información sobre ellos desde la API Graph.

Administración de la comunidad

Cada comunidad de Workplace se mantiene separada de las demás, de modo que solo puedes usar la API Graph para acceder al contenido de tu propia comunidad y de grupos entre empresas a los que se hayan añadido miembros de tu comunidad.

En lo que respecta al acceso a la API Graph, tu comunidad se trata como un grupo. Puedes pensar en la comunidad como un grupo raíz al que se añaden todos los grupos como elementos secundarios. Para recuperar información sobre tu comunidad en la API Graph, necesitarás el identificador de comunidad, que se recupera mediante programación desde la API Graph mediante una solicitud HTTP GET a graph.facebook.com/community con un identificador de acceso a la aplicación válido.

Control de versiones de la API Graph

La API Graph para Workplace se basa en la API Graph. De esta forma, hereda el mismo comportamiento de control de versiones de la API.

Las versiones de la API Graph se lanzan aproximadamente cada tres meses y los cambios en todas las API Graph y de Workplace se publican en el Registro de cambios de la API Graph.

Al realizar una llamada a la API Graph, puedes especificar una versión en la ruta de la API, como se muestra a continuación:

      https://graph.facebook.com/v2.11/community/groups

No obstante, hay algunas restricciones en las versiones disponibles:

Cuando se lanza una nueva versión, se convierte en la versión actual de la API, cuyo funcionamiento se garantiza durante dos años tras su lanzamiento.
Cuando se crea una aplicación, se establece de forma predeterminada en la versión actual de la API en el momento de la creación y esta se convierte en la versión mínima de la API disponible para dicha aplicación.
Las aplicaciones pueden especificar cualquier versión de la API al realizar las llamadas, pero no podrán realizar llamadas a versiones obsoletas o inferiores a la versión mínima de la API para la aplicación.
Las llamadas a la API sin versión se establecerán de forma predeterminada en la versión mínima de la API para dicha aplicación.

Al crear una nueva integración personalizada, la versión mínima disponible de la API será la versión actual de la API en el momento de la creación. La versión mínima afecta a las llamadas a la API Graph y a las suscripciones a Webhooks.

Control de versiones de la plataforma Registro de cambios de la API Graph

Comprobación de la versión de la API Graph

Si no tienes claro qué versión usas, puedes consultarla de varias formas. Para comprobar qué versión de la API Graph se puede usar con tu aplicación, puedes añadir el parámetro debug a la llamada a la API.

      https://graph.facebook.com/community?debug=all

De esta forma, se devolverá información de depuración adicional que confirmará la versión que se está usando.

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

Si intentas usar una versión inferior a la versión mínima de la API para tu aplicación, te lo indicará el mensaje debug.

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

Comprobación de las versiones del webhook

Las suscripciones a webhooks usan la versión mínima de la API si la suscripción se realizó mediante el cuadro de diálogo emergente de integraciones personalizadas. En cambio, si la suscripción se realizó mediante el extremo de suscripciones de la API Graph /app/subscriptions, usan la versión especificada de la API.

Puedes usar el extremo de suscripciones para confirmar la versión del webhook aplicada en cada tema y campo del webhook. Este extremo requiere un identificador de acceso a la aplicación.

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...

En función de cómo se active la suscripción al webhook, es posible que los diferentes campos de un objeto de webhook único devuelvan cargas útiles con números de versión distintos.

Si la carga útil no está en el formato previsto, comprueba el número de versión y vuelve a realizar la suscripción con una versión más reciente si es necesario.

Uso de identificadores de acceso

Obtener un identificador de acceso a la aplicación

A fin de realizar llamadas a la API Graph para tu comunidad, deberás crear una aplicación y recuperar un identificador de acceso. Esto implica crear una nueva aplicación y, a continuación, otorgarle los permisos necesarios para la funcionalidad que quieras compilar.

Para obtener más información sobre la creación de aplicaciones y el modelo de permisos, consulta la guía de permisos.