Первый вызов API

В этом руководстве мы рассмотрим, как осуществить первый вызов интерфейса AdWords API. Это откроет вам доступ ко всем его возможностям.

В видео рассматриваются Java и Eclipse, но вы можете использовать любой язык и клиентскую библиотеку. Ниже приведены инструкции для всех поддерживаемых языков.

Общие сведения

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

После настройки файла конфигурации можно осуществлять вызовы API.

Вот шесть основных шагов, которые нужно выполнить:

  1. Запрос токена разработчика.
  2. Создание тестовых аккаунтов.
  3. Получение клиентской библиотеки.
  4. Настройка аутентификации через OAuth2.
  5. Получение токена обновления OAuth2 и настройка клиента.
  6. Выполнение первого вызова API.

Эти шаги подробно описаны ниже.

Запрос токена разработчика

Токен разработчика от Google обеспечивает связь приложения с AdWords API. Чтобы запросить токен разработчика, следуйте инструкциям в руководстве по регистрации (если вы ещё этого не сделали). После регистрации вы получите токен разработчика, ожидающий рассмотрения.

Прежде чем вы сможете использовать токен разработчика с рабочими аккаунтами AdWords, он должен быть одобрен.

Создание тестовых аккаунтов

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

  1. Перейдите на страницу управляющих аккаунтов AdWords и создайте тестовый управляющий аккаунт.
  2. Создайте тестовый клиентский аккаунт в тестовом управляющем аккаунте через веб-интерфейс AdWords. Все клиентские аккаунты, которые создаются в тестовом управляющем аккаунте, автоматически становятся тестовыми.
  3. Создайте несколько тестовых кампаний в тестовом клиентском аккаунте через веб-интерфейс AdWords.
  4. Запишите идентификатор клиента для нового тестового клиентского аккаунта. Его нужно будет добавить в файл конфигурации позже. Идентификатор клиента представлен ниже.

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

Получение клиентской библиотеки

Клиентские библиотеки обрабатывают все серверные вызовы API и предоставляют подходящие объекты, в том числе примеры кода, практически для всех основных задач в работе с API.

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

Выберите используемый язык ниже и следуйте инструкциям.

Java

  1. Перейдите в раздел Начало работы файла README для клиентской библиотеки Java на портале GitHub, после чего скачайте и установите клиентскую библиотеку AdWords API для Java.
  2. Вернитесь на эту страницу, прежде чем настраивать учетные данные OAuth2. Мы сделаем это на следующем шаге.

.NET

  1. Перейдите в раздел Начало работы файла README для клиентской библиотеки .NET, после чего скачайте и установите клиентскую библиотеку AdWords API для CSharp или Visual Basic.
  2. Вернитесь на эту страницу, прежде чем настраивать учетные данные OAuth2. Мы сделаем это на следующем шаге.

Python

  1. Перейдите в раздел Начало работы файла README для клиентской библиотеки Python, после чего скачайте и установите клиентскую библиотеку AdWords API для Python.
  2. Вернитесь на эту страницу, прежде чем настраивать учетные данные OAuth2. Мы сделаем это на следующем шаге.

PHP

  1. Перейдите в раздел Начало работы файла README для клиентской библиотеки PHP, после чего скачайте и установите клиентскую библиотеку AdWords API для PHP.
  2. Вернитесь на эту страницу, прежде чем настраивать учетные данные OAuth2. Мы сделаем это на следующем шаге.

Perl

  1. Перейдите в раздел Начало работы файла README для клиентской библиотеки Perl, после чего скачайте и установите клиентскую библиотеку AdWords API для Perl.
  2. Вернитесь на эту страницу, прежде чем настраивать учетные данные OAuth2. Мы сделаем это на следующем шаге.

Ruby

  1. Перейдите в раздел Начало работы файла README для клиентской библиотеки Ruby, после чего скачайте и установите клиентскую библиотеку AdWords API для Ruby.
  2. Вернитесь на эту страницу, прежде чем настраивать учетные данные OAuth2. Мы сделаем это на следующем шаге.

Настройка аутентификации через OAuth2

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

Чтобы настроить доступ приложения к API, вам потребуется идентификатор и секретный ключ клиента OAuth2.

  1. Войдите в управляющий аккаунт и откройте страницу Учетные данные в Google Developers Console.
  2. В раскрывающемся меню проектов выберите Создать проект, затем укажите название проекта и нажмите кнопку Создать.
  3. Выберите Создать учетные данные, а затем – Идентификатор клиента OAuth.
  4. Вам может быть предложено указать название продукта. В этом случае нажмите Настроить окно запроса доступа, укажите запрашиваемую информацию и нажмите Сохранить, чтобы вернуться к экрану Учетные данные.
  5. В разделе Тип приложения выберите Другие типы. Укажите название в появившемся поле.
  6. Нажмите кнопку Создать. Появятся идентификатор и секретный ключ клиента OAuth2. Скопируйте и сохраните их. На следующем шаге их нужно будет добавить в файл конфигурации.

