Requêtes asynchrones et par lot

Utilisez des requêtes asynchrones pour créer des publicités et envoyer plusieurs requêtes publicitaires sans devoir recourir au blocage. Précisez une URL à appeler lorsque les requêtes sont terminées ou vérifiez le statut de la requête. Consultez la page Référence sur les publicités.

Le moyen le plus efficace de gérer des publicités consiste à envoyer des requêtes par lot. Utilisez cette méthode pour certaines des requêtes les plus courantes.

Requêtes asynchrones

Par exemple, pour obtenir le statut de l'ensemble de requêtes asynchrones :

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Cela renvoie le statut global de l'ensemble de requêtes asynchrones sous forme d’objet JSON. Certains champs ne sont pas affichés par défaut. Pour que votre requête inclue des champs qui ne sont pas des champs par défaut, précisez-les dans les fields, comme fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Après l’obtention du statut global de l'ensemble de requêtes asynchrones, procurez-vous les détails de chaque requête :

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

Cela renvoie le statut et les détails de chaque requête de l’ensemble de requêtes asynchrones. Pour la création de publicités asynchrones, faites une requête pour créer une publicité. Le paramètre de statut permet de filtrer les requêtes selon leur propre statut et il peut s’agir de n'importe quelle combinaison des valeurs suivantes :

• initial : pas encore traitée
• in_progress : requête en cours de traitement
• success : requête terminée avec succès
• error : requête terminée qui a échoué
• canceled : requête annulée par l’utilisateur·ice

La réponse se présente sous la forme d’un tableau JSON avec des champs par défaut. Pour inclure des champs qui ne sont pas des champs par défaut, précisez-les dans les fields, comme fields=id,scope_object_id,status,result,input,async_request_set.

Obtenir les détails de la requête

Pour obtenir les détails d’une requête asynchrone spécifique, effectuez cet appel :

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

Cela renvoie un objet JSON avec les champs mentionnés ci-dessus.

Faire une liste des ensembles de requêtes pour un compte

Vous pouvez créer plusieurs ensembles de requêtes publicitaires asynchrones. Pour interroger tous les ensembles de requêtes publicitaires asynchrones d’un compte publicitaire :

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

Cela renvoie un tableau JSON des objets d’ensembles de requêtes asynchrones. Chaque objet est le même comme spécifié dans la section des ensembles de requêtes asynchrones. Vous pouvez filtrer les résultats avec is_completed. Si is_completed=true, vous ne verrez que l’ensemble de requêtes asynchrones terminé.

Faire une liste des requêtes pour un ensemble de publicités

Vous pouvez passer un appel asynchrone pour créer des publicités dans différents ensembles de publicités. Pour obtenir le statut de chaque ensemble de publicités, procurez-vous toutes les requêtes de création de publicités pour un ensemble de publicités :

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_SET_ID>/asyncadrequests

Cela renvoie un tableau JSON des objets de requêtes asynchrones. Les champs de statut, de filtre et de requêtes asynchrones sont les mêmes que ceux de l’API https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests.

Mettre à jour les ensembles de requêtes

Vous pouvez modifier name, notification_uri et notification_mode pour un ensemble de requêtes asynchrones.

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Cela renvoie true lorsque la mise à jour a réussi. Vous ne pouvez modifier notification_uri et notification_mode qu’avant l’envoi de la notification.

Annuler la requête

Vous pouvez annuler une requête asynchrone, mais elle ne pourra être annulée que si elle n'a pas encore été traitée.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_ID>

Cela renvoie true lorsque l’annulation a réussi. Vous pouvez également annuler les requêtes non traitées dans l'ensemble de requêtes asynchrones :

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

Cela renvoie true lorsque l’annulation a réussi.

Exemples de requêtes asynchrones

Obtention du statut d'une requête asynchrone spécifique :

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/"

Cela renvoie les valeurs :

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

Pour obtenir les résultats des requêtes :

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/requests"

