Visão geral da Graph API

A Graph API é a principal forma de incluir e excluir dados na plataforma do Facebook. É uma API baseada em HTTP de nível inferior que você pode usar para consultar dados de forma programada, publicar novas histórias, gerenciar anúncios, carregar fotos e realizar várias outras tarefas que um aplicativo pode implementar.

Noções básicas

A Graph API recebeu esse nome com base na ideia de um "gráfico social", uma representação das informações no Facebook formada por:

  • nós - basicamente "coisas" como um Usuário, uma Foto, uma Página, um Comentário
  • bordas - as conexões entre essas "coisas", como Fotos de uma Página ou os comentários de uma Foto
  • campos - informações sobre essas "coisas", como o aniversário de uma pessoa ou o nome de uma Página

A Graph API tem base em HTTP, portanto, funciona com qualquer linguagem que tenha uma biblioteca HTTP, como cURL e urllib. Explicaremos um pouco mais sobre o que você pode fazer com isso na seção abaixo, mas significa que você também pode usar a Graph API diretamente em seu navegador, por exemplo, uma solicitação da Graph API é equivalente a:

GET graph.facebook.com
  /facebook/picture?
    redirect=false

A maioria das solicitações da Graph API exigem tokens de acesso que podem ser gerados por seu aplicativo por meio da implementação do Login no Facebook.

Essa visão geral mostrará a você como a Graph API pode ler e publicar dados no gráfico social.

Como ela é estruturada

Abordamos esse tópico em nosso guia Como usar a Graph API, mas, em geral, você pode ler APIs fazendo solicitações HTTP GET para os nós ou para as bordas nesses nós.

Quase todas as solicitações são passadas à API em graph.facebook.com - a única exceção é com carregamentos de vídeo que usam graph-video.facebook.com.

IDs de objeto

Cada nó tem um ID exclusivo que é usado para acessá-lo por meio da Graph API. Nós não documentamos qualquer estrutura ou formato de ID de nó/objeto, pois é extremamente provável que isso mude com o tempo, e os aplicativos não devem fazer suposições com base na estrutura atual.

Veja como você usaria o ID para fazer uma solicitação para um nó:

GET graph.facebook.com
  /{node-id}

Ou para uma borda:

GET graph.facebook.com
  /{node-id}/{edge-name}

Geralmente, você pode publicar em APIs fazendo solicitações HTTP POST com parâmetros para o nó:

POST graph.facebook.com
  /{node-id}

Ou para uma borda:

POST graph.facebook.com
  /{node-id}/{edge-name}

A exclusão via APIs é realizada usando solicitações HTTP DELETE (e a atualização via solicitações POST) para os mesmos endpoints.

Versões da API

A Graph API tem várias versões disponíveis para acesso a qualquer momento. Cada versão contém um conjunto de operações de campos e de bordas principais. Garantimos que essas APIs principais estarão disponíveis e não sofrerão modificações nessa versão por pelo menos dois anos a partir da data de lançamento. O log de alterações da plataforma pode informar a você quais versões estão disponíveis no momento.

Certas operações, por exemplo, a publicação dentro de uma borda, ou certos campos dentro de um nó, podem ser principais sem que toda a borda ou nó seja principal. Anotamos essas APIs principais usando este símbolo dentro de nossos documentos de referência da Graph API.

Tudo que esteja fora dessas APIs principais é chamado de APIs estendidas. Essas APIs ainda são acessadas por meio de caminhos com versão, mas podem ser modificadas ou removidas a qualquer momento, sujeitas às migrações de 90 dias que seriam anunciadas no roteiro de nossa plataforma. Como alternativa, elas podem ser simplesmente incluídas na próxima versão de API disponível.

Você pode ler mais sobre a intenção do controle de versão em nosso guia, mas aqui explicaremos como fazer uma chamada para uma versão específica da Graph API.

É realmente simples, basta pré-anexar o identificador de versão no início do caminho da solicitação. Por exemplo, esta é uma chamada para v2.2:

GET graph.facebook.com
  /v2.2/me

Isso funciona para todas as versões, neste formato geral:

GET graph.facebook.com
  /vX.Y/{request-path}

