Como usar a Graph API

Abordamos as noções básicas de terminologia e estrutura da Graph API na visão geral da Graph API. Este documento se aprofunda nas várias operações que você pode executar com a Graph API

HTTP/1.1

Todas as transferências de dados estão em conformidade com o HTTP/1.1, e todos os pontos de extremidade exigem HTTPS. Também ativamos a diretiva HSTS includeSubdomains no facebook.com, mas isso não deve impactar negativamente suas chamadas da Graph API.

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.

Tokens de acesso

Os tokens de acesso permitem que seu aplicativo acesse a Graph API. Em geral, eles desempenham duas funções:

  • permitem que seu aplicativo acesse as informações de um Usuário sem exigir a senha do Usuário, e
  • permitem que identifiquemos seu aplicativo, o Usuário que o está usando e quais dados o Usuário autorizou o aplicativo a acessar.

Todos os pontos de extremidade da Graph API exigem algum tipo de token de acesso, por isso cada vez que você acessar um ponto de extremidade, sua solicitação deverá incluir um.

Como os tokens funcionam

Os tokens de acesso estão em conformidade com o protocolo OAuth 2.0. O OAuth 2.0 permite que entidades como o Usuário ou a Página autorizem tokens. Em geral, isso se dá por meio de uma interface da web. Após autorizados, os aplicativos podem usar os tokens para acessar informações específicas.

Por exemplo, este aplicativo está pedindo permissão para acessar as fotos, vídeos e endereço de email do Usuário:

Como você pode ver, essa é uma interface do Facebook. O Usuário apenas usou a interface para entrar na conta, o que nos permitiu autenticá-lo. Se o Usuário continuar, trocaremos o token antigo (um token do aplicativo) por um novo (um token do usuário). Assim, o aplicativo poderá usar o novo token do usuário para fazer solicitações à Graph API, mas só poderá acessar as fotos, vídeos e endereço de email desse Usuário específico.

Este é um atributo importante dos tokens de acesso. Os IDs de usuário e aplicativo são codificados no próprio token (entre outros elementos). Além disso, usamos esses IDs para acompanhar quais dados o usuário permitiu que o aplicativo acesse. Por exemplo, se você inspecionasse o token após a permissão do Usuário, veria estas informações:

Como os tokens permitem acessar os dados de um Usuário e podem ser usados por qualquer pessoa, são extremamente valiosos; por isso, tome todas as precauções ao usá-los em suas consultas. A forma mais fácil de fazer isso é usando o Login do Facebook para controlar seus tokens.

Login do Facebook

O OAuth2.0 envolve muitos redirecionamentos, prompts de login e trocas de token. Então, para facilitar as coisas para você, criamos o produto Login do Facebook. O Login do Facebook tem funções e métodos práticos para todas os nossos SDKs, tornando o trabalho com os tokens de acesso mais simples do que criar sua própria solução.

Para saber mais sobre os tokens de acesso e o Login do Facebook, ou para saber como criar sua própria solução, leia nossa documentação sobre o Login do Facebook.

Leitura

Nós

As operações de leitura quase sempre começam com um . Um nó é um objeto individual com uma identificação única. Por exemplo, existem vários objetos de nós de Página, cada um com uma identificação única, e a Página da Coca-Cola é a única que tem a identificação 820882001277849. Para ler qualquer nó, você deve consultar um ID de objeto específico. Assim, para ler o nó da Página da Coca-Cola, você consultaria a identificação dela:

GET https://graph.facebook.com/820882001277849

Esta solicitação retornaria os seguintes campos (propriedades do nó) por padrão, formatados em JSON:

{
  "name": "Coca-Cola",
  "id": "820882001277849"
}

Bordas

Os nós possuem bordas, que geralmente podem retornar coleções de outros nós anexados a eles. Para ler uma borda, é preciso incluir no caminho o ID do nó e o nome da borda. Por exemplo, os nós /page têm uma borda /feed que pode retornar todos os nós de Publicação de uma Página. Veja como você usaria a borda para obter todas as Publicações na Página da Coca-Cola:

