Présentation de l’API Graph

L’API Graph est le meilleur moyen d’insérer et de récupérer des données dans la plate-forme de Facebook. Il s’agit d’une API HTTP de bas niveau qui vous permet d’avoir recours à la programmation pour interroger des données, publier de nouvelles actualités, gérer des publicités, télécharger des photos et réaliser différentes autres tâches qu’une app peut être amenée à effectuer.

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 composée des éléments suivants :

  • nœuds : représentent essentiellement des « éléments », comme un utilisateur, une photo, une Page ou un commentaire ;
  • arêtes : représentent les liens entre ces « éléments », comme les photos d’une Page ou les commentaires d’une photo ;
  • champs : informations relatives à ces « éléments », comme la date de naissance d’une personne ou le nom d’une Page.

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. Nous reviendrons plus longuement sur les tâches que vous pouvez réaliser dans la section ci-dessous. Toutefois, cela signifie que vous pouvez aussi utiliser l’API Graph directement dans votre navigateur. Par exemple, une requête de l’API Graph équivaut à :

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

La plupart des requêtes de l’API Graph requièrent des tokens d’accès, que votre app peut générer en implémentant Facebook Login.

Ce document explique comment l’API Graph peut lire et publier des données dans le graphe social.

Structure

Nous abordons en détail ce sujet dans notre guide Utilisation de l’API Graph. Toutefois, vous pouvez généralement lire des API en effectuant des requêtes HTTP GET vers des nœuds ou les arêtes de ces nœuds.

Presque toutes les requêtes sont transmises à l’API sur graph.facebook.com. La seule exception concerne les téléchargements de vidéos qui utilisent graph-video.facebook.com.

ID d’objet

Chaque nœud possède un ID unique qui vous permet d’y accéder par le biais de l’API Graph. En particulier, nous ne documentons pas la structure ou le format d’un ID de nœud/d’objet, car il est fort probable qu’ils changent au fil du temps et les apps ne doivent pas formuler d’hypothèses à partir de la structure actuelle.

Voici comment utiliser l’ID afin d’effectuer une requête pour un nœud :

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

ou une arête :

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

En général, vous pouvez publier vers des API en effectuant des requêtes HTTP POST avec des paramètres vers le nœud :

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

ou une arête :

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

Pour supprimer un élément par le biais d’une API, effectuez des requêtes HTTP DELETE (et une mise à jour au moyen de requêtes POST) vers les mêmes points de terminaison.

Versions d’API

L’API Graph possède plusieurs versions accessibles à tout moment. Chaque version contient un ensemble de champs de base et d’opérations d’arêtes. Nous garantissons que ces API de base sont disponibles et ne sont pas modifiées dans cette version pendant au moins deux ans à partir de sa publication. Le changelog de la plate-forme peut vous indiquer les versions actuellement disponibles.

Certaines opérations, comme la publication dans une arête ou certains champs d’un nœud, peuvent être des éléments de base sans que ce soit le cas de l’intégralité de l’arête ou du nœud. Nous annotons ces API de base à l’aide du symbole dans nos documents de référence sur l’API Graph.

Tout ce qui se trouve en dehors de ces API de base est appelé API étendues. Ces dernières restent accessibles par le biais de différentes versions. Toutefois, elles peuvent être modifiées ou supprimées à tout moment, en faisant l’objet de migrations sous 90 jours annoncées sur le calendrier de notre plate-forme. Dans d’autres cas, elles peuvent simplement être intégrées à la prochaine version disponible de l’API.

Vous pouvez en apprendre davantage sur l’objectif de la gestion des versions dans notre guide, mais nous allons expliquer ici comment effectuer un appel vers une version particulière de l’API Graph.

C’est très simple : il vous suffit d’ajouter préalablement l’identifiant de la version au début du chemin de requête. Par exemple, voici un appel vers la version v2.2 :

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

Cela fonctionne pour toutes les versions, sous la forme générale suivante :

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

X.Y correspond à la version nécessaire. Nous publions une liste complète des versions disponibles dans notre changelog. Tous nos documents de référence sur l’API Graph fournissent des informations sur chaque version. Assurez-vous donc d’examiner la version appropriée : certaines d’entre elles suppriment des nœuds et des arêtes, et d’autres en ajoutent.

Essayons à présent d’effectuer une requête d’API, pour vous montrer à quel point cette opération est simple.

Charger le Graph API Explorer

