Внимание! Вы просматриваете документацию по интерфейсу REST API. Большинство наших официальных клиентских библиотек используют gRPC. Подробнее см. в разделе Введение в REST .

Эта страница переведена с помощью Cloud Translation API.

Примеры

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

Предпосылки

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

Вам также понадобится токен разработчика , тестовый доступ к аккаунту и аккаунт менеджера Google Ads, содержащий как минимум один клиентский аккаунт.

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

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

Введите учётные данные и идентификаторы, как показано, а затем скопируйте и вставьте их в терминал, чтобы настроить переменные среды, используемые в последующих примерах. Руководство по авторизации содержит инструкции по созданию токена доступа OAuth 2.0.

API_VERSION="20"
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 создают новый бюджет и кампанию.

Поиск

Руководство «Query Cookbook» содержит множество примеров отчётов, соответствующих некоторым стандартным экранам Google Ads и работающих с теми же переменными среды, которые используются в этом руководстве. Наш интерактивный конструктор запросов также является отличным ресурсом для интерактивного создания собственных запросов.

Пронумеровано

Метод search использует пагинацию с фиксированным размером страницы в 10 000 элементов и токеном page_token указанным вместе с 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 '{
"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 -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 Ads, доступных с заданным токеном доступа 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 с заполнением или без него.

В этом примере для краткости кодируется GIF-изображение размером в 1 пиксель. На практике объём 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'
      }
    }
  }
]
}"

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

Попробовать

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

Предпосылки

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

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

Поиск

Пронумеровано

завиток

GAQL

завиток

GAQL

Мутирует

Создает

Обновления

Удаляет

Частичные отказы

Групповые операции

Управление счетами

Создать учетные записи

Список доступных учетных записей

Загрузить бинарные активы

Примеры