В этом руководстве приведены примеры прямого вызова конечных точек REST без использования клиентской библиотеки.
Скрипты из этого руководства находятся в репозитории GitHub с примерами кода REST, включая каталог rest_guide.
Чтобы посмотреть тела запросов и ответов для каждого метода API, ознакомьтесь со справочной документацией по конкретным конечным точкам сервиса.
Например, на справочной странице для GoogleAdsService.Search показаны тела запроса и ответа для метода Search.
Требования
Все приведенные здесь примеры предназначены для копирования и вставки в оболочку bash с помощью команды curl.
Вам также понадобится проект Google Cloud (достаточно доступа к тестовому аккаунту) и управляющий аккаунт Google Рекламы, содержащий хотя бы один клиентский аккаунт.
Переменные среды
Введите учетные данные аккаунта и идентификаторы, как показано на примере, а затем скопируйте и вставьте их в терминал, чтобы настроить переменные среды, используемые в последующих примерах. Инструкции по созданию токена доступа OAuth 2.0 приведены в руководстве по авторизации.
API_VERSION="26"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"Дополнительные необязательные идентификаторы объектов
Некоторые из приведенных ниже примеров работают с существующими бюджетами или кампаниями. Если у вас есть идентификаторы существующих объектов, которые можно использовать в этих примерах, введите их, как показано.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_IDВ противном случае два примера Mutates - Creates создают новый бюджет и кампанию.
Поиск
В руководстве по созданию запросов содержится множество примеров отчетов, которые соответствуют некоторым экранам Google Рекламы по умолчанию и работают с теми же переменными среды, которые используются в этом руководстве. Наш интерактивный конструктор запросов – это ещё один отличный инструмент для создания специальных запросов.
Разбивка на страницы
В методе search используется разбивка на страницы с фиксированным размером страницы в 10 000 элементов и page_token, указанным вместе с query.
Для первого запроса оставьте поле PAGE_TOKEN пустым. Чтобы получить следующую страницу, задайте для параметра PAGE_TOKEN значение nextPageToken из предыдущего ответа и повторите запрос.
PAGE_TOKEN=""curl
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "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}" } EOF
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'
Потоковая передача
Метод searchStream передает все результаты в одном ответе, поэтому поле pageSize не поддерживается.
curl
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<'EOF' { "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' " } EOF
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'
Изменения
В одном теле запроса JSON можно отправить несколько операций изменения (create, update или remove), заполнив массив operations.
Создает
В этом примере в одном запросе создаются два общих бюджета кампании.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "name": "My Campaign Budget #${RANDOM}", "amountMicros": 500000 } }, { "create": { "name": "My Campaign Budget #${RANDOM}", "amountMicros": 500000 } } ] } EOF
В следующем примере используется BUDGET_ID существующего бюджета кампании. Вы можете скопировать и вставить его из выходных данных предыдущего шага.
BUDGET_ID=BUDGET_IDРесурсы, которые ссылаются на другие ресурсы, делают это по названию ресурса.
В примере ниже кампания ссылается на campaignBudget по строковому названию ресурса.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "status": "PAUSED", "advertisingChannelType": "SEARCH", "geoTargetTypeSetting": { "positiveGeoTargetType": "PRESENCE_OR_INTEREST", "negativeGeoTargetType": "PRESENCE" }, "name": "My Search campaign #${RANDOM}", "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}", "targetSpend": {}, "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING" } } ] } EOF
Обновления
Обновлять атрибуты существующих объектов с помощью операций update. В следующем примере используется существующая кампания. Вы можете скопировать и вставить ее из выходных данных предыдущего шага.
CAMPAIGN_ID=CAMPAIGN_IDДля всех изменений требуется поле updateMask – разделенный запятыми список атрибутов JSON, которые должны быть в запросе и которые нужно применить в качестве обновления.
Атрибуты, перечисленные в updateMask, но отсутствующие в теле запроса, удаляются из объекта. Атрибуты, не указанные в updateMask, но присутствующие в теле запроса, игнорируются.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "update": { "resourceName": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}", "name": "A changed campaign name #${RANDOM}" }, "updateMask": "name" } ] } EOF
Удаление
Чтобы удалить объект, укажите название его ресурса в качестве операции remove.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "remove": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}" } ] } EOF
Частичные сбои
Если в одном запросе несколько операций, можно указать partialFailure. Если задано значение true, то выполняются только допустимые операции, а недопустимые возвращают ошибки. Если задано значение false, все операции в запросе будут выполнены, только если они все допустимы.
В следующем примере используется существующая кампания. Вы можете скопировать и вставить выходные данные из примера Создание.
CAMPAIGN_ID=CAMPAIGN_IDСледующий запрос содержит две операции: первая отключает оптимизированную цену за клик в указанной кампании, а вторая пытается удалить кампанию с недействительным идентификатором. Поскольку для поля partialFailure задано значение true, первая операция выполняется успешно, а в поле partialFailureError возвращается ошибка для второй операции.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "partialFailure": true, "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" } ] } EOF
Сгруппированные операции
Метод googleAds:mutate поддерживает отправку групп операций с несколькими типами ресурсов. Вы можете отправить несколько операций разных типов, чтобы объединить в цепочку последовательность операций, которые должны выполняться как группа.
Набор операций выполняется успешно, если ни одна операция не завершается сбоем, или все операции завершаются сбоем, если хотя бы одна операция завершается сбоем.
В этом примере показано, как создать бюджет кампании, кампанию, группу объявлений и объявление за один набор действий. Каждая последующая операция зависит от предыдущей. Если одна из них не будет выполнена, то не будет выполнена вся группа.
Отрицательные целые числа (-1, -2, -3) используются в качестве плейсхолдеров в названиях ресурсов и динамически заполняются во время выполнения результатами последовательности операций.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "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" }, "name": "My Search campaign #${RANDOM}", "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/-1", "targetSpend": {}, "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING" } } }, { "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": [ { "pinnedField": "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" ] } } } } ] } EOF
Управление аккаунтом
Вы можете создавать аккаунты, просматривать список доступных аккаунтов и загружать двоичные объекты.
Создание аккаунтов
Создайте новые аккаунты с помощью метода createCustomerClient. Обратите внимание, что в URL нужно указать идентификатор управляющего аккаунта, а не клиентского. В управляющем аккаунте будет создан новый клиентский аккаунт.
curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "customerClient": { "descriptiveName": "Account created with CustomerService #${RANDOM}", "currencyCode": "USD", "timeZone": "America/New_York" } } EOF
Как получить список доступных аккаунтов
Чтобы получить список аккаунтов Google Рекламы, доступных с помощью определенного токена доступа OAuth 2.0, отправьте простой запрос GET к методу listAccessibleCustomers. В этом запросе не должны использоваться идентификаторы управляющих или клиентских аккаунтов.
curl -f --request GET \ "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"
Загрузка двоичных объектов
Используйте метод assets:mutate, чтобы загружать объекты и управлять ими. Закодируйте двоичные данные, например изображение, в виде строки Base64. API принимает стандартную или URL-безопасную кодировку base64 с заполнением или без него.
В этом примере кодируется GIF-изображение размером 1 пиксель, чтобы полезная нагрузка была небольшой. На практике полезная нагрузка data намного больше. Скачайте изображение и закодируйте его с помощью утилиты командной строки base64:
curl -sLO https://developers.google.com/google-ads/api/images/1pixel.gif
IMAGE_CONTENT="$(base64 < 1pixel.gif | tr -d '[:space:]')"Отправьте значение в кодировке Base64 в поле data запроса assets:mutate:
curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "imageAsset": { "data": "${IMAGE_CONTENT}" }, "name": "Marketing Image" } } ] } EOF