從 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 API 也有對應的概念，可取代標準 Ad Manager SOAP 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。
  • 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。
  • 基礎 ID 空間與 SOAP 相同。您可以從資源名稱的最後一個區段擷取數字 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 不同：

  • 顯示名稱：Ad Manager API 中的 SOAP name 欄位已重新命名為 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 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，可以將報表遷移至 UI 中的互動式報表，並在兩個 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 錯誤 (例如欄位違規原因) 會在錯誤酬載的錯誤詳細資料中傳回。