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

Структура вызова API

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

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

Google Ads API – это gRPC API с привязками REST. Это означает, что вызовы API можно выполнять двумя способами.

Предпочтительный вариант

Создайте тело запроса в виде буфера протокола.
Отправьте его на сервер с помощью HTTP/2.
Десериализовать ответ в буфер протокола.
Проанализируйте полученные данные.

В большинстве наших документов описывается использование gRPC.

Необязательно:

Создайте тело запроса в виде объекта JSON.
Отправьте его на сервер с помощью HTTP 1.1.
Десериализуйте ответ как объект JSON.
Проанализируйте полученные данные.

Подробную информацию об использовании REST можно найти в руководстве по интерфейсу REST.

Идентификаторы ресурсов

Объекты в Google Ads API адресуются с помощью структурированных названий ресурсов и составных идентификаторов.

Названия ресурсов

Большинство объектов в API идентифицируются по строкам с названиями ресурсов. Эти строки также используются в качестве URL при работе с интерфейсом REST. Их структура описана в разделе Названия ресурсов статьи об интерфейсе REST.

Составные идентификаторы

Если идентификатор объекта не является глобально уникальным, для него создается составной идентификатор, который получается путем добавления к идентификатору объекта идентификатора его родительского объекта и тильды (~).

Например, у AdGroupAd шаблон названия ресурса выглядит так: customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Поскольку составной идентификатор сочетает идентификатор родительской группы объявлений (ad_group.id) и идентификатор объявления (ad_group_ad.ad.id), мы добавляем идентификатор группы объявлений к идентификатору объявления:

AdGroupId из 123 + ~ + AdId из 45678 = составная группа объявлений идентификатор объявления 123~45678.

Заголовки запроса

Ниже перечислены HTTP-заголовки (или метаданные gRPC), которые сопровождают тело запроса:

Авторизация

Вам необходимо включить токен доступа OAuth 2.0 в форме Authorization: Bearer YOUR_ACCESS_TOKEN, который идентифицирует либо управляющий аккаунт, действующий от имени клиента, либо рекламодателя, напрямую управляющего собственным аккаунтом. Инструкции по получению токена доступа можно найти в руководстве по OAuth2. Срок действия токена доступа составляет один час. По истечении этого срока обновите токен доступа, чтобы получить новый. Обратите внимание, что наши клиентские библиотеки автоматически обновляют токены с истекшим сроком действия.

Если возникают ошибки авторизации, убедитесь, что вы используете правильные учетные данные и у вас достаточно разрешений. Ошибка USER_PERMISSION_DENIED означает, что у аутентифицированного пользователя может не быть доступа к аккаунту клиента, указанному в запросе. Если ваш облачный проект Google Cloud одобрен только для доступа к Test, а вы отправляете запрос к рабочему аккаунту, API возвращает ошибку AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION в версии 25 и более поздних или AuthorizationError.ACTION_NOT_PERMITTED в версии 24 и более ранних. Подробнее об уровнях доступа в Google Рекламе…

login-customer-id

Это идентификатор клиента, авторизованного для использования в запросе, без дефисов (-). Если доступ к клиентскому аккаунту осуществляется через управляющий аккаунт, этот заголовок обязателен и должен содержать идентификатор клиента управляющего аккаунта. Если при аутентификации через управляющий аккаунт не указать login-customer-id, возникнет ошибка AuthorizationError.USER_PERMISSION_DENIED. Подробнее о распространенных ошибках… Подробную информацию о том, как предоставляется доступ к аккаунту, можно найти в руководстве по модели доступа OAuth.

https://googleads.googleapis.com/v25/customers/1234567890/campaignBudgets:mutate

Установка значения login-customer-id аналогична выбору аккаунта в интерфейсе Google Рекламы после входа в систему или нажатия на изображение профиля в правом верхнем углу. Если вы не добавите этот заголовок, по умолчанию будет использоваться оператор.

linked-customer-id

Этот заголовок является обязательным и используется партнерами (например, сторонними поставщиками аналитики приложений или партнерами по данным) при работе со связанным аккаунтом Google Рекламы. В этом заголовке должен быть указан идентификатор клиента аккаунта Google Рекламы, в котором есть связь с продуктом.

Предположим, что партнеру нужно выполнять вызовы API в аккаунт Google Рекламы на основе связи с продуктом.

Рекламодатель. Аккаунт Google Рекламы, которым управляет или который обновляет вызов API. Идентификатор аккаунта рекламодателя указан в запросе. В REST это параметр пути customerId (например, customers/1111111111/...), а в gRPC – поле customer_id в запросе.
Партнер. Аккаунт партнера, например стороннего поставщика аналитики приложений или партнера по обработке данных.
Связанный аккаунт. Аккаунт Google Рекламы, в котором установлена связь с продуктом Партнера, предоставляющая Партнеру доступ к Рекламодателю.

Пользователь, у которого есть доступ к аккаунту Партнера, выполняет вызовы API, чтобы совершать действия с объектами в аккаунте Рекламодателя (например, загружать конверсии или управлять списками пользователей). Связанный аккаунт может быть аккаунтом рекламодателя или управляющим аккаунтом аккаунта рекламодателя.

Заголовки запроса должны быть заданы следующим образом:

Authorization – маркер доступа OAuth 2.0 для пользователя, у которого есть доступ к Partner.
login-customer-id – идентификатор клиента аккаунта партнера. У аутентифицированного пользователя должен быть доступ к этому аккаунту.
linked-customer-id – идентификатор клиента связанного аккаунта. Этот заголовок указывает, что авторизация для этого запроса основана на связи аккаунта с продуктом партнера.

Возможны два сценария связывания:

Если аккаунт рекламодателя напрямую связан с аккаунтом партнера, то в качестве связанного аккаунта указывается рекламодатель, а для параметра linked-customer-id необходимо задать идентификатор клиента аккаунта рекламодателя.
Если аккаунт Рекламодателя управляется управляющим аккаунтом, который связан с аккаунтом Партнера, то Связанный аккаунт – это управляющий аккаунт, а для параметра linked-customer-id необходимо указать идентификатор клиента управляющего аккаунта.

Пример 1. Прямая ссылка

Если аккаунт рекламодателя 1111111111 напрямую связан с аккаунтом партнера 2222222222 и вызов API направлен на customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Пример 2. Ссылка на управляющий аккаунт

Если аккаунт рекламодателя 1111111111 управляется управляющим аккаунтом 3333333333, управляющий аккаунт 3333333333 связан с аккаунтом партнера 2222222222, а вызов API предназначен для customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Заголовки ответа

Вместе с текстом ответа возвращаются следующие заголовки (или gRPC trailing-metadata). Мы рекомендуем регистрировать эти значения для отладки.

request-id

request-id – строка, которая однозначно идентифицирует запрос. Укажите это значение, когда обращаетесь в службу поддержки, чтобы помочь устранить неполадки с отклоненными или неожиданными запросами API.

Метаданные ресурса