Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Примеры

В этом руководстве приведены примеры прямого вызова конечных точек REST без использования клиентской библиотеки.

Более подробные примеры кода REST можно найти в репозитории GitHub.

Чтобы посмотреть тела запросов и ответов для каждого метода API, ознакомьтесь со справочной документацией по конкретным конечным точкам сервиса.

Например, на справочной странице для GoogleAdsService.Search показаны тела запроса и ответа для метода Search.

Требования

Все приведенные здесь примеры предназначены для копирования и вставки в оболочку bash с помощью команды curl.

Вам также потребуется проект Google Cloud (достаточно доступа к тестовому аккаунту) и управляющий аккаунт Google Рекламы, содержащий хотя бы один клиентский аккаунт.

Важно! В этих примерах предполагается, что вы входите в клиентский аккаунт (CUSTOMER_ID) как пользователь с правами администратора управляющего аккаунта (MANAGER_CUSTOMER_ID), который непосредственно управляет клиентским аккаунтом. Если вы получаете доступ к отдельному клиентскому аккаунту напрямую, не указывайте заголовок login-customer-id или задайте для него то же значение, что и для CUSTOMER_ID. Обратите внимание, что для некоторых примеров, таких как Создание аккаунтов, требуется управляющий аккаунт.

Переменные среды

Введите учетные данные аккаунта и идентификаторы, как показано на изображении, а затем скопируйте и вставьте их в терминал, чтобы настроить переменные среды, используемые в следующих примерах. Инструкции по созданию токена доступа 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.

curl

curl -f --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 '{
"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'

Потоковая передача

Метод searchStream передает все результаты в одном ответе, поэтому поле pageSize не поддерживается.

curl

curl -f --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 '{
"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'

Изменения

В одном теле запроса JSON можно отправить несколько операций изменения (create, update или remove), заполнив массив operations.

Создает

В этом примере в одном запросе создаются два общих бюджета кампании.

curl -f --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 "{
'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 "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 "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 "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
  }
],
}"

Частичные сбои

Если в одном запросе несколько операций, можно указать partialFailure. Если задано значение true, то выполняются только допустимые операции, а недопустимые возвращают ошибки. Если задано значение false, все операции в запросе будут выполнены, только если они все действительны.

В следующем примере используется существующая кампания. Вы можете скопировать и вставить выходные данные из примера Создание.

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 "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 "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 "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'customerClient': {
  'descriptiveName': 'My Client #${RANDOM}',
  'currencyCode': 'USD',
  'timeZone': 'America/New_York'
}
}"

Как получить список доступных аккаунтов

Чтобы получить список аккаунтов 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 с заполнением. Принимается стандартная или безопасная для URL кодировка base64 с заполнением или без него.

В этом примере для краткости закодирован GIF-файл размером 1 пиксель. На практике полезная нагрузка data намного больше.

Используйте утилиту командной строки base64 (входит в состав GNU core utilities), чтобы закодировать GIF-изображение размером 1 пиксель.

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 "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'
      }
    }
  }
]
}"

Распространенные ошибки

Попробовать

Примеры Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Требования

Переменные среды

Дополнительные необязательные идентификаторы объектов

Поиск

Разбивка на страницы

curl

GAQL

Потоковая передача

curl

GAQL

Изменения

Создает

Обновления

Удаление

Частичные сбои

Сгруппированные операции

Управление аккаунтом

Создание аккаунтов

Как получить список доступных аккаунтов

Загрузка двоичных объектов

Примеры