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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, у 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/v26/customers/1234567890/campaignBudgets:mutate

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

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). Рекомендуем регистрировать эти значения для отладки.

request-id

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

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