Commerce REST API 參考(私人預覽)

Note

Web IQ Commerce 以私有預覽形式提供給部分 Azure 客戶。 在私人預覽期間,使用費為每 1,000 次 API 呼叫 7.00 美元。 API 表面和合約可能會改變。

符合資格的客戶可以在 Web IQ 開發者入口網站的 Playground 試用 Commerce API。 如果你沒用過 Playground,建議先從 快速入門開始。

我們會在私人預覽期間擴大使用權;存取權並非保證。 若要申請存取或提問,請開啟 Web IQ 支援請求,選擇「 認證與存取 」為問題類型,選擇 API 金鑰設定 為子類型,選擇 建立支援請求,並包含你的 AppID(從 Web IQ 開發者入口網站的個人檔案管理中複製),若尚未有,則提供你的公司名稱及 Web IQ 資源名稱。

Web IQ 商務 API 包括 商務搜尋、 優惠與 產品詳情。 Commerce Search 會回傳排名過的產品和賣家優惠,針對產品查詢。 使用可用產品、SKU,以及與優惠的優惠識別碼。 產品詳情接受產品及SKU識別碼。

三個端點都接受 POST 帶有 JSON 主體的請求。 請在標頭中啟用 Commerce 的 API 金鑰x-apikey,或在標頭中使用 Microsoft Entra ID 存取權杖Authorization來驗證。 請參閱 認證 部分的設定說明。

範例中使用虛構的Contoso產品、賣家、識別碼、網址及價格。 在提出後續請求時,請將範例識別碼替換為 Commerce Search 回應中的數值。

請求標頭

標頭 類型 Description
x-apikey 或 授權 字串 你的 API 金鑰或 Entra ID 存取權杖用於認證。
內容類型 字串 請求實體的 MIME 類型。 請使用 application/json。

支援的市場

在私有預覽期間,Commerce API 支援這些組合 language 和 region。 其他組合不支援。

市場 language region
英文 (美國) en US
西班牙文 (美國) es US
英文 (加拿大) en CA
法語(加拿大) fr CA
英文 (英國) en GB
德文 (德國) de DE
法文 (法國) fr FR
英文 (澳大利亞) en AU
日文 (日本) ja JP

對於你提出的每個報價,無論是用戶還是代理代理人,都應完全按照 clickUrl 回應中回覆的資訊來回應。 預設情況下,clickUrl是 Microsoft 託管的重定向;Microsoft 也可以回傳直接商家的網址。 僅用於 displayUrl 展示或模型上下文中識別商家或賣家,絕不可作為連結或導覽目標。 如果一個報價沒有可用的 clickUrl,就不要提出該報價。

當作不透明來處理 clickUrl 。 歸因參數是必需的,且可以放在重定向內,因此可能看不到。 不要剝離、重寫、截斷、解碼或替換 clickUrl 其歸因參數,也不要自己繞過它的重定向或新增參數。 只有當 a clickUrl 能不修改原始 clickUrl 連結通過時,才能用自己的追蹤或重定向連結包裹。 不要為了不同的回應、查詢、使用者或目的重複使用, clickUrl 包括透過快取。 最終使用者自己的分享或轉發並不算重複使用。

在應用程式代碼 clickUrl 中,從回應中的連結建立,而不是讓模型重現它。 關於適用的條款,請參閱 Web IQ 使用條款的附件 B。

端點:POST https://api.microsoft.ai/v3/search/commerce/products

退貨、排名產品及賣家優惠,針對產品查詢。 使用可用產品、SKU,以及與 優惠的優惠識別碼。 產品詳情 接受產品及SKU識別碼。

Commerce Search 範例請求

curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Contoso wireless headphones",
    "maxResults": 1,
    "language": "en",
    "region": "US",
    "location": "lat:37.7749;long:-122.4194"
  }'

商業搜尋參數

參數 Required 類型 Default Description
query Yes 字串 - 產品搜尋查詢不是空白的。 最大長度為1,000字元。
maxResults No 整數 10 最多可退回的產品數量,從1到50個不等。
language No 字串 en 兩字母 ISO 639-1 結果語言。 參見 支援市場。
region No 字串 US 兩個字母的國家或地區代碼。 參見 支援市場。
location No 字串 - 例如lat:37.7749;long:-122.4194格式中的lat:<latitude>;long:<longitude>位置。 緯度必須是 -90 度到90度,經度則是 -180 度到180度。

