Ce guide contient des exemples d'appel direct des points de terminaison REST, sans l'utilisation d'une bibliothèque cliente.
Prérequis
Tous les exemples ci-dessous doivent être copiés et collés dans une interface système bash à l'aide de la commande curl.
Vous avez également besoin d'un jeton de développeur, d'un accès au compte test et d'un compte administrateur Google Ads contenant au moins un compte client.
Variables d'environnement
Saisissez les identifiants et les ID de compte ci-dessous, puis copiez-collez ces éléments dans votre terminal pour configurer les variables d'environnement utilisées dans les exemples suivants. Le guide sur les autorisations fournit des instructions pour générer un jeton d'accès OAuth 2.0.
API_VERSION="16"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"
ID d'objets facultatifs supplémentaires
Certains des exemples suivants s'appliquent à des campagnes ou des budgets préexistants. Si vous disposez des ID d'objets existants à utiliser avec ces exemples, saisissez-les ci-dessous.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Sinon, les deux exemples Mutates - Creates créent un budget et une campagne.
Rechercher
Le guide Query Cookbook contient de nombreux exemples de rapports qui correspondent à certains des écrans Google Ads par défaut et fonctionnent avec les mêmes variables d'environnement que celles utilisées dans ce guide. Notre outil de création de requêtes interactif est également une excellente ressource pour créer des requêtes personnalisées de manière interactive.
Paginée
La méthode search
utilise la pagination, avec un paramètre pageSize
ajustable spécifié avec le query
.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "pageSize": 10, "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Flux de données
La méthode searchStream
diffuse tous les résultats dans une seule réponse. Par conséquent, le champ pageSize
n'est pas accepté.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Transformations
Plusieurs opérations mutate (create
, update
ou remove
) peuvent être envoyées dans un seul corps de requête JSON en remplissant le tableau operations
.
Création
Dans cet exemple, deux budgets de campagne partagés sont créés dans une seule demande.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
L'exemple suivant utilise un BUDGET_ID
correspondant au budget d'une campagne existante. Vous pouvez copier et coller le résultat de l'étape précédente.
BUDGET_ID=BUDGET_ID
Les ressources qui font référence à d'autres ressources le font par nom de ressource. La campagne créée ci-dessous fait référence à une campaignBudget
par son nom de ressource sous forme de chaîne.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
Changements
Mettez à jour les attributs des objets existants à l'aide d'opérations update
. L'exemple suivant utilise une campagne existante. Vous pouvez copier et coller le résultat de l'étape précédente.
CAMPAIGN_ID=CAMPAIGN_ID
Toutes les mises à jour nécessitent un champ updateMask
, c'est-à-dire une liste des attributs JSON séparés par une virgule devant figurer dans la requête et devant être appliqués en tant que mise à jour. Les attributs répertoriés dans updateMask
, mais non présents dans le corps de la requête, sont effacés pour un objet. Les attributs non répertoriés dans updateMask
, mais présents dans le corps de la requête, sont ignorés.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
Suppressions
Pour supprimer des objets, spécifiez le nom de leur ressource en tant qu'opération remove
.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
Échecs partiels
Lorsque plusieurs opérations figurent dans une même requête, vous pouvez éventuellement spécifier partialFailure
. Si la valeur est true
, les opérations réussies sont effectuées et les opérations non valides renvoient des erreurs. Si la valeur est false
, toutes les opérations de la requête aboutissent si et seulement si elles sont toutes valides.
L'exemple suivant utilise une campagne existante. Vous pouvez copier et coller le résultat de l'exemple Créer.
CAMPAIGN_ID=CAMPAIGN_ID
La requête suivante contient deux opérations. La première tentative de modification de la stratégie d'enchères de la campagne fournie, et la suivante essaie de supprimer une campagne dont l'ID n'est pas valide. Étant donné que la deuxième opération génère une erreur (l'ID de campagne n'est pas valide) et comme partialFailure
est défini sur false
, la première opération échoue également et la stratégie d'enchères de la campagne existante n'est pas mise à jour.
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
Opérations groupées
La méthode googleAds:mutate
permet d'envoyer des groupes d'opérations avec plusieurs types de ressources. Vous pouvez envoyer de nombreuses opérations de différents types pour enchaîner une séquence d'opérations à effectuer en tant que groupe.
L'ensemble d'opérations réussit si aucune opération n'échoue ou si l'une d'elles échoue toutes.
Cet exemple illustre la création d'un budget de campagne, d'une campagne, d'un groupe d'annonces et d'une annonce comme un seul ensemble d'actions. Chaque opération successive dépend de la précédente. En cas d'échec, l'ensemble du groupe d'opérations échoue.
Les entiers négatifs (-1
, -2
, -3
) sont utilisés comme espaces réservés dans les noms de ressources et sont renseignés de manière dynamique au moment de l'exécution avec les résultats de la séquence d'opérations.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
Gestion de compte
Création de comptes
Créez des comptes à l'aide de la méthode createCustomerClient
. Notez que l'URL nécessite un ID de compte administrateur au lieu d'un ID de compte client. Un compte client est créé sous le compte administrateur.
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
Répertorier les comptes accessibles
Envoyez une requête GET
simple à la méthode listAccessibleCustomers
pour obtenir la liste des comptes Google Ads accessibles à l'aide du jeton d'accès OAuth 2.0 donné. Aucun ID de compte administrateur ni aucun numéro de compte client ne doit être utilisé dans cette demande.
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
Importer des éléments binaires
La méthode assets:mutate
permet d'importer et de gérer des éléments. Les données binaires, telles qu'une image, sont encodées sous forme de chaîne à l'aide d'un encodage standard base64 avec marge intérieure. L'encodage en base64 standard ou adapté aux URL avec ou sans marge intérieure est accepté.
Cet exemple encode un GIF de 1 pixel pour qu'il soit concis. En pratique, les charges utiles data
sont beaucoup plus volumineuses.
Utilisez l'utilitaire de ligne de commande base64
(qui fait partie des utilitaires principaux GNU) pour encoder une image GIF de 1 pixel.
base64 1pixel.gif
La valeur encodée en base64 est spécifiée en tant qu'attribut data
dans une requête API.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"