Utilisation de l’API Graph

L’API Graph est le principal moyen de récupérer des données du graphe social de Facebook et d’en ajouter. Il s’agit d’une API HTTP de bas niveau utilisée pour interroger des données, publier de nouvelles actualités, importer des photos et réaliser différentes autres tâches qu’une app peut être amenée à effectuer. Ce guide explique comment y parvenir dans l’API Graph.

Notions de base

Nous abordons les notions de base de la terminologie et de la structure de l’API Graph dans notre présentation de l’API Graph. Les sections suivantes détaillent les différentes opérations qui peuvent être réalisées à l’aide de l’API.

Lecture

Tous les nœuds et les arêtes de l’API Graph peuvent être lus simplement à l’aide d’une requête HTTP GET adressée au point de terminaison adéquat. Par exemple, si vous souhaitez récupérer des informations sur l’utilisateur actuel, vous devez effectuer une requête HTTP GET de ce type :

GET /v2.5/me HTTP/1.1
Host: graph.facebook.com

La plupart des appels d’API doivent être signés au moyen d’un token d’accès. Vous pouvez déterminer les autorisations nécessaires dans ce token d’accès en consultant la référence concernant l’API Graph qui correspond au nœud ou à l’arête que vous voulez lire. Vous pouvez également utiliser le Graph API Explorer afin de générer rapidement des tokens pour expérimenter l’API et découvrir son fonctionnement.

Le nœud /me est un point de terminaison spécial qui se traduit par le user_id de la personne (ou le page_id de la Page Facebook) dont le token d’accès est utilisé pour effectuer les appels d’API. Si vous aviez un token d’accès utilisateur, vous pourriez récupérer toutes les photos d’un utilisateur à l’aide de :

GET graph.facebook.com
  /me/photos

La réponse que vous recevez dépend du nœud ou de l’arête que vous lisez, mais prend la forme générale suivante :

{
   "fieldname": {field-value},
   ....
}

Choix des champs

Par défaut, tous les champs d’un nœud ou d’une arête ne sont pas renvoyés lorsque vous effectuez une requête. Vous pouvez choisir les champs ou les arêtes que vous voulez recevoir à l’aide du paramètre de requête fields. Cela contribue fortement à l’efficacité et à la rapidité de vos appels d’API.

Par exemple, l’appel d’API Graph suivant https://graph.facebook.com/me?fields=id,name,picture en utilisant votre propre token d’accès d’utilisateur ne renverra que l’identifiant, le nom et l’image figurant sur votre profil :

GET graph.facebook.com/me?fields=id,name,picture

Tri

Vous pouvez trier certains ensembles de données par ordre chronologique. Par exemple, vous pouvez trier les commentaires d’une photo dans l’ordre chronologique inverse à l’aide de la clé reverse_chronological :

GET graph.facebook.com
  /{photo-id}?
    fields=comments.order(reverse_chronological)

order doit correspondre à l’une des valeurs suivantes :

  • chronological
  • reverse_chronological

Recherche d’URL

La plupart des objets peuvent être découverts à l’aide de leur identifiant, mais il arrive que ce ne soit pas possible et qu’une URL soit tout ce dont vous disposiez pour identifier quelque chose.

Vous pouvez utiliser le nœud d’URL qui a été ajouté à la version 2.1 pour renvoyer les identifiants d’URL d’objets Open Graph ou pour trouver des données associées à une URL App Link.

Pour en savoir plus sur la recherche de données App Link, consultez l’API Index dans notre documentation pour App Links.

Modification des requêtes d’API

Certains points de terminaison d’API peuvent être utilisés avec des paramètres supplémentaires qui modifient la requête. La nature de l’effet de ces modificateurs varie, nous avons donc documenté chacun d’entre eux séparément dans les documents de référence concernant l’API, le cas échéant. Vous trouverez ci-dessous une liste des modificateurs qui peuvent être utilisés avec la plupart des points de terminaison.

Nom Description Type

return_ssl_resources

Utilisé lorsque vous demandez qu’une photo soit renvoyée au moyen d’une connexion sécurisée (HTTPS) pour éviter des avertissements de contenu mixte dans les navigateurs.

bool

locale

Utilisé si votre application nécessite la capacité à récupérer du contenu localisé dans la langue correspondant à un paramètre régional particulier (si disponible).

Locale

D’autres modificateurs relatifs à la pagination et à l’introspection figurent ci-dessous.

Envoi de requêtes imbriquées