Получение токена обновления OAuth2 и настройка клиента

Поскольку доступ через OAuth2 предоставляется на ограниченное время, для его автоматического продления используется токен обновления OAuth2.

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

Java

  1. Следуйте инструкциям на портале GitHub, чтобы получить токен обновления OAuth2 и настроить клиентскую библиотеку.
  2. По завершении вернитесь на эту страницу. Теперь ваш файл ads.properties должен иметь все необходимое для выполнения тестовых вызовов API и содержать примерно следующие значения:
[...]
api.adwords.developerToken=123axxxxxxxxxxxxxxxxxx
api.adwords.clientId=xxxxxxxxxx.apps.googleusercontent.com
api.adwords.clientSecret=zZxxxxxTxxxxxxxxxxx
api.adwords.clientCustomerId=123-456-7890
api.adwords.refreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
api.adwords.userAgent=Company_Name
[...]

.NET

  1. Следуйте инструкциям на портале GitHub, чтобы получить токен обновления OAuth2 и настроить клиентскую библиотеку.
  2. По завершении вернитесь на эту страницу. Теперь ваш файл app.config должен иметь все необходимое для выполнения тестовых вызовов API и содержать примерно следующие значения:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="AdWordsApi"
        type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <AdWordsApi>
    <!-- Settings specific to AdWords API.-->
    <add key="UserAgent" value="My AdWords API application"/>
    <add key="DeveloperToken" value="xxxxxxxxxxxxxxxxxxxxxx"/>
    <add key="ClientCustomerId" value="123-456-7890"/>

    <!-- OAuth2 configuration -->
    <add key="AuthorizationMethod" value="OAuth2" />
    <add key="OAuth2ClientId" value="xxxxxxxxxx.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="zZxxxxxTxxxxxxxxxxx" />
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2RefreshToken" value="1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxx" />
  </AdWordsApi>
</configuration>

Python

  1. Следуйте инструкциям на портале GitHub, чтобы получить токен обновления OAuth2 и настроить клиентскую библиотеку.
  2. По завершении вернитесь на эту страницу. Теперь ваш файл googleads.yaml должен иметь все необходимое для выполнения тестовых вызовов API и содержать примерно следующие значения:
adwords:
  developer_token: 123axxxxxxxxxxxxxxxxxx
  user_agent: Company_Name
  client_customer_id: 123-456-7890
  client_id: xxxxxxxxxx.apps.googleusercontent.com
  client_secret: zZxxxxxTxxxxxxxxxxx
  refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

PHP

  1. Следуйте инструкциям на портале GitHub, чтобы получить токен обновления OAuth2 и настроить клиентскую библиотеку.
  2. По завершении вернитесь на эту страницу. Теперь ваш файл auth.ini должен иметь все необходимое для выполнения тестовых вызовов API и содержать примерно следующие значения:
[...]
developerToken = 123axxxxxxxxxxxxxxxxxx
userAgent = Company_Name
clientCustomerId = 123-456-7890
client_id = xxxxxxxxxx.apps.googleusercontent.com
client_secret = zZxxxxxTxxxxxxxxxxx
refresh_token = 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Perl

  1. Следуйте инструкциям на портале GitHub, чтобы получить токен обновления OAuth2 и настроить клиентскую библиотеку.
  2. По завершении вернитесь на эту страницу. Теперь ваш файл adwords.properties должен иметь все необходимое для выполнения тестовых вызовов API и содержать примерно следующие значения:
[...]
userAgent = Company_Name
developerToken=123axxxxxxxxxxxxxxxxxx
clientId=123-456-7890
oAuth2ClientId=xxxxxxxxxx.apps.googleusercontent.com
oAuth2ClientSecret=zZxxxxxTxxxxxxxxxxx
oAuth2RefreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Ruby

  1. Следуйте инструкциям на портале GitHub, чтобы получить токен обновления OAuth2 и настроить клиентскую библиотеку.
  2. По завершении вернитесь на эту страницу. Теперь ваш файл adwords_api.yml должен иметь все необходимое для выполнения тестовых вызовов API и содержать примерно следующие значения:
