从 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"。您不能使用单引号来封装字符串字面量。

移除 order by 子句

在 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

迁移报告

SOAP API 只能在已弃用的“报告”工具中读取和生成报告。 相反，REST API 只能读取、写入和运行互动式报告。

报告工具和 API 具有不同的 ID 空间。SOAP API 中 SavedQuery 的 ID 无法在 REST API 中使用。

如果您使用的是 SavedQuery，则可以在界面中将报告迁移到互动式报告，并在两个 ID 空间之间创建映射。如需详细了解如何迁移报告，请参阅将报告迁移到互动式报告。

了解 API 差异

SOAP API 和 REST API 在处理报告定义和结果方面存在一些差异：

  • 如果报告仅请求了 NAME，SOAP API 会自动向结果添加相应的 ID 维度。在 REST API 中，您必须明确将 ID 维度添加到 ReportDefinition，才能将其纳入结果中。

  • SOAP API 没有明确的指标类型。REST API 定义了一种数据类型，该类型记录在 Dimension 枚举值中。请注意，ENUM 维度是开放式枚举。在解析结果时，您必须处理新的和未知的枚举值。

  • SOAP API 将 Dimensions 和 DimensionAttributes 分开。REST API 具有包含这两者的统一 Dimension 枚举。

  • SOAP API 对维度的数量没有限制。互动式报告在界面和 API 中都最多只能包含 10 个维度。按同一 ID 空间细分的维度会被视为一个维度。例如，在计算限制时，仅包含 ORDER_NAME、ORDER_ID 和 ORDER_START_DATE 仅计为 1 个维度。