Referencia de la API Graph

Información general

La API Graph para Workplace permite ingresar y extraer datos en Workplace mediante programación. Es una API basada en HTTP de bajo nivel que se puede usar para consultar datos sobre los objetos de un gráfico de Workplace.

La API Graph recibe su nombre por los modelos de datos de gráficos, donde los objetos se representan por nodos y se unen en los perímetros. En el nivel de la API, es la forma en que las apps acceden a la información de Workplace. La API Graph de Workplace admite un subconjunto de funcionalidades de la API Graph. Esta funcionalidad está limitada a las interacciones con una comunidad de Workplace y, en algunos casos, puede presentar diferencias para conseguir un rendimiento o una facilidad de uso mayores.

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

Crear apps Crear bots Permisos Muestras

Objetos de la API Graph de Workplace

Se puede acceder a los siguientes nodos a través de la API Graph de Workplace. Para acceder a todos los nodos se debe usar un token de acceso de integración personalizado.

Community

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

Groups

Un grupo de Workplace.

Posts

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

Members

La cuenta de un usuario específico de Workplace.

Para consultar ejemplos donde se combinen llamadas a la API Graph a fin de solucionar problemas específicos, echa un vistazo al listado de apps de muestra.

Uso de la API Graph

Objetos de la API Graph

La API Graph es una representación de la información disponible en Workplace, que comprende lo siguiente:

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

Todos los artículos del gráfico de Workplace se encuentran representados por un identificador singular. Los grupos, los miembros, las publicaciones e incluso los comentarios tienen sus propios identificadores, los cuales pueden utilizarse para recuperar información sobre ellos desde la API Graph.

Administración de tu comunidad

Cada comunidad de Workplace se mantiene separada de las demás, de modo que puedes usar la API Graph únicamente para acceder al contenido que se encuentra dentro de tu propia comunidad y de los grupos entre empresas donde ya se agregaron a los miembros de la comunidad.

A los efectos del acceso a la API Graph, se tratará a tu comunidad como un grupo. Puedes pensar en tu comunidad como un grupo raíz al cual todos tus grupos se agregan como elementos secundarios. Para recuperar información sobre tu comunidad en la API Graph, necesitarás el identificador de tu comunidad, el cual se recupera programáticamente desde la API Graph mediante una solicitud HTTP GET a graph.facebook.com/community con un token de acceso a la app válido.

Versiones de la API Graph

La API Graph de Workplace se construye sobre la API Graph. De esta manera, hereda la misma dinámica de versiones de la API.

Las versiones de la API Graph se lanzan aproximadamente cada tres meses, y los cambios implementados 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 la versión en la ruta de la API de la siguiente manera:

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

No obstante, existen algunas restricciones sobre las versiones disponibles:

Cuando se lanza una nueva versión, esta se convierte en la versión actual de la API, la cual tiene una garantía de funcionamiento de dos años a partir de la fecha de lanzamiento.
Cuando se crea una app, esta adopta de forma predeterminada la versión actual de la API al momento de la creación y se convierte en la versión mínima de la API disponible para dicha app.
Las apps pueden especificar cualquier versión de la API cuando realizan llamadas a la API, pero no podrán realizar llamadas a aquellas versiones obsoletas de la API ni a versiones inferiores a la versión mínima de la API.
Las llamadas a la API sin versión adoptarán de forma predeterminada la versión mínima de la API de la app.

Cuando se crea una nueva integración personalizada, su versión mínima de la API disponible será la versión actual de la API al momento de la creación. Tal versión mínima afecta tanto a las llamadas a la API Graph como a las suscripciones al Webhook.

Versiones de la plataforma Registro de cambios de la API Graph

Consulta de versión de la API Graph

Si no sabes con certeza qué versión utilizas, existen varias formas de consultarla. Para consultar qué versión de la API Graph puede utilizarse con tu app, puedes agregar el parámetro debug a tu llamada a la API.

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

De esta manera, se devolverá información de depuración adicional que confirmará la versión utilizada.

      {
         "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 mínima de la API correspondiente para tu app, el mensaje debug te lo notificará.

      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"
               }
            ]
         }
      }

Consulta de versión del Webhook

Las suscripciones al Webhook usan la versión mínima de la API si la suscripción fue realizada mediante el diálogo emergente de la integración personalizada, o bien si la versión especificada de la API es una suscripción realizada a través del punto de conexión de suscripciones de la API Graph /app/subscriptions.

Puedes usar el punto de conexión de las suscripciones para confirmar la versión del Webhook aplicado en cada tema y campo del Webhook. Este punto de conexión requiere un token de acceso a la app.

      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"
              },
      ...

Dependiendo de cómo se habilitó la suscripción al Webhook, es posible que los distintos campos dentro de un único objeto Webhook devuelvan cargas con números de versión diferentes.

Si la carga no se encuentra en el formato que esperas, consulta nuevamente el número de la versión y vuelve a realizar la suscripción con una versión más nueva si es necesario.

Uso de tokens de acceso

Obtener un token de acceso a la app

Para realizar llamadas a la API Graph en tu comunidad, necesitarás crear una app y recuperar un token de acceso. Esto conlleva crear una nueva app y luego otorgarle los permisos necesarios para la funcionalidad que quieras crear.

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