從 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 方法的對應範例：

驗證

如要使用 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：新的或現有的重新整理權杖。

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

瞭解篩選器的差異

Ad Manager API (Beta 版) 查詢語言支援所有發布商查詢語言 (PQL) 功能，但兩者之間存在重大的語法差異。

以下是列出 Order 物件的範例，說明主要變更，例如移除繫結變數、區分大小寫的運算子，以及以個別欄位取代 ORDER BY 和 LIMIT 子句：

<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>

{
  "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