La fonctionnalité d’élargissement des champs de l’API Graph vous permet d’imbriquer efficacement plusieurs requêtes du graphe dans un seul appel. Certaines ressources, notamment la majorité des API Ads, ne peuvent pas utiliser l’élargissement de champs sur certaines voire toutes les connexions.

Par exemple, vous pouvez demander les N premières photos des K premiers albums dans un seul appel. La réponse conserve la hiérarchie des données afin que les développeurs ne soient pas obligés de réunir les données sur le client.

Il s’agit d’une fonctionnalité différente des requêtes par lot qui vous permet d’effectuer plusieurs appels de l’API Graph, potentiellement sans rapport, dans une seule requête.

Le format de l’élargissement de champs est généralement le suivant :

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

<first-level>, dans ce cas, serait un ou plusieurs champs ou arêtes (séparés par des virgules) du nœud parent. <second-level> serait un ou plusieurs champs ou arêtes (séparés par des virgules) du nœud de premier niveau.

Aucune limite ne s’applique ici à la quantité d’imbrication de niveaux possible. Vous pouvez également utiliser un argument .limit(n) pour chaque champ ou arête pour limiter le nombre d’objets que vous voulez obtenir.

Puisqu’il est plus facile de comprendre grâce à un cas pratique, voici un exemple de requête qui récupérera jusqu’à cinq albums créés par une personne, ainsi que les cinq dernières publications de son fil.

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

Nous pouvons ensuite élargir davantage cette requête et, pour chaque objet d’album, récupérer également les deux premières photos et les personnes identifiées dans chacune d’entre elles :

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

Nous pouvons ensuite l’élargir à nouveau en récupérant l’intitulé de chaque photo, l’URL de l’image et les personnes identifiées :

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

Voyons un exemple utilisant la pagination en fonction de curseurs :

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

Vous constatez que l’élargissement de champs peut fonctionner sur l’ensemble des nœuds, des arêtes et des champs pour renvoyer des données vraiment complexes dans une seule requête.

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 maximal d’objets qui peuvent ê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 limit sur 20, 20 objets seront trouvés, mais seuls 9 seront affichés en raison d’un filtre de confidentialité. Si vous réinitialisez la limit sur 40, 40 objets seront trouvés, mais, encore une fois, seuls 12 résultats seront renvoyés en raison d’un filtre de confidentialité. Si votre recherche ne renvoie aucun résultat, aucune pagination ni indication n’indiquera que plus d’éléments sont disponibles. Cependant, il peut y avoir plus d’éléments si vous augmentez la limit. Certaines arêtes peuvent aussi comporter une limite maximale pour la valeur limit pour des raisons de performance.
  • 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 horodatage Unix ou une valeur de données strtotime qui désigne la fin de la plage de données temporelles.
  • since : un horodatage 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.

Envoi de requêtes volumineuses

Certains points de terminaison de l’API Graph peuvent inclure des paramètres très volumineux. Si vos requêtes finissent par dépasser plusieurs milliers de caractères, il est possible que des erreurs de serveur s’affichent, car nos serveurs refusent les requêtes GET très volumineuses.

Pour les requêtes volumineuses, nous recommandons d’effectuer une requête POST plutôt qu’une requêteGET et d’ajouter un paramètre method=GET. Si vous suivez cette recommandation, la requête POST sera interprétée comme une requête GET.

Envoi de plusieurs requêtes

La version standard de l’API Graph est conçue pour obtenir des données concernant un objet isolé et parcourir les connexions entre les objets facilement. Elle inclut également une capacité limitée à récupérer des données concernant un petit nombre d’objets en même temps.

Si votre application nécessite la capacité à accéder à une quantité considérable de données en même temps ou si vous devez effectuer des modifications sur plusieurs objets à la fois, il est souvent plus efficace de grouper vos requêtes que d’envoyer plusieurs requêtes HTTP séparément.

Pour ce faire, l’API Graph prend en charge un certain nombre de fonctions, notamment la recherche de plusieurs identifiants et les requêtes par lot. Les requêtes par lot sont expliquées dans un guide distinct. Vous pouvez toutefois en savoir plus sur les identifiants multiples ci-dessus.

Requêtes de lecture de plusieurs identifiants

Vous pouvez effectuer une requête GET unique qui récupère plusieurs nœuds en utilisant le point de terminaison ?ids avec les identifiants d’objet de ces nœuds. Par exemple, pour rechercher la page pour les développeurs Facebook et l’utilisateur de la session actuelle dans une seule requête, vous pouvez utiliser l’appel d’API Graph suivant :