商業搜尋回應

回傳一個包含排名產品及其優惠的 CommerceResponse。 若無相符的乘積,回應為 200 OK 空 products 陣列。

範例 200 OK 回應(節錄):

{
  "products": [
    {
      "offers": [
        {
          "id": "100000000001",
          "name": "Contoso Wireless Headphones",
          "seller": {
            "name": "Contoso Electronics",
            "logoUrl": "https://contoso.example/logo.png"
          },
          "price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
        }
      ],
      "id": "PG_00000000000000000000000000000001",
      "skuId": "00000000000000000000000000000001"
    }
  ],
  "traceId": "<trace-id>"
}

商業搜尋錯誤

缺少、空白或過長query、超出範圍maxResults、regionlanguage非兩個字元的 或 或 無效location回傳400(HandlerInvalidInput)。 服務失敗會返回 500 (InternalServerError)。 關於認證、授權、格式及配額錯誤,請參見 「錯誤」部分。

商業搜尋限制

  • query:1到1,000字元,而且不只是空白。
  • maxResults:1到50,預設 10。 退回的產品數量取決於可用的配對。 沒有分頁,也沒有針對每個產品提供數量的參數。
  • language 以及 region:兩字元代碼。 location 座標必須在參數表的範圍內。
  • 你的應用程式設定檔(AppID)的 速率限制和每日配額 也會適用。

Offers

端點:POST https://api.microsoft.ai/v3/fetch/commerce/products/offers

退貨符合資格的賣家優惠、單一產品、SKU,或 Commerce Search 的代表性報價。 它回傳的是賣家的優惠,而不是產品層級的回饋或價格歷史。

邀請範例請求

curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/offers" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "productId": "PG_00000000000000000000000000000001",
    "skuId": "00000000000000000000000000000001",
    "offerId": "100000000001",
    "language": "en",
    "region": "US"
  }'

提供參數

從商業搜尋回應中,傳送所有可用產品、SKU,以及所選產品的優惠識別碼。 如果只回傳一個識別碼,則傳送該識別碼。 至少需要一個非空白的識別碼;沒有 的請求會回傳 400 (HandlerInvalidInput)。

參數 Required 類型 Default Description
productId Conditional 字串 - 商品 id 由Commerce Search退回。 最多1,000字元。
skuId Conditional 字串 - 商品 skuId 由Commerce Search退回。 最多1,000字元。
offerId Conditional 字串 - 商務搜尋退回的代表報價 id 。 最多1,000字元。
language No 字串 en 兩字母 ISO 639-1 結果語言。 參見 支援市場。
region No 字串 US 兩個字母的國家或地區代碼。 參見 支援市場。
location No 字串 - 格式中的 lat:<latitude>;long:<longitude> 地點。 緯度必須是 -90 度到90度,經度則是 -180 度到180度。

提供回應

商務優惠回應

Field 類型 Description
offers CommerceOffer 的 array 先發出主要或代表性報價,接著是其他報價。
traceId 字串 請求追蹤識別碼用於除錯與關聯。

關於優惠欄位,請參見 CommerceOffer、 CommerceOfferImage、 CommerceInstallmentInfo 及 Supporting objects。 未知識別碼 200 OK 則回傳為空 offers 陣列。

範例 200 OK 回應(節錄):

{
  "offers": [
    {
      "id": "100000000001",
      "name": "Contoso Wireless Headphones",
      "seller": {
        "name": "Contoso Electronics",
        "logoUrl": "https://contoso.example/logo.png"
      },
      "price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
    }
  ],
  "traceId": "<trace-id>"
}

出錯

缺少或空白識別碼、超過1,000個字元的識別碼、 language 一個不是兩個字元的或 region ,或是無效 location 的回傳 400 (HandlerInvalidInput)。 未知識別碼 200 OK 則回傳為空 offers 陣列。 服務失敗會返回 500 (InternalServerError)。 請參見錯誤。

