Примеры

В этом руководстве приведены примеры прямого вызова конечных точек 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