Visão geral

A Graph API é a principal forma de inserir e extrair dados da plataforma do Facebook. É uma API baseada em HTTP de nível inferior que os aplicativos podem usar para consultar dados de forma programática, para publicar novas histórias, gerenciar anúncios, carregar fotos e realizar diversas outras tarefas.

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. Ela é composta de:

  • nós — são basicamente "objetos" individuais, como um Usuário, Foto, Página ou Comentário
  • bordas — são as conexões entre uma coleção de objetos e um objeto único, como Fotos em uma Página ou Comentários em uma Foto
  • campos — são os dados a respeito de um objeto, como a data de aniversário do Usuário ou o nome de uma Página

Em geral, os nós são usados para a obtenção de dados sobre um objeto específico, as bordas são usadas para obter coleções de objetos sobre um objeto único e os campos para obter dados sobre um objeto único ou sobre cada objeto de uma coleção.

HTTP

A Graph API tem base em HTTP, portanto, funciona com qualquer linguagem que tenha uma biblioteca HTTP, como cURL e urllib. Isso quer dizer que você pode usar a Graph API diretamente em seu navegador. Por exemplo, solicitar esta URL em seu navegador...

https://graph.facebook.com/facebook/picture?redirect=false

...é o mesmo que executar esta solicitação de cURL:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture?redirect=false&access_token={valid-access-token-goes-here}"

Tokens de acesso

Você deve ter notado o parâmetro access_token e o valor de espaço reservado na solicitação de cURL acima. A maioria das solicitações da Graph API exigem um token de acesso. Posteriormente, leia nossa documentação sobre token de acesso para saber como os tokens de acesso funcionam. Por enquanto, tudo o que você precisa saber é que:

  • quase todas as solicitações da Graph API exigem algum tipo de token de acesso, e
  • a maneira mais fácil de obter tokens de acesso é implementando o Login do Facebook

Os exemplos de pseudo-códigos de solicitação/resposta que aparecem em toda a documentação da Graph API podem não fazer referência explícita ao token de acesso, mas subentende-se que ele tenha sido incluído na solicitação de modo a receber a resposta.

Estrutura

Tratamos disso em mais detalhes em Como usar o guia da Graph API, mas em geral:

  • os nós são usados para a obtenção de dados sobre objetos individuais
  • as bordas são usadas para a obtenção de coleções de objetos conectados a um nó ou para a publicação de objetos nessas coleções
  • os campos são usados para especificar quais dados incluir nas respostas

URL de hospedagem

Quase todas as solicitações são passadas à URL de hospedagem graph.facebook.com. A única exceção são os carregamentos de vídeo, que usam o graph-video.facebook.com.

IDs de objeto

Os nós são objetos individuais, cada um com uma identificação única, então, para obter informações sobre um nó, consulte diretamente a identificação dele. Por exemplo, a Página oficial do Facebook tem a identificação 20531316728. Consulte-a diretamente usando a identificação:

GET graph.facebook.com
  /20531316728

Se quiser obter dados específicos (chamados de campos) sobre um nó, inclua o parâmetro fields e especifique quais campos deseja que a resposta retorne. Uma olhada rápida na referência sobre nós de Páginas revela que um dos campos obtidos ao ler um objeto de Página é o campo cover, que é a foto da capa da Página. A consulta seria assim:

GET graph.facebook.com
  /20531316728?fields=cover

A maioria dos nós tem bordas que podem retornar coleções de objetos conectados ao nó. Para consultar uma borda, use o ID do nó e o nome da borda. Uma das bordas listadas na referência sobre nós de Páginas é a borda photos, que retorna todos os objetos Foto que a Página possui. Então, para obter todas as fotos da Página do Facebook, consulte a borda photos do nó:

GET graph.facebook.com
  /20531316728/photos

Alguns nós permitem a atualização de campos com operações POST. Por exemplo, se você fosse administrador da Página do Facebook, poderia atualizar o campo description dela assim:

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

As bordas, em geral, permitem a publicação de novos objetos nas coleções do nó com a execução de operações POST. Você poderia publicar uma foto na coleção de fotos da Página do Facebook assim:

POST graph.facebook.com
  /20531316728/photos

É claro que a publicação de um objeto em uma coleção normalmente exige campos adicionais para esse objeto, como a URL da foto, um título ou descrição. A documentação de referência sobre as bordas indica os campos obrigatórios e opcionais.

Por fim, é possível excluir um nó executando a operação DELETE no ID do objeto:

DELETE graph.facebook.com
  /20531316728

Versões

A Graph API tem muitas versões. Leia mais sobre o controle de versão em nosso guia da Versão do aplicativo, mas explicaremos aqui como fazer uma chamada para uma versão específica.

É bem simples: basta adicionar a letra v seguida do número da versão ao início do caminho da solicitação. Por exemplo, esta é uma chamada para a versão 2.9:

GET graph.facebook.com
  /v2.9/20531316728/photos

Se você não incluir o número da versão, usaremos por padrão a versão mais antiga disponível, então, é sempre indicado incluí-lo nas solicitações.

O log de alterações da Graph API relaciona todas as versões disponíveis, e nossos Documentos de referência permitem filtrar o conteúdo por versão.

Próximas etapas

Agora, vamos analisar o tópico Como usar a Graph API para ver algumas solicitações mais elaboradas e as respectivas respostas, além de outras ações que você pode realizar com a Graph API.