Referência da Graph API

Visão geral

A Graph API para o Workplace é uma forma programática de inserir e extrair dados do Workplace. Com essa API baseada em HTTP de baixo nível, você pode consultar dados sobre objetos em um gráfico do Workplace.

O nome da Graph API é baseado na ideia de um modelo de dados de gráfico, em que os objetos são representados por nós e unidos ao longo das bordas. No nível da API, é dessa forma que os apps acessam as informações no Workplace. A Graph API para o Workplace permite um subconjunto de funcionalidades da Graph API. Essa funcionalidade é limitada a interações com uma comunidade do Workplace e pode variar em alguns casos para oferecer melhor desempenho ou usabilidade.

É possível ver mais informações sobre como usar a Graph API no Workplace a seguir:

Como criar apps Como criar bots Permissões Amostras

Objetos da Graph API para o Workplace

Os nós a seguir podem ser acessados por meio da Graph API do Workplace. É preciso usar um token de acesso de integração personalizada para acessar todos os nós.

Comunidade

Uma comunidade do Workplace. O grupo raiz para as suas chamadas da Graph API para o Workplace.

Grupos

Um grupo do Workplace.

Publicações

Uma publicação feita em um grupo ou no perfil de um membro.

Membros

A conta de um usuário específico do Workplace.

Se quiser ver exemplos de combinações de chamadas da Graph API para resolver problemas específicos, confira a lista de exemplos de apps.

Como usar a Graph API

Objetos da Graph API

A Graph API é uma representação das informações no Workplace, composta pelos elementos a seguir:

Nós: objetos como um usuário, uma foto, uma publicação, um comentário.
Bordas: as conexões entre esses "itens", como um arquivo de publicação ou comentários de uma foto.
Campos: metadados sobre objetos, como o nome de uma pessoa ou a privacidade de um grupo.

Cada item é representado por um ID único no gráfico do Workplace. Os itens grupos, membros, publicações e até mesmo comentários têm os próprios IDs e podem ser usados para recuperar informações sobre eles na Graph API.

Como gerenciar sua comunidade

As comunidades do Workplace ficam separadas umas das outras. Por isso, você só pode usar a Graph API para acessar conteúdo dentro da sua própria comunidade e em grupos de várias empresas a que os membros da sua comunidade foram adicionados.

Para fins de acesso à Graph API, sua comunidade é tratada como um grupo. Você pode pensar na sua comunidade como um grupo raiz, usado para adicionar todos os seus grupos derivados. Para recuperar informações sobre sua comunidade na Graph API, você precisa do ID da comunidade. Esse código é recuperado programaticamente a partir da Graph API, fazendo uma solicitação HTTP GET para graph.facebook.com/community com um token de acesso do app válido.

Controle de versões da Graph API

A Graph API para o Workplace foi criada com base na Graph API. Isso significa que ela herdou o mesmo comportamento de controle de versões da API.

As versões da Graph API são lançadas a cada três meses, aproximadamente, e as mudanças em todas as APIs do Workplace e da Graph API são publicadas no registro de alterações da Graph API.

Ao fazer uma chamada à Graph API, você pode especificar uma versão no caminho da API desta forma:

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

No entanto, existem algumas restrições às versões disponíveis:

Quando uma nova versão é lançada, ela se torna a versão atual da API e tem garantia de funcionamento de dois anos após o lançamento.
Quando um app é criado, o padrão é usar a versão atual da API no momento da criação, que se torna a versão mínima da API disponível para o app.
Os apps têm a liberdade de especificar qualquer versão da API ao fazer chamadas de API, mas não podem fazer chamadas para uma versão obsoleta nem para versões abaixo da versão mínima da API.
As chamadas de API sem versão usarão a versão mínima da API para o app por padrão.

Quando uma nova integração personalizada for criada, a versão mínima da API disponível será a versão atual da API no momento da criação. Essa versão mínima afeta as chamadas da Graph API e as assinaturas de Webhook.

Versões da plataforma Registro de alterações da Graph API

Como verificar a versão da Graph API

Se você não tiver certeza de qual versão está usando, existem algumas maneiras de verificar essa informação. Para descobrir qual versão da API Graph pode ser usada com seu app, adicione o parâmetro debug sua chamada de API.

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

Isso retornará informações extras de depuração para confirmar a versão que está sendo usada.

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

Se você tentar usar uma versão que está abaixo da versão mínima da API para seu app, a mensagem debug mostrará essa informação.

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

Como verificar as versões do Webhook

As assinaturas de Webhook usam a versão mínima da API, se a assinatura for feita por meio do diálogo pop-up "Integração personalizada", ou tem a versão da API especificada, caso a assinatura seja concluída por meio do ponto de extremidade /app/subscriptions da Graph API.

Você pode usar o ponto de extremidade de assinaturas para confirmar a versão aplicada a cada campo e tópico do webhook. Esse ponto de extremidade exige um token de acesso do 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"
              },
      ...

Dependendo de como a assinatura do webhook foi habilitada, diferentes campos em um único objeto de webhook podem retornar cargas usando números de versões distintos.

Caso sua carga não esteja no formato esperado, verifique o número da versão e faça a assinatura novamente usando uma versão mais recente, se necessário.

Como usar tokens de acesso

Obter um token de acesso do app

Para fazer qualquer chamada da Graph API para sua comunidade, você precisará criar um app e recuperar um token de acesso. Isso inclui criar um novo app e, depois, conceder a ele as permissões necessárias para a funcionalidade que você quer desenvolver.

Para saber mais sobre como criar apps e conhecer o modelo de permissão, consulte o guia sobre permissões.