В этом руководстве приведены примеры прямого вызова конечных точек REST без использования клиентской библиотеки.
Предварительные условия
Все приведенные ниже примеры предназначены для копирования и вставки в оболочку bash с помощью команды Curl .
Вам также понадобится токен разработчика , возможен доступ к тестовому аккаунту и управляющий аккаунт Google Рекламы, содержащий хотя бы один клиентский аккаунт.
Переменные среды
Введите учетные данные и идентификаторы учетной записи ниже, а затем скопируйте и вставьте их в свой терминал, чтобы настроить переменные среды, используемые в последующих примерах. Руководство по авторизации содержит инструкции по созданию токена доступа 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"
Дополнительные необязательные идентификаторы объектов
Некоторые из следующих примеров применимы к уже существующим бюджетам или кампаниям. Если у вас есть идентификаторы существующих объектов, которые можно использовать в этих примерах, введите их ниже.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
В противном случае два примера Mutates – Creates создают новый бюджет и кампанию.
Поиск
Руководство по книге рецептов запросов содержит множество примеров отчетов, которые соответствуют некоторым экранам Google Рекламы по умолчанию и работают с теми же переменными среды, которые используются в этом руководстве. Наш инструмент интерактивного построения запросов также является отличным ресурсом для интерактивного создания пользовательских запросов.
с разбивкой на страницы
Метод search использует нумерацию страниц с настраиваемым параметром pageSize , указанным рядом с query .
КУЛЬ
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'
Потоковое вещание
Метод searchStream передает все результаты в один ответ, поэтому поле pageSize не поддерживается.
КУЛЬ
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'
Мутирует
Несколько операций изменения ( create , update или remove ) можно отправить в одном теле запроса JSON, заполнив массив operations .
Создает
В этом примере создаются два общих бюджета кампании в одном запросе.
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,
}
}
]
}"
В следующем примере используется BUDGET_ID существующего бюджета кампании; вы можете скопировать и вставить результаты предыдущего шага.
BUDGET_ID=BUDGET_ID
Ресурсы, которые ссылаются на другие ресурсы, делают это по имени ресурса . Кампания, созданная ниже, ссылается на campaignBudget по имени ресурса со строковым значением.
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': {}
}
}
]
}"
Обновления
Обновите атрибуты существующих объектов с помощью операций update . В следующем примере используется существующая кампания; вы можете скопировать и вставить результаты предыдущего шага.
CAMPAIGN_ID=CAMPAIGN_ID
Для всех обновлений требуется поле updateMask — список атрибутов JSON, разделенных запятыми, которые должны присутствовать в запросе, который должен применяться как обновление. Атрибуты, перечисленные в updateMask , но отсутствующие в теле запроса, удаляются для объекта. Атрибуты , не перечисленные в updateMask , но присутствующие в теле запроса, игнорируются.
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'
}
],
}"
Удаляет
Объекты удаляются путем указания имени их ресурса в качестве операции 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}'
}
],
}"
Частичные отказы
Если в одном запросе выполняется несколько операций, при необходимости укажите partialFailure . Если true , выполняются успешные операции, а недопустимые операции возвращают ошибки. Если false , все операции в запросе завершаются успешно тогда и только тогда, когда все они действительны.
В следующем примере используется существующая кампания; вы можете скопировать и вставить выходные данные примера Creates .
CAMPAIGN_ID=CAMPAIGN_ID
Следующий запрос содержит две операции. Первый пытается изменить стратегию назначения ставок указанной кампании, а следующий пытается удалить кампанию с неверным идентификатором. Поскольку вторая операция приводит к ошибке (идентификатор кампании недействителен) и поскольку для partialFailure установлено значение false , первая операция также завершается неудачно, и существующая стратегия назначения ставок кампании не обновляется.
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'
}
]
}"
Сгруппированные операции
Метод googleAds:mutate поддерживает отправку групп операций с несколькими типами ресурсов. Вы можете отправить множество операций разных типов, чтобы объединить последовательность операций, которые должны выполняться как группа. Набор операций завершается успешно, если ни одна операция не завершается сбоем, или все операции завершаются неудачно, если какая-либо отдельная операция завершается неудачно.
В этом примере показано создание бюджета кампании, кампании, группы объявлений и объявления как единого набора действий. Каждая последующая операция зависит от предыдущей. Если одна из них терпит неудачу, то вся группа операций терпит неудачу.
Отрицательные целые числа ( -1 , -2 , -3 ) используются в качестве заполнителей в именах ресурсов и динамически заполняются во время выполнения результатами последовательности операций.
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']
}
}
}
}
]
}"
Управление аккаунтом
Создание учетных записей
Создайте новые учетные записи, используя метод createCustomerClient . Обратите внимание, что для URL-адреса требуется идентификатор управляющего аккаунта , а не идентификатор клиентского аккаунта. Под управляющим аккаунтом создается новый клиентский аккаунт.
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'
}
}"
Список доступных аккаунтов
Используйте простой запрос GET к методу listAccessibleCustomers , чтобы получить список аккаунтов Google Рекламы, доступных с помощью данного токена доступа OAuth 2.0. В этом запросе нельзя использовать идентификаторы управляющего или клиентского аккаунта.
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}" \
Загрузка бинарных активов
Метод assets:mutate используется для загрузки и управления ресурсами . Двоичные данные, такие как изображение, кодируются как строка с использованием стандартной кодировки base64 с дополнением. Принимается стандартная или URL-безопасная кодировка Base64 с заполнением или без него.
В этом примере кодируется 1-пиксельный GIF-файл, чтобы образец был кратким. На практике полезная нагрузка data намного больше.
Используйте утилиту командной строки base64 (часть основных утилит GNU ) для кодирования 1-пиксельного изображения GIF .
base64 1pixel.gif
Значение в кодировке Base64 указывается как атрибут data в запросе 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'
}
}
}
]
}"