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 aplicativos acessam as informações no Workplace. A Graph API para o Workplace permite um subconjunto de funcionalidades da Graph API para o Facebook. Essa funcionalidade é limitada a interações com uma comunidade do Workplace e pode variar em alguns casos para oferecer melhor desempenho ou usabilidade.

Objetos da Graph API para o Workplace

Os nós a seguir podem ser acessados por meio da Graph API para o Workplace usando uma integração personalizada ou um token de acesso do aplicativo de terceiros.

Comunidade

Uma comunidade do Workplace. O grupo raiz para 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. Esse nó também é usado para visualizar e editar mensagens recebidas e enviadas por esse usuário.

Habilidades

Uma habilidade adicionada ao perfil de um membro.

Evento

Um evento de grupo ou comunidade do Workplace.

Categoria

Uma categoria na Biblioteca de Conhecimento para armazenar conteúdo importante da empresa.

Conjuntos de pessoas

Uma coleção de pessoas definida por critérios ou listas.

Conteúdo denunciado

Conteúdo no Workplace que foi denunciado e deve passar pela análise de um administrador.

Turno

Dados da programação de turnos para trabalhadores horistas no Workplace.

Pesquisa

Pesquisas criadas no Workplace.

Exportação de dados

Trabalhos de exportação de dados para exportação em massa no 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 aplicativo válido.

Controle de versões da Graph API

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

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 do Facebook 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 aplicativo é 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 aplicativo.
Os aplicativos 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 aplicativo 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 aplicativo, adicione o parâmetro debug a 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 aplicativo, 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 aplicativo.

      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 ativada, 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 aplicativo

Para fazer qualquer chamada da Graph API para sua comunidade, você precisará criar um aplicativo e recuperar um token de acesso. Isso inclui criar uma nova integração personalizada e, em seguida, conceder a ela as permissões necessárias para a funcionalidade que você quer desenvolver.

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

Obter um token de acesso de membro

Um token de acesso do aplicativo permite que um aplicativo acesse e interaja com objetos de toda a comunidade. Já um token de acesso de membro possibilita que um serviço faça chamadas em nome de uma conta específica.

Você pode buscar um token de acesso de membro fazendo uma solicitação GET para o ponto de extremidade /member_id para um membro específico. Para isso, use um token de acesso de administrador e solicite o campo adicional impersonate_token.

Essa funcionalidade requer a permissão "Passar-se por" para o aplicativo que faz a chamada.

A permissão "Passar-se por" está obsoleta. Não crie novos recursos usando essa permissão. Ela não pode mais ser adicionada a integrações personalizadas.

Os tokens de "Passar-se por" só podem ser obtidos para contas que foram ativadas.