Utilisation de l’API Graph

Nous abordons les notions de base de la terminologie et de la structure de l’API Graph dans la présentation de l’API Graph. Ce document aborde plus en détail les différentes opérations que vous pouvez effectuer à l’aide de l’API Graph.

HTTP/1.1

Tous les transferts de données sont conformes au protocole HTTP1.1 et tous les points de terminaison nécessitent le protocole HTTPS. 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. 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 cet utilisateur ;
  • ils nous permettent d’identifier votre application, l’utilisateur qui utilise votre application et le type de données que l’utilisateur permet à votre application de consulter.

Tous les points de terminaison de l’API Graph nécessitent un token d’accès quel qu’il soit. Chaque fois que vous accédez à un point de terminaison, votre demande doit donc en contenir un.

Fonctionnement des tokens

Les tokens d’accès sont conformes au protocole OAuth 2.0. OAuth 2.0 permet à des entités telles qu’un utilisateur ou une page d’autoriser les tokens. Pour ce faire, une interface web est généralement utilisée. Une fois ces tokens autorisés, les applications peuvent les utiliser pour accéder à des informations particulières.

Par exemple, cette application demande à un utilisateur de l’autoriser à accéder à ses photos, ses vidéos et son adresse e-mail :

Comme vous pouvez le voir, il s’agit d’une interface Facebook. L’utilisateur a simplement utilisé l’interface pour se connecter à son compte, ce qui nous a permis de l’authentifier. Si l’utilisateur continue, nous remplacerons l’ancien token (un token d’application) par un nouveau (un token d’utilisateur). L’application peut ensuite utiliser le nouveau token d’utilisateur pour effectuer des demandes à l’API Graph, mais peut uniquement accéder aux photos, aux vidéos et à l’adresse e-mail de cet utilisateur en particulier.

Il s’agit d’un attribut important des tokens d’accès. L’app et les ID utilisateur sont encodés dans le token même (entre autres) et nous utilisons ces ID pour suivre les données dont l’utilisateur a autorisé l’accès. Par exemple, si vous avez inspecté le token après que l’utilisateur a accordé son autorisation, les informations suivantes seront disponibles :

Étant donné que les tokens autorisent l’accès aux données d’un utilisateur, et puisqu’ils peuvent être utilisés par n’importe qui, ils sont extrêmement précieux. Vous devez donc prendre des précautions lorsque vous les utilisez dans vos demandes. Le meilleur moyen est d’utiliser Facebook Login pour gérer vos tokens.

Facebook Login

OAuth 2.0 implique un grand nombre redirections, d’invitations à se connecter et d’échanges de token. Pour vous faciliter les choses, nous avons donc créé le produit Facebook Login. Facebook Login comporte des fonctions et des méthodes faciles à utiliser pour l’ensemble de vos SDK qui peuvent rendre le travail avec les tokens d’accès beaucoup plus facile qu’en créant votre propre solution.

Pour en savoir plus sur les tokens d’accès et Facebook Login, ou pour savoir comment créer votre propre solution, consultez notre documentation concernant Facebook Login.

Lecture

Nœuds

Les opérations de lecture commencent presque toujours par un nœud. Un nœud un objet individuel avec un identifiant unique. Par exemple, il existe de nombreux objets de type nœud de Page, chacun possédant un identifiant unique. La Page Coca-Cola est la seule qui possède l’identifiant 820882001277849. Pour lire un nœud, vous devez interroger l’identifiant d’un objet spécifique. Donc pour lire le nœud de la Page Coca-Cola, vous devez interroger son identifiant :

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

La demande renverra les champs suivants (propriétés du nœud) par défaut, au format JSON :

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

Arêtes

Les nœuds possèdent des arêtes, qui peuvent généralement renvoyer des collections d’autres nœuds qui y sont associés. Pour lire une arête, vous devez inclure à la fois l’identifiant du nœud et le nom de l’arête dans le chemin d’accès. Par exemple, les nœuds /page comportent une arête /feed qui peut renvoyer tous les nœuds de publications d’une Page. Voici comment utiliser l’arête pour obtenir toutes les publications de la Page Coca-Cola :

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

La réponse JSON ressemblera à ceci :

{
  "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"
    }
  ]
}

