SOAP XML 请求和响应标头

本页介绍了必需的 SOAP XML 请求标头以及在响应中返回的标头。

必需的请求标头

所有 API SOAP 调用的标头中都必须包含 <RequestHeader> 元素;所有服务 WSDL 中都定义了此元素。客户端库为您提供了添加此标头的方法(使用您提供的值)。以下是 <RequestHeader> 所有元素的说明:

元素 说明
<networkCode>

正在处理的广告网络的代码。发出除 NetworkService.getAllNetworks()NetworkService.makeTestNetwork() 以外的所有请求时,必须提供广告资源网代码。

请确保仅使用适用于您的帐号登录信息的广告联盟代码。您可以在 Google Ad Manager 网站上为您的帐号找到该代码,具体位置在“管理”>“广告资源网设置”页面上的“广告资源网代码”旁边。

<applicationName> 用于标识您的应用的任意字符串名称。此元素将显示在 Google 的日志文件中。例如:“我的广告资源应用”或“App_1”。

注意:您的应用向 Ad Manager API 发送的每个请求都必须包含 OAuth2 访问令牌。在 HTTP 标头中以 Authorization: Bearer YOUR_ACCESS_TOKEN 形式传递该令牌。

示例请求

以下代码是 SOAP 请求调用 getAdUnitsByStatement() 以查找根 AdUnit 的示例。

<?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://www.google.com/apis/ads/publisher/v202402">
      <ns1:networkCode>123456</ns1:networkCode>
      <ns1:applicationName>DfpApi-Java-2.1.0-dfp_test</ns1:applicationName>
    </ns1:RequestHeader>
  </soapenv:Header>
  <soapenv:Body>
    <getAdUnitsByStatement xmlns="https://www.google.com/apis/ads/publisher/v202402">
      <filterStatement>
        <query>WHERE parentId IS NULL LIMIT 500</query>
      </filterStatement>
    </getAdUnitsByStatement>
  </soapenv:Body>
</soapenv:Envelope>

注意:如果您的 SOAP 请求导致 Unmarshalling error,请参阅常见错误,了解相应的问题排查提示。

响应标头

从 API 返回的所有响应均包含以下标头元素。我们建议的最佳实践是记录这些值。

元素 说明
<requestId> 相应请求的唯一标识。如果您遇到任何支持问题,请将此 ID 发送给我们,以便我们更轻松地找到您的请求。
<responseTime> 网络服务接收请求和发送响应之间间隔的时间。

响应示例

以下代码展示了针对上述请求的 SOAP 响应示例。

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <ResponseHeader xmlns="https://www.google.com/apis/ads/publisher/v202402">
      <requestId>xxxxxxxxxxxxxxxxxxxx</requestId>
      <responseTime>1063</responseTime>
    </ResponseHeader>
  </soap:Header>
  <soap:Body>
    <getAdUnitsByStatementResponse xmlns="https://www.google.com/apis/ads/publisher/v202402">
      <rval>
        <totalResultSetSize>1</totalResultSetSize>
        <startIndex>0</startIndex>
        <results>
          <id>2372</id>
          <name>RootAdUnit</name>
          <description></description>
          <targetWindow>TOP</targetWindow>
          <status>ACTIVE</status>
          <adUnitCode>1002372</adUnitCode>
          <inheritedAdSenseSettings>
            <value>
              <adSenseEnabled>true</adSenseEnabled>
              <borderColor>FFFFFF</borderColor>
              <titleColor>0000FF</titleColor>
              <backgroundColor>FFFFFF</backgroundColor>
              <textColor>000000</textColor>
              <urlColor>008000</urlColor>
              <adType>TEXT_AND_IMAGE</adType>
              <borderStyle>DEFAULT</borderStyle>
              <fontFamily>DEFAULT</fontFamily>
              <fontSize>DEFAULT</fontSize>
            </value>
          </inheritedAdSenseSettings>
        </results>
      </rval>
    </getAdUnitsByStatementResponse>
  </soap:Body>
</soap:Envelope>