Структура вызова API

В этом руководстве описаны элементы вызова API и показано, как выполнить простой вызов с помощью cURL.

Если вы работаете с AdWords API через клиентскую библиотеку или библиотеку SOAP, скорее всего, вам не понадобятся знания SOAP и XML, но они могут пригодиться при устранении неполадок.

Чтобы выполнить вызов в API, необходимо отправить службе запрос HTTPS POST и интерпретировать ответ. Тело запроса и ответа представляет собой документ XML, определенный с помощью WSDL. Вы можете вывести WSDL на печать, добавив ?wsdl к URL службы:

https://adwords.google.com/api/adwords/cm/v201609/CampaignService?wsdl.

Заголовки запроса

Наряду с SOAP + XML в теле запроса также используются HTTP-заголовки.

Авторизация
Необходимо включить токен доступа OAuth2 в форме Authorization : Bearer YOUR_ACCESS_TOKEN, определяющий либо управляющий аккаунт, либо рекламодателя, управляющего собственным аккаунтом. Подробнее о том, как получить токен доступа, читайте в руководстве по OAuth2. Он действует в течение часа с момента получения. По окончании срока действия токена нужно получить новый. Клиентские библиотеки автоматически обновляют устаревшие токены.
developerToken
A 22–character string that uniquely identifies an AdWords API developer. Пример: ABcdeFGH93KL-NOPQ_STUv.
userAgent
Строка, которая задается пользователем и определяет отправителя, а также цель запроса. Укажите название и версию приложения, чтобы нам было проще найти ваши запросы в случае обнаружения неполадок. Пример: example.com:ReportDownloader:V7.18.
clientCustomerId
Идентификатор клиента целевого аккаунта AdWords. Стандартный формат: 123-456-7890. Требуется при вызове всех служб, за исключением CustomerService и ReportDefinitionService.
validateOnly (необязательно)
Если задано значение true, запрос подтверждается, но не выполняется. Этот заголовок можно применять для проверки пользовательских данных.
partialFailure (необязательно и доступно только для некоторых служб)
Если присвоено значение true, служба будет выполнять операции, с которыми не возникло проблем, и возвращать ошибки в случае неудавшихся операций. Этот заголовок игнорируется для всех операций, кроме mutate.

Заголовки ответа

В XML-ответе возвращаются следующие заголовки. Рекомендуем регистрировать эти значения в журналах – они пригодятся вам при устранении неполадок.

requestId
Строка – уникальный идентификатор запроса.
operations
Количество операций, выполненных в запросе.
responseTime
Время в миллисекундах, прошедшее между получением запроса и отправкой ответа веб-службой.

Пример вызова API

Пример взаимодействия с помощью cURL позволяет продемонстрировать работу функций AdWords API на самом базовом уровне. Применять cURL и SOAP + XML для разработки реальных приложений нецелесообразно.

