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

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

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

Объекты в Google Ads API адресуются с помощью структурированных названий ресурсов и составных идентификаторов.

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

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

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

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

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

Например, у ресурса AdGroupAd шаблон названия выглядит так: customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Поскольку составной идентификатор объединяет идентификатор родительской группы объявлений (ad_group.id) и идентификатор объявления (ad_group_ad.ad.id), мы добавляем идентификатор группы объявлений перед идентификатором объявления:

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

Примечание. Использовать один и тот же AdId в нескольких группах объявлений запрещено. Если вы попытаетесь создать новый объект AdGroupAd, который ссылается на существующий объект AdId в другой группе объявлений, то получите ошибку AdGroupAdError.AD_SHARING_NOT_ALLOWED.

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

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

Авторизация

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

Если вы столкнулись с ошибками авторизации, убедитесь, что вы используете правильные учетные данные и у вас есть достаточные разрешения. Ошибка USER_PERMISSION_DENIED указывает на то, что у аутентифицированного пользователя может не быть доступа к аккаунту клиента, указанному в запросе. Если ваш облачный проект Google Cloud одобрен только для доступа к Test и вы отправляете запрос, предназначенный для рабочего аккаунта, API возвращает AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION в версии 25 и более поздних (или AuthorizationError.ACTION_NOT_PERMITTED в версии 24 и более ранних). Подробнее об уровнях доступа в Google Рекламе…

login-customer-id

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

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

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

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

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

linked-customer-id

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

Рассмотрим сценарий, в котором партнеру нужно выполнить вызовы API к аккаунту Google Рекламы на основе связи с продуктом.

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

Пользователь, у которого есть доступ к аккаунту партнера, выполняет вызовы 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): Рекомендуем регистрировать эти значения для отладки.

request-id

request-id – это строка, которая уникальным образом идентифицирует этот запрос. Укажите это значение при обращении в службу поддержки, чтобы помочь устранить неполадки, связанные с неудачными или непредвиденными запросами API.