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

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

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

Google Ads API — это gRPC API с REST-привязками. Это означает, что существует два способа обращения к API.

Предпочтительно :

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

Большая часть нашей документации описывает использование gRPC .

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

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

Для получения дополнительной информации об использовании REST обратитесь к руководству по REST-интерфейсу .

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

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

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

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

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

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

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

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

Авторизация

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

Если вы столкнулись с ошибками авторизации, убедитесь, что используете правильные учетные данные и имеете достаточные права доступа. Ошибка USER_PERMISSION_DENIED указывает на то, что авторизованный пользователь может не иметь доступа к учетной записи клиента, указанной в запросе. Подробную информацию об управлении правами доступа см. в разделе «Уровни доступа Google Ads» .

login-customer-id

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

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

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

связанный-идентификатор-клиента

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

Рассмотрим ситуацию, когда партнеру необходимо совершать API-запросы к аккаунту Google Ads на основе ссылки на товар.

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

Пользователь, имеющий доступ к партнерскому аккаунту, выполняет вызовы 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 — это строка, которая однозначно идентифицирует данный запрос.

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