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

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

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

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

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

1. Создайте тело запроса как буфер протокола .

2. Отправьте его на сервер по протоколу HTTP/2 .

3. Десериализуйте ответ в буфер протокола.

4. Интерпретируйте результаты.

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

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

1. Создайте тело запроса как JSON -объект.

2. Отправьте его на сервер, используя HTTP 1.1.

3. Десериализуйте ответ как объект JSON.

4. Интерпретируйте результаты.

Дополнительную информацию об использовании 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 Ads. Пример строки токена разработчика: ABcdeFGH93KL-NOPQ_STUv . Токен разработчика должен быть указан в формате developer-token : ABcdeFGH93KL-NOPQ_STUv .

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

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

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

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

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

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

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

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