SOAP の基本

AdWords API SOAP のリクエスト ヘッダーとレスポンス ヘッダーについて説明し、次に cURL を使った SOAP の呼び出しのサンプルをご覧いただきます。

リクエスト ヘッダー

HTTP ヘッダー

承認手続き
OAuth2 アクセス トークンを次の形式で入れてください: Authorization : Bearer YOUR_ACCESS_TOKEN。これはクライアント センター マネージャがクライアントの代理なのか、広告主様が直接アカウントを関しているのかを識別するために必要となります。 アクセス トークンを取得する方法については OAuth2 ガイドをご覧ください。 アクセス トークンの有効期限は取得後 1 時間です。失効した場合は、アクセス トークンを更新して新たに取得してください。(クライアント ライブラリは失効したトークンを自動的に更新します。)

SOAP ヘッダー

AdWords API ウェブ サービスにリクエストを送信する際は、常に次のヘッダーをリクエストに含める必要があります。

developerToken
AdWords API の開発者を個別に識別するための 22 文字の文字列です。開発者トークンは、たとえば ABcdeFGH93KL-NOPQ_STUv のような文字列になります。
userAgent
リクエストの送信者と目的を定義するユーザー固有の文字列です。問題を診断する際にリクエストが見つかりやすいようにアプリケーション名とバージョンに設定してください。例: example.com:ReportDownloader:V7.18
clientCustomerId
クライアントの代理人の場合は、このヘッダーでクライアントのお客様 ID を指定します。通常、お客様 ID は 123-456-7890 のような形式になります。
validateOnly(オプション)
true に設定すると、リクエストの実行はせずに検証だけが行われます。このヘッダーを使用すると、ユーザーが入力したデータを検証することができます。
partialFailure(オプション、AdGroupCriterionService、AdGroupAdService、v201206 以降: AdGroupService、CampaignService、CampaignAdExtensionService、CampaignCriterionService)
true に設定すると、サービスはエラーのないオペレーションをすべて実行し、失敗したオペレーションのエラーを返します。このヘッダーは、変換以外のオペレーションでは無視されます。

レスポンス ヘッダー

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

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

SOAP 送信のサンプル

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

  1. 0. アクセス トークンを取得します。

    最初に Google Developers Console を使ってアプリケーションを登録し、[Installed application] タイプのお客様 ID を作成します。そうすると、後で必要になるクライアント ID やクライアント シークレットなどの情報が Google から提供されます。

    OAuth2 から認証トークンをリクエストするには、次の URL をブラウザに貼り付けます。

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

    アプリケーションによる 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"
    }

  2. 1. SOAP リクエストを作成します。

    次の XML では、予算を追加する SOAP リクエストを定義します。この XML は(実際の認証トークンとアカウントのログイン情報でプレースホルダーを置き換えたうえで)hello_world.xml として保存します。clientCustomerId を識別する必要がある場合は、こちらをご覧ください。

    <?xml version="1.0" encoding="UTF-8"?>
    <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 soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="https://adwords.google.com/api/adwords/cm/v201506">
          <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/v201506">
          <operations>
            <operator>ADD</operator>
            <operand>
              <name>Hello World</name>
              <status>PAUSED</status>
              <budget>
                <budgetId>987654321</budgetId>
              </budget>
              <settings xsi:type="ns2:GeoTargetTypeSetting" xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201506">
                <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
              </settings>
              <settings xsi:type="ns3:KeywordMatchSetting" xmlns:ns3="https://adwords.google.com/api/adwords/cm/v201506">
                <optIn>false</optIn>
              </settings>
              <networkSetting>
                <targetGoogleSearch>true</targetGoogleSearch>
                <targetSearchNetwork>true</targetSearchNetwork>
                <targetContentNetwork>false</targetContentNetwork>
              </networkSetting>
              <biddingStrategyConfiguration>
                <biddingScheme xsi:type="ns4:ManualCpcBiddingScheme" xmlns:ns4="https://adwords.google.com/api/adwords/cm/v201506">
                  <enhancedCpcEnabled>false</enhancedCpcEnabled>
                </biddingScheme>
              </biddingStrategyConfiguration>
            </operand>
          </operations>
        </mutate>
      </soapenv:Body>
    </soapenv:Envelope>
    
  3. 2. リクエストを送信します。

    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/v201506

    AdWords API サーバーでリクエストの処理が完了すると、新たに追加したキャンペーンを表す XML データを含むレスポンスが返されます。

    <?xml version="1.0" encoding="UTF-8"?>
      <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Header>
          <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201506">
            <requestId>0004e93c496104180a42fee300007f7d</requestId>
            <serviceName>CampaignService</serviceName>
            <methodName>mutate</methodName>
            <operations>0</operations>
            <responseTime>602</responseTime>
          </ResponseHeader>
        </soap:Header>
        <soap:Body>
          <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201506">
            <rval>
              <ListReturnValue.Type>CampaignReturnValue</ListReturnValue.Type>
              <value>
                <id>123456789</id>
                <name>Hello World</name>
                <status>PAUSED</status>
                <servingStatus>SUSPENDED</servingStatus>
                <startDate>20131021</startDate>
                <endDate>20371230</endDate>
                <budget>
                  <budgetId>987654321</budgetId>
                  <name>Interplanetary Budget #1382345043485</name>
                  <period>DAILY</period>
                  <amount>
                    <ComparableValue.Type>Money</ComparableValue.Type>
                    <microAmount>50000000</microAmount>
                  </amount>
                  <deliveryMethod>STANDARD</deliveryMethod>
                  <isExplicitlyShared>true</isExplicitlyShared>
                  <status>ACTIVE</status>
                </budget>
                <conversionOptimizerEligibility>
                  <eligible>false</eligible>
                  <rejectionReasons>CAMPAIGN_IS_NOT_ACTIVE</rejectionReasons>
                  <rejectionReasons>CONVERSION_TRACKING_NOT_ENABLED</rejectionReasons>
                </conversionOptimizerEligibility>
                <adServingOptimizationStatus>OPTIMIZE</adServingOptimizationStatus>
                <settings xsi:type="KeywordMatchSetting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <Setting.Type>KeywordMatchSetting</Setting.Type>
                  <optIn>false</optIn>
                </settings>
                <settings xsi:type="GeoTargetTypeSetting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <Setting.Type>GeoTargetTypeSetting</Setting.Type>
                  <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
                </settings>
                <networkSetting>
                  <targetGoogleSearch>true</targetGoogleSearch>
                  <targetSearchNetwork>true</targetSearchNetwork>
                  <targetContentNetwork>false</targetContentNetwork>
                </networkSetting>
                <biddingStrategyConfiguration>
                  <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
                  <biddingScheme xsi:type="ManualCpcBiddingScheme" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>
                    <enhancedCpcEnabled>false</enhancedCpcEnabled>
                  </biddingScheme>
                </biddingStrategyConfiguration>
              </value>
            </rval>
          </mutateResponse>
        </soap:Body>
      </soap:Envelope>
    

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

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