从 Ad Manager SOAP API 迁移

Ad Manager SOAP API 是一项旧版 API，用于读取和写入 Ad Manager 数据以及运行报告。如果您可以迁移，我们建议您使用 Ad Manager API（Beta 版）。不过，Ad Manager SOAP API 版本在其典型生命周期内受支持。如需了解详情，请参阅 Ad Manager SOAP API 弃用时间表。

以下指南概述了 Ad Manager SOAP API 与 Ad Manager API（Beta 版）之间的差异。

学习

标准 Ad Manager SOAP API 服务方法在 Ad Manager API 中具有等效的概念。Ad Manager API 还提供了用于读取单个实体的相关方法。下表显示了 Order 方法的示例映射：

SOAP 方法 REST 方法
getOrdersByStatement networks.orders.get
networks.orders.list

身份验证

如需使用 Ad Manager API（Beta 版）进行身份验证，您可以使用现有的 Ad Manager SOAP API 凭据，也可以创建新的凭据。无论您选择哪种方式，都必须先在 Google Cloud 项目中启用 Ad Manager API。如需了解详情，请参阅身份验证。

如果您使用的是客户端库，请将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账号密钥文件的路径，以设置应用默认凭据。如需了解详情，请参阅应用默认凭据的工作原理。

如果您使用的是已安装的应用凭据，请按以下格式创建 JSON 文件，并将环境变量设置为其路径：

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

替换以下值：

  • CLIENT_ID：您的新客户端 ID 或现有客户端 ID。
  • CLIENT_SECRET：您的新客户端密钥或现有客户端密钥。

  • REFRESH_TOKEN：新的或现有的刷新令牌。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

了解过滤器方面的差异

Ad Manager API（Beta 版）查询语言支持所有发布商查询语言 (PQL) 功能，但存在明显的语法差异。

以下用于列出 Order 对象的示例展示了主要变更，例如移除了绑定变量、区分大小写的运算符，以及将 ORDER BY 和 LIMIT 子句替换为单独的字段：

Ad Manager SOAP API 

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

Ad Manager API（Beta 版）

JSON 格式

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

网址编码

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

Ad Manager API（Beta 版）支持所有 PQL 功能，但与 Ad Manager SOAP API 存在以下语法差异：

  • 在 Ad Manager API（Beta 版）中，AND 和 OR 运算符区分大小写。小写的 and 和 or 会被视为裸字面量搜索字符串，这是 Ad Manager API（Beta 版）中用于跨字段搜索的功能。

    使用大写运算符

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    将小写字符串视为字面量

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false

  • 字符 * 是用于字符串匹配的通配符。Ad Manager API（Beta 版）不支持 like 运算符。

    Ad Manager SOAP API PQL

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    Ad Manager API（Beta 版）

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • 字段名称必须显示在比较运算符的左侧：

    有效过滤条件

    updateTime > "2024-01-01T00:00:00Z"

    过滤条件无效

    "2024-01-01T00:00:00Z" < updateTime

  • Ad Manager API（Beta 版）不支持绑定变量。所有值都必须内嵌。

  • 包含空格的字符串字面量必须用英文双引号括起来，例如 "Foo bar"。您不能使用单引号来封装字符串字面量。

移除排序子句

在 Ad Manager API（Beta 版）中，指定排序顺序是可选的。如果您想为结果集指定排序顺序，请移除 PQL ORDER BY 子句，改为设置 orderBy 字段：

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

从偏移量迁移到分页令牌

Ad Manager API（Beta 版）使用分页令牌（而非 LIMIT 和 OFFSET 子句）对大型结果集进行分页。

Ad Manager API（Beta 版）使用 pageSize 参数来控制页面大小。与 Ad Manager SOAP API 中的 LIMIT 子句不同，省略页面大小不会返回整个结果集。相反，列表方法使用默认的页面大小 50。以下示例将 pageSize 和 pageToken 设置为网址参数：

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

与 Ad Manager SOAP API 不同，Ad Manager API（Beta 版）返回的结果可能少于请求的页面大小，即使有其他页面也是如此。使用 nextPageToken 字段确定是否有其他结果。

虽然分页不需要偏移量，但您可以使用 skip 字段进行多线程处理。使用多线程时，请使用第一页中的分页令牌，以确保您从同一结果集中读取数据：

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50