Структура вызова 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 .

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

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

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

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

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

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

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

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

Авторизация

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

токен разработчика

Токен разработчика — это строка из 22 символов, которая однозначно идентифицирует разработчика API Google Ads. Пример строки токена разработчика — ABcdeFGH93KL-NOPQ_STUv . Токен разработчика должен быть включен в форме developer-token : ABcdeFGH93KL-NOPQ_STUv .

логин-идентификатор-клиента

Это идентификатор клиента авторизованного клиента для использования в запросе, без дефисов ( - ). Если ваш доступ к учетной записи клиента осуществляется через учетную запись менеджера, этот заголовок является обязательным и должен быть установлен на идентификатор клиента учетной записи менеджера.

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

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

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

Этот заголовок используется только сторонними поставщиками аналитики приложений при загрузке конверсий в связанный аккаунт Google Ads .

Рассмотрим сценарий, в котором пользователи учетной записи A предоставляют доступ на чтение и редактирование своих сущностей учетной записи B через ThirdPartyAppAnalyticsLink . После привязки пользователь учетной записи B может выполнять вызовы API к учетной записи A в соответствии с разрешениями, предоставленными ссылкой. В этом случае разрешения на вызовы API для учетной записи A определяются сторонней ссылкой на учетную запись B , а не отношениями менеджер-учетная запись, которые используются в других вызовах API.

Сторонний поставщик аналитики приложений выполняет вызов API следующим образом:

  • linked-customer-id : учетная запись аналитики стороннего приложения, которая загружает данные (учетная запись B ).
  • customer-id : аккаунт Google Ads, в который загружаются данные (аккаунт A ).
  • login-customer-id и заголовок Authorization : комбинация значений для идентификации пользователя, имеющего доступ к учетной записи B

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

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

запрос-идентификатор

request-id — это строка, которая уникально идентифицирует этот запрос.

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