Vous remarquerez que la réponse contient non seulement les identifiants des nœuds de publication de la collection, mais également les champs created_time et message. Ce phénomène est fréquent. La plupart des arêtes contiendront un ou plusieurs champs par défaut.

Champs

Les champs sont des propriétés de nœud. Lorsque vous interrogez un nœud, il 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. Cela remplacera les paramètres par défaut et renverra uniquement les champs précisés, ainsi que l’identifiant de l’objet, qui est toujours renvoyé.

Par exemple, la référence concernant les nœuds de Page indique les champs que vous pouvez demander lors de la lecture d’un nœud de Page. Si vous voulez obtenir les champs about, fan_count et website pour la Page Coca-Cola, vous pouvez procéder comme suit :

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

La réponse suivante sera renvoyée :

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

Les arêtes, qui renvoient généralement des collections d’objets, renvoient également les champs concernant chaque objet de la collection. Admettons que vous avez utilisé l’arête /photos pour obtenir tous les nœuds de photo présents sur la Page Coca-Cola :

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

Une réponse similaire à ce qui suit sera générée :

{
  "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"
    }
  ]
}

Comme vous pouvez le voir, l’arête /photos renvoie par défaut une collection d’identifiants de nœud de photo, ainsi que la propriété created_time pour chaque photo. Tout comme avec les nœuds, vous pouvez utiliser le paramètre fields pour préciser les champs que vous voulez recevoir pour chacun des objets renvoyés dans la collection.

Admettons que vous voulez obtenir les champs height, width et link (URL) pour chaque nœud de photo renvoyé par l’arête /photos :

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

La réponse devrait ressembler à ceci :

{
  "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"
    }
  ]
}

Veuillez noter que vous pouvez également préciser une arête à l’aide du paramètre fields, ce qui s’avère utile lorsque vous utilisez l’élargissement de champ.

Élargissement de champ

Si jamais vous testez la demande GET /page/photos ci-dessus dans l’Explorateur de l’API Graph, vous remarquerez probablement que la demande renvoie plus de trois objets et effectue une pagination des résultats. Ce phénomène est fréquent pour la plupart des arêtes. Nous discuterons prochainement du défilement des résultats, mais pour le moment, intéressons-nous à l’élargissement de champ, qui vous permet non seulement d’effectuer des demandes imbriquées, mais également de limiter et trier les résultats.

Limitation de résultats

La limitation vous permet de contrôler le nombre d’objets renvoyés dans chaque ensemble de résultats paginés. Pour limiter les résultats, ajoutez un argument .limit() à chaque champ ou arête.

Par exemple, effectuer une demande GET sur l’arête /feed de la Page Coca-Cola peut renvoyer des centaines de publications. Vous pouvez limiter le nombre de publications renvoyées pour chaque page de résultats de la manière suivante :

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

Toutes les publications de la Page Coca-Cola sont renvoyées, mais le nombre d’objets sur chaque page de résultat est limité à trois. Vous remarquerez qu’au lieu de préciser l’arête de flux dans l’URL du chemin d’accès (/page/feed), vous la précisez dans le paramètre fields (?fields=feed), ce qui vous permet d’ajouter l’argument .limit(3).

Voici les résultats de la demande :

{
  "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"
}

Comme vous pouvez le voir, seuls trois objets apparaissent sur cette page de résultats paginés, mais la réponse comprend un champ next et une URL que vous pouvez utiliser pour récupérer la page suivante.

Tri des résultats

Vous pouvez trier les résultats en fonction de l’heure de création des objets. Pour ce faire, utilisez un argument .order() avec l’une des valeurs suivantes sur un champ ou une arête.

  • chronological — trie les résultats en positionnant les objets les plus anciens en premier.
  • reverse_chronological — trie les résultats en positionnant les objets les plus récents en premier.

Par exemple, obtenons tous les commentaires sur l’une des publications vidéo de la Page Coca-Cola (1809938745705498), trions les résultats par ordre chronologique (les plus anciens en premier) et limitons le nombre d’objets par résultat paginé à trois :

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

De nouveau, vous remarquerez que pour pouvoir utiliser un argument sur une arête, vous devez préciser cette arête dans le paramètre fields. Et, comme vous pouvez le voir, vous pouvez combiner les arguments .limit() et .order() sur un champ ou une arête unique.

En voici les résultats :

{
  "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"
}

Publication

