從 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 也提供讀取單一實體的方法。下表顯示 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。
  • 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 中的 ID 無法用於 REST API。SavedQuery

如果您使用 SavedQuery，可以將報表遷移至 UI 中的互動式報表，並在兩個 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 個維度。