Exemples

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.

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'
      }
    }
  }
]
}"