API Graph

Requêtes par lot

Envoyez une seule requête HTTP contenant plusieurs appels API Graph Facebook. Les opérations indépendantes sont traitées en parallèle tandis que les opérations dépendantes sont traitées séquentiellement. Une fois l’ensemble des opérations terminées, vous recevez une réponse consolidée et la connexion HTTP se ferme.

Les réponses sont renvoyées dans le même ordre que les opérations de la requête. Vous devez donc traiter les réponses dans l’ordre pour déterminer les opérations qui ont abouti et celles qui doivent faire l’objet d’une nouvelle requête.

Limites

  • Les requêtes sont limitées à 50 par lot. Chaque appel au sein du lot est comptabilisé séparément afin de déterminer les limites d’appels de l’API et les limites des ressources. Par exemple, un lot de 10 appels d’API correspond à 10 appels, et un appel de ce lot consomme la même quantité de ressources CPU que les autres appels du lot. Pour en savoir plus, consultez notre guide sur les plafonds.
  • Les requêtes par lot ne peuvent pas inclure plusieurs ensembles de publicités sous la même campagne. Pour en savoir plus, consultez l’article Requêtes par lot pour l’API Marketing.

Requêtes par lot simples

Une requête par lot réceptionne un objet JSON qui est un tableau de vos requêtes. Elle renvoie un tableau de réponses HTTP logiques représentées sous la forme de tableaux JSON. Chaque réponse contient un code de statut, un tableau d’en-têtes facultatif et un corps facultatif (à savoir une chaîne encodée JSON).

Pour créer une requête par lot, envoyez une requête POST à un point de terminaison, en indiquant votre objet JSON dans le paramètre batch.

POST /ENDPOINT?batch=[JSON-OBJECT]

Exemple de requête par lot

Dans cet exemple, nous recevons des informations à propos de deux pages gérées par notre application.

Formaté pour plus de lisibilité.
curl -i -X POST 'https://graph.facebook.com/me?batch=  
  [
    {
      "method":"GET",
      "relative_url":"PAGE-A-ID"
    },  
    {
      "method":"GET",
      "relative_url":"PAGE-B-ID"
    }
  ]
  &include_headers=false             // Included to remove header information
  &access_token=ACCESS-TOKEN'

Une fois toutes les opérations terminées, une réponse est envoyée avec le résultat de chaque opération. Dans certains cas, les en-têtes renvoyés peuvent être plus volumineux que la réponse d’API. Une solution consiste alors à les supprimer dans un souci d’efficacité. Pour inclure des informations d’en-tête, supprimez le paramètre include_headers ou définissez-le sur true.

Exemple de réponse

Le champ de corps contient un objet chaîne encodé au format JSON :

[
  {
    "code": 200,
    "body": "{
      \"name\": \"Page A Name\",
      \"id\": \"PAGE-A-ID\"
      }"
  },
  {
    "code": 200,
    "body": "{
      \"name\": \"Page B Name\",
      \"id\": \"PAGE-B-ID\"
      }"
  }
]

Requêtes par lot complexes

Il est possible de combiner des opérations qui utilisent normalement différentes méthodes HTTP au sein d’une requête par lot. Les opérations GET et DELETE peuvent uniquement contenir les champs relative_url et method, mais les opérations POST et PUT peuvent également contenir un champ body facultatif. Le corps doit être formaté comme une chaîne POST HTTP brute, à la manière d’une chaîne de requête d’URL.

Exemple de requête

L’exemple suivant publie une publication d’abord dans une Page que nous gérons et pour laquelle nous disposons d’autorisations de publication, puis dans le fil d’actualité de la Page, le tout en une seule opération :

curl "https://graph.facebook.com/PAGE-ID?batch=
  [
    { 
      "method":"POST",
      "relative_url":"PAGE-ID/feed",
      "body":"message=Test status update"
    },
    { 
      "method":"GET",
      "relative_url":"PAGE-ID/feed"
    }
  ]
  &access_token=ACCESS-TOKEN"

