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

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

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

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

1. [Предпочтительно] Создайте тело запроса в виде буфера протокола , отправьте его на сервер с помощью HTTP/2 , десериализуйте ответ в буфер протокола и интерпретируйте результаты. Большая часть нашей документации описывает использование gRPC.

2. [Необязательно] Создайте тело запроса в виде объекта JSON , отправьте его на сервер с помощью HTTP 1.1, десериализуйте ответ как объект JSON и интерпретируйте результаты. Дополнительную информацию об использовании REST см. в руководстве по интерфейсу REST .

Примечание. В этом руководстве описаны структура и транспортные заголовки, общие для протоколов gRPC и REST.

Имена ресурсов

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

Ключевой момент: ознакомьтесь с документацией по ресурсам , чтобы узнать обо всех поддерживаемых ресурсах и их пути ( resource_name ). Тот же формат используется для других сервисов.

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

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

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

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

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

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

Авторизация

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

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

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

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

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

Ключевой термин: Действующий клиент — это идентификатор клиента в полезных данных запроса. Например, действующий клиент в следующем запросе CampaignBudgetService — 1234567890 :

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

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

Примечание. Вы можете получить список учетных записей, к которым доступен прямой доступ с вашими учетными данными OAuth, выполнив запрос CustomerService.ListAccessibleCustomers . login-customer-id не требуется для этого типа запроса и не влияет на возвращаемый список клиентов.

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

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

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

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

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

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

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

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

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