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

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

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

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

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

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

  • 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 . Для получения дополнительной информации об этом типе ошибки см. раздел «Распространенные ошибки ».

https://googleads.googleapis.com/v22/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 — это строка, которая однозначно идентифицирует данный запрос.

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