Запрос

  1. Получите идентификатор и секретный ключ клиента OAuth2 (если вы этого ещё не сделали). Инструкции см. в руководстве по OAuth2.

  2. Получите токен доступа OAuth2. Чтобы его запросить, введите свой идентификатор клиента OAuth2 в следующем URL и скопируйте его в браузер:

    https://accounts.google.com/o/oauth2/auth?client_id=your-client-id&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords&redirect_uri=urn:ietf:wg:oauth:2.0:oob&access_type=offline&prompt=consent
    

    Появится экран, где вы должны будете предоставить приложению доступ к данным AdWords:

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

    Чтобы получить токен доступа, выполните следующий запрос:

    curl \
      -d code=your-authorization-code \
      -d client_id=your-client-id \
      -d client_secret=your-client-secret \
      -d redirect_uri=urn:ietf:wg:oauth:2.0:oob \
      -d grant_type=authorization_code https://accounts.google.com/o/oauth2/token

    Если все данные указаны верно, Google вернет токен для OAuth2. Токен доступа (выделенный полужирным шрифтом после access_token :) необходим для отправки запросов в службы AdWords API.

    {
      "access_token" : "ya29.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/Ixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }

  3. Создание запроса SOAP. Следующий код XML определяет запрос SOAP, который добавляет бюджет. Сохраните этот код (с токеном аутентификации и именем аккаунта вместо меток-заполнителей) под названием hello_world.xml.

    <?xml version="1.0"?>
    <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>
        <ns1:RequestHeader xmlns:ns1="https://adwords.google.com/api/adwords/cm/v201609" soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0">
          <ns1:clientCustomerId>xxx-xxx-xxxx</ns1:clientCustomerId>
          <ns1:developerToken>YOUR_DEVELOPER_TOKEN</ns1:developerToken>
          <ns1:userAgent>YOUR_APPLICATION_NAME</ns1:userAgent>
          <ns1:validateOnly>false</ns1:validateOnly>
          <ns1:partialFailure>false</ns1:partialFailure>
        </ns1:RequestHeader>
      </soapenv:Header>
      <soapenv:Body>
        <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201609">
          <operations>
            <operator>ADD</operator>
            <operand>
              <name>Hello World</name>
              <status>PAUSED</status>
              <budget>
                <budgetId>YOUR_BUDGET_ID</budgetId>
              </budget>
              <settings xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201609" xsi:type="ns2:GeoTargetTypeSetting">
                <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
              </settings>
              <advertisingChannelType>SEARCH</advertisingChannelType>
              <networkSetting>
                <targetGoogleSearch>true</targetGoogleSearch>
                <targetSearchNetwork>true</targetSearchNetwork>
                <targetContentNetwork>false</targetContentNetwork>
              </networkSetting>
              <biddingStrategyConfiguration>
                <biddingScheme xmlns:ns4="https://adwords.google.com/api/adwords/cm/v201609" xsi:type="ns4:ManualCpcBiddingScheme">
                  <enhancedCpcEnabled>false</enhancedCpcEnabled>
                </biddingScheme>
              </biddingStrategyConfiguration>
            </operand>
          </operations>
        </mutate>
      </soapenv:Body>
    </soapenv:Envelope>
    
  4. Отправка запроса. С помощью cURL отправьте этот SOAP-запрос службе CampaignService. Токен доступа можно добавить в заголовок HTTP следующим образом:

    curl --header "Content-Type: application/soap+xml" \
         --header "Authorization : Bearer YOUR_ACCESS_TOKEN" \
         --data @hello_world.xml \
           https://adwords.google.com/api/adwords/cm/v201609/CampaignService

Ответ

Когда сервер AdWords API обработает этот запрос, он вернет ответ с данными XML, представляющими добавленную кампанию:

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201609">
      <requestId>00053282f54911280ac10da199076e99</requestId>
      <serviceName>CampaignService</serviceName>
      <methodName>mutate</methodName>
      <operations>1</operations>
      <responseTime>269</responseTime>
    </ResponseHeader>
  </soap:Header>
  <soap:Body>
    <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201609">
      <rval>
        <ListReturnValue.Type>CampaignReturnValue</ListReturnValue.Type>
        <value>
          <id>123456789</id>
          <name>Hello World</name>
          <status>PAUSED</status>
          <servingStatus>SUSPENDED</servingStatus>
          <startDate>20160510</startDate>
          <endDate>20371230</endDate>
          <budget>
            <budgetId>YOUR_BUDGET_ID</budgetId>
            <name>...</name>
            <amount>
              <ComparableValue.Type>Money</ComparableValue.Type>
              <microAmount>50000000</microAmount>
            </amount>
            <deliveryMethod>STANDARD</deliveryMethod>
            <isExplicitlyShared>true</isExplicitlyShared>
            <status>ENABLED</status>
          </budget>
          <conversionOptimizerEligibility>
            <eligible>false</eligible>
            <rejectionReasons>NOT_ENOUGH_CONVERSIONS</rejectionReasons>
          </conversionOptimizerEligibility>
          <adServingOptimizationStatus>OPTIMIZE</adServingOptimizationStatus>
          <settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="GeoTargetTypeSetting">
            <Setting.Type>GeoTargetTypeSetting</Setting.Type>
            <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
          </settings>
          <advertisingChannelType>SEARCH</advertisingChannelType>
          <networkSetting>
            <targetGoogleSearch>true</targetGoogleSearch>
            <targetSearchNetwork>true</targetSearchNetwork>
            <targetContentNetwork>false</targetContentNetwork>
            <targetPartnerSearchNetwork>false</targetPartnerSearchNetwork>
          </networkSetting>
          <biddingStrategyConfiguration>
            <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
            <biddingScheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ManualCpcBiddingScheme">
              <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>
              <enhancedCpcEnabled>false</enhancedCpcEnabled>
            </biddingScheme>
          </biddingStrategyConfiguration>
          <campaignTrialType>BASE</campaignTrialType>
          <baseCampaignId>123456789</baseCampaignId>
        </value>
      </rval>
    </mutateResponse>
  </soap:Body>
</soap:Envelope>

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

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