Vue d’ensemble

L’API Graph est le meilleur moyen d’insérer et de récupérer des données dans la plate-forme Facebook. Il s’agit d’une API HTTP de bas niveau qui permet aux applications d’avoir recours à la programmation pour interroger des données, publier de nouvelles actualités, gérer des publicités, importer des photos et réaliser un large éventail d’autres tâches.

Les bases

Le nom de l’API Graph s’inspire de l’idée d’un « graphe social » : une représentation des informations sur Facebook. Il est composé des éléments suivants :

  • nœuds : représentent essentiellement des objets individuels, comme un utilisateur, une photo, une Page ou un commentaire ;
  • arêtes : connexions entre une collection d’objets et un objet unique, comme des photos sur une Page ou des commentaires sur une photo ;
  • champs : données concernant un objet, comme la date d’anniversaire d’un utilisateur ou le nom d’une Page.

Généralement, vous utilisez les nœuds pour obtenir des données sur un objet en particulier, les arêtes pour obtenir des collections d’objets sur un objet unique et les champs pour obtenir des données sur un objet unique ou sur chaque objet d’une collection.

HTTP

Puisque l’API Graph est basée sur le protocole HTTP, elle est compatible avec tous les langages qui ont une bibliothèque HTTP, comme cURL ou urllib. Cela signifie que vous pouvez utiliser l’API Graph directement dans votre navigateur. Par exemple, demander cette URL dans votre navigateur…

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

…équivaut à effectuer cette demande cURL :

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

Tokens d’accès

Vous avez probablement remarqué le paramètre access_token et la valeur de texte de remplacement dans la demande cURL ci-dessus. La plupart des requêtes de l’API Graph nécessitent un token d’accès. À terme, vous devrez apprendre comment fonctionnent les tokens d’accès en lisant notre documentation relative aux tokens d’accès. Pour l’instant, vous devez uniquement savoir ce qui suit :

  • presque toutes les requêtes de l’API Graph nécessitent un token d’accès d’une certaine nature ;
  • le moyen le plus facile d’obtenir des tokens d’accès est d’implémenter Facebook Login.

Les exemples de demande et réponse dans un code simplifié figurant dans notre documentation sur l’API Graph ne feront pas explicitement référence à un token d’accès, mais vous devez supposer qu’un token d’accès a été inclus dans la demande pour qu’une réponse ait été reçue.

Structure

Nous traitons entièrement ce sujet dans notre guide sur l’utilisation de l’API Graph. De manière générale, vous devez :

  • utiliser des nœuds pour obtenir des données sur des objets individuels ;
  • utiliser des arêtes pour obtenir des collections d’objets reliés à un nœud ou pour publier des objets dans ces collections ;
  • utiliser les champs pour préciser les données à inclure dans les réponses.

URL d’hébergement

Presque toutes les demandes sont transmises à l’URL d’hébergement graph.facebook.com. Les seules exceptions sont les importations de vidéos, qui utilisent graph-video.facebook.com.

ID d’objet

Les nœuds sont des objets individuels, chacun possédant un identifiant unique. Pour obtenir des informations sur un nœud, vous interrogez directement son identifiant. Admettons que la Page Facebook officielle comporte l’identifiant 20531316728. Vous devez l’interroger directement à l’aide de son identifiant :

GET graph.facebook.com
  /20531316728

Si vous souhaitez obtenir des données spécifiques (appelées champs) concernant un nœud, vous pouvez inclure le paramètre fields et préciser les champs que vous voulez voir dans la réponse. Une lecture rapide de la référence concernant les nœuds de Page révèle que, parmi les champs que vous pouvez obtenir lors de la lecture d’un objet de page, se trouve le champ cover, qui correspond à la photo de couverture de la Page. Voici à quoi ressemblerait cette requête :

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

La plupart des nœuds ont des arêtes, qui peuvent renvoyer des collections d’objets associés à ce nœud. Pour interroger une arête, utilisez à la fois l’identifiant du nœud et le nom de l’arête. Parmi les arêtes répertoriées dans la référence concernant les nœuds de Page, se trouve l’arête photos, qui renvoie tous les objets photo appartenant à la Page. Pour obtenir toutes les photos appartenant à la Page Facebook, vous devez interroger l’arête photos du nœud :

GET graph.facebook.com
  /20531316728/photos

Certains nœuds vous permettent de mettre à jour les champs à l’aide d’opérations POST. Par exemple, si vous êtes administrateur de la Page Facebook, vous pouvez mettre à jour son champ description comme suit :

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

Les arêtes vous permettent généralement de publier de nouveaux objets dans la collection de nœuds en effectuant des opérations POST. Voici comment publier une photo dans la collection de photos appartenant à la Page Facebook :

POST graph.facebook.com
  /20531316728/photos

La publication d’un objet dans une collection nécessite généralement des champs supplémentaires concernant cet objet, notamment l’URL de la photo, un titre ou une description. La documentation de référence sur les arêtes indique les champs requis et les champs facultatifs.

Pour finir, vous pouvez normalement supprimer un champ en effectuant l’opération DELETE sur l’identifiant de l’objet :

DELETE graph.facebook.com
  /20531316728

Versions

L’API Graph comporte plusieurs versions. Vous pouvez en apprendre davantage sur la gestion des versions dans notre guide concernant les versions d’application, mais nous allons expliquer ici comment effectuer un appel vers une version particulière.

C’est très simple : il vous suffit d’ajouter la lettre v, suivie par le numéro de la version au début du chemin de requête. Voici, par exemple, un appel à la version 2.9 :

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

Si vous n’incluez pas de numéro de version, nous choisirons par défaut la version la plus ancienne disponible. Il est donc préférable d’inclure le numéro de version dans vos demandes.

Le changelog de l’API Graph répertorie toutes les versions disponibles et nos documents de référence vous permettent de filtrer le contenu par version.

Étapes suivantes

Penchons-nous à présent sur l’utilisation de l’API Graph afin de voir quelques demandes plus élaborées et leur réponse, ainsi que les autres actions que vous pouvez effectuer à l’aide de l’API Graph.