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

Примеры

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

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

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

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

Предварительные требования

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

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

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

переменные окружающей среды

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

API_VERSION="23"
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'

Мутирует

В одном 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 "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 , все операции в запросе выполняются успешно только в том случае, если все они корректны.

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

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

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

Для получения списка аккаунтов Google Ads, доступных с помощью предоставленного токена доступа OAuth 2.0, используйте простой GET запрос к методу listAccessibleCustomers . В этом запросе не следует использовать идентификаторы аккаунтов менеджеров или клиентов.

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 ) для кодирования 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 "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

Мутирует

Создает

Обновления

Удаляет

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

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

Управление учетными записями

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

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

Загрузка бинарных файлов

Примеры