Exemples

Ce guide contient des exemples d'appel direct des points de terminaison REST, sans le d'une bibliothèque cliente.

Prérequis

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

Vous avez également besoin d'un jeton de développeur, test l'accès à votre compte est acceptable, et un Compte administrateur Google Ads contenant au moins un compte client.

Important :Dans ces exemples, nous supposons que vous accédez à un compte client (CUSTOMER_ID) par un utilisateur disposant d'un accès administrateur à un compte administrateur (MANAGER_CUSTOMER_ID) qui gère directement le compte client. Si vous utilisez accédez directement à un compte client individuel, omettez la login-customer-id ou lui attribuer la même valeur que CUSTOMER_ID. Remarque que certains exemples, tels que la section Créer des comptes, requièrent une compte administrateur.

Variables d'environnement

Saisissez les identifiants et les ID de compte ci-dessous, puis copiez-collez-les dans votre 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="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 afin de disposer des identifiants des 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 la campagne.

Rechercher

Le guide Query Cookbook contient de nombreux rapports qui correspondent à certains des écrans Google Ads par défaut et qui fonctionnent avec les mêmes variables d'environnement utilisées dans ce guide. La requête interactive l'outil de création 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'

Streaming

La méthode searchStream transmet tous les résultats en une seule réponse. Par conséquent, le 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 corps de requête JSON unique 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 du budget d'une campagne existante. vous pouvez en effectuant un copier-coller à partir du résultat de l'étape précédente.

BUDGET_ID=BUDGET_ID

Les ressources qui se réfèrent à d'autres ressources le font en nom de ressource. La campagne créée ci-dessous fait référence à 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. La prochaine exemple utilise une campagne existante. que vous pouvez copier et coller du résultat de l'étape.

CAMPAIGN_ID=CAMPAIGN_ID

Toutes les mises à jour nécessitent un champ updateMask, une liste de valeurs séparées par une virgule les attributs JSON à inclure dans la requête, qui doivent être appliqués mise à jour. Attributs listés dans le updateMask, mais non présents dans la requête sont effacés pour un objet. Attributs non listés dans le 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, 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 réussir si et seulement si elles sont toutes valides.

L'exemple suivant utilise une campagne existante. vous pouvez effectuer un copier-coller Crée un exemple de résultat.

CAMPAIGN_ID=CAMPAIGN_ID

La requête suivante contient deux opérations. La première tentative de modification de la campagne fournie et que la suivante tente de supprimer campagne dont l'ID n'est pas valide. Étant donné que la deuxième opération entraîne une erreur (le l'ID de campagne n'est pas valide) et comme partialFailure est défini sur false, le la première opération échoue également et la stratégie d'enchères de la campagne existante est non mises à 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 types différents enchaîner une séquence d'opérations qui doivent être effectuées en groupe. L'ensemble d'opérations réussit si aucune opération n'échoue ou échouent toutes le cas échéant. une seule opération échoue.

Cet exemple montre comment créer un budget de campagne, une campagne, un groupe d'annonces et l'annonce sous la forme d'un même ensemble d'actions. Chaque opération successive dépend par rapport à 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 la ressource et sont renseignés dynamiquement au moment de l'exécution avec les résultats de la séquence des 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 nouveau 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 simple requête GET à la méthode listAccessibleCustomers pour obtenir une liste. des comptes Google Ads accessibles à l'aide du jeton d'accès OAuth 2.0 donné. Aucun administrateur ou les ID de compte client doivent être utilisés 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 Composants : Les données binaires, telles qu'une image, sont encodées sous la forme une chaîne utilisant l'encodage base64 standard avec une marge intérieure. Standard ou L'encodage base64 adapté aux URL avec ou sans marge intérieure est accepté.

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

Utilisez l'utilitaire de ligne de commande base64 (qui fait partie de Utilitaires GNU de base) 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'
      }
    }
  }
]
}"