清查資源

發行項
12/21/2023

注意事項

清查 API 僅適用于已關閉的試驗參與者。 API 和檔可能會變更。

清查資源可讓您更新 Microsoft 商家中心 (MMC) 存放區中產品的定價和可用性。如需使用清查資源的相關資訊，請參閱更新產品定價。如需示範如何更新定價和可用性的範例，請參閱程式碼範例。

基底 URI

以下是您附加範本的基底 URI。

https://content.api.bingads.microsoft.com/shopping/v9.1

範本

若要建立用來更新產品供應專案的端點，請將適當的範本附加至基底 URI。

[範本]	HTTP 動詞	說明
/bmc/{mmcMerchantId}/inventory/batch	POST	使用在單一要求中執行多個產品定價更新。設定 `{mmcMerchantId}` 為 MMC 存放區識別碼。要求物件： Batch 回應物件： Batch
/bmc/{mmcMerchantId}/inventory/{storeCode}/products/{productUniqueId}	POST	使用來更新單一產品的定價和可用性。設定 `{mmcMerchantId}` 為 MMC 存放區識別碼。設定 `{storeCode}` 為 [線上]。設定 `{productUniqueId}` 為完整產品識別碼 (例如 Online：en：US：Sku123) 。要求物件： Product 回應物件： Product

查詢參數

端點可能包含下列查詢參數。

參數	說明
dry-run	選用。在偵錯應用程式以測試呼叫時使用。包含此參數的呼叫不會影響生產資料。如果發生錯誤，回應會包含呼叫通常產生的任何錯誤，但資料品質、編輯問題和資料庫相關驗證等次要錯誤訊息除外。如需測試應用程式的詳細資訊，請參閱沙箱。

標題

以下是要求和回應標頭。

頁首	說明
AuthenticationToken	要求標頭。將此標頭設定為 OAuth 存取權杖。如需取得存取權杖的資訊，請參閱驗證您的認證。
Content-Type	要求和回應標頭。要求或回應主體中的內容類型。設定為 application/json。
CustomerAccountId	要求標頭。您代表標頭中指定的客戶所管理之任何帳戶的 `CustomerId` 帳戶識別碼。您指定的帳號並不重要。只有在您代表客戶管理帳戶時，才指定此標頭。
CustomerId	要求標頭。您管理其存放區之客戶的客戶識別碼。只有在您代表客戶管理市集時，才指定此標頭。如果您設定此標頭，也必須設定 `CustomerAccountId` 標頭。
DeveloperToken	要求標頭。用戶端應用程式的開發人員權杖。每個要求都必須包含此標頭。如需取得權杖的相關資訊，請參閱您是否有 Microsoft Advertising 認證和開發人員權杖？
位置	回應標頭。已更新之產品的 URL。
WebRequestActivityId	回應標頭。包含要求詳細資料的記錄專案識別碼。如果發生錯誤，您應該一律擷取此識別碼。如果您無法判斷並解決問題，請包含此識別碼以及您提供支援小組的其他資訊。

要求和回應物件

以下是 API 所使用的要求和回應物件。

物件	描述
批	定義批次要求中要更新的產品清單。
錯誤	定義錯誤。
ErrorResponse	定義非批次更新的最上層錯誤物件。
BatchEntryError	定義批次處理期間針對專案所發生的錯誤。
Entry	定義批次要求或回應中的專案。
產品	定義產品。
ProductPrice	定義產品的價格。

批

定義要在批次中更新的產品清單。

名稱	值	類型
條目	要在批次中更新的產品清單。您可以指定的產品數目上限為 400。	Entry[]

BatchEntryError

定義批次處理期間針對專案所發生的錯誤。

名稱	值	類型
錯誤	處理專案時發生的錯誤清單。	Error[]
code	錯誤的 HTTP 狀態碼。	字串
訊息	與錯誤相關聯的訊息。	字串

錯誤

定義錯誤。

名稱	值	類型
網域	僅限內部使用。	字串
訊息	錯誤的描述。	字串
reason	要求失敗的原因。例如，產品驗證失敗。	字串

ErrorResponse

定義單一產品更新的最上層錯誤物件。

名稱	值	類型
錯誤	處理專案時發生的錯誤清單。	Errors[]

錯誤

定義產品的錯誤清單。

名稱	值	類型
錯誤	處理專案時發生的錯誤清單。	Error[]
code	錯誤的 HTTP 狀態碼。	字串
訊息	與錯誤相關聯的訊息。	字串

項目

定義批次要求中的專案。