Résultat :

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Pour obtenir la liste des ensembles de requêtes d’un compte publicitaire :

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_71597454/asyncadrequestsets"

Résultat :

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Obtention d’une liste de requêtes pour une campagne :

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/6008248529789/asyncadrequests"
    

Cela renvoie les valeurs :

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Requêtes par lot

Les requêtes par lot permettent de combiner plusieurs appels de l’API Graph dans la requête HTTP. L’API Marketing divise cette requête en plusieurs requêtes constitutives. De ce fait, les requêtes par lot sont le moyen d’interaction le plus efficace avec l’API Marketing. Pour encore plus d’efficacité, vous pouvez faire des requêtes par lot en parallèle à l’aide de fils de discussion de traitement séparés.

Les requêtes par lot pour les publicités, les contenus publicitaires et les ensembles de publicités sont similaires ; c’est pourquoi nous ne les aborderons pas séparément. Pour plus d’informations, consultez les pages API Graph, Requêtes par lot et ETags.

Créer des publicités

Vous pouvez fournir des contenus publicitaires et d'autres objets publicitaires dans une requête par lot. Par exemple, vous pouvez créer trois publicités à l’aide d’un contenu publicitaire et de trois spécifications de ciblage différentes. Commencez par définir votre contenu publicitaire, puis référencez-le lorsque vous créez une publicité :

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

La réponse comprend des codes de réponse individuels pour chaque requête et la réponse standard de l'API Graph. Pour plus d’informations, consultez la page Envoi de plusieurs demandes d’API.

Le processus de requête par lot utilise le format d’expression JSONPath pour référencer les requêtes précédentes.

Mettre à jour les publicités

Vous pouvez mettre à jour les publicités avec des requêtes par lot. Pour mettre à jour les enchères pour trois publicités :

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

Si vous incluez redownload=1 dans l’URL relative, vous obtiendrez les détails complets des publicités, y compris leur ID. Cela permet d’identifier les publicités que vous avez mises à jour.

Pour mettre à jour un contenu publicitaire, spécifiez le contenu dans son intégralité ou indiquez un nouvel ID de contenu publicitaire. Cela est dû au fait que les contenus publicitaires ne peuvent pas être modifiés après leur création, à l’exception de leur nom et de leur statut d’exécution.

Lire les publicités

Si vous avez de nombreuses publicités, divisez la requête en plusieurs requêtes au sein d’une requête par lot :

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

6003356308839 et 6004164369439 sont des ID de publicité, alors que 6003356307839 et 6004164259439 sont des ID d’ensemble de publicités.

Insights publicitaires

Si vous avez de nombreux insights publicitaires, divisez la requête en plusieurs requêtes au sein d’une requête par lot :

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

Dans cet exemple, 6003356308839 et 6004164369439 sont des ID de publicité, alors que 6003356307839 et 6004164259439 sont des ID d’ensemble de publicités.

Pour les comptes publicitaires contenant de nombreuses publicités, il n’est pas recommandé d’utiliser act_<account_ID>/adgroupstats, car cela peut entraîner l’expiration de la requête.

Requête par lot pour une estimation de la couverture

Vous pouvez demander jusqu’à 50 estimations de couverture dans une seule requête par lot. L’exemple suivant montre l’estimation de la couverture demandée pour deux spécifications de ciblage différentes :

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

API Batch

L’API Batch permet de faire des requêtes par lot et de les envoyer de manière asynchrone. Regroupez plusieurs appels de l'API Graph dans une requête HTTP, et exécutez-les de manière asynchrone sans qu’un blocage soit nécessaire. Vous pouvez également spécifier des dépendances entre les opérations connexes.

Facebook traite chaque opération indépendante dans des processus parallèles et vos opérations dépendantes de manière séquentielle. Chaque appel d'API peut contenir un maximum de 1 000 requêtes.

Passer un appel de l’API Batch

Pour passer un appel de l’API Batch :

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