GET https://graph.facebook.com/820882001277849/feed

A resposta JSON seria semelhante a esta:

{
  "data": [
    {
      "created_time": "2017-12-08T01:08:57+0000",
      "message": "Love this puzzle. One of my four coke puzzles",
      "id": "820882001277849_1805191182846921"
    },
    {
      "created_time": "2017-12-07T20:06:14+0000",
      "message": "You need to add grape as a flavor for Coke in your freestyle machines.",
      "id": "820882001277849_1804966026202770"
    },
    {
      "created_time": "2017-12-07T01:29:12+0000",
      "message": "Plz play the old commercial’s with the polar bears. Would be nice to see them this holiday",
      "id": "820882001277849_1804168469615859"
    }
  ]
}

Veja que a resposta não só contém os IDs dos nós de Publicação na coleção, mas também os campos created_time e message. Isso é normal. A maioria das bordas incluem um ou mais campos por padrão.

Campos

Os campos são propriedades dos nós. Ao consultar um nó, ele retornará um conjunto de campos por padrão, como mostram os exemplos acima. No entanto, é possível especificar que campos você deseja retornar usando o parâmetro fields e listando cada campo. Isso substituirá os padrões e retornará somente os campos especificados, além do ID do objeto, que sempre é retornado.

Por exemplo, a referência sobre nós de Página indica quais campos você pode pedir ao ler um nó de Página. Se quisesse obter os campos about, fan_count e website da Página da Coca-Cola, você poderia fazer o seguinte:

GET https://graph.facebook.com/820882001277849
    ?fields=about,fan_count,website

Isso retornaria a seguinte resposta:

{
  "about": "Welcome to the happiest Facebook page on, um, Facebook.",
  "fan_count": 106714402,
  "website": "http://coca-cola.com",
  "id": "820882001277849"
}

As bordas, que geralmente retornam coleções de objetos, também retornam campos sobre cada objeto da coleção. Digamos que você tenha usado a borda /photos para obter todos os nós de Fotos na Página da Coca-Cola:

GET https://graph.facebook.com/820882001277849/photos

Isso geraria uma resposta semelhante a esta:

{
  "data": [
    {
      "created_time": "2016-08-23T13:12:10+0000",
      "id": "1308573619175349"
    },
    {
      "created_time": "2016-08-05T22:34:19+0000",
      "id": "1294456907253687"
    },
    {
      "created_time": "2016-04-29T16:17:02+0000",
      "id": "1228552183844160"
    }
  ]
}

Como você pode ver, a borda /photos retornará por padrão uma coleção de IDs de nós de Foto, além da propriedade created_time de cada foto. Da mesma forma que acontece com os nós, é possível usar o parâmetro fields para especificar quais campos você deseja que retornem para cada objeto retornado na coleção.

Digamos que você quisesse obter os campos height, width e link (URL) de cada nó de Foto retornado pela borda /photos:

GET https://graph.facebook.com/820882001277849/photos
      ?fields=height,width,link

A resposta teria a seguinte aparência:

{
  "data": [
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1308573619175349/?type=3",
      "id": "1308573619175349"
    },
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1294456907253687/?type=3",
      "id": "1294456907253687"
    },
    {
      "height": 180,
      "width": 180,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1228552183844160/?type=3",
      "id": "1228552183844160"
    }
  ]
}

Observe que você também pode especificar uma borda com o parâmetro fields, o que é útil ao usar expansão de campo.

Expansão de campo

Caso tenha testado a consulta GET /page/photos acima no Explorador da Graph API, você deve ter notado que a solicitação retornou mais de três objetos e que também paginou os resultados. Isso é normal para a maioria das bordas. Trataremos em breve sobre como percorrer os resultados. Vejamos agora a expansão de campo, que permite executar consultas aninhadas, além de limitar e ordenar os resultados.

Como limitar resultados

A limitação permite controlar o número de objetos retornados em cada conjunto de resultados paginados. Para limitar os resultados, adicione um argumento .limit() a qualquer campo ou borda.

