从 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 还提供用于读取单个实体的方法。此外，在 SOAP API 中使用单个 perform<Entity>Action 方法的状态更改操作现在在 REST API 中针对每种操作类型都有专用方法。

下表显示了 Order 方法的映射示例：

SOAP 方法	REST 方法
createOrders	networks.orders.batchCreate
getOrdersByStatement	networks.orders.get networks.orders.list
updateOrders	networks.orders.batchUpdate
performOrderAction	每种操作类型对应一种方法。 例如： networks.orders.batchApprove networks.orders.batchPause networks.orders.batchResume

状态更改操作响应

在 SOAP API 中，perform<Entity>Action 返回了一个 UpdateResult 对象，其中包含一个 numChanges 字段，用于指明修改了多少个实体。在 Ad Manager API（Beta 版）中，批量操作方法会返回一个空响应对象。检查是否成功执行（HTTP 200 OK 状态或客户端库中没有异常），以确定操作是否成功。

重命名和拆分的服务

Ad Manager API 中已重命名或拆分部分服务：

SOAP 服务	REST 资源 / 服务
InventoryService	networks.adUnits
MobileApplicationService	networks.applications
CustomTargetingService	networks.customTargetingKeys networks.customTargetingValues

身份验证

如需使用 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 SOAP API 中，实体由数字 Long ID 标识。 SOAP 中的实体关系也会引用这些数字 ID。

在 Ad Manager API 中，实体由标准资源名称（格式为字符串）标识：

networks/{networkCode}/{collection}/{id}

例如，如果某个订单在广告资源网 123 中的 ID 为 123456，则其资源名称为 networks/123/orders/123456。

迁移代码时：

• 单实体方法和批处理操作方法采用资源名称字符串，而不是数字 ID。
• 实体关系和外键引用使用资源名称。例如，Order.advertiser 是 networks/123/companies/456 而不是 Order.advertiserId。
• 与 SOAP 相比，底层 ID 空间保持不变。您可以从资源名称的最后一部分提取数字 ID。

了解更新掩码

在 Ad Manager SOAP API 中，更新方法接受完整的实体对象并更新所有修改后的字段。

在 Ad Manager API 中，更新操作使用更新掩码。更新掩码用于控制在更新期间修改哪些字段：

• 只有 updateMask 中列出的字段会被修改。掩码中省略的字段保持不变。
• 如果您未指定 updateMask，则请求中存在的所有字段都会更新。

如需了解详情，请参阅字段掩码。

了解过滤条件差异

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 中的字段名称遵循标准化的 REST 和 Google Cloud 惯例，这与 SOAP 不同：

• 显示名称：SOAP name 字段在 Ad Manager API 中重命名为 displayName。例如，Order.name 现在写作 Order.displayName，AdUnit.name 现在写作 AdUnit.displayName。
• 时间戳：SOAP DateTime 字段（例如 lastModifiedDateTime 和 startDateTime）替换为 RFC 3339 时间戳字符串。updateTime和startTime。
• 布尔值：布尔值字段会舍弃 is 等前缀。例如，isArchived 现为 archived。

移除 order by 子句

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

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

提示： 虽然 Ad Manager SOAP API 建议始终添加 ORDER BY 子句以确保分页一致性，但 Ad Manager API（Beta 版）通过分页令牌来保持一致性。

从偏移量迁移到分页令牌

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 空间之间创建映射。如需详细了解如何在界面中迁移报告，请参阅将报告迁移到互动式报告。

如需查看 SOAP 到 REST 枚举值的完整映射，请参阅报告参考文档。

了解 API 差异

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

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

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

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

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

处理错误

在 SOAP API 中，错误以 SOAP 故障的形式返回，并使用 ApiException 和特定于服务的理由代码进行处理。

Ad Manager API 使用标准 Google Cloud RPC 和 HTTP 错误模型：

• 错误会返回标准 HTTP 状态代码，例如 400 INVALID_ARGUMENT、404 NOT_FOUND 或 403 PERMISSION_DENIED。
• 详细的 API 错误（例如字段违规原因）会在错误载荷的错误详细信息中返回。