API Graph

Présentation

L’API Graph est le meilleur moyen d’insérer et de récupérer des données dans la plateforme Facebook. Il s’agit d’une API basée sur le protocole HTTP qui permet aux apps 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.

Le nom de l’API Graph s’inspire de l’idée d’un « graphe social » : une représentation des informations sur Facebook. II est composé de nœuds, d’arêtes et de champs. 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. Dans notre documentation, nous pouvons faire référence à un nœud et à une arête comme un « point de terminaison ». Par exemple, « envoyer une demande GET au point de terminaison de l’utilisateur ».

HTTP

Tous les transferts de données sont conformes au protocole HTTP1.1 et tous les points de terminaison nécessitent le protocole HTTPS. 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"

Nous avons également activé la directive HSTS includeSubdomains sur facebook.com, mais cela ne devrait pas affecter vos appels à l’API Graph.

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.

Tokens d’accès

Les tokens d’accès permettent à votre application d’accéder à l’API Graph. Presque tous les points de terminaison de l’API Graph exigent un token d’accès d’une certaine nature. Votre demande peut donc en nécessiter un chaque fois que vous accédez à un point de terminaison. Ils remplissent généralement deux fonctions :

  • Ils permettent à votre application d’accéder aux informations d’un utilisateur sans avoir besoin du mot de passe de ce dernier ; Par exemple, votre application a besoin de l’e-mail d’un utilisateur pour exécuter une fonction. Si l’utilisateur accepte d’autoriser votre application à récupérer son adresse e-mail à partir de Facebook, il n’aura pas à saisir son mot de passe Facebook pour la récupération.
  • Ils nous permettent d’identifier votre application, son utilisateur et le type de données que celui-ci permet à votre application de consulter.

Pour en savoir plus, consultez notre documentation sur les tokens d’accès.

Nœuds

Un nœud un objet individuel avec un identifiant unique. Il existe, par exemple, de nombreux objets de type nœud d’utilisateur, chacun possédant un identifiant unique qui représente une personne sur Facebook. Pages, Groupes, Publications, Photos et Commentaires sont des exemples de nœuds du graphe social de Facebook.

L’exemple de cURL suivant est un appel vers le nœud d’utilisateur.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

Cette demande renverra les données suivantes par défaut, au format JSON :

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

Métadonnées de nœud

Vous pouvez obtenir la liste de tous les champs, y compris le nom du champ, la description et le type de données, d’un objet nœud, tel qu’un utilisateur, une page ou une photo. Envoyez une demande GET pour un ID d’objet en incluant le paramètre metadata=1 :

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

La réponse JSON contiendra la propriété metadata qui répertorie tous les champs pris en charge pour le nœud en question :

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

Le nœud /me est un point de terminaison spécial qui se transforme en ID d’objet de la personne ou la Page dont le token d’accès est utilisé pour effectuer les appels d’API. Si vous disposiez d’un token d’accès utilisateur, vous pourriez récupérer le nom et l’ID d’un utilisateur à l’aide de :

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

Arêtes

Une arête est une connexion entre deux nœuds. Par exemple, un nœud d’utilisateur peut être connecté à des photos, et un nœud de photo peut être connecté à des commentaires. L’exemple de cURL suivant renvoie une liste des photos publiées sur Facebook par une personne.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

Chaque ID renvoyé représente un nœud de photo et la date de sa publication sur Facebook.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

Champs

Les champs sont des propriétés de nœud. Lorsque vous interrogez un nœud ou une arête, il ou elle renvoie un ensemble de champs par défaut, comme le montrent les exemples ci-dessus. Toutefois, vous pouvez préciser les champs que vous voulez recevoir en utilisant le paramètre fields et en répertoriant chaque champ. Cette opération remplace les paramètres par défaut et renvoie uniquement les champs précisés, ainsi que l’identifiant de l’objet, qui est toujours renvoyé.

La demande de cURL suivante inclut le paramètre fields, ainsi que le nom, l’e-mail et la photo de profil de l’utilisateur.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

Données renvoyées

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

Paramètres complexes

La plupart des types de paramètres sont des primitives directes telles que bool, string et int, mais les types list et object peuvent aussi être indiqués dans la demande.

Le type list est indiqué dans la syntaxe JSON, par exemple : ["firstitem", "seconditem", "thirditem"]

Le type object est aussi indiqué dans la syntaxe JSON, par exemple : {"firstkey": "firstvalue", "secondKey": 123}

Publication, mise à jour et suppression

Consultez notre Guide sur le partage Facebook pour découvrir comment effectuer une publication dans le Facebook d’un utilisateur ou la documentation sur l’API Pages pour publier dans le fil Facebook d’une Page.

Certains nœuds vous permettent de mettre à jour des champs avec des opérations POST. Par exemple, vous pouvez mettre à jour votre champ email comme suit :

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

Lecture après écriture

Pour les points de terminaison de création et mise à jour, l’API Graph peut immédiatement lire un objet publié ou mis à jour et renvoyer les champs pris en charge par le point de terminaison de lecture correspondant.

Par défaut, un ID de l’objet créé ou mis à jour est renvoyé. Pour inclure d’autres informations dans la réponse, ajoutez le paramètre fields dans votre demande et spécifiez les champs à renvoyer. Par exemple, pour publier le message « Salut » sur le fil d’une Page, vous pouvez faire la demande suivante :

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
L'exemple de code ci-dessus a été formaté pour plus de lisibilité.

Cela renverra les champs spécifiés en tant que réponse au format JSON comme celle-ci :

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

Reportez-vous à la documentation de référence de chaque point de terminaison pour vérifier si elle prend en charge la lecture après l’écriture et connaître les champs disponibles.

Erreurs

En cas d’échec de la lecture pour une raison quelconque (par exemple, demander un champ qui n’existe pas), l’API Graph renvoie une réponse d’erreur standard. Pour plus d’informations, consultez notre Guide sur la gestion des erreurs.

Vous pouvez généralement supprimer un nœud, tel qu’un nœud Publication ou Photo en effectuant une opération DELETE sur l'ID de l'objet :

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

Vous ne pouvez normalement supprimer que les nœuds que vous avez créés. Consultez toutefois les conditions requises pour les opérations de suppression dans le guide de référence de chaque nœud.

Webhooks

Vous pouvez être notifié·e des changements apportés aux nœuds ou des interactions avec les nœuds en vous abonnant à des webhooks. Consultez Webhooks.

Versions

L’API Graph est disponible dans plusieurs versions avec des sorties trimestrielles. Vous pouvez spécifier la version dans vos appels en ajoutant « v » et le numéro de version au début du chemin de la demande. Par exemple, voici un appel vers la version 4.0 :

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

Si vous n'incluez pas de numéro de version, nous choisirons par défaut la version la plus ancienne disponible. Il est donc recommandé d'en inclure un dans vos demandes.

Pour en savoir plus sur les versions, consultez notre Guide sur la gestion des versions et découvrez toutes les versions disponibles dans le Changelog de l’API Graph.

API, SDK et plates-formes Facebook

Connectez des interfaces et développez sur plusieurs plates-formes à l'aide des différentes API, SDK et plates-formes Facebook.

Étapes suivantes

Premiers pas avec l'API Graph : partons à la découverte du graphe social de Facebook grâce à l’Explorateur de l’API Graph et profitons-en pour exécuter quelques requêtes afin d’obtenir des données.