Por exemplo, executar uma solicitação GET na borda /feed da Página da Coca-Cola pode retornar centenas de Publicações. É possível limitar o número de Publicações retornadas por cada página de resultados fazendo o seguinte:

GET https://graph.facebook.com/820882001277849
    ?fields=feed.limit(3)

Isso retornará todas as Publicações na Página da Coca-Cola, mas limitará a três a quantidade de objetos em cada página de resultados. Veja que em vez de especificar a borda Feed no caminho da URL (/page/feed), a especificação é no parâmetro fields (?fields=feed), que permite acrescentar o argumento .limit(3).

Estes são os resultados da consulta:

{
  "feed": {
    "data": [
      {
        "created_time": "2017-12-12T01:24:21+0000",
        "message": "This picture of my grandson with Santa screams Coca Cola",
        "id": "820882001277849_1809387339093972"
      },
      {
        "created_time": "2017-12-11T23:40:17+0000",
        "message": ":)",
        "id": "820882001277849_1809316002434439"
      },
      {
        "created_time": "2017-12-11T23:31:38+0000",
        "message": "Thought you might enjoy this.  My horse loves Coke!",
        "id": "820882001277849_1809310929101613"
      }
    ],
    "paging": {
      "cursors": {
        "before": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5UTRNakE0T0RJd01ERXlOemM0TkRrNkxUVXdPRE16TXpVM01EQXpNVFUwTkRRME5Ua1BER0ZA3YVY5emRHOXllVjlwWkE4ZA09ESXdPRGd5TURBeE1qYzNPRFE1WHpFNE1Ea3pPRGN6TXprd09UTTVOeklQQkhScGJXVUdXaTh2eFFFPQZDZD",
        "after": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5TTRNakE0T0RJd01ERXlOemM0TkRrNk1UTTJORE01T0RVNU1UZAzVPRGMyTnpFNE1BOE1ZAWEJwWDNOMGIzSjVYMmxrRHlBNE1qQTRPREl3TURFeU56YzRORGxmTVRnd09USXdOamsxTlRjM09EWTNOdzhFZAEdsdFpRWmFMdk9HQVE9PQZDZD"
      },
      "next": "https://graph.facebook.com/820882001277849/feed?access_token=valid_token_goes_here"
    }
  },
  "id": "820882001277849"
}

Como você pode ver, apenas três objetos aparecem nesta página de resultados, mas a resposta incluiu uma URL e campo next que podem ser usados para buscar a próxima página.

Como ordenar resultados

É possível ordenar resultados com base na hora de criação do objeto. Para isso, use um argumento .order() com um dos valores a seguir em um campo ou em uma borda.

  • chronological — ordena os resultados mostrando primeiro os objetos criados mais antigos.
  • reverse_chronological — ordena os resultados mostrando primeiro os objetos criados mais recentes.

Por exemplo, vamos pegar todos os Comentários de uma das Publicações de vídeo da Página da Coca-Cola (1809938745705498), ordenar os resultados cronologicamente (os mais antigos primeiro) e limitar a três a quantidade de objetos por resultado paginado.

GET https://graph.facebook.com/1809938745705498
    ?fields=comments.order(chronological).limit(3)

Mais uma vez, observe que para usar um argumento em uma borda, é preciso especificá-la no parâmetro fields. Como você pode ver, é possível combinar os argumentos .limit() e .order() em um único campo ou borda.

Eis os resultados:

{
  "comments": {
    "data": [
      {
        "created_time": "2017-12-12T14:12:20+0000",
        "message": ":) :) :)",
        "id": "1809938745705498_1809939942372045"
      },
      {
        "created_time": "2017-12-12T14:14:03+0000",
        "message": "seasons greetings!",
        "id": "1809938745705498_1809941802371859"
      },
      {
        "created_time": "2017-12-12T14:14:11+0000",
        "message": "My bestie <3",
        "id": "1809938745705498_1809941879038518"
      }
    ],
    "paging": {
      "cursors": {
        "before": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd3T1Rrek9UZAzROVGN3TlRNNE5Eb3hOVEV6TURnM09UTTIZD",
        "after": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd4TURBd09UazROVFk1T0RNM05Eb3hOVEV6TURreU5qQXoZD"
      },
      "next": "https://graph.facebook.com/1809938745705498/comments?access_token=valid_token_goes_here"
    }
  },
  "id": "1809938745705498"
}

