API 调用结构

本指南介绍了 API 调用的元素,并演示了如何使用 cURL 进行基本调用。

如果您使用客户端库或 SOAP 库与 API 进行互动,可能不用操心底层 SOAP 和 XML 的情况;但在进行测试和调试时,对它们有所了解还是很有用的。

调用 API 包括向某个服务发送 HTTPS POST 请求和解析响应。请求和响应的正文由 WSDL 所定义的 XML 组成。要输出 WSDL,请将 ?wsdl 附加到服务网址中:

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

请求标头

在请求中,HTTP 标头是伴随 SOAP+XML 正文的:

授权
您需要以 Authorization : Bearer YOUR_ACCESS_TOKEN 格式添加 OAuth2 访问令牌,以标识代表客户操作的经理帐号或直接管理自己帐号的广告客户。有关如何获取访问令牌的说明,请阅读 OAuth2 指南。访问令牌在获得后 1 小时之内有效;过期后,您可以刷新访问令牌来获取新令牌。请注意,我们的客户端库会自动刷新过期令牌。
developerToken
由 22 个字符组成的字符串,用于唯一标识 AdWords API 开发者。例如,ABcdeFGH93KL-NOPQ_STUv 就是一个开发者令牌字符串。
userAgent
用户指定的设定发送者和请求目的的字符串。将此设置为您的应用名称和版本,以帮助我们在诊断问题时找到您的请求,例如 example.com:ReportDownloader:V7.18
clientCustomerId
目标 AdWords 帐号的客户 ID,通常采用 123-456-7890 格式。除 CustomerServiceReportDefinitionService 之外,对所有服务的所有调用都需要此 ID。
validateOnly(可选)
如果设为 true,相应请求将会进行验证,但不会执行。您可以使用此标头验证用户提供的数据。
partialFailure(可选,仅适用于部分服务)
如果设为 true,相应服务将执行没有错误的所有操作,并返回失败操作的错误。对于非 Mutate 操作,将忽略此标头。

响应标头

以下标头随响应 XML 一起返回。我们建议您记录这些值,以用于调试。

requestId
唯一标识相应请求的字符串。
operations
在此请求中执行的操作数量。
responseTime
网络服务从收到请求到发送响应所经历的时间,以毫秒为单位。

API 调用示例

此示例演示如何使用 cURL 与 API 进行互动。虽然使用 cURL 和 SOAP+XML 来构建实际应用可能不太现实,但此示例可以说明 AdWords API 在最低一级的工作原理。

请求

  1. 获取您的 OAuth2 客户端 ID 和客户端密钥(如果您尚未完成这些操作的话)。按照 OAuth2 指南中的说明操作。

  2. 获取 OAuth2 访问令牌。要从 OAuth2 请求访问令牌,请在以下网址输入您的 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 访问令牌。在向 AdWords API 服务发送请求时,您需要使用该访问令牌(在 access_token : 后以粗体显示)。

    {
      "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>

发送以下问题的反馈:

此网页
AdWords API
AdWords API
需要帮助?请访问我们的支持页面