GET graph.facebook.com
  /?ids=platform,me

Ce qui équivaut aux requêtes d’API individuelles suivantes :

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

Les données renvoyées auront alors l’aspect suivant :

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

Cette opération peut également fonctionner avec les arêtes tant que tous les identifiants demandés comportent l’arête demandée. Par exemple :

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

Ce qui équivaut aux requêtes d’API individuelles suivantes :

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

Les données renvoyées auront alors l’aspect suivant :

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

Notez que même si le filtrage de champs, l’élargissement de champs et la limitation sont compatibles avec ces recherches d’identifiants multiples, une erreur sera générée si l’un des objets ne comporte pas l’un des champs demandés. Par exemple, si vous recherchez une Page et un utilisateur à l’aide de cette méthode, puis ajoutez le filtre fields=id,picture,gender, la requête échouera, car les Pages ne comportent pas de champ gender.

Introspection

L’API Graph prend en charge l’introspection de nœuds. Cela vous permet de voir toutes les arêtes d’un nœud sans connaître son type à l’avance. Pour obtenir cette information, ajoutez metadata=1 à la requête d’API Graph :

GET graph.facebook.com
  /{node-id}?
    metadata=1

Le JSON qui en résultera contiendra une propriété metadata qui répertorie toutes les arêtes prises en charge pour le nœud en question :

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

Publication

La plupart des nœuds de l’API Graph ont des arêtes sur lesquelles il est possible de publier, comme /{user-id}/feed ou /{album-id}/photos. Toutes les publications de l’API Graph sont effectuées au moyen d’une requête HTTP POST vers l’arête pertinente en incluant tous les paramètres nécessaires. Par exemple, pour mettre en ligne une publication au nom de quelqu’un, vous devez effectuer une requête HTTP POST de ce type :

POST graph.facebook.com
  /{user-id}/feed?
    message={message}&
    access_token={access-token}

Tous les appels de publication doivent être signés au moyen d’un token d’accès. Vous pouvez déterminer les autorisations nécessaires dans ce token d’accès en consultant la référence concernant l’API Graph qui correspond au nœud sur lequel vous voulez publier.

Il existe un grand nombre d’arêtes sur lesquelles il est possible de publier. Les détails sont disponibles dans le document de référence pour chaque nœud.

Le guide Scénarios courants pour l’utilisation de l’API Graph contient des informations supplémentaires concernant quelques scénarios courants pour la publication.

Envoi de plusieurs requêtes

Vous pouvez associer des appels de publication et des appels de lecture grâce aux requêtes par lot. Pour en savoir plus, consultez la section Envoi de plusieurs requêtes d’API.

Lecture après écriture

Plusieurs arêtes prennent en charge la lecture après l’écriture 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.

Mise à jour

Toutes les mises à jour de l’API Graph sont effectuées au moyen d’une requête HTTP POST vers le nœud pertinent en incluant tous les paramètres mis à jour, y compris :

POST graph.facebook.com
  /{node-id}?
    {updated-field}={new-value}&
    access_token={access-token}

Tous les appels de mise à jour doivent être signés à l’aide d’un token d’accès ayant les mêmes autorisations nécessaires pour la publication vers ce point de terminaison, conformément à la référence concernant l’API Graph du nœud que vous voulez mettre à jour.

Lecture après écriture

Plusieurs arêtes prennent en charge la lecture après l’écriture 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.

Suppression

Supprimez des nœuds du graphe en leur adressant des requêtes HTTP DELETE :

DELETE graph.facebook.com
  /{node-id}?
    access_token=...

En règle générale, une app peut uniquement supprimer du contenu qu’elle a créé. Pour en savoir plus, consultez le guide de référence sur le nœud ou l’arête.

Pour prendre en charge des clients non compatibles avec toutes les méthodes HTTP, vous pouvez également adresser une requête POSTà un point de terminaison avec l’argument supplémentaire method=delete pour passer outre la méthode HTTP. Par exemple, vous pouvez supprimer un commentaire en émettant la requête suivante :

POST graph.facebook.com
  /{comment-id}?
    method=delete

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.

Pour utiliser cette fonctionnalité, ajoutez un paramètre fields dans votre demande et répertoriez les champs à renvoyer. Par exemple, pour publier le message « Salut » dans le fil d’un utilisateur, vous pouvez faire la demande suivante :

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

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": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

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

