Recherche et SearchStream

Vidéo: reporting

L'API Google Ads dispose d'un mécanisme unifié de récupération des attributs et de rapports sur les métriques qui vous permet de créer des requêtes à l'aide du langage de requête Google Ads. Cela permet d'effectuer des requêtes complexes qui peuvent renvoyer de grandes quantités de données sur les différents comptes Google Ads.

Vous pouvez créer des requêtes à l'aide des méthodes Search ou SearchStream. Les deux méthodes acceptent les mêmes requêtes et renvoient des résultats équivalents. La méthode Search renvoie des données dans des tailles de page personnalisables, ce qui vous permet d'effectuer une itération sur un ensemble de résultats à l'aide de la pagination. Cela peut être avantageux dans des conditions de réseau peu fiables ou peu fiables, par exemple pour segmenter un ensemble de résultats volumineux en réponses plus petites qui peuvent être récupérées à nouveau en cas de perte de connexion. En revanche, la méthode SearchStream transmet l'ensemble des résultats en flux continu dans une seule réponse, ce qui peut s'avérer plus efficace pour la récupération groupée de données.

Search et SearchStream utilisent la même URL de base:

    https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds

La méthode de recherche basée sur les pages utilise un paramètre pageSize facultatif qui limite le nombre de résultats renvoyés dans une seule réponse d'API.

POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}

S'il y a plus de lignes dans les résultats que pageSize, une nextPageToken est renvoyée dans la réponse:

{
  "results": [
    // ...
    // ...
    // ...
  ],
  "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
  "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}

La répétition de la même requête avec l'ajout d'un pageToken avec la valeur ci-dessus permet de récupérer la page de résultats suivante:

POST /v17/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}

Pour utiliser la méthode SearchStream, qui renvoie tous les résultats dans une seule réponse diffusée, il vous suffit de remplacer la méthode de service dans l'URL par searchStream (pageSize et pageToken ne sont pas requis par SearchStream):

POST /v17/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
    "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}