Pour comprendre facilement l’API Graph, il suffit de l’utiliser avec le Graph API Explorer, un outil de bas niveau qui vous permet d’interroger, d’ajouter et de supprimer des données. Il s’agit d’une ressource très pratique que vous devez avoir à portée de main lors du processus d’intégration à Facebook. La prochaine étape consiste donc à accéder au Graph API Explorer.

Graph API Explorer

Générer un token d’accès utilisateur de base

Lorsque vous commencez à créer votre propre app, vous devez connaître les tokens d’accès, ainsi que la façon de les générer à l’aide de Facebook Login. Pour le moment, nous pouvons en récupérer un très rapidement par le biais du Graph API Explorer :

  1. Cliquez sur le bouton Get Token en haut à droite de l’Explorer.
  2. Choisissez l’option Get User Access Token.
  3. Dans la boîte de dialogue suivante, ne cochez aucune case, mais cliquez simplement sur le bouton bleu Get Access Token.
  4. Une boîte de dialogue Facebook Login s’affiche. Cliquez sur OK pour continuer.

Effectuer votre première requête

Maintenant que vous êtes prêt à effectuer votre première requête de l’API Graph, nous allons commencer par une requête « read ». Dans le champ de texte situé à côté du bouton déroulant « GET » (nous l’appellerons « champ du chemin d’accès »), supprimez le texte existant et saisissez « me » :

Appuyez maintenant sur le bouton Submit. Le traitement peut prendre quelques secondes, mais un grand nombre d’informations doit à présent s’afficher dans le panneau de réponse. Les éléments qui apparaissent sont déterminés par les paramètres de confidentialité de votre profil. Cependant, il doit aussi contenir au moins quelques champs de base :

Les opérations que vous venez d’effectuer dans le Graph API Explorer équivalent à la requête « read » de l’API Graph ci-après :

GET graph.facebook.com
  /me

/me est un point de terminaison spécial qui se traduit par l’ID utilisateur de la personne dont le token d’accès est utilisé pour effectuer la requête.

Félicitations, vous venez d’effectuer votre première requête de l’API Graph !

Obtenir des autorisations de publication

Nous allons ensuite essayer de publier du contenu sur Facebook à l’aide de l’API Graph. Effectuez cette opération dans votre app uniquement lorsque vous créez votre propre éditeur personnalisé et que vous n’utilisez pas l’une des boîtes de dialogue Partager disponibles sur le web, sur iOS ou sur Android. Avec les boîtes de dialogue Partager de Facebook, vous n’êtes pas obligé(e) d’implémenter Facebook Login ou de créer votre propre interface pour autoriser le partage de contenu.

Pour explorer les fonctionnalités de publication avec l’API Graph, cliquez de nouveau sur le bouton « Get Access Token » et, cette fois-ci, choisissez l’autorisation publish_actions :

Cliquez à présent sur le bouton bleu « Get Access Token » (Obtenir le token d’accès) pour afficher de nouveau la boîte de dialogue Login. Le système demande votre autorisation pour permettre au Graph API Explorer de publier du contenu en votre nom. Si vous le souhaitez, vous pouvez modifier l’audience ici et choisir « Moi uniquement » pour que vous seul(e) puissiez consulter le contenu publié. Toutefois, vous devez accepter cette boîte de dialogue et passer à l’étape suivante.

Publier du contenu

Si vous avez demandé l’autorisation publish_actions, cliquez sur le bouton GET et choisissez POST dans le menu déroulant qui s’affiche. Saisissez me/feed dans le champ du chemin d’accès, puis cliquez sur Add a Field.

Dans les nouveaux champs qui s’affichent, indiquez message pour « name » et Hello, World pour « value ». Le résultat devrait ressembler à ceci :

Cliquez maintenant sur le bouton bleu Submit et, après quelques secondes, le panneau de réponse doit afficher le résultat suivant :

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

Cela signifie que vous venez de publier votre premier contenu par le biais de l’API Graph ! Accédez à votre profil. Vous devez pouvoir y consulter la publication :

Les opérations que vous venez d’effectuer dans le Graph API Explorer équivalent à la requête « publish » de l’API Graph ci-après :

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

Étapes suivantes

Vous venez de découvrir les bases, alors pourquoi ne pas en apprendre davantage sur l’utilisation de l’API Graph ? Si vous ne l’avez pas déjà fait, nous vous recommandons de consulter d’abord la page sur Facebook Login et, en particulier, de découvrir comment générer des tokens d’accès, car vous en aurez besoin pour effectuer des requêtes d’API Graph plus complexes.