Publicação

A maioria das bordas permite publicar objetos em uma coleção em um nó. É possível fazer isso usando uma solicitação POST na borda do nó. Por exemplo, é possível publicar um Comentário em uma Foto usando a borda /comments do nó da Foto.

POST https://graph.facebook.com
  /1809938745705498
    /comments
      ?message=Awesome!

Em caso de sucesso, a maioria das bordas retornará o ID do objeto que você acabou de publicar, que em geral é uma combinação do ID sob o qual o objeto foi publicado e uma nova cadeia de caracteres do ID:

{
  "id": "1809938745705498_1810399758992730"
}

As publicações normalmente exigem permissões adicionais, por isso, verifique a documentação de referência de cada borda para confirmar quais são as permissões obrigatórias.

O token de acesso usado para publicar o objeto pode afetar a aparência do objeto. Se um token de acesso à Página for usado, parecerá que a Página publicou o objeto, enquanto que um token de acesso do usuário fará parecer que o objeto foi publicado por uma pessoa.

Muitas bordas também são compatíveis com recursos avançados, como Read-After-Write, que permite ler um objeto recém-publicado imediatamente, e Publicação em lote, que permite encadear múltiplas operações de publicação.

Atualização

É possível realizar operações de atualização em um nó existente usando solicitações POST. Por exemplo, para atualizar o campo message em um Comentário existente, faça o seguinte:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?message=Happy%20Holidays!

Em caso de sucesso, o nó retornará um campo success e um valor de true:

{
  "success": true
}

Assim como as operações de publicação, as de atualização exigem permissões adicionais, que estarão listadas na documentação de referência de cada nó. Além disso, assim como a maioria das bordas, muitos nós são compatíveis com Read-After-Write.

Como excluir

É possível excluir um nó usando uma operação DELETE:

DELETE https://graph.facebook.com
  /1809938745705498_1810399758992730

Em caso de sucesso, o nó retornará um campo success e um valor de true:

{
  "success": true
}

Normalmente, só é possível excluir nós criados por você, mas verifique o guia de referência de cada nó para ver as exigências para operações de exclusão.

Para oferecer suporte a clientes sem compatibilidade com métodos HTTP, envie uma solicitação POST ao nó e inclua o valor e o parâmetro method=delete para substituir o método HTTP:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?method=delete

Como percorrer os resultados paginados

Quando você faz uma solicitação à API para um nó ou uma borda, normalmente não recebe todos os resultados dessa solicitação em uma única resposta. Isso ocorre por que algumas respostas podem conter milhares de objetos. Portanto, a maioria das respostas é paginada por padrão.

Paginação com base no cursor

A paginação com base no cursor é a forma mais eficiente de paginação e deve, sempre que possível, ser usada. Um cursor se refere a uma cadeia de caracteres aleatória que marca um item específico em uma lista de dados. A menos que esse item seja excluído, o cursor sempre apontará para a mesma parte da lista, mas será invalidado caso um item seja removido. Portanto, seu aplicativo não deve armazenar cursores ou supor que eles ainda sejam válidos no futuro.

Ao ler uma borda que oferece suporte à paginação de cursor, você verá a seguinte resposta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Uma borda paginada com cursor oferece suporte aos seguintes parâmetros:

  • before : esse é o cursor que aponta para o início da página de dados retornados.
  • after : esse é o cursor que aponta para o final da página de dados retornados.
  • limit : esse é o número máximo de objetos que podem ser retornados. Uma consulta pode retornar menos que o valor do limit devido à filtragem. Não dependa do número de resultados menor que o valor limit para indicar que sua consulta alcançou o final da lista de dados. Em vez disso, use a ausência de next como descrito abaixo. Por exemplo, se você definir o limit para dez, e retornarem nove resultados, pode haver mais dados disponíveis, mas um item foi removido devido à filtragem de privacidade. Algumas bordas também podem ter um máximo para o valor limit, por questões de desempenho. Em todos os casos, a API retornará os links de paginação corretos.
  • next : o ponto de extremidade da Graph API que retornará a próxima página de dados. Se não estiver incluído, esta será a última página de dados. Devido ao modo como a paginação funciona com visibilidade e privacidade, é possível que uma página esteja vazia, mas contenha um link de página "avançar". Interrompa a paginação quando o link "avançar" não aparecer mais.
  • previous : o ponto de extremidade da Graph API que retornará a página de dados anterior. Se não estiver incluído, esta será a primeira página de dados.