優惠限額

  • 每個請求只需一個產品、SKU,或代表性報價查詢;不支援批次查詢。 每個識別碼限制為 1,000 個字元。
  • 沒有 maxResults、 偏移量或游標參數。 報價數量取決於可用性。
  • language 以及 region:兩字元代碼。 location 座標必須在參數表的範圍內。
  • 你的應用程式設定檔(AppID)的 速率限制和每日配額 也會適用。

產品細節

端點:POST https://api.microsoft.ai/v3/fetch/commerce/products/details

回傳商品標題()、name描述,以及商品 ID、SKU ID 或兩者的綜合評分,來自 Commerce Search。 若有描述,也會附上。

產品細節範例請求

curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/details" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "productId": "PG_00000000000000000000000000000002",
    "skuId": "00000000000000000000000000000002",
    "language": "en",
    "region": "US"
  }'

產品細節參數

至少需要其中一份 productId 或 skuId 那份不是空白的,你可以兩份都寄出。 offerId 不是替代方案:只有 offer ID 的請求會無法驗證。

參數 Required 類型 Default Description
productId Conditional 字串 - 商品 id 來自Commerce Search。 當收到「不」 skuId 時,必須如此。 最多1,000字元。
skuId Conditional 字串 - Commerce Search 提供的 SKU ID。 當收到「不」 productId 時,必須如此。 最多1,000字元。
language No 字串 en 兩個字母的語言代碼。 若省略或 null,則使用預設值。 參見 支援市場。
region No 字串 US 產品查詢用的兩字母區域代碼。 若省略或 null,則使用預設值。 參見 支援市場。

產品細節回應

商務產品詳細回應

Field 類型 Description
products 商用產品細節陣列 零或一個匹配的產品。 批次查詢不被支援。
traceId 字串 請求追蹤識別碼。

商務產品詳情

Field 類型 Description
id 字串 跨變體的產品識別碼,與商業搜尋相符。
name 字串 產品名稱(如有)。
description 字串 產品說明(如有)提供。
rating 商業評級 產品平均評分與評分計數,分為1到5分。

商業評級

若無評級資料,則會省略該 rating 物件。

Field 類型 Description
value number 產品平均評分,四捨五入至小數點後兩位。
scaleMin number 評分表的底部(1)。
scaleMax number 評分表頂端(5)。
count 整數 產品評分數。 計數為零時返回為 0。

未知產物會以空products陣列返回200 OK。

範例 200 OK 回應:

{
  "products": [
    {
      "id": "PG_00000000000000000000000000000002",
      "name": "Contoso Wireless Earbuds",
      "description": "Illustrative wireless in-ear headphones",
      "rating": { "value": 4.2, "scaleMin": 1, "scaleMax": 5, "count": 42 }
    }
  ],
  "traceId": "<trace-id>"
}

產品細節錯誤

缺少或空白的產品或 SKU 識別碼、超過 1,000 字元的識別碼,或 language 非兩個字元的 or region 則回傳 400 (HandlerInvalidInput)。 服務失敗會返回 500 (InternalServerError)。 請參見錯誤。

產品細節限制

  • 至少有一個產品或 SKU 識別碼,每個最多 1,000 字元。 批次查詢和只依優惠 ID 查詢都不支援。
  • language 以及 region:兩字元代碼。
  • 你的應用程式設定檔(AppID)的 速率限制和每日配額 也會適用。

回應物件

這些物件由Commerce Search and Offers退回。

CommerceResponse(商業回應)

Field 類型 Description
products CommerceProduct 陣列 產品依排名順序排列。
traceId 字串 請求追蹤識別碼用於除錯與關聯。

商務產品

Field 類型 Description
id 字串 跨變體的產品識別碼。
skuId 字串 目錄 SKU 識別碼。
offers CommerceOffer 的 array 主要賣家出價。

CommerceOffer

