Ce guide contient des exemples permettant d'appeler directement les points de terminaison REST, sans passer par une bibliothèque cliente.
Conditions préalables
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 de 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-les dans votre terminal pour configurer les variables d'environnement utilisées dans les exemples suivants. Le guide Autorisation fournit des instructions pour générer un jeton d'accès OAuth 2.0.
API_VERSION="17"
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 fonctionnent avec 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 qui 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 une taille de page fixe de 10 000 éléments et un page_token spécifié avec 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 '{
"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'
",
"page_token":"${PAGE_TOKEN}"
}'
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'
Tampon
La méthode searchStream diffuse tous les résultats en 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'
Modification
Plusieurs opérations mutate (create, update ou remove) peuvent être envoyées dans un seul corps de requête JSON en renseignant le tableau operations.
Crée
Dans cet exemple, deux budgets de campagne partagés sont créés dans une même 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 d'un budget de campagne existant. Vous pouvez effectuer un copier-coller à partir du 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 à valeur 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': {}
}
}
]
}"
Mises à jour
Mettez à jour les attributs d'objets existants à l'aide d'opérations update. L'exemple suivant utilise une campagne existante. Vous pouvez effectuer un copier-coller à partir du résultat de l'étape précédente.
CAMPAIGN_ID=CAMPAIGN_ID
Toutes les mises à jour nécessitent un champ updateMask, une liste des attributs JSON à inclure dans la requête, séparés par une virgule, devant être appliqués en tant que mises à jour. Les attributs listés dans updateMask, mais qui ne sont pas présents dans le corps de la requête, sont effacés d'un objet. Les attributs non listé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 leur nom de 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, spécifiez éventuellement 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 effectuer un copier-coller à partir de l'exemple Creates.
CAMPAIGN_ID=CAMPAIGN_ID
La requête suivante contient deux opérations. La première tente de modifier la stratégie d'enchères de la campagne fournie, et la suivante tente de supprimer une campagne dont l'ID n'est pas valide. Étant donné que la deuxième opération entraîne une erreur (l'ID de campagne n'est pas valide) et que 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 échouent toutes en cas d'échec d'une seule opération.
Cet exemple montre comment créer un budget de campagne, une campagne, un groupe d'annonces et une annonce sous la forme d'un seul ensemble d'actions. Chaque opération successive dépend de l'opération précédente. Si l'une d'elles échoue, 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 dynamiquement 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 du 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éé dans 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 simple requête GET à 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 ou 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 de l'encodage base64 standard avec marge intérieure. Les formats d'encodage base64 standard ou adapté aux URL avec ou sans marge intérieure sont acceptés.
Cet exemple encode un GIF d'un pixel pour que l'exemple reste concis. En pratique, les charges utiles data sont beaucoup plus importantes.
Utilisez l'utilitaire de ligne de commande base64 (qui fait partie des utilitaires GNU Core) 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'
}
}
}
]
}"