Le résultat de cet appel ressemblerait à ce qui suit :

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

L’exemple suivant illustre la création d’une publicité pour une campagne et l’obtention des détails de l’objet qui vient d’être créé. Notez le codage de l’URL pour le paramètre de corps :

curl \
-F 'access_token=...' \
-F 'batch=[
  {
    "method":"POST",
    "name":"create-ad",
    "relative_url":"11077200629332/ads",
    "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
  }, 
  {
    "method":"GET",
    "relative_url":"?ids={result=create-ad:$.data.*.id}"
  }
]' \
https://graph.facebook.com

Dans l’exemple suivant, plusieurs pages sont ajoutées à un compte Business Manager :

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
  {
    "method":"POST",
    "name":"test1",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_1>"
  }, 
  {
    "method":"POST",
    "name":"test2",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_2>"
  }, 
  {
    "method":"POST",
    "name":"test3",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_3>"
  }, 
]' \
"https://graph.facebook.com/v12.0"

Où :

  • <ACCESS_TOKEN> est un token d’accès incluant l’autorisation business_management.
  • <BUSINESS_ID> est l’ID du compte Business Manager sur lequel les pages doivent être revendiquées.
  • <PAGE_ID_n> sont les ID de Page à revendiquer.

Erreurs

Il se peut que l’une des opérations que vous avez demandées génère une erreur. Cela peut arriver notamment si vous ne disposez pas de l’autorisation requise pour effectuer l’opération demandée. La réponse renvoyée est similaire à celle de l’API Graph standard, mais encapsulée dans la syntaxe de la réponse par lot :

[
    { "code": 403,
      "headers": [
          {"name":"WWW-Authenticate", "value":"OAuth…"},
          {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
      "body": "{\"error\":{\"type\":\"OAuthException\", … }}"
    }
]

Les autres requêtes du lot devraient normalement être traitées correctement et seront renvoyées, comme d’habitude, avec un code de statut 200.

Délais d’expiration

Le délai de réponse peut expirer pour les lots volumineux ou complexes lorsque le traitement des requêtes au sein du lot dure trop longtemps. Le lot n’est alors traité que partiellement. Dans un lot partiellement traité, les requêtes qui ont abouti renvoient le résultat habituel avec le code de statut 200. Les requêtes qui échouent renvoient la réponse null. Vous pouvez retenter les requêtes échouées.

Appels par lot avec JSONP

L’API Batch prend en charge JSONP, comme le reste de l’API Graph : la fonction de rappel JSONP est indiquée à l’aide des paramètres de chaîne de requête ou de publication de formulaire callback.

Utilisation de plusieurs tokens d’accès

Chaque requête d’une requête par lot peut contenir son propre token d’accès dans un paramètre de chaîne ou de publication de formulaire. Dans ce cas, le token d’accès de niveau supérieur est considéré comme un token de secours et sert uniquement si la requête individuelle n’a indiqué aucun token d’accès de manière explicite.

Cela peut s’avérer utile lorsque vous souhaitez interroger l’API au moyen de tokens d’accès distincts de plusieurs utilisateurs, ou si vous avez besoin d’un token d’accès d’application pour passer certains de vos appels.

Vous devez toujours inclure un token d’accès comme paramètre de niveau supérieur et ce, même lorsque toutes les requêtes individuelles possèdent leur propre token.

Téléchargement de données binaires

Un appel par lot peut permettre de télécharger plusieurs éléments binaires. Pour ce faire, vous devez ajouter à votre requête tous les éléments binaires en tant que pièces jointes MIME/multi-parties, et chaque opération doit faire référence à ses éléments binaires au moyen de la propriété attached_files. La valeur de la propriété attached_files peut être une liste de noms de pièces jointes séparées par des virgules.

L’exemple suivant illustre la manière de télécharger deux photos dans un seul appel par lot :

curl 
     -F 'access_token=…' \
     -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
     -F 'file1=@cat.gif' \
     -F 'file2=@dog.jpg' \
    https://graph.facebook.com
-->