Документация по запрошенной версии недоступна.Документация по запрошенным различиям не предоставляется.
Руководство разработчика API AdWords описывает, как с помощью API Google AdWords можно управлять аккаунтами AdWords.
Это руководство предназначено для разработчиков, которым необходимо организовать программный доступ к аккаунтам AdWords. Предполагается знание принципов работы с веб-службами и языка программирования. Кроме того, предполагается знакомство с Google AdWords.
Документации для всех поддерживаемых версий API AdWords объединены в этом руководстве. Чтобы просмотреть документацию о конкретной версии API, выберите ее в раскрывающемся списке в правом верхнем углу. Кроме того, это раскрывающееся меню позволяет просмотреть различия между двумя версиями. При просмотре различий добавленный текст выделяется подчеркиванием и зеленым цветом, а удаленный – зачеркиванием.
Примечание. Данное руководство для сохранения выбранной версии при переходе между страницами использует файлы cookie. Если сохранение файлов cookie отключено, то всегда будет отображаться только последняя версия страниц данного руководства.
API AdWords обеспечивает создание и управление кампаниями, группами объявлений, ключевыми словами и рекламными объявлениями. Кроме того, генерируются варианты ключевых слов, оценка трафика прогнозируемых показов, подсчет кликов и CTR, а также формирование отчетов о фактической эффективности.
Для реализации доступа к аккаунту AdWords и управления аккаунтом через API AdWords необходимо создать клиентское приложение, которое будет подключаться к одной или нескольким веб-службам. И хотя каждая из служб может использоваться отдельно от остальных, но на практике, как правило (например, при создании новой кампании с группами объявлений, объявлениями и ключевыми словами), клиентскому приложению приходится работать с несколькими службами.
Технология обмена сообщениями в API AdWords построена на основе широко распространенного протокола SOAP (протокол простого доступа к объектам) на базе XML и HTTP. API AdWords использует стиль document/literal протокола SOAP версии 1.1.
В состав API AdWords входят следующие веб-службы.
| 
CampaignService
Служба Campaign Service позволяет создавать и изменять кампании, а также вести их списки. Например, для кампании эта служба позволяет изменить название, задать дневной бюджет и дату окончания. Эта служба также позволяет совершать действия с кампаниями, например приостанавливать кампанию.
AdGroupService
Служба AdGroup Service позволяет создавать группы объявлений, вести их списки, связывать группы объявлений с кампаниями и выполнять другие действия. Например, она дает возможность для всех ключевых слов в группе объявлений установить цену за клик.
CriterionService
Служба Criterion Service позволяет получать информацию о критериях таргетинга. Например, эта служба дает возможность просмотреть список ключевых слов для кампании с таргетингом на ключевые слова или веб-сайтов для кампаний с таргетингом на места размещения. Кроме того, она позволяет создавать и изменять критерии таргетинга для ключевых слов и веб-сайтов.
AdService
Служба Ad Service позволяет создавать и изменять рекламные объявления и связывать их с группами объявлений.
SiteSuggestionService
Служба Site Suggestion Service позволяет оценить эффективность ключевых слов, групп объявлений и кампаний.
TrafficEstimatorService
Служба Traffic Estimator Service позволяет оценить эффективность ключевых слов, групп объявлений и кампаний. Кроме этого, она дает возможность оценить цену за клик, CTR и среднюю позицию рекламного объявления.
KeywordToolService
Служба Keyword Tool Service позволяет создать список ключевых слов на основе одного ключевого слова или текста на указанной веб-странице или на сайте.
ReportService
Служба Report Service позволяет формировать отчеты об эффективности кампаний AdWords. Например, можно получить отчет о количестве показов, кликов и CTR за день. Рекламодатель, управляющий несколькими пользовательскими аккаунтами AdWords, может получить отчеты обо всех этих аккаунтах.
InfoService
Служба Info Service позволяет получить основные сведения об интенсивности использования API AdWords.
AccountService
Служба Account Service позволяет изменять аккаунты AdWords.
Подробнее о каждой веб-службе см. в Обзоре веб-служб.
Подробнее о кампаниях, ключевых словах, группах объявлений и аккаунтах AdWords см. на веб-сайте Google AdWords http://adwords.google.com/intl/ru/.
Ниже перечислены ссылки на дополнительную информацию.
Перед началом использования API AdWords необходимо зарегистрироваться на веб-сайте разработчиков API AdWords. При регистрации предоставленная информация будет проверена, и после подтверждения вам будут выданы идентификатор разработчика и идентификатор приложения. Идентификатор разработчика однозначно определяет разработчика и позволяет отслеживать использование единиц API, а идентификатор приложения однозначно определяет приложение, отправляющее запросы в API AdWords.
Оба идентификатора обязательны для доступа к API AdWords. Они должны быть указаны в заголовке каждого запроса, как описано в разделеЗаголовок запроса.
Обращения к веб-службам API AdWords с вашего аккаунта учитываются в виде единиц API. Оплата начисляется по цене 0,25 долларов США (или эквивалентная сумма в местной валюте) за 1000 израсходованных единиц API, при этом за одну операцию принимается минимальная единица работы, например установление ставки за одно ключевое слово. Одно обращение к SOAP может содержать несколько операций. Подробнее см. в разделе Использование и оплата
Некоторые рекламодатели пользуются бесплатными единицами API, но все разработчики при регистрации должны предоставить платежную информацию. После подтверждения идентификаторов рекламодателям предоставляется информация о том, имеют ли они право на бесплатные единицы API.
При каждом запросе к веб-службам API AdWords в заголовке запроса должен быть указан идентификатор разработчика (подробное описание заголовка запроса см. в разделе Заголовок запроса), чтобы обеспечить отслеживание использования API AdWords и правильное выставление счетов. Кроме того, для отслеживания доступа к приложениям в заголовке запроса должен быть указан идентификатор приложения.
InfoService дает возможность увидеть, каким образом используется API (например, сколько операций было выполнено за данный период времени).
Для работы с API AdWords необходимо написать клиентскую программу на каком-либо языке программирования (Java, Perl, Python, C, C++, PHP). Клиентская программа должна отправить запрос в одну из веб-служб AdWords, например TrafficEstimatorService или AdGroupService. После этого клиентская программа должна выполнить синтаксический анализ ответа, возвращенного службой после обработки запроса.
Установка каких-либо компонентов для работы API AdWords не требуется, так как программа представляет собой набор веб-служб. Для работы с API AdWords необходимо только программное обеспечение для создания клиентской программы на каком-либо языке программирования. Например, для написания клиентской программы на языке Java нужна только среда выполнения Java и набор инструментов SOAP, например Axis. Список наборов инструментов для различных языков программирования см. в разделе Наборы инструментов SOAP.
Все операции, поддерживаемые веб-службой, описаны в файле (WSDL). Для подключения к веб-службе необходимо знать URL WSDL-файла этой службы. Для каждой веб-службы API AdWords имеется отдельный WSDL-файл. URL любого WSDL-файла представлен в следующем виде, где N – номер версии, а SERVICE_NAME – имя службы.
https://adwords.google.com/api/adwords/vN/SERVICE_NAME?wsdl
Например, ниже приведен URL для WSDL-файла службы Campaign Service версии 12.
https://adwords.google.com/api/adwords/v12/CampaignService?wsdl
Сведения о подключении клиентского приложения к WSDL зависят от языка программирования и используемого набора инструментов SOAP. Набор инструментов SOAP обычно содержит соответствующую функцию для подключения к службе по указанному URL. Рассмотрим пример кода на языке Perl для подключения к службе CampaignService: версии 12.
# Specify the WSDL $url = https://adwords.google.com/api/adwords/v12/CampaignService?wsdl # Connect to the service using the SOAP::Lite toolkit my $service = SOAP::Lite->service($url);
Клиентское приложение после подключения к веб-службе может выполнять любые операции, которые эта служба поддерживает. Например, после подключения к службе CampaignService клиентская программа может отправить запрос addCampaign на добавление новой кампании.
Типы данных, заданные в верхнем регистре, например Campaign и NetworkType, которые описаны в справочнике по API данного руководства, представляют собой сложные структуры данных или перечисления, определенные в WSDL.
Типы данных в этом руководстве, заданные в нижнем регистре, например boolean и string, являются типами данных XML-схемы, которые определены в следующем пространстве имен.
http://www.w3.org/2001/XMLSchema
Идентификаторы разработчика и приложения выдаются разработчику при регистрации перед началом работы с API AdWords. В каждом запросе должны быть правильно указаны идентификатор разработчика и идентификатор приложения – оба они необходимы для доступа к API AdWords.
Однозначно идентифицирует разработчика и позволяет отслеживать использование единиц API. Чтобы обеспечить конфиденциальность и защиту от мошенничества при выставлении счетов, не сообщайте персональный идентификатор разработчика другим пользователям. Узнать свой идентификатор разработчика можно в Центре API AdWords на вкладке "Мой аккаунт".
Однозначно идентифицирует приложение, выполняющее запрос в API AdWords. Если приложение вызывает другое приложение, то в запросе должен быть указан идентификатор приложения, которое фактически отправляет запрос. Для каждого приложения, использующего API AdWords, требуется отдельный идентификатор. Чтобы получить дополнительный идентификатор, перейдите по ссылке "добавить" в разделе "Ваши идентификаторы приложений" в Центре API AdWords.
Подробнее о включении этих идентификаторов в запросы см. в разделе Заголовок запроса
Необходимо связать свой аккаунт в службе "Мой центр клиентов" (MCC) с клиентским аккаунтом, которым вы собираетесь управлять. После этого при создании запроса к API необходимо включить в заголовок запроса адрес электронной почты и пароль MCC, а также адрес электронной почты для входа или идентификатор пользователя (ID) для клиентского аккаунта.
Обратите внимание, что существует два способа связать MCC с клиентским аккаунтом: "Пользовательский интерфейс и API" и "Только API". Оба они дают доступ к API, но только один из них предоставляет кредит на все расходы клиентского аккаунта в отношении потребленных единиц API. Подробнее об уровнях доступа "Только API" и "Мой центр клиентов" см. в Частых вопросах.
Инструкции для cвязи MCC c клиентскими аккаунтами см. на странице Как связать аккаунт. Частые вопросы о MCC см. в Справочном центре MCC.
Примечание. Функции безопасности позволяют предотвратить несанкционированный доступ к аккаунту, отслеживая подозрительные попытки входа и блокируя доступ к нему. Например, если программа слишком много раз пытается войти с неверным паролем. При попытке получить доступ к заблокированному аккаунту отображается ошибка с кодом 86 – аккаунт заблокирован. Чтобы разблокировать его, см. описание кода ошибки 86.
Следующие элементы заголовка должны обязательно присутствовать в запросах, отправляемых веб-службам API AdWords.
Адрес электронной почты для доступа к аккаунту AdWords.
Пароль для доступа к аккаунту AdWords.
Произвольная строка, которая идентифицирует пользователя, отправляющего запрос.
Примечание. В любом другом контексте элемент заголовка useragent идентифицирует браузер или клиентское приложение, которое отправляет запрос. В API AdWords элемент useragent рассматривается как идентификатор пользователя, приславшего запрос, а также может указывать на цель этого запроса.
Строка, однозначно идентифицирующая разработчика API AdWords. Пример идентификатора разработчика – ABcdeFGH93KL-NOPQ_STUv. Идентификатор разработчика состоит из 22 символов.
Строка, однозначно идентифицирующая приложение, которому разрешен доступ к веб-службам API AdWords. При прямых вызовах API AdWords из приложения необходимо указывать соответствующий applicationToken. Пример строки идентификатора – ZYXwvu-TSR123_456ABCDE. Идентификатор приложения состоит из 22 символов.
Следующие элементы заголовка являются необязательными. Может быть указан либо элемент clientEmail, либо элемент clientCustomerId (но не оба сразу).
Адрес электронной почты, однозначно идентифицирующий пользователя MCC. Этот элемент заголовка применим только в том случае, когда у вас есть аккаунт MCC. Элемент заголовка clientEmail указывается в том случае, когда нужно изменить аккаунт клиента, а не собственный аккаунт MCC. Если этот элемент указан, то API AdWords считает, что производится доступ к тому аккаунту, который принадлежит пользователю, указанному в элементе clientEmail. Управление клиентом, имя которого указано в элементе clientEmail, должно производиться основным аккаунтом MCC, имя которого указано в элементе email. Назначение этого элемента – предоставить диспетчерам MCC возможность управления аккаунтами своих клиентов без их паролей.
Примечание. Необходимо передавать элементы заголовка <email/> и <password/>. В этих полях для аутентификации нужно указывать свой адрес электронной почты и пароль.
Номер, например 123-456-7890, который однозначно идентифицирует клиента MCC. Этот элемент заголовка можно указывать вместо clientEmail.
Способ создания заголовка клиентской программой зависит от используемого языка программирования и набора инструментов, но обычно для этого в наборе инструментов предусмотрена отдельная функция. Примеры установки заголовков запроса в различных наборах инструментов см. в примерах кода.
Пример XML-кода для установки заголовка запроса см. в разделе Пример запроса SOAP далее на этой странице.
Все ответы, возвращаемые веб-службами API AdWords, содержат следующие элементы. Их значения рекомендуется регистрировать.
Уникальный идентификатор данного запроса. Если у вас возникли какие-либо проблемы с поддержкой, пришлите нам этот идентификатор, это позволит нам быстрее отыскать ваш запрос.
Количество операций в запросе.
Количество единиц API, использованных в запросе.
Время, прошедшее с момента получения запроса веб-службой до отправки ответа.
Пример XML-кода для заголовка ответа см. в разделе Пример ответа SOAP ниже.
API AdWords поддерживает несколько предыдущих версий WSDL для того, чтобы у разработчиков было время для перехода на самую последнюю версию. Старая версия поддерживается в течение четырех месяцев с момента выхода новой версии WSDL.
В течение этого срока API AdWords предоставляет разработчику доступ и документацию для всех версий с датой не позднее двух месяцев назад.
Можно указать версию WSDL, к которой выполняется доступ, в URL, так как в нем содержится номер версии. Номера версий указываются в формате vN.
Сведения о версии содержат сводку изменений, появившихся в данной версии. Также сообщения о выходе новых и прекращении поддержки старых версий можно найти в Блоге API AdWords.
Обозначение "устарело" предупреждает разработчика, что функция API, вероятнее всего, будет удалена в одной из следующих версий. Обратите внимание, что в той версии, где функция помечена в документации как устаревшая, она, как правило, пока еще не удалена и может использоваться. Заметка об устаревшей функции содержит также и указание на новую функцию API, которой она заменена (если есть). Это означает, что нужно запланировать изменение кода для поддержки новой версии. Обозначение "устарело" может относиться к службе, объекту данных, запросу или полю.
В веб-службах API AdWords используются задокументированные версии простого протокола доступа к объектам (SOAP). Клиентская программа посылает SOAP-запрос, веб-служба обрабатывает его и возвращает ответ. И запрос, и ответ упакованы как XML-сообщения, состоящие из заголовка и тела. Заголовок содержит метаданные о сообщении, а в теле указана запрошенная операция.
С точки зрения API AdWords, все API-сообщения передаются как HTTPS-запросы. Формат XML для запроса SOAP передается в виде HTTP-запроса POST со специальным заголовком SOAPAction. Ответ отправляется обратно в ответ на запрос POST. Все вызовы API AdWords зашифрованы с помощью SSL (т.е. как HTTPS) для обеспечения конфиденциальности передаваемых данных.
Запросы, которые может обрабатывать веб-служба, определены в XML-файле на языке определения веб-службы (WSDL). WSDL-файл содержит описания операций, которые веб-служба может выполнять, обязательные параметры и ответы для каждой из этих операций.
Обычно для работы с веб-службами API AdWords необходимо загрузить набор инструментов, который может интерпретировать WSDL-файлы и кодировать/декодировать сообщения запросов и ответов в формате XML. После получения запроса веб-служба возвращает ответ в виде XML-сообщения. Набор инструментов для работы с веб-службой выполняет синтаксический анализ ответа и возвращает данные в виде структуры или объекта.
Используемый набор инструментов SOAP зависит от языка программирования, на котором написано ваше клиентское приложение. Информацию о наборах инструментов, которые были нами протестированы, см. на странице Наборы инструментов SOAP.
В большинстве случаев набор инструментов SOAP генерирует XML-код для работы с веб-службами API AdWords автоматически. Однако для некоторых наборов инструментов необходимо кодировать фрагменты XML-кода вручную. Например, пакет nusoap.php требует написания XML-кода для входных параметров.
Примечание. В API AdWords используется стиль SOAP document/literal, а не rpc/encoded. Некоторые наборы инструментов работают с веб-службами в стиле document не так, как в стиле rpc.
В некоторых случаях в целях отладки полезно перехватывать XML-сообщения с запросами и ответами. См. страницу Как увидеть XML-код, созданный для запроса и для ответа?.
Подробнее о протоколе SOAP см. в Руководстве по SOAP на сайте W3Schools.
В этом разделе содержатся примеры WSDL-файлов и XML-сообщений с запросами.
Следующий код представляет собой пример запроса SOAP. В заголовке задан адрес электронной почты для входа и пароль, а также строка useragent. Тело сообщения запрашивает оценку трафика для ключевого слова flowers по максимальной цене за клик (maxCPC) в размере 50 000 микро, что в валюте США равно 5 центам (микро – это миллионная доля основной валютной единицы).
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns="https://adwords.google.com/api/adwords/v8">
<soap:Header>
<email>loginemail@youraccount.com</email>
<password>secretpassword</password>
<useragent>Your User Agent description</useragent>
<developerToken>_developer_token_here_</developertoken>
<applicationToken>_application_token_here_</applicationtoken>
</soap:Header>
<soap:Body>
<estimateKeywordList>
<keywordRequests>
<type>Broad</type>
<text>flowers</text>
<maxCpc>50000</maxCpc>
</keywordRequests>
</estimateKeywordList>
</soap:Body>
</soap:Envelope>
Следующий код представляет собой пример ответа SOAP, который содержит информацию об оценке трафика для предыдущего запроса.
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<responseTime
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
10636
</responseTime>
<operations
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
1
</operations>
<units
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
1
</units>
<requestId
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
eb21e6667abb131c117b58086f75abbd
</requestId>
</soapenv:Header>
<soapenv:Body>
<estimateKeywordListResponse
xmlns="https://adwords.google.com/api/adwords/v8">
<estimateKeywordListReturn>
<avgPosition>2.9376502</avgPosition>
<cpc>50000</cpc>
<ctr>0.01992803</ctr>
<id>-1</id>
<impressions>62823</impressions>
<notShownPerDay>139255</notShownPerDay>
</estimateKeywordListReturn>
</estimateKeywordListResponse>
</soapenv:Body>
</soapenv:Envelope>
Запросы, которые могут быть обработаны веб-службой, описаны в XML-файле на языке определения веб-служб (WSDL). WSDL-файл содержит описания операций, которые веб-служба может выполнять, обязательные параметры и ответы для каждой из этих операций. Полное определение операции может оказаться весьма сложным. Например, определение операции getName в WSDL-файле службы AdGroup Service, которая возвращает имя группы объявлений по ее идентификатору, представлено следующим кодом.
<element name="getName">
<complexType>
<sequence>
<element name="adgroupID" type="xsd:int" />
</sequence>
</complexType>
</element>
<element name="getNameResponse">
<complexType>
<sequence>
<element name="getNameReturn" type="xsd:string" />
</sequence>
</complexType>
</element>
<wsdl:message name="getNameRequest">
<wsdl:part element="impl:getName" name="parameters" />
</wsdl:message>
<wsdl:message name="getNameResponse">
<wsdl:part element="impl:getNameResponse" name="parameters" />
</wsdl:message>