Si la lecture échoue pour une raison quelconque (par exemple, la demande d’un champ non existant), l’API Graph enverra une réponse d’erreur standard. De plus, la réponse comprendra une propriété original_response dont la valeur sera équivalente à celle renvoyée par le point de terminaison en cas de succès.

Par exemple, cette demande contient un champ non valide :

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

La réponse serait alors :

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

Vous pouvez faire une recherche sur de nombreux objets publics dans le graphe social à l’aide du point de terminaison /search. La syntaxe de la recherche est la suivante :

GET graph.facebook.com
  /search?
    q={your-query}&
    type={object-type}

Toutes les requêtes de recherche de l’API Graph nécessitent qu’un token d’accès soit inclus dans la requête. Un token d’accès utilisateur est requis pour pouvoir effectuer une recherche.

Types de recherche disponibles

Nous prenons en charge la recherche des types suivants :

Type Description Valeur « q »

user

Recherche d’une personne (si elle autorise la recherche de son nom).

Nom

page

Recherche d’une Page.

Nom

event

Recherche d’un évènement.

Nom

group

Recherche d’un groupe.

Nom

place

Recherche d’un lieu. Vous pouvez affiner votre recherche selon un endroit ou une distance spécifique en ajoutant le paramètre center (avec une latitude et une longitude), ainsi qu’un paramètre distance facultatif (en mètres).

Nom

placetopic

Renvoie une liste de sujets de Page sur des lieux possibles et de leurs identifiants. Utilisez le paramètre topic_filter=all pour obtenir la liste complète.

Aucune

ad_*

Une collection de différentes options de recherche qui peuvent être utilisées pour trouver des options de ciblage.

Consultez les options de ciblage

Exemple :

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

Gestion des erreurs

Les requêtes envoyées à nos API peuvent générer un certain nombre de réponses différentes avec des erreurs. La rubrique suivante décrit les tactiques de récupération et fournit une liste de valeurs d’erreur en les associant à la tactique de récupération la plus couramment utilisée.

Réception de codes d’erreur

Ce qui suit représente une réponse avec erreur courante résultant d’une requête d’API qui a échoué :

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}
  • message : une description humainement lisible de l’erreur.
  • code : un code d’erreur. Les valeurs courantes sont répertoriées ci-dessous, ainsi que les tactiques de récupération courantes.
  • error_subcode : des informations supplémentaires sur l’erreur. Les valeurs courantes sont répertoriées ci-dessous.
  • error_user_msg : le message à montrer à l’utilisateur. La langue du message est basée sur le paramètre régional de la requête d’API.
  • error_user_title : le titre de la boîte de dialogue, s’il est affiché. La langue du message est basée sur le paramètre régional de la requête d’API.
  • fbtrace_id : l’identifiant de prise en charge interne. Lors du signalement d’un bug lié à un appel de l’API Graph, incluez fbtrace_id pour nous aider à trouver les données de journal à des fins de débogage.

Codes d’erreur

Code ou type Nom Ce qu’il faut faire

OAuthException

Si aucun sous-code n’est présent, cela signifie que la connexion ou le token d’accès a expiré, a été annulé(e) ou n’est pas valide. Obtenez un nouveau token d’accès.

Si un sous-code est présent, affichez-le.

102

Session de l’API

Si aucun sous-code n’est présent, cela signifie que la connexion ou le token d’accès a expiré, a été annulé(e) ou n’est pas valide. Obtenez un nouveau token d’accès.

Si un sous-code est présent, affichez-le.

1

API inconnue

Peut-être un problème temporaire dû à un temps d’arrêt. Attendez et retentez l’opération. Si cela se reproduit, vérifiez que vous interrogez une API existante.

2

Service d’API

Problème temporaire dû à un temps d’arrêt. Attendez et retentez l’opération.

4

Trop d’appels d’API

Problème temporaire dû à une régulation. Attendez et retentez l’opération, ou examinez votre volume de requêtes d’API.

17

Trop d’appels d’API par l’utilisateur

Problème temporaire dû à une régulation. Attendez et retentez l’opération, ou examinez votre volume de requêtes d’API.

10

Autorisation de l’API refusée

L’autorisation n’a pas été accordée ou a été supprimée. Gérez les autorisations manquantes.

190

Le token d’accès a expiré

Obtenez un nouveau token d’accès.

200-299

Autorisation de l’API (plusieurs valeurs en fonction de l’autorisation)

L’autorisation n’a pas été accordée ou a été supprimée. Gérez les autorisations manquantes.