[...]
:oauth2_client_id: xxxxxxxxxx.apps.googleusercontent.com
:oauth2_client_secret: zZxxxxxTxxxxxxxxxxx
:refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
:developer_token: 123axxxxxxxxxxxxxxxxxx
:client_customer_id: 123-456-7890
:user_agent: Company_Name
[...]

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

Итак, у вас настроены среда и файл конфигурации. Теперь пришло время выполнить первый вызов API.

Java

  1. В среде IDE откройте и запустите файл GetCampaigns.java.
  2. В консоли должен появиться список тестовых кампаний, ранее добавленных в тестовый аккаунт.

.NET

  1. В среде IDE откройте и запустите файл GetCampaigns.cs или GetCampaigns.vb.
  2. В консоли должен появиться список тестовых кампаний, ранее добавленных в тестовый аккаунт.

Python

  1. В среде IDE откройте и запустите файл get_campaigns.py.
  2. В консоли должен появиться список тестовых кампаний, ранее добавленных в тестовый аккаунт.

PHP

  1. В среде IDE откройте и запустите файл GetCampaigns.php.
  2. В консоли должен появиться список тестовых кампаний, ранее добавленных в тестовый аккаунт.

Perl

  1. В среде IDE откройте и запустите файл get_campaigns.pl.
  2. В консоли должен появиться список тестовых кампаний, ранее добавленных в тестовый аккаунт.

Ruby

  1. В командной строке запустите файл get_campaigns.rb. Для этого введите следующее:
    ruby get_campaigns.rb
  2. В консоли должен появиться список тестовых кампаний, ранее добавленных в тестовый аккаунт.

Итак, вы выполнили первый вызов AdWords API.

В этом разделе мы рассмотрели довольно много информации. Ниже мы более подробно опишем некоторые элементы конфигурации.

Анализ элементов конфигурации

В предыдущем разделе мы рассмотрели, что нужно для выполнения первого вызова API.

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

Тестовые и рабочие аккаунты

В предыдущем разделе вы создали тестовый управляющий аккаунт и тестовый клиентский аккаунт.

Тестовые аккаунты позволяют экспериментировать с API, не влияя на показ объявлений и расходы. Они также хорошо подходят для экспериментов с веб-интерфейсом AdWords без каких-либо последствий.

Если в веб-интерфейсе AdWords выполнен вход в тестовый аккаунт, появится ярко-красная надпись.

Поскольку тестовые аккаунты не осуществляют показ объявлений, данные о показах и расходах в отчетах и вызовах API будут обнулены.

Подробнее о тестовых аккаунтах, рабочих аккаунтах и настройке иерархии аккаунтов читайте в разделе Управление аккаунтами.

Элементы конфигурации

Поскольку используется клиентская библиотека, мы не будем рассматривать, как именно осуществляются вызовы API. Но если вы хотите подробнее узнать, как SOAP, OAuth2 и другие протоколы обеспечивают работу вызовов, ознакомьтесь с разделом Структура вызова API.

Даже при использовании клиентских библиотек вам потребуются некоторые элементы. Выше уже обсуждалось, как их настроить. Здесь мы рассмотрим их подробнее.

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

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

Подробнее читайте в разделе Управление аккаунтами.

Идентификатор и секретный ключ клиента OAuth2

Эти элементы обеспечивают соответствие клиентского приложения проекту в Google Developers Console и используются для аутентификации через OAuth2, что позволяет приложению работать от имени аккаунта.

Подробнее читайте в разделе Аутентификация OAuth2.

Токены доступа и обновления OAuth2

Чтобы обеспечить доступ приложения к закрытым данным через API, оно должно получить токен доступа OAuth2.

Если используются клиентские библиотеки, получение токена доступа OAuth2 происходит автоматически. В противном случае обратитесь к примеру вызова API в разделе Структура вызова API, где описывается, как создать токен доступа.

Токены доступа OAuth2 имеют ограниченный срок действия. Поэтому в клиентских библиотеках используется токен обновления OAuth2 для автоматического повторного создания токена доступа OAuth2.

Мы уже создали токен обновления выше с помощью клиентской библиотеки.

Подробнее об использовании OAuth2 с API Google читайте в разделе Аутентификация OAuth2 и в документации по идентификационным данным OAuth2.

Идентификатор клиента

Идентификатор клиента – это номер клиентского аккаунта AdWords, которым вы хотите управлять через API, например 123-456-7890.

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

Подробнее читайте в разделе Примеры кода и варианты использования.

Дальнейшие действия

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

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

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.