名稱	值	類型
batchId	使用者定義的識別碼，可在批次要求中唯一識別此專案。例如，如果批次包含 10 個專案，您可以指派識別碼 1 到 10。	Unsigned Integer
錯誤	錯誤物件，其中包含發生的驗證錯誤清單。只有在發生錯誤時，回應才會包含此欄位。	BatchEntryError
庫存	更新的價格和可用性。	產品
商家識別碼	商家中心商店識別碼。因為 URL 包含存放區識別碼，所以會忽略此欄位。	Unsigned Long
productId	完整產品識別碼 (例如要更新之產品的 Online：en：US：Sku123) 。請勿包含具有相同產品識別碼的多個專案。	字串
storeCode	識別要更新之存放區的程式碼。設定為線上，以更新線上商店中產品的價格和可用性。	字串

產品

定義產品。

屬性	說明	類型	必要
可用性	產品的可用性。可能的值：內建缺貨 preorder	字串	是
kind	物件的型別。設定為 content#inventory。	字串	否
價格	產品的新價格。以目標國家或地區的貨幣指定價格。如需是否要在價格中包含稅金的資訊，請參閱 Microsoft 商家中心目錄稅務原則。價格必須符合產品網頁上顯示的價格，且必須介於 0.01 (1 cent) 到 10000000.00 (10000 萬) 範圍內。不過，如果符合下列條件，您可以將價格設定為 0.0 (零) 。產品的 `googleProductCategory` 欄位設定為下列其中一個類別：電子 > 通訊 > 電話語音 > 行動電話電子 > 電腦 > Tablet 電腦產品的 `title` 欄位包含下列其中一個關鍵字：合同安裝租賃付款上述關鍵字會以英文顯示;不過，title 和關鍵字必須是指定市場語言。標題通常會包含片語，例如「...含方案」或「...僅限合約」。合約關鍵字可在所有市場中使用;不過，收款、付款和租用只能在美國市場使用。	ProductPrice	是
salePrice	產品的銷售價格。針對銷售專案，請設定銷售價格和銷售生效日期 (請參閱 `salePriceEffectiveDate`) 。如果您設定銷售價格，但未設定銷售價格生效日期，則會繼續使用銷售價格，直到產品到期或您設定有效日期為止。銷售價格必須介於 0.01 (1 cent) 到 10000000.00 (1000 萬) 範圍內。不過，如果符合下列條件，您可以將銷售價格設定為 0.0 (零) 。 googleProductCategory 欄位設定為下列其中一個類別：電子 > 通訊 > 電話語音 > 行動電話電子 > 電腦 > Tablet 電腦標題欄位包含下列其中一個關鍵字：合同安裝租賃付款上述關鍵字會以英文顯示;不過，title 和關鍵字必須是指定市場語言。標題通常會包含片語，例如「...含方案」或「...僅限合約」。合約關鍵字可在所有市場中使用;不過，收款、付款和租用只能在美國市場使用。如果未指定，則會從供應專案中移除目前銷售的價格。請勿傳遞 null。	ProductPrice	否
salePriceEffectiveDate	銷售的 UTC 開始和結束日期。只有在您設定時，才指定 `salePrice` 日期。以 ISO 8601 格式指定開始和結束日期。例如，2016-04-05T08：00-08：00/2016-04-10T19：30-08：00 (使用斜線 ('/') 來分隔開始和結束日期) 。如需詳細資訊，請參閱 `salePrice`。如果未指定，則會從供應專案中移除目前銷售的日期。請勿傳遞 null。	字串	否

ProductPrice

定義產品的價格或銷售價格。

名稱	值	類型
貨幣	價格所述的貨幣。可能的值： AUD (澳大利亞元) 加拿大元 () CHF (瑞士法郎) 歐元 (歐元) GBP (英國) INR (印度盧比) SEK (瑞典克朗) 美元 (美國美元)	字串
數值	產品的價格。	雙精度浮點數

HTTP 狀態碼

要求可能會傳回下列 HTTP 狀態碼。

狀態碼	描述
200	成功。
400	不正確的要求。查詢參數值無效，或要求本文中的某個專案無效。如果發生錯誤，失敗的批次專案將會包含錯誤。
401	未經授權。使用者的認證無效。
403	禁止。使用者沒有使用資源的許可權。
404	找不到。
409	衝突。無法完成作業，因為與資源的目前狀態發生衝突。
413	要求實體太大。要求的大小超過允許的最大值。
500	伺服器錯誤。

共用方式為