Начало работы

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

Содержание

Подготовка

Создание аккаунта AdSense

Для тестирования вам будет необходим аккаунт AdSense. Если у вас уже есть тестовый аккаунт, никаких дополнительных действий не потребуется. Создавать, менять и просматривать тестовые данные можно в пользовательском интерфейсе AdSense.

Знакомство с AdSense

Если вы не знакомы с основными понятиями AdSense, изучите краткое описание и пользовательский интерфейс, прежде чем приступить к составлению кода.

Регистрация приложения

Чтобы приступить к использованию API хостов AdSense, необходимо зарегистрировать разрабатываемое приложение в Google. Для этого:

  1. Откройте консоль API.
  2. Войдите в свой аккаунт Google или создайте новый.
  3. Создайте проект.
  4. Нажмите на ссылку Request access (Запросить доступ) в строке API хостов AdSense для этого проекта.

Для приложений, в которых используется OAuth 2.0, выполните также дополнительные инструкции, описанные на этой странице.

Примечание. Для регистрации необходимо использовать свой аккаунт разработчика. Адрес этого аккаунта Google будут видеть пользователи вашего приложения. Он может быть не связан с AdSense, так как пользователи будут использовать приложение для доступа только к собственным данным.

Общее представление об API хостов AdSense

Основные понятия

В API хостов AdSense используются базовые понятия AdSense.

  • Рекламные клиенты обеспечивают связь между аккаунтом и продуктом AdSense (например, для контента или для поиска). В аккаунте AdSense может быть несколько рекламных клиентов.
  • Каналы – инструменты, позволяющие отслеживать эффективность отдельных страниц и доменов.
  • Отчеты дают представление о доходе и влияющих на него факторах. С помощью каналов можно создавать отчеты как по всему аккаунту, так и по любому набору интересующих вас ресурсов.

Поддерживаемые операции

В таблице ниже описаны все операции, которые в настоящее время поддерживаются в API.

Операция Описание Соответствие в REST HTTP
list Перечисление всех ресурсов в коллекции. GET для URI коллекции.
get Получение определенного ресурса. GET для URI ресурса.
generate Создание набора результатов на основе определенного ресурса (используется только для отчетов). GET/POST для URI коллекции (ресурс передается как определение для создания).

Все операции выполняются только при условии успешной аутентификации.

Стиль вызовов

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

REST – это сокращение от Representational State Transfer (передача состояния представления). В API Google система REST позволяет использовать методы HTTP для извлечения и изменения представлений данных, сохраняемых Google.

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

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

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

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

Подробнее о REST читайте на следующих ресурсах:


Использование REST в API хостов AdSense

Поддерживаемые операции напрямую соответствуют методам REST HTTP, как описано в этом разделе.

Для URI в API хостов AdSense используется следующий формат:

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

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

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

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

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

Ниже приведен пример того, как это работает в API хостов AdSense.

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

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

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

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

Выполнение запросов

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

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

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

Для авторизации запросов ваше приложение должно использовать протокол OAuth 2.0. Никакие другие протоколы авторизации не поддерживаются.

Авторизация запросов с помощью OAuth 2.0

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

Особенности процесса авторизации с помощью OAuth 2.0 зависят от типа приложения. В общих чертах процедура выглядит так:

  1. Создавая приложение, зарегистрируйте его в Google. Вы получите информацию, которая пригодится позже, например идентификатор и секретный ключ клиента.
  2. Активируйте API хостов AdSense с помощью Консоли Google Developers (если такого API там нет, пропустите этот шаг).
  3. Когда приложению необходимы пользовательские данные, оно запрашивает у Google определенную область доступа.
  4. Google показывает пользователю диалоговое окно с просьбой авторизовать приложение для запроса этих данных.
  5. Если пользователь соглашается, Google предоставляет приложению токен доступа с коротким сроком действия.
  6. Ваше приложение запрашивает пользовательские данные, указывая токен доступа.
  7. Получив действительный запрос и токен, Google возвращает необходимые данные.

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

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

Диапазон Назначение
https://www.googleapis.com/auth/adsensehost Доступ к данным AdSense с правом на чтение и запись.

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

Совет. Клиентские библиотеки API Google автоматически выполняют часть задач, связанных с авторизацией. Они доступны для различных языков программирования. Дополнительную информацию можно получить на странице Библиотеки и примеры кода.

Подробнее о протоколе OAuth 2.0…

Выполнение запроса

Последний этап – выполнение запроса API. Если вы не используете клиентские библиотеки, ознакомьтесь со справочной документацией.

Если вы используете клиентские библиотеки, задача существенно упрощается. Подробнее о том, как выполнять запросы с помощью клиентских библиотек Java, Python, PHP и JavaScript, читайте в разделе Библиотеки и примеры кода.

OAuth 2.0

Аутентификация и авторизация в API хостов AdSense осуществляются по протоколу OAuth 2.0. Однако в силу некоторой специфики API хостов AdSense процесс немного отличается от принятого в других API Google.

Участники

В обработке запроса OAuth 2.0 принимают участие три стороны:

  • пользователь, предоставляющий доступ к своим личным данным;
  • разработчик, запрашивающий через приложение доступ к личным данным пользователя;
  • компания Google, которая выполняет аутентификацию всех участвующих сторон и предоставляет доступ к API.

Однако в случае API хостов AdSense пользователь и разработчик являются одним лицом: вы как разработчик будете использовать API для доступа к собственному пользовательскому аккаунту AdSense, а через него – к аккаунтам издателей.

Создание проекта

Новые проекты создаются в консоли API.
Рис. 1. Создание проекта с помощью консоли API

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

На вкладке Services (Службы) вы можете выбрать активные API проекта.
Рис. 2. Активация и отключение API для проекта

Более подробную информацию о создании проектов API вы можете найти в документации к консоли API.

Настройка доступа к API

Теперь, когда у вас есть проект, нужно открыть для него доступ к API, создав идентификатор клиента OAuth 2.0.

Клиентов OAuth 2.0 можно создавать на вкладке API Access (Доступ к API).
Рис. 3. Создание нового клиента OAuth 2.0 с помощью консоли API

Рекомендуем среди всех доступных на этом шаге вариантов выбрать проект Installed Application (Установленное приложение) – это упростит дальнейшую работу.

Однократная аутентификация на неограниченный срок

Для аутентификации вам нужно будет использовать данные собственного аккаунта AdSense. Это можно сделать с помощью небольшого скрипта или тестового приложения (см. примеры кода).

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

Сохраните токен обновления в хранилище данных приложения, чтобы использовать его во всех будущих запросах на аутентификацию.

Использование сохраненного токена в приложении

Теперь, когда у вас есть токен обновления, больше не важно, какой тип приложения вы выбрали: Web Server Application (Приложение для веб-сервера) или Installed Application (Установленное приложение). По мере надобности вы можете создавать новые токены доступа, отправляя запросы на основе токена обновления. Если вы используете одну из клиентских библиотек, в документации к ней вы найдете информацию о предоставлении собственных токенов. Возможно, вам понадобится кое-что изменить в автоматически созданном файле или записи в базе данных.

Конечный результат

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

Уведомления

Следите за нашими объявлениями о выходе новых версий, функций и обновлений.

Оставить отзыв о...

Текущей странице
AdSense Host API
AdSense Host API