Não armazene cursores. Os cursores podem se tornar inválidos rapidamente se os itens forem adicionados ou excluídos.

Paginação com base no tempo

A paginação de tempo é usada para navegar pelos dados dos resultados usando carimbos de data e hora Unix, que apontam para horários específicos em uma lista de dados.

Ao usar um ponto de extremidade que usa a paginação com base no tempo, você verá a seguinte resposta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

Uma borda paginada por tempo oferece suporte aos seguintes parâmetros:

  • until : um carimbo de data e hora Unix ou um valor de dados strtotime que aponta para o final do intervalo de dados baseados no tempo.
  • since : um carimbo de data e hora Unix ou um valor de dados strtotime que aponta para o início do intervalo de dados baseados no tempo.
  • limit : esse é o número máximo de objetos que podem ser retornados. Uma consulta pode retornar menos que o valor do limit devido à filtragem. Não dependa do número de resultados menor que o valor limit para indicar que sua consulta alcançou o final da lista de dados. Em vez disso, use a ausência de next como descrito abaixo. Por exemplo, se você definir o limit para dez, e retornarem nove resultados, pode haver mais dados disponíveis, mas um item foi removido devido à filtragem de privacidade. Algumas bordas também podem ter um máximo para o valor limit, por questões de desempenho. Em todos os casos, a API retornará os links de paginação corretos.
  • next : o ponto de extremidade da Graph API que retornará a próxima página de dados.
  • previous : o ponto de extremidade da Graph API que retornará a página de dados anterior.

Para resultados consistentes, especifique os parâmetros since e until. Além disso, é recomendável que o intervalo de tempo seja de no máximo seis meses.

Paginação com base em deslocamento

A paginação por deslocamento pode ser usada quando você não se importa com a cronologia e quer retornar apenas uma quantidade específica de objetos. Isso deve ser usado apenas se a borda não suportar a paginação com base em cursor ou no tempo.

Uma borda com paginação por deslocamento oferece suporte aos seguintes parâmetros:

  • offset : desloca o início de cada página de acordo com o número especificado.
  • limit : esse é o número máximo de objetos que podem ser retornados. Uma consulta pode retornar menos que o valor do limit devido à filtragem. Não dependa do número de resultados menor que o valor limit para indicar que sua consulta alcançou o final da lista de dados. Em vez disso, use a ausência de next como descrito abaixo. Por exemplo, se você definir o limit para dez, e retornarem nove resultados, pode haver mais dados disponíveis, mas um item foi removido devido à filtragem de privacidade. Algumas bordas também podem ter um máximo para o valor limit, por questões de desempenho. Em todos os casos, a API retornará os links de paginação corretos.
  • next : o ponto de extremidade da Graph API que retornará a próxima página de dados. Se não estiver incluído, esta será a última página de dados. Devido ao modo como a paginação funciona com visibilidade e privacidade, é possível que uma página esteja vazia, mas contenha um link de página "avançar". Interrompa a paginação quando o link "avançar" não aparecer mais.
  • previous : o ponto de extremidade da Graph API que retornará a página de dados anterior. Se não estiver incluído, esta será a primeira página de dados.

Observe que se novos objetos forem adicionados à lista de itens paginados, o conteúdo de cada página baseada em deslocamento mudará.

A paginação com base em deslocamento não tem suporte para todas as chamadas de API. Para obter resultados consistentes, recomendamos a paginação usando os links voltar/avançar que retornamos na resposta.