Делайте прямые запросы

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

Стиль вызова

REST — это стиль программной архитектуры, обеспечивающий удобный и согласованный подход к запросу и изменению данных.

Термин REST расшифровывается как « Representational State Transfer» (передача репрезентативного состояния ). В контексте API Google это означает использование HTTP-глаголов для получения и изменения представлений данных, хранящихся в Google.

В RESTful-системе ресурсы хранятся в хранилище данных; клиент отправляет запрос серверу на выполнение определенного действия (например, создание, получение, обновление или удаление ресурса), а сервер выполняет действие и отправляет ответ, часто в виде представления указанного ресурса.

В RESTful API от Google клиент указывает действие, используя HTTP-глагол, такой как POST , GET , PUT или DELETE . Он указывает ресурс с помощью глобально уникального URI следующего вида:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Поскольку все ресурсы API имеют уникальные URI, доступные по протоколу HTTP, REST обеспечивает кэширование данных и оптимизирован для работы с распределенной инфраструктурой сети.

Возможно, вам пригодятся определения методов в документации по стандартам HTTP 1.1; они включают спецификации для GET , POST , PUT и DELETE .

REST в API управления AdSense

Поддерживаемые операции напрямую соответствуют HTTP-глаголам REST.

Конкретный формат URI для API управления AdSense следующий:

https://adsense.googleapis.com/v2/resourceID?parameters

где resourceID — это идентификатор рекламного клиента, рекламного блока, URL-канала, пользовательского канала или коллекции отчетов, а parameters — любые параметры, применяемые к запросу.

Формат расширений пути resourceID позволяет идентифицировать ресурс, с которым вы в данный момент работаете, например:

https://adsense.googleapis.com/v2/accounts/account_id/adclients
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels
...

Полный набор URI, используемых для каждой поддерживаемой операции в API, приведен в справочном документе по API управления AdSense .

Вот несколько примеров того, как это работает в API управления AdSense.

Список рекламных клиентов:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/

Список рекламных блоков в рекламном клиенте ca-pub-1234567890123456:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits

Формат данных

JSON (JavaScript Object Notation) — это распространённый, независимый от языка формат данных, предоставляющий простое текстовое представление произвольных структур данных. Для получения дополнительной информации см. json.org .

Авторизация запросов

Обратите внимание, что AdSense не поддерживает служебные аккаунты; вместо этого необходимо использовать схему установленных приложений.

Каждый запрос, отправляемый вашим приложением в API управления AdSense, должен включать токен авторизации. Этот токен также идентифицирует ваше приложение для Google.

О протоколах авторизации

Для авторизации запросов ваше приложение должно использовать OAuth 2.0 . Другие протоколы авторизации не поддерживаются. Если ваше приложение использует вход через Google , некоторые аспекты авторизации обрабатываются автоматически.

Авторизация запросов с использованием OAuth 2.0

Все запросы к API управления AdSense должны быть авторизованы аутентифицированным пользователем.

Этот процесс упрощается благодаря использованию идентификатора клиента OAuth.

Получите идентификатор клиента OAuth.

Или создайте учетные данные на странице «Учетные данные» .

Детали процесса авторизации, или «потока», для OAuth 2.0 несколько различаются в зависимости от типа разрабатываемого приложения. Следующий общий процесс применим ко всем типам приложений:

  1. Когда вашему приложению требуется доступ к пользовательским данным, оно запрашивает у Google определенный объем доступа.
  2. Google отображает пользователю экран согласия , в котором ему предлагается разрешить вашему приложению запрашивать некоторые из его данных.
  3. Если пользователь одобрит запрос, Google предоставит вашему приложению кратковременный токен доступа .
  4. Ваше приложение запрашивает данные пользователя, прикрепляя к запросу токен доступа.
  5. Если Google определит, что ваш запрос и токен действительны, он вернет запрошенные данные.

Некоторые сценарии включают дополнительные шаги, например, использование токенов обновления для получения новых токенов доступа. Подробную информацию о сценариях для различных типов приложений см. в документации Google по OAuth 2.0 .

Вот информация об области действия OAuth 2.0 для API управления AdSense:

Объем Значение
https://www.googleapis.com/auth/adsense Доступ на чтение/запись к данным AdSense.
https://www.googleapis.com/auth/adsense.readonly Доступ к данным AdSense только для чтения.

Для запроса доступа с использованием OAuth 2.0 вашему приложению необходима информация об области действия, а также информация, которую Google предоставляет при регистрации вашего приложения (например, идентификатор клиента и секретный ключ клиента).

Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the page with libraries and samples for more details.

Отправка запроса

Последний шаг — отправка запроса к API. Подробную информацию см. в справочной документации .