範例 API 要求

發行項
10/07/2024

本文顯示一些範例 API 要求及相關的回覆。每個範例都會顯示基本建議案例以及其他回覆修改功能，例如篩選、分頁、選取替代演算法等等。如果想要在您的智慧建議端點上試用這些範例，請務必根據您的資料，更換端點名稱 (DNS 部分) 並調整參數。

注意

計數參數會控制每個回覆中傳回的項目數目。為清晰簡潔起見，範例將計數設定為 5。如需 API 要求建構方式的詳細資訊，請參閱智慧建議 API 和呼叫 API 快速入門手冊。

範例

以下是一些可以使用智慧建議帳戶進行測試的範例：

如果測試回覆時遇到錯誤，請查看錯誤記錄。

取得新項目

新項目 API 會傳回依發行日期排序的產品清單。

API 要求看起來像這樣：

https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/New?modeling=adw&Count=5

成功的回覆看起來像這樣：

{
    "id": "Lists",
    "name": "Lists",
    "version": "v1.0",
    "interactionsVersion": "20220104115104",
    "items": [
        {
            "id": "70000",
            "trackingId": "00000000-0000-0000-0000-000000000003"
        },
        {
            "id": "70002",
            "trackingId": "00000000-0000-0000-0000-000000000003"
        },
        {
            "id": "70003",
            "trackingId": "00000000-0000-0000-0000-000000000003"
        },
        {
            "id": "70004",
            "trackingId": "00000000-0000-0000-0000-000000000003"
        },
        {
            "id": "70005",
            "trackingId": "00000000-0000-0000-0000-000000000003"
        }
    ],
    "title": "New",
    "longTitle": "New",
    "titleId": 3,
    "pagingInfo": {
        "totalItems": 278
    },
    "status": "Success"
}

AlgoType	定義	支援 API
RecentPurchases	精選建議是根據使用者最近的購買項目計算而來。	僅適用於使用者精選 API。
視覺效果	項目相似性是根據目錄影像的視覺相似性計算而來。	僅適用於類似 API。
文字	專案相似性是根據文字 (語言理解) 目錄文字描述的相似性來計算。	僅適用於類似 API。

程式碼	執行狀態	原因	如何解決
200	成功	API 要求已成功。	無法使用
200	EmptyResults	對此種子項目 (itemId) 有一些建議，但是全都篩選掉了。	篩選的主要原因是資料已與目錄中的項目相關聯。當您預計特定產品要遭到退回時，請務必驗證其可用日期，並確定這些產品都是使用適當的篩選指派 (例如類別、通路、目錄和可用性) 正確設定。
200	DataDoesNotExist	結果中沒有種子項目 (itemId)。輸入資料中可能缺少指定的 itemId，或是資料不足，無法取得計算結果。	檢查項目是否： - 有效 - 屬於正確管道 - 有足夠的互動/影像/文字。如需詳細資訊，請參閱資料合約格式設定指南。
200	WaitingForData	建立新的模型元件時，計算可能需要一些時間，並且可能尚未準備好傳回結果。	檢查記錄或模型狀態報表，以了解是否發生錯誤。如果 24 小時後問題仍然存在，且沒有錯誤記錄，請連絡我們。
400	UnsupportedRequest	其中一個 API 參數有不支援的值，或是 API 要求發生另一個問題，例如：不支援或已停用的案例。	檢查標頭值是否與實際參數不同。如需工作中 API 要求的範例，請移至本文頂端。根據模型功能集是設定為標準還是進階，停用不同的 API 要求。您也可以檢查模型狀態報表，以了解是否有任何演算法發生錯誤。
400	UnsupportedFeature	您正在嘗試根據目前的模型功能集呼叫不支援的 API。	啟用設定為 [標準] 或 [進階] 的正確模型功能集。每個功能集可用的案例清單。
401		未驗證的要求	確定您的租用戶已指派要讓服務運作的權限。依照下列步驟檢查您的驗證。
408	RequestTimeout	您的要求已逾時。	嘗試重新呼叫 API 要求。
429		RPS 高於預先配置階層，並且有遭到節流的風險。	將預先配置 RPS 容量增加至更高階層，或減少目前的 RPS。
500	內部伺服器錯誤	智慧建議一方發生錯誤。	這可能是暫時性問題，因此請在幾分鐘後再試一次。檢查記錄或模型狀態報表，以了解是否發生錯誤。如果問題仍然存在，且沒有錯誤記錄，請連絡我們。
503	ServiceUnavailable	服務無法處理帳戶。	檢查記錄或模型狀態報表，以了解是否發生錯誤。如果問題仍然存在，且沒有錯誤記錄，請連絡我們。

共用方式為

範例 API 要求

範例

取得新項目

在跳過前 3 名的同時取得新項目

取得熱門項目

取得特定類別中的熱門項目

使用離散篩選，取得特定類別中的熱門項目

在篩選一系列值的同時，取得特定類別中的熱門項目

取得類似項目

使用隨機順序取得類似項目

產生外觀

完成類似樣式

完成類似項目

取得使用者精選

使用 sessionId 取得使用者精選

後續最佳動作

中繼資料標記和使用者貯體

如何使用 AlgoType 參數

範例 AlgoType

使用 AlgoType 建構 API 要求

如何使用 Refinements 參數

使用 Refinements 建構 API 要求

API 狀態碼

另請參閱

其他資源