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

Примеры

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

Предпосылки

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

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

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

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

API_VERSION="13"
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

В противном случае два примера Mutations — Creates создадут новый бюджет и кампанию.

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

Метод search использует разбиение на страницы с регулируемым параметром pageSize , указанным вместе с query .

CURL

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

ГАКЛ

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

ГАКЛ

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

В этом примере показано создание бюджета кампании, кампании, группы объявлений и объявления вместе как единого набора действий. Каждая последующая операция зависит от предыдущей. Если один из них терпит неудачу, вся группа операций терпит неудачу.

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 с отступами или без них.

Используйте утилиту командной строки 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'
      }
    }
  }
]
}"
Назад
Другие методы