Field 類型 Description
id 字串 報價識別碼。
name 字串 賣方所有權證。
description 字串 賣家描述。
specifications 陣列 CommerceSpecification 提供方案層級規格與選定屬性。 重複的檔案與原始順序均被保留。 參見 輔助物件。
seller CommerceSeller 商家資料。 參見 輔助物件。
price CommerceOfferPrice 以ISO 4217小單位提供價格。 offeredPrice 這會回到 listPrice 沒有折扣價格的時候。 參見 輔助物件。
displayUrl 字串 商家或賣家網址,僅供展示或模型上下文參考。 不要把它當作連結或導航目標。
clickUrl 字串 每個連結或導覽的目的地。 請完全照原樣使用。 請參閱 優惠連結與出處。
images 商業服務圖片 提供圖片。
installmentInfo CommerceInstallmentInfo 商業分期付款資訊 分期付款詳情。
shippingInfo 字串 運送資訊,以可讀文字呈現。
condition 字串 賣家提供的商品狀況。

商業提供圖片

Field 類型 Description
url 字串 圖片網址。

CommerceInstallmentInfo 商業分期付款資訊

Field 類型 Description
description 字串 分期付款計畫的說明,以易讀文字呈現。
downPayment CommercePrice 需要先付清金額。 參見 輔助物件。
monthlyPayment CommercePrice 每月分期付款。 參見 輔助物件。
months 整數 月數。

輔助物件

價格以ISO 4217小單位為整數。 例如, 10000 當 currencyUSD 是 $100.00。

物件 Field 類型 Description
CommerceOfferPrice listPrice 整數 原價以ISO 4217小單位計算。
CommerceOfferPrice offeredPrice 整數 目前價格以ISO 4217小單位計算。 這會回到 listPrice 沒有折扣價格的時候。
CommerceOfferPrice currency 字串 ISO 4217 貨幣代碼。
CommercePrice amount 整數 付款金額以ISO 4217小單位計算。
CommercePrice currency 字串 ISO 4217 貨幣代碼。
CommerceSeller name 字串 商家顯示名稱。
CommerceSeller logoUrl 字串 商家標誌網址。
CommerceSpecification name 字串 提供屬性名稱。
CommerceSpecification values 字串陣列 屬性顯示值、保留重複值及來源順序。

Errors

這些錯誤適用於所有三個端點。 每個端點的驗證與空結果行為會在獨立章節中說明。

HTTP 狀態 錯誤代碼 意義與作用
400 RequestInvalidFormat,HandlerInvalidInput JSON格式不佳,或請求參數缺失或無效。 利用端點的參數表和限制來修正請求。
401 認證錯誤,例如AuthNoTokenAuthInvalidApiKey 憑證遺失、無效或過期。 用有效的憑證重新驗證。
403 AuthUnauthorizedService 呼叫者無權存取所請求的資源。 如果您的應用程式設定檔未啟用商務服務,請依照本頁頂端說明申請存取權限。
405 MethodNotAllowed 使用 POST,而不是 GET。
415 RequestUnsupportedMediaType 發送 content-type: application/json。
429 AuthUserThrottled,AuthUserDailyUsageExceeded 你的應用程式設定檔(AppID)的速率上限或每日配額被超標了。 等時間到再 retryAfter 重試。
500 InternalServerError 服務無法完成這個請求。 在標示的延遲後再試一次,並在聯絡客服時附上說明 traceId 。

錯誤回應

錯誤則使用共享 錯誤回應結構。

Field 類型 Description
errorCode 字串 機器可讀的錯誤代碼。
errorCategory 字串 UserError 或 SystemError。
userMessage 字串 錯誤說明清楚易懂。
technicalDetails 字串 可選的診斷細節。
retryAfter 字串 可選的重試延遲以秒為單位,後接s後綴(例如)。 "60s"
requestId 字串 可選的請求識別碼。
traceId 字串 支援可選的分散式追蹤識別碼。

錯誤範例

商業搜尋請求不含 query:

curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{}'

400 Bad Request 回應:

{
  "errorCode": "HandlerInvalidInput",
  "errorCategory": "UserError",
  "userMessage": "Invalid input provided. Please check your request parameters.",
  "technicalDetails": "query is required",
  "traceId": "<trace-id>"
}

速率限制

這三個端點都使用你 Web IQ AppID 的速率限制和每日配額(預設每秒 15 次查詢),這些配額會與其他 App ID 呼叫的 Web IQ API 共享。 回應包含429重試延遲。retryAfter 每日配額將於 00:00 UTC 重置。 關於重試指引,請參見 錯誤處理。