Attention:Vous consultez la documentation de l'interface REST de l'API. La plupart de nos bibliothèques clientes officielles utilisent gRPC. Pour en savoir plus, consultez la présentation de REST.

Cette page a été traduite par l'API Cloud Translation.

Exemples

Ce guide contient des exemples d'appels directs aux points de terminaison REST, sans utiliser de bibliothèque cliente.

Prérequis

Tous les exemples présentés ici sont conçus pour être copiés et collés dans un shell bash à l'aide de la commande curl.

Vous devez également disposer d'un jeton de développeur (un accès à un compte de test suffit) et d'un compte administrateur Google Ads contenant au moins un compte client.

Variables d'environnement

Saisissez les identifiants et les ID de compte comme indiqué, puis copiez-les et 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="20"
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 sur des budgets ou des campagnes préexistants. Si vous disposez d'ID d'objets existants à utiliser avec ces exemples, saisissez-les comme indiqué.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Sinon, les deux Mutates – Creates examples créent un budget et une campagne.

Rechercher

Le guide Cookbook des requêtes contient de nombreux exemples de rapports qui correspondent à certains é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 interactives 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é à côté de 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'

### Streaming La méthode `searchStream` diffuse tous les résultats dans une seule réponse. Le champ `pageSize` n'est donc pas pris en charge.

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'

Mutations

Plusieurs opérations de mutation (create, update ou remove) peuvent être envoyées dans un seul corps de requête JSON en remplissant le tableau operations.

Créations

Cet exemple crée deux budgets de campagne partagés dans une seule requête.

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 de budget de campagne existant. Vous pouvez le 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 dans l'exemple suivant fait référence à un campaignBudget par son nom de ressource de type 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 des objets existants à l'aide des 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, qui est une liste d'attributs JSON séparés par une virgule et qui doivent figurer dans la requête pour être appliqués en tant que mise à jour. Les attributs listés dans updateMask, mais qui ne figurent pas 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

Les objets sont supprimés en spécifiant 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, vous pouvez 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 réussissent si et seulement si elles sont toutes valides.

L'exemple suivant utilise une campagne existante. Vous pouvez copier et coller la sortie 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 avec un ID non valide. Étant donné que la deuxième opération génère 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 groupe. L'ensemble des opérations réussit si aucune opération n'échoue, ou échoue si une seule opération échoue.

Cet exemple montre comment créer un budget de campagne, une campagne, un groupe d'annonces et une annonce en tant qu'ensemble unique d'actions. Chaque opération successive dépend de la 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 remplis 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 des comptes

Vous pouvez créer des comptes, lister les comptes accessibles et importer des ressources binaires.

Créer des 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'
}
}"

Lister les comptes accessibles

Utilisez une simple requête GET à la méthode listAccessibleCustomers pour obtenir la liste des comptes Google Ads accessibles avec le jeton d'accès OAuth 2.0 donné. Aucun ID de compte administrateur ni de compte client ne doit être utilisé dans cette requête.

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 composants binaires

La méthode assets:mutate permet d'importer et de gérer les éléments. Les données binaires, telles qu'une image, sont encodées sous forme de chaîne à l'aide d'un encodage Base64 standard avec remplissage. L'encodage base64 standard ou sécurisé pour les URL, avec ou sans remplissage, est accepté.

Cet exemple encode un GIF d'un pixel pour que l'échantillon reste concis. En pratique, les charges utiles data sont beaucoup plus volumineuses.

Utilisez l'utilitaire de ligne de commande base64 (qui fait partie des utilitaires GNU core) pour encoder une image GIF d'un 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'
      }
    }
  }
]
}"

Erreurs courantes

Essayer

Exemples Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Prérequis

Variables d'environnement

ID d'objets facultatifs supplémentaires

Rechercher

Paginée

curl

GAQL

curl

GAQL

Mutations

Créations

Mises à jour

Suppressions

Échecs partiels

Opérations groupées

Gestion des comptes

Créer des comptes

Lister les comptes accessibles

Importer des composants binaires

Exemples