no qual X.Y é a versão necessária. Publicamos uma lista completa das versões disponíveis em nosso log de alterações. Todos os nossos documentos de referência da Graph API fornecem informações de acordo com a versão. Portanto, garanta que está usando a versão correta, algumas versões removem nós e bordas, outras adicionam.

Agora, vamos tentar uma solicitação de API, para que você veja como é fácil.

Carregue o Explorador da Graph API

A maneira mais fácil de entender a Graph API é usá-la com o Explorador da Graph API, uma ferramenta de nível baixo que você pode usar para consultar, adicionar e remover dados. É um recurso muito útil para se ter ao alcance durante a integração com o Facebook. O seu próximo passo é acessar o Explorador da Graph API.

Explorador da Graph API

Gere um token de acesso de usuário básico

Ao criar seu próprio aplicativo, você precisará aprender sobre tokens de acesso e como gerá-los usando o Login no Facebook, mas, por enquanto, podemos criar um rapidamente por meio do Explorador da Graph API:

  1. Clique no botão Get Token no canto superior direito do Explorador.
  2. Escolha a opção Get User Access Token.
  3. No seguinte diálogo, não marque qualquer caixa, apenas clique no botão Get Access Token azul.
  4. Você verá uma caixa de diálogo de Login do Facebook. Clique em OK para continuar.

Faça sua primeira solicitação

Agora você está pronto para fazer sua primeira solicitação da Graph API, começaremos com uma solicitação de "leitura". No campo de texto ao lado do botão suspenso "GET" (chamamos isso de campo de caminho), exclua o texto existente e digite "me":

Agora pressione o botão "Enviar". O processamento demorará alguns segundos, mas você deverá ver várias informações no painel de resposta. O que aparece aqui para você é determinado pelas configurações de privacidade de seu perfil, mas deve haver pelo menos alguns campos básicos:

O que você acabou de fazer aqui no Explorador da Graph API é o equivalente à seguinte solicitação de "leitura" da Graph API:

GET graph.facebook.com
  /me

/me é um endpoint especial que é traduzido para o ID de usuário da pessoa cujo token de acesso está sendo usado para fazer a solicitação.

Parabéns, você fez sua primeira solicitação da Graph API!

Obter permissões de publicação

Em seguida, tentaremos publicar algo no Facebook usando a Graph API. Você faria isso em seu aplicativo somente se estivesse criando seu próprio compositor personalizado e não usando um dos diálogos de Compartilhamento na Web, no iOS ou no Android. Os diálogos de Compartilhamento do Facebook não exigem a implementação do Login no Facebook ou a construção de sua própria interface para permitir que as pessoas compartilhem.

Para explorar a publicação com a Graph API, clique novamente nesse botão "Obter token de acesso" e, desta vez, escolha a permissão publish_actions:

Agora, clique no botão azul "Obter token de acesso", e você verá o diálogo de Login novamente. Aqui, você receberá uma solicitação de permissão para o Explorador da Graph API publicar em seu nome. Se quiser, você pode alterar o público para "Somente eu", de modo que apenas você possa ver a publicação, mas é preciso aceitar esse diálogo e ir para a próxima etapa.

Fazer uma publicação

Se você tiver solicitado a permissão para publish_actions, clique no botão "GET" e escolha "POST" no seletor suspenso que aparece. Digite me/feed no campo de caminho e clique em "Adicionar um campo".

Nos novos campos que aparecem, coloque message como o "nome" e Hello, World como o "valor". Ele deve ficar assim:

Agora, clique no botão azul "Enviar" e, após alguns segundos, o painel de resposta deverá mostrar algo parecido com o seguinte:

{
  "id": "{new-post-id}"
}

Isso significa que você acabou de fazer sua primeira publicação por meio da Graph API! Você pode acessar seu perfil e ver a publicação lá:

O que você acabou de fazer aqui no Explorador da Graph API é o equivalente à seguinte solicitação de "publicação" da Graph API:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

Próximas etapas

Você cobriu os tópicos básicos aqui, então por que não continuar e aprender mais sobre Como usar a Graph API? Caso ainda não tenha feito isso, recomendamos primeiro a leitura sobre o Login no Facebook, especialmente sobre como gerar tokens de acesso, que você precisará saber para fazer solicitações mais complexas da Graph API.