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 permite un subconjunto de funcionalidades de la API Graph de Facebook. 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.

Objetos de la API Graph de Workplace

Los siguientes nodos son accesibles a través de la API Graph de Workplace mediante una integración personalizada o un token de acceso a la app de un tercero.

Comunidad

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

Grupos

Un grupo de Workplace.

Publicaciones

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

Miembros

La cuenta de un usuario específico de Workplace. Este nodo también se usa para ver y editar los mensajes enviados y recibidos por este usuario.

Habilidades

Una habilidad agregada al perfil de un miembro.

Evento

Un evento de grupo o una comunidad de Workplace.

Categoría

Una categoría de la biblioteca de recursos para almacenar contenido importante de la empresa.

Conjunto de personas

Una colección de personas definida mediante criterios o listas.

Contenido reportado

Contenido de Workplace que un administrador reportó para su revisión.

Turnos

Datos del calendario de turnos de trabajadores por hora en Workplace.

Encuesta

Encuestas que se crearon en Workplace.

Exportación de datos

Tareas de exportación de datos de forma masiva desde Workplace.

Si quieres ver ejemplos donde se combinen llamadas a la API Graph para 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 a los grupos entre empresas donde los miembros de la comunidad ya han sido agregados.

A los efectos del acceso a la API Graph, tu comunidad será tratada 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 plataforma de la API Graph de Facebook. Esto significa que hereda la misma dinámica de versiones de la API que se utiliza en Facebook.

Las versiones de la API Graph se lanzan aproximadamente cada tres meses, y los cambios implementados en todas las API de Facebook y 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.
• De forma predeterminada, las llamadas a la API sin versión adoptarán la versión mínima de la API de esa app.

Cuando se cree una nueva integración personalizada, la versión mínima de la API disponible será la versión actual de la API en el 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.

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

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 integración personalizada, 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.

Obtener un token de acceso para miembros

Mientras un token de acceso a la app permite que una app tenga acceso a objetos de la comunidad e interactúe con ellos, un token de acceso para miembros permite a un servicio realizar llamadas en nombre de una cuenta determinada.

Puedes captar un token de acceso para miembros mediante una solicitud GET al punto de conexión /member_id de un miembro determinado utilizando un token de acceso para administradores y solicitando además el campo impersonate_token.

Esta funcionalidad requiere el permiso de suplantación para la app que realiza la llamada.