Fournissez un tableau de requêtes HTTP POST sous forme de tableaux JSON. Chaque requête comporte les éléments suivants :

• name
• relative_url : partie de l’URL après graph.facebook.com
• body

L'API renvoie un ID que vous utiliserez pour interroger la progression des requêtes.

Par exemple, créez une campagne avec un ensemble de publicités au format JSONPath pour référencer les requêtes précédentes :

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

Pour obtenir le statut de l’ensemble de requêtes :

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>"

Cela renvoie le statut global des ensembles de requêtes asynchrones sous forme d’objets JSON. Certains champs ne sont pas inclus par défaut. Pour les inclure, spécifiez les fields, comme fields=id,owner_id,name,total_count,success_count,error_count,is_completed

Après l’obtention du statut global, vous pourrez avoir les détails pour chaque requête :

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests"

Cela renvoie les détails sous forme de tableau JSON. Pour inclure des champs qui ne sont pas des champs par défaut, précisez-les dans les fields, comme fields=id,scope_object_id,status,result,input,async_request_set.

Faire une liste des requêtes de l’API Batch pour le compte publicitaire

Vous pouvez créer plusieurs ensembles de requêtes de l’API Batch. Pour interroger tous les ensembles de requêtes d’un compte publicitaire :

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_requests"

ETags

L’API Marketing prend en charge les ETags. Cela vous permet de déterminer si les données que vous interrogez ont changé depuis votre dernière vérification. Principe de fonctionnement :

1. Lorsque vous passez un appel, l'en-tête de la réponse comprend un ETag dont la valeur correspond au hachage des données renvoyées lors de l'appel de l'API. Enregistrez cette valeur ETag pour l’utiliser lors de l’étape suivante.
2. La prochaine fois que vous passerez le même appel d’API, incluez l’en-tête de requête If-None-Match avec la valeur ETag que vous avez enregistrée.
3. Si les données n’ont pas changé, le code de statut de la réponse sera 304 – Not Modified et aucune donnée ne sera renvoyée.
4. Si les données ont changé depuis la dernière requête, les données seront renvoyées de la manière habituelle avec un nouvel ETag. Enregistrez la nouvelle valeur ETag et utilisez-la pour les appels suivants.

Bien que les ETags permettent de réduire le trafic des données, If-None-Match GET est toujours pris en compte par rapport aux limites de débit pour votre application.

L’ETag est calculé à l’aide de l’intégralité de la réponse de l’appel d’API, y compris son format. Le format de la réponse peut être affecté par la chaîne de l'agent utilisateur. Par conséquent, vous devez veiller à ce que votre agent utilisateur reste cohérent entre les appels passés par le même client.

Exemples d’Etags

Pour vérifier si les comptes publicitaires de l'utilisateur·ice ont changé.

Étape 1 : Déterminer l'ETag pour les données actuelles

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

La réponse sera la suivante :

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

Dans cet exemple, l’ETag est "7776cdb01f44354af8bfa4db0c56eebcb1378975". Notez que l’ETag inclut les guillemets (").

Étape 2 : Déterminer si des données ont été modifiées

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

S’il n’y a eu aucun changement, la réponse sera la suivante :

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

Notez la réponse 304 Not Modified. En cas de changements dans les données, une réponse d’API normale sera renvoyée.

Exemple de lot pour vérifier si les publicités de l'utilisateur·ice ont changé.

Étape 1 : Déterminer l'ETag pour les données actuelles

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

La réponse contiendra les valeurs ETag comme suit :

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

Dans cet exemple, les ETags sont "21d371640127490b2ed0387e8af3f0f8c9eff012" et "410e53bb257f116e8716e4ebcc76df1c567b87f4". Notez que l’ETag inclut les guillemets (").

Étape 2 : Déterminer si des données ont été modifiées

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

S’il n’y a eu aucun changement, la réponse sera la suivante :

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

Notez la réponse 304 Not Modified. Si les données ont changé, une réponse d’API normale sera renvoyée.