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 para Facebook. 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.

Objetos de la API Graph para Workplace

Se puede acceder a los nodos que se indican a continuación a través de la API Graph para Workplace mediante un identificador de acceso a la aplicación de terceros o una integración personalizada.

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. Este nodo también se usa para ver y editar los mensajes que recibe y envía este usuario.

Aptitudes

Una aptitud añadida al perfil de un miembro.

Evento

Un evento de un grupo o comunidad de Workplace.

Categoría

Una categoría de la Biblioteca de conocimiento para almacenar contenido importante de la empresa.

Conjunto de personas

Un grupo de personas que se ha definido mediante criterios o listas.

Contenido denunciado

Contenido de Workplace que se ha denunciado y un administrador debe revisarlo.

Turno

Los datos del calendario de turnos para los trabajadores de Workplace que trabajan por horas.

Encuesta

Encuestas que se han creado en Workplace.

Exportación de datos

Los trabajos de exportación de datos para la exportación masiva de datos desde 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 para la plataforma de Facebook. De esta forma, hereda el mismo comportamiento de control de versiones de la API que se usa en Facebook.

Las versiones de la API Graph se lanzan aproximadamente cada tres meses y los cambios 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 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.

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

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

Obtener un identificador de acceso de miembro

Un identificador de acceso a la aplicación permite que una aplicación acceda a los objetos de la comunidad e interactúe con ellos, mientras que un identificador de acceso de miembro permite que un servicio realice llamadas en nombre de una cuenta específica.

Puedes recuperar un identificador de acceso de miembro mediante una solicitud GET al extremo /member_id de un miembro determinado, con un identificador de acceso de administrador y una solicitud del campo adicional impersonate_token.

Esta funcionalidad necesita el permiso de suplantación para la aplicación que realiza la llamada.