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'appel direct des points de terminaison REST, sans utiliser de bibliothèque cliente.

Prérequis

Tous les exemples ci-dessous doivent être copiés et collés dans un shell bash à l'aide de la commande curl.

Vous avez également besoin d'un jeton de développeur (un accès à un compte de test est acceptable) 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="19"
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 ci-dessous.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Sinon, les deux Mutations - Crée des exemples créent un budget et une campagne.

Rechercher

Le guide Cookbook de requêtes 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 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é du 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 lit 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'

Modification

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ée

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 d'un budget de campagne existant. Vous pouvez copier-coller à partir de la sortie 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 à un 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 copier-coller à partir de la sortie de l'étape précédente.

CAMPAIGN_ID=CAMPAIGN_ID

Toutes les mises à jour nécessitent un champ updateMask, une liste d'attributs JSON à inclure dans la requête, séparés par une virgule, qui doivent ê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 sur 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 sont incluses 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 aboutissent si et seulement si elles sont toutes valides.

L'exemple suivant utilise une campagne existante. Vous pouvez copier-coller à partir de la sortie de l'exemple Créations.

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 seconde tente 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 la 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 d'opérations aboutit si aucune opération ne échoue, ou échoue si une seule opération échoue.

Cet exemple montre comment créer un budget, une campagne, un groupe d'annonces et une annonce en même temps, en tant qu'ensemble 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 et -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

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

Utilisez une requête GET simple à 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 ou 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 éléments 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 en tant que chaîne à l'aide de l'encodage standard en base64 avec remplissage. L'encodage base64 standard ou sécurisé pour les URL, avec ou sans remplissage, est accepté.

Cet exemple encode un GIF de 1 pixel pour que l'exemple soit concis. En pratique, les charges utiles data sont beaucoup plus importantes.

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

Autres méthodes

Essayer