341

Nombre maximum de requêtes atteint

Problème temporaire dû à un temps d’arrêt ou à une régulation. Attendez et retentez l’opération, ou examinez votre volume de requêtes d’API.

368

Bloqué temporairement pour des violations de règles

Attendez et retentez l’opération.

506

Double publication

Les publications en double ne peuvent pas être publiées consécutivement. Modifiez le contenu de la publication et réessayez.

1609005

Erreur de publication du lien

Un problème s’est produit lors de la récupération des données du lien indiqué. Vérifiez l’adresse URL et réessayez.

Sous-codes d’erreur d’authentification

Code Nom Ce qu’il faut faire

458

Application non installée

L’utilisateur n’est pas connecté à votre application. Authentifiez l’utilisateur à nouveau.

459

Utilisateur soumis à un point de contrôle

L’utilisateur doit se connecter à l’adresse https://www.facebook.com ou à l’adresse https://m.facebook.com pour corriger un problème.

460

Mot de passe modifié

Sur iOS 6 et les versions ultérieures, si la personne s’est connectée à l’aide du flux intégré au système d’exploitation, elle doit être redirigée vers les paramètres du système d’exploitation Facebook sur l’appareil pour mettre à jour son mot de passe. Sinon, elle doit se reconnecter à l’application.

463

Expiré

L’état de la connexion ou le token d’accès a expiré, a été annulé ou n’est pas valide. Gérez les tokens d’accès expirés.

464

Utilisateur non confirmé

L’utilisateur doit se connecter à l’adresse https://www.facebook.com ou à l’adresse https://m.facebook.com pour corriger un problème.

467

Token d’accès non valide

Le token d’accès a expiré, a été annulé ou n’est pas valide. Gérez les tokens d’accès expirés.

Paramètre complexes

La plupart des types de paramètres sont des primitives directes telles que 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}

Débogage des requêtes d’API

Mode débogage de l’API Graph

Lorsque le mode débogage est activé, la réponse de l’API Graph peut contenir des champs supplémentaires qui expliquent les problèmes possibles de la requête.

Pour activer le mode débogage, utilisez le paramètre de chaîne d’interrogation debug. Par exemple :

GET graph.facebook.com
  /v2.3/me/friends
    access_token=...&
    debug=all

Si l’autorisation user_friends n’a pas été accordée, la réponse suivante est générée :

{
  "data": [
  ], 
  "__debug__": {
    "messages": [
      {
        "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", 
        "type": "warning"
      }, 
      {
        "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", 
        "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", 
        "type": "info"
      }
    ]
  }
}

La valeur du paramètre debug peut être définie sur « all » ou sur un niveau de gravité demandé minimum qui correspond au type de message :

Valeur du paramètre de débogage Réponse envoyée

all

Tous les messages de débogage disponibles.

info

Messages de débogage de type info et warning.

warning

Uniquement les messages de débogage de type warning.

Si elles sont disponibles, les informations de débogage sont renvoyées sous forme d’objet JSON sous la clé __debug__, dans le tableau messages. Chaque élément de ce tableau est un objet JSON qui contient les champs suivants :

Champ Type de données Description

message

Chaîne

Le message.

type

Chaîne

La gravité du message.

link

Chaîne

[Facultatif] Une URL qui envoie vers des informations connexes.

Vous pouvez également utiliser le mode débogage avec le Graph API Explorer.

Déterminer la version utilisée par les requêtes d’API

Lorsque vous créez une application et effectuez des requêtes d’API Graph, la détermination de la version de l’API qui vous envoie une réponse peut vous être utile. Par exemple, si vous effectuez des appels sans préciser de version, la version d’API qui répond peut vous être inconnue.

L’API Graph fournit un en-tête de requête avec toute réponse intitulée facebook-api-version qui indique la version exacte de l’API qui génère la réponse. Par exemple, un appel de l’API Graph qui génère une requête avec la version 2.0 aura l’en-tête HTTP suivant :

facebook-api-version:v2.0

L’en-tête facebook-api-version vous permet de déterminer les appels d’API qui sont renvoyés à partir de la version escomptée.

Informations de débogage pour le signalement des bugs

Si vous devez signaler un bug dans l’API Graph, nous incluons certains en-têtes de requête supplémentaires que vous devriez envoyer avec votre signalement de bug pour nous aider à déterminer et à reproduire votre problème. Ces en-têtes de requête sont X-FB-Debug, x-fb-rev et X-FB-Trace-ID.