API 呼び出しの仕組み

このガイドでは API 呼び出しの構成要素を解説し、cURL を使った基本的な呼び出しも例示します。

API とのやり取りにクライアント ライブラリや SOAP ライブラリを使用している場合は SOAP や XML について特に考慮する必要はありませんが、テストやデバッグを行う際には SOAP や XML の知識が役立ちます。

AdWords API の呼び出しを行うと、サービスに HTTPS POST リクエストが送信され、レスポンスが解釈されます。リクエストとレスポンスの本文は WSDL で定義された XML 形式です。WSDL は次のようにサービスの URL に ?wsdl を追加して出力できます。

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

リクエストのヘッダー

HTTP ヘッダーはリクエストの本文(SOAP と XML)に付けられます。

Authorization
OAuth2 アクセス トークンAuthorization : Bearer YOUR_ACCESS_TOKEN の形式で含めてください。これはクライアント センター(MCC)アカウントがクライアントの代理なのか、広告主様がアカウントを直接管理しているのかを識別するために必要となります。アクセス トークンを取得する方法については OAuth2 ガイドをご覧ください。アクセス トークンの有効期限は取得後 1 時間です。失効した場合は、アクセス トークンを更新して新たに取得してください。クライアント ライブラリを使用している場合、失効したトークンは自動的に更新されます。
developerToken
AdWords API の開発者を個別に識別するための 22 文字の文字列です。 開発者トークン文字列の例: ABcdeFGH93KL-NOPQ_STUv
userAgent
リクエストの送信者と目的を定義するユーザー指定の文字列です。問題を診断する際にリクエストが見つかりやすいように、アプリケーション名とバージョンを設定してください(例: example.com:ReportDownloader:V7.18)。
clientCustomerId
対象とする AdWords アカウントのお客様 ID です。通常は 123-456-7890 のような形式になります。CustomerServiceReportDefinitionService を除くすべてのサービスに対するすべての呼び出しで必須です。
validateOnly(省略可)
true に設定すると、リクエストの実行はせずに検証だけが行われます。このヘッダーを使用すると、ユーザーが入力したデータを検証することができます。
partialFailure(省略可能で、一部のサービスでのみ利用可能)
true に設定すると、サービスはエラーのないオペレーションをすべて実行し、失敗したオペレーションのエラーを返します。mutate オペレーションでない場合はこのヘッダーは無視されます。

レスポンス ヘッダー

レスポンス XML では次のヘッダーが返されます。デバッグに備え、これらの値を記録しておくことをおすすめします。

requestId
このリクエストを一意に識別する文字列
operations
このリクエストで実行されたオペレーションの数
responseTime
ウェブサービスがリクエストを受信してレスポンスを送信するまでの所要時間 (ミリ秒単位)

API 呼び出しのサンプル

次のサンプルは cURL を使用して AdWords API と通信する方法を示すものです。cURL と SOAP / XML の組み合わせは、実際のアプリケーション開発には向きませんが、AdWords API の最も基礎的な機能の使用方法を示す例としてお役立てください。

リクエスト

  1. OAuth2 のクライアント ID とクライアント シークレットを取得します(未取得の場合)。OAuth2 ガイドの手順に従ってください。

  2. OAuth2 アクセス トークンを取得します。OAuth2 のアクセス トークンをリクエストするには、次の URL に OAuth2 のクライアント ID を挿入してブラウザに貼り付けます。

    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 リクエストを定義しています。この XML を(プレースホルダを実際の認証トークンとアカウントのログイン情報に置き換えたうえで)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>

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。