La plupart des arêtes vous permettent de publier des objets dans une collection sur un nœud. Pour ce faire, utilisez une demande POST sur l’arête du nœud. Par exemple, vous pouvez publier un commentaire sur une photo en utilisant l’arête /comments du nœud de photo :

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

Si l’opération réussit, la plupart des arêtes renverront l’identifiant de l’objet que vous venez de publier, qui correspond souvent à une combinaison de l’identifiant sur lequel l’objet a été publié et d’une nouvelle chaîne d’identifiant.

{
  "id": "1809938745705498_1810399758992730"
}

La publication nécessite généralement des autorisations supplémentaires, vous devez donc consulter la documentation de référence de chaque arête pour déterminer les autorisations requises.

Le token d’accès utilisé pour publier l’objet peut affecter l’apparence de cet objet. Si un token d’accès de Page est utilisé, cela donnera l’impression que la Page a publié l’objet, tandis qu’un token d’accès d’utilisateur donnera l’impression d’objet publié par une personne.

De nombreuses arêtes prennent également en charge des fonctionnalités avancées, notamment la lecture après écriture, qui vous permet de lire immédiatement un nouvel objet publié, et la publication groupée, qui vous permet d’associer plusieurs opérations de publication.

Mise à jour

Vous pouvez effectuer des opérations de mise à jour sur un nœud existant à l’aide de demandes POST. Par exemple, pour mettre à jour le champ message sur un commentaire existant, procédez comme suit :

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

En cas de réussite, le nœud renvoie un champ success et une valeur de true :

{
  "success": true
}

Tout comme les opérations de publication, les opérations de mise à jour nécessitent des autorisations supplémentaires répertoriées dans la documentation de référence de chaque nœud. Comme la plupart des arêtes, beaucoup de nœuds prennent en charge la lecture après écriture.

Suppression

Vous pouvez généralement supprimer un nœud à l’aide d’une opération DELETE :

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

En cas de réussite, le nœud renvoie un champ success et une valeur de true :

{
  "success": true
}

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.

Pour prendre en charge les clients non compatibles avec toutes les méthodes HTTP, vous pouvez envoyer une demande POST au nœud et inclure le paramètre method=delete et la valeur pour remplacer la méthode HTTP :

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

Défilement des résultats paginés

Lorsque vous adressez une requête d’API à un nœud ou à une arête, vous ne recevez généralement pas tous les résultats de cette requête dans une seule réponse. Cela est dû au fait que certaines réponses peuvent contenir des milliers d’objets. La plupart des réponses sont donc paginées par défaut.

Pagination en fonction de curseurs

La pagination en fonction de curseurs est la méthode de pagination la plus efficace et devrait toujours être utilisée, si possible. Un curseur fait référence à une chaîne de caractères aléatoire qui marque un élément particulier dans une liste de données. À moins que cet élément soit supprimé, le curseur désignera toujours la même partie de la liste, mais ne sera plus valide si un élément est supprimé. Votre application ne doit donc pas stocker de curseurs et partir du principe qu’ils resteront valides à l’avenir.

Lors de la lecture d’une arête qui prend en charge la pagination avec curseurs, vous pouvez voir la réponse JSON suivante :

{
  "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="
  }
}

Une arête paginée à l’aide de curseurs prend en charge les paramètres suivants :

  • before : il s’agit du curseur qui désigne le début de la page de données renvoyée.
  • after : il s’agit du curseur qui désigne la fin de la page de données renvoyée.
  • limit : il s’agit du nombre maximum d’objets pouvant être renvoyés. Une requête peut renvoyer moins d’objets que la valeur limit en raison d’un filtrage. Si le nombre de résultats est inférieur à la valeur limit, utilisez plutôt l’absence de next comme décrit ci-dessous, pour indiquer que votre requête a atteint la fin de la liste de données. Par exemple, si vous définissez une limit sur 10 et 9 résultats sont renvoyés, d’autres données peuvent être disponibles, mais un élément a été supprimé en raison d’un filtre de confidentialité. Certaines arêtes peuvent aussi comporter une limite maximale pour la valeur limit pour des raisons de performance. Dans tous les cas, l’API renvoie les liens de pagination corrects.
  • next : le point de terminaison de l’API Graph qui renvoie la page de données suivante. S’il n’est pas inclus, il s’agit de la dernière page de données. Étant donné le fonctionnement de la pagination en termes de visibilité et de confidentialité, il est possible qu’une page soit vide, mais contienne un lien de pagination permettant de passer à la suivante. Vous devez cesser la pagination lorsque ce lien n’apparaît plus.
  • previous : le point de terminaison de l’API Graph qui renvoie la page de données précédente. S’il n’est pas inclus, il s’agit de la première page de données.

