API 要求のサンプル

[アーティクル]
10/07/2024

この記事では、API リクエストと関連するレスポンスの例をいくつか示します。各例では、基本的な推奨シナリオに加え、フィルタリング、ページング、代替アルゴリズムの選択など、その他の応答修正機能を示します。もしこれらの例を Intelligent Recommendations のエンドポイントで試用する場合は、必ずエンドポイント名 (DNS 部分) を置き換え、パラメータをご利用のデータに合わせて調整してください。

Note

count パラメーターは、各レスポンスで返されるアイテムの数を制御します。例では、わかりやすく簡潔にするため、カウントを 5 にしています。 API リクエストを作成する方法の詳細については、Intelligent Recommendations APIとAPIを呼び出すためのクイックスタートガイドを参照してください。

使用例

Intelligent Recommendations アカウントでテストできるいくつかの例を次に示します:

応答のテスト中にエラーが発生した場合は、エラーログを参照してください。

新しい項目の取得

New Items 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	Definition	サポートされる API
RecentPurchases	レコメンデーションは、ユーザーの最新の購入に基づいて計算されます。	ユーザーピック API でのみ使用できます。
ビジュアル	アイテムの類似性は、カタログ画像の視覚的な類似性に基づいて計算されます。	類似 API でのみ使用できます。
テキスト	項目の類似性は、カタログのテキスト記述のテキスト (言語理解) の類似性に基づいて計算されます。	類似 API でのみ使用できます。

コード	状態	Reason	解決する方法
200	Success	API 要求は正常に完了しました。	N/A
200	EmptyResults	このシードアイテム (itemId) にはレコメンデーションがありますが、それらはすべて除外されました。	フィルタリングの主な理由は、カタログ内のアイテムに関連付けられたデータです。特定の製品の返品が予想される場合は、その製品の入手可能日を確認し、カテゴリ、チャネル、カタログ、在庫状況などの適切なフィルター割り当てを使用して正しく構成されていることを確認することが重要です。
200	DataDoesNotExist	シードアイテム (itemId) が結果に存在しません。指定された itemId が入力データにないか、計算結果を得るのに十分なデータがない可能性があります。	アイテムが次の状態であることを確認します: - 有効である - 適切なチャンネルに属している - 十分な対話/画像/テキストがある。詳細については、データコントラクト形式ガイドのチェックを参照してください。
200	WaitingForData	新しいモデリングコンポーネントが作成されると、計算に時間がかかり、結果を返す準備ができていない場合があります。	ログまたはモデリングステータスレポートをチェックして、エラーがあるかどうかを確認します。 24 時間経過してもエラーログが記録されずに問題が解決しない場合は、お問い合わせください。
400	UnsupportedRequest	API パラメーターの 1 つにサポートされていない値が含まれているか、API 要求に別の問題があります (サポートされていない、または無効になっているシナリオなど)。	ヘッダー値が実際のパラメーターと異なるかどうかを確認してください。実際の API 要求の例については、この記事の先頭に移動してください。モデリング機能セットが Standard と Premium のどちらに設定されているかに応じて、異なる API 要求が無効になります。また、モデリングステータスレポートをチェックして、アルゴリズムにエラーがないかどうかを確認することもできます。
400	UnsupportedFeature	現在のモデリング機能セットに基づいてサポートされていない API を呼び出そうとしています。	Standard または Premium に設定された正しいモデリング機能を有効にします。各機能セットで利用可能なシナリオのリスト。
401		Unauthenticated 要求	サービスを操作するためのアクセス許可がテナントに割り当てられていることを確認してください。検証をチェックするには、次のステップに従います。
408	RequestTimeout	要求がタイムアウトしました。	API 要求を再度呼び出してみてください。
429		RPS は事前に割り当てられた層を超えているため、調整される危険があります。	事前に割り当てられた RPS の容量を上位層に増やすか、現在の RPS を減らします。
500	内部サーバーエラー	Intelligent Recommendations 側でエラーが発生しました。	この問題は一時的なものである可能性があるため、数分後にもう一度試してください。ログまたはモデリングステータスレポートをチェックして、エラーがあるかどうかを確認します。エラーログが記録されずに問題が解決しない場合は、お問い合わせください。
503	ServiceUnavailable	サービスがアカウントを処理できません。	ログまたはモデリングステータスレポートをチェックして、エラーがあるかどうかを確認します。エラーログが記録されずに問題が解決しない場合は、お問い合わせください。

次の方法で共有

API 要求のサンプル

使用例

新しい項目の取得

上位 3 をスキップしながら新しいアイテムを取得する

人気のある項目を取得する

特定のカテゴリーで人気のある項目を取得する

特定のカテゴリーで人気のある項目を離散的なフィルターで取得する

特定のカテゴリーで、数値の範囲をフィルターしながら人気のある項目を取得する

類似する項目を取得する

シャッフルで類似する項目を入手する

外観の導入

完全な類似スタイル

完全な類似アイテム

ユーザー ピックを取得する

SessionID を使用してユーザーの選択を取得

次に行うべき最良の対応

メタデータのタグ付けとユーザーのバケット化

AlgoType パラメーターの使用方法

AlgoTypes の例

AlgoType を使用した API 要求の作成

Refinements パラメーターの使用方法

Refinements を使用した API 要求の作成

API 状態コード

参照

その他のリソース

ユーザーピックを取得する