Структура вызова 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-интерфейсу .

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

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

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

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

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

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

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

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

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

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

Авторизация

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

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

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

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

login-customer-id

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

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

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

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

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

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

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

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

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

Пользователь, имеющий доступ к Partner, выполняет вызовы API для работы с объектами в Advertiser (например, для загрузки данных о конверсиях или управления списками пользователей). Связанный аккаунт может принадлежать самому Advertiser или управляющему аккаунту Advertiser.

Заголовки запроса должны быть установлены следующим образом:

• Authorization : токен OAuth2 для пользователя, имеющего доступ к Partner.
• developer-token : Токен разработчика для API-приложения, обычно связанный с Партнером.
• login-customer-id : Идентификатор клиента партнера. Авторизованный пользователь должен иметь доступ к этой учетной записи.
• linked-customer-id : Идентификатор клиента связанной учетной записи. Этот заголовок указывает на то, что авторизация для данного запроса зависит от связи продукта связанной учетной записи с партнером.

Существует два сценария связывания:

• Если у рекламодателя есть прямая связь продукта с партнером, то связанным аккаунтом является рекламодатель, а linked-customer-id должен быть установлен на идентификатор клиента рекламодателя.
• Если рекламодатель управляется учетной записью менеджера, которая связана продуктом с партнером, то связанной учетной записью является учетная запись менеджера, а linked-customer-id должен быть установлен на идентификатор клиента менеджера.

Пример 1: Прямая ссылка

Если у рекламодателя 1111111111 есть прямая связь с партнером 2222222222 , и вызов API нацелен на customers/1111111111/... :

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Пример 2: Ссылка на менеджера

Если рекламодатель 1111111111 управляется менеджером 3333333333 , то менеджер 3333333333 имеет связь с партнером 2222222222 , и вызов API нацелен на customers/1111111111/... :

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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

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

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

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