Ne stockez pas de curseurs. Les curseurs peuvent rapidement ne plus être valides si des éléments sont ajoutés ou supprimés.

Pagination en fonction du temps

La pagination en fonction du temps est utilisée pour parcourir les résultats de données à l’aide d’horodatages Unix qui désignent des heures particulières dans une liste de données.

Lorsque vous utilisez un point de terminaison qui a recours à une pagination en fonction du temps, vous pouvez voir la réponse JSON suivante :

{
  "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"
  }
}

Une arête paginée en fonction du temps prend en charge les paramètres suivants :

  • until : un timestamp Unix ou une valeur de données strtotime qui désigne la fin de la plage de données temporelles.
  • since : un timestamp Unix ou une valeur de données strtotime qui désigne le début de la plage de données temporelles.
  • limit : il s’agit du nombre maximum d’objets pouvant être renvoyés. Une requête peut renvoyer moins d’objets que la valeur limit en raison d’un filtrage. Si le nombre de résultats est inférieur à la valeur limit, utilisez plutôt l’absence de next comme décrit ci-dessous, pour indiquer que votre requête a atteint la fin de la liste de données. Par exemple, si vous définissez une limit sur 10 et 9 résultats sont renvoyés, d’autres données peuvent être disponibles, mais un élément a été supprimé en raison d’un filtre de confidentialité. Certaines arêtes peuvent aussi comporter une limite maximale pour la valeur limit pour des raisons de performance. Dans tous les cas, l’API renvoie les liens de pagination corrects.
  • next : le point de terminaison de l’API Graph qui renvoie la page de données suivante.
  • previous : le point de terminaison de l’API Graph qui renvoie la page de données précédente.

Pour obtenir des résultats cohérents, indiquez les deux paramètres since et until. De plus, nous vous recommandons que la différence soit de 6 mois au maximum.

Pagination en fonction de repères

La pagination en fonction de repères peut être utilisée lorsque la chronologie vous importe peu et que vous souhaitez simplement qu’un nombre d’objets précis vous soit renvoyé. Elle doit être utilisée uniquement si l’arête ne prend pas en charge la pagination en fonction de curseurs ou du temps.

Une arête paginée en fonction de repères prend en charge les paramètres suivants :

  • offset : ce repère indique le début de chaque page en fonction du nombre indiqué.
  • limit : il s’agit du nombre maximum d’objets pouvant être renvoyés. Une requête peut renvoyer moins d’objets que la valeur limit en raison d’un filtrage. Si le nombre de résultats est inférieur à la valeur limit, utilisez plutôt l’absence de next comme décrit ci-dessous, pour indiquer que votre requête a atteint la fin de la liste de données. Par exemple, si vous définissez une limit sur 10 et 9 résultats sont renvoyés, d’autres données peuvent être disponibles, mais un élément a été supprimé en raison d’un filtre de confidentialité. Certaines arêtes peuvent aussi comporter une limite maximale pour la valeur limit pour des raisons de performance. Dans tous les cas, l’API renvoie les liens de pagination corrects.
  • next : le point de terminaison de l’API Graph qui renvoie la page de données suivante. S’il n’est pas inclus, il s’agit de la dernière page de données. Étant donné le fonctionnement de la pagination en termes de visibilité et de confidentialité, il est possible qu’une page soit vide, mais contienne un lien de pagination permettant de passer à la suivante. Vous devez cesser la pagination lorsque ce lien n’apparaît plus.
  • previous : le point de terminaison de l’API Graph qui renvoie la page de données précédente. S’il n’est pas inclus, il s’agit de la première page de données.

Notez que si de nouveaux objets sont ajoutés à la liste d’éléments paginés, le contenu de chaque page basée sur des repères sera modifié.

La pagination en fonction de repères n’est pas prise en charge pour tous les appels d’API. Pour obtenir des résultats constants, nous vous recommandons d’effectuer une pagination à l’aide des liens précédent/suivant que nous renvoyons dans la réponse.