カタログ データ エンティティ
この記事では、Intelligent Recommendations データ契約でカタログ データ エンティティを構成する方法を説明します。
データ エンティティ レビュー
データ エンティティ は、1 つ以上のデータ テキスト ファイルのセットであり、それぞれに実際のデータ値を含む列 (または 属性) と行の一覧があります。
Intelligent Recommendations は、それぞれ独自の目的を持つデータ エンティティの論理グループを定義します。
Note
データ エンティティはオプションなので (特に明記されていない限り)、データが空または欠落している可能性があります。
カタログ データ エンティティの概要
カタログ データ エンティティは、レコメンデーション結果に表示される候補となるすべての品目と品目バリアントを表します。 候補は、品目に 利用可能性 を適用して決定されます。これは、システムに品目を推奨結果に含めるように指示する日付です。 有効な利用状態がない場合、結果が返されるときに品目は無視されます。
Intelligent Recommendations は、次の機能とシナリオをサポートしています:
複数のバリエーションがある品目 (たとえば、サイズや色が異なるシャツ)、またはバリエーションがまったくない品目。 これらのバリエーションをバリアントと呼びます。 バリアントを持たない品目を スタンドアロン品目 と呼び、少なくとも 1 つのバリアントを持つ品目を 品目マスター と呼びます。
品目へのフィルター値の割り当て (カテゴリー、色、サイズなど)。 後でレコメンデーションを照会するときに、これらのフィルター値でフィルターできます。
品目への画像の割り当て。
品目は、組織内のさまざまな論理エンティティ内で使用できます。 Intelligent Recommendations では、次の 2 つの階層レベルがサポートされています:
Channel: 品目を チャネル に割り当てることができるため、Intelligent Recommendations が、特定のチャネルに含まれる製品のみを対象としたレコメンデーションを提供できます。 すべての品目は、予約済みチャネル ID として文字列 0 (ゼロ) を使用する、既定のチャネルに自動的に関連付けられます。
用例:
この例では、データセットには X、Y、Z の 3 つの品目しか含まれていません。これらの 3 つの品目は、既定のチャネル (Channel=0) に自動的に割り当てられます。 これらの品目を独自のカスタム チャネルに割り当てることもできます。 たとえば、品目 X と Y を Channel=C1 に、品目 Y と Z を Channel=C2 に割り当てることができます。
したがって、レコメンデーションを要求するときに、次の他のクエリ パラメーターを渡すことができます。
- Channel パラメーターなし (既定のチャネルと等しい): 3 つの品目すべてを応答で返すことができます
- Channel=0: これは既定のチャネルであるため、パラメーターなしと同じです
- Channel=C1: C1 チャネルに属する品目 (品目 X および Y) のみが応答で返されます
- Channel=C2: C2 チャネルに属する品目 (品目 Y および Z) のみが応答で返されます
- Channel=SomethingElse: このチャネルが定義されておらず、品目が割り当てられていないため、応答が空になります
Catalog: カタログ は、利用可能性の細分性をさらに細かくした別のレベルです。 チャネル内で複数のカタログを定義し、特定のカタログのレコメンデーションを取得できます。 チャネルと同様に、すべての品目は、予約済みカタログ ID として文字列 0 (ゼロ) を使用する、チャネル内の既定のカタログに自動的に関連付けられます。
用例:
Channel の例では、品目 X、Y、Z があります。品目 X および Y をチャネル C1 に割り当て、それらをチャネルの既定のカタログに (Catalog=0 を使用して) 自動的に割り当てます。 これらの品目をチャネル内のカスタム カタログに割り当てることで、さらに細かく設定できます。 品目 X を Catalog=A に、品目 X と Y を Catalog=B に割り当てます。
したがって、レコメンデーションを要求するときに、次の他のクエリ パラメーターを渡すことができます。
- Channel=C1: カタログ パラメーターがなく、既定のカタログと同じです。 品目 X と Y の両方を応答で返すことができます。
- Channel=C1&Catalog=0: これは既定のカタログであるため、カタログ パラメーターなしと同じです。
- Channel=C1&Catalog=A: チャネル C1 の A カタログに属する品目のみ (品目 X のみ) が、応答で返されます。
- Channel=C1&Catalog=B: チャネル C1 の B カタログに属する品目のみ (品目 X と Y) が、応答で返されます。
- Channel=C1&Catalog=SomethingElse: このカタログがチャネル C1 で定義されておらず、品目が割り当てられていないため、応答が空になります。
品目の利用可能性を宣言:
- 利用可能な開始日/終了日: 利用可能な時間の範囲外の品目は、レコメンデーションの応答から除外されます。
- 利用可能性の詳細な細分性: 特定のチャネル/カタログ ID 内で開始日/終了日を定義します。
カタログはいくつかのデータ エンティティで構成されていますが、すべてオプション (使用する機能によって異なる) であり、Intelligent Recommendations ルート フォルダーから空 (または欠落) のままにすることができます。 このデータ エンティティを指定しない場合は、以下で説明する Reco_ItemsAndVariants データ エンティティのガイドラインに従ってください。
カタログ データ エンティティのリスト
次のデータ エンティティはカタログの一部です:
品目とバリアント
データ エンティティ名:Reco_ItemsAndVariants
説明: すべての品目と品目バリアント
属性:
| 件名 | データ型 | 必須 | 規定値 | 無効な値の動作 | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | 有効 | エントリをドロップ | 品目 ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| ItemVariantId | String(16) | 番号 | エントリをドロップ | 品目バリアント ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| 肩書き | String(256) | 番号 | 値のトリミング | 長さは 256 文字に制限されています。 | |
| 設定 | String(2048) | 番号 | 値のトリミング | 長さは 2048 文字に制限されています。 | |
| ReleaseDate | DateTime | 番号 | 1970-01-01T00:00:00.000Z | エントリをドロップ | DateTime 値については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 |
ガイドライン:
品目バリアントは、品目マスターの属性を継承します。 たとえば、品目バリアントにタイトルがない場合、品目マスター (つまり、同じ ItemId だが空の ItemVariantId) が存在すれば、タイトルを継承します。
ItemIds は ItemVariantIds と 一対多 の関連付けを持つことができます。 1 つの ItemId を複数の ItemVariantId にマッピングして、品目マスターからその品目バリアントへの関係を取得することができます。 特定の ItemId と ItemVariantId の組み合わせに対して、他の ItemId と ItemVariantId の組み合わせを指定せずに、1 つのエントリを持つことが可能です。
ReleaseDate 属性は、品目が市場でリリース (公開、導入) された日付を表します。 この属性は、品目の 利用可能性 (API 呼び出しで品目/製品を返すことができる場合) とは異なりますが、ReleaseDate は、品目の注文日付に依存する新規やトレンドなどのシナリオで使用される場合があります。
このデータ エンティティが空 (または欠落) の場合、Intelligent Recommendations は、自動的に Reco_Interactions データ エンティティにあるすべての品目と品目バリアントをカタログ品目のセットとして使用し、各品目と品目バリアントに既定のタイトル、説明、およびリリース日を割り当てます。 これらの品目は、Reco_ItemAndVariantAvailabilities データ エンティティで明示的な利用可能性が割り当てられていない限り、常に利用可能 と見なされます。
Intelligent Recommendations では、Title と Description の属性を使用して、テキスト ベースのレコメンデーションを提供できます。 Intelligent Recommendations は現在、テキスト レコメンデーションに対して en-us ロケールのみをサポートしているため、他のロケールで Title と Description を指定すると、テキスト レコメンデーションの品質が低下する可能性があります。
サンプル データ:
ヘッダーは便宜上表示されるものであり、実際のデータの一部ではありません。
| ItemId | ItemVariantId | 肩書き | 設定 | ReleaseDate |
|---|---|---|---|---|
| アイテム 1 | 2018-05-15T13:30:00.000Z | |||
| アイテム 1 | Item1Var1 | 黒のサングラス | 子供用の黒いサングラス | 2018-08-01T10:45:00.000Z |
| アイテム 1 | Item1Var2 | 茶色のサングラス | 大人用茶色のサングラス | |
| アイテム 2 | 眼鏡用クリーニング クロス | 2019-09-20T18:00:00.000Z | ||
| Item3 | Item3Var1 |
品目カテゴリ
データ エンティティ名:Reco_ItemCategories
説明: すべての品目カテゴリ。
属性:
| 件名 | データ型 | 必須 | 規定値 | 無効な値の動作 | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | 有効 | エントリをドロップ | 品目 ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| Category | String(64) | 有効 | 値のトリミング | 長さは 64 文字に制限されています。 |
ガイドライン:
各 ItemId は複数のカテゴリを持つことができ、これはデータの複数エントリに表示されることを意味します。
データがカテゴリ ツリーを使用して構築されている場合は、各品目のカテゴリの完全なセット (フラット化) を指定する必要があります。
サンプル データ:
ヘッダーは便宜上表示されるものであり、実際のデータの一部ではありません。
| ItemId | Category |
|---|---|
| アイテム 1 | Category1 |
| アイテム 1 | Category1_subCategoryX |
| アイテム 1 | Category1_subCategoryY |
| アイテム 2 | Category1_subCategoryX |
品目とバリアントの画像
データ エンティティ名:Reco_ItemAndVariantImages
説明: すべての品目と品目バリアントの画像
属性:
| 件名 | データ型 | 必須 | 規定値 | 無効な値の動作 | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | 有効 | エントリをドロップ | 品目 ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| ItemVariantId | String(16) | 番号 | エントリをドロップ | 品目バリアント ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| ImageFullUrl | String(2048) | 有効 | エントリをドロップ | 絶対 URL である必要があります。 URL は適切にエンコードされている必要があります (パーセント エンコードを使用)。 長さは 2048 文字に制限されています。 | |
| IsPrimaryImage | Bool | イエス | ガイドラインを参照 | ブール値については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 |
ガイドライン:
画像を ItemId および関連する各 ItemVariantId に明示的に割り当てる必要があります。 品目に割り当てられた画像は、すべての品目バリアントに自動的に割り当てられるわけではなく、その逆も同様です。 品目バリアントに割り当てられた画像は、そのバリアントの品目マスターに自動的には割り当てられません。
同じ <ItemId, ItemVariantId> 組み合わせに対して複数のプライマリ画像が指定されている場合、これらの画像の 1 つだけが視覚的レコメンデーションの推論ステップに使用され、他の画像は視覚モデル全体をトレーニングするときにのみ使用されます。
Intelligent Recommendations がアクセスに失敗した画像の場合、画像の URL は無視され、レコメンデーション モデルには使用されません。
IsPrimaryImage 値が無効な場合は、false の値が使用されます (たとえば、非プライマリ画像)。
品目または品目バリアントに非プライマリ画像のみが指定された場合、Intelligent Recommendations は指定された画像の 1 つをプライマリ画像として使用して、その品目または品目バリアントの視覚的なレコメンデーションを引き続き提供します。
サポートされている URL には、次の 2 種類があります:
- パブリックに利用可能な HTTPS URL: Authorization ヘッダーは必要ありません。 この URL には、サポートされていない公開/匿名で利用可能な Azure BLOB の URL は含まれません。
-
認証を必要とする Azure Blob Storage URL: 公開/匿名で利用できません。 画像 BLOB を読み取るためのアクセス許可は、Intelligent Recommendations の展開 で説明されているように、Intelligent Recommendations に付与する必要があります。 Blob URL は、次の接頭辞で始まる必要があります:
https://<StorageAccountName>.blob.core.windows.net/。
1 枚の画像で使用可能な最大サイズは 512 KB です。 512 KB を超える画像は、システムによって無視されます。
画像の ContentType は、画像のコンテンツ タイプが必要です (image で始まる必要があります)。 この要件は、HTTPS と画像 BLOB (BLOB ContentType プロパティ経由) の両方で利用可能なすべての画像に適用されます。
サンプル データ:
ヘッダーは便宜上表示されるものであり、実際のデータの一部ではありません。
| ItemId | ItemVariantId | ImageFullUrl | IsPrimaryImage |
|---|---|---|---|
| アイテム 1 | https://my.server.org/images/Item1_primary.jpg |
True | |
| アイテム 1 | https://my.server.org/images/Item1_secondary.jpg |
False | |
| アイテム 1 | Item1Var1 | https://my.server.org/images/Item1Var1.jpg |
True |
| アイテム 2 | https://my.server.org/images/Item2.jpg |
True |
品目とバリアントのフィルター
データ エンティティ名:Reco_ItemAndVariantFilters
説明: 実行時の結果のフィルターに使用される品目および品目バリアントのプロパティ
属性:
| 件名 | データ型 | 必須 | 規定値 | 無効な値の動作 | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | 有効 | エントリをドロップ | 品目 ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| ItemVariantId | String(16) | 番号 | エントリをドロップ | 品目バリアント ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| FilterName | String(64) | 有効 | 値のトリミング | ||
| FilterValue | String(64) | 有効 | 値のトリミング | 長さは 64 文字に制限されています。 | |
| FilterType | String | 有効 | エントリをドロップ | 指定できる値: テキスト、数値。 |
ガイドライン:
品目と品目バリアントには親子関係があります。 このガイドラインは、品目バリアントが品目マスターのフィルターを継承することを意味します。 たとえば、“Color” フィルターが特定の ItemId に対して宣言された場合、同じ ItemId のすべての品目バリアントは、品目バリアントに別の “Color” の値が指定されていない限り、同じ “Color” フィルターの値を取得します。
テキスト フィルター タイプは、"equals" フィルター操作をサポートします。 たとえば、API 要求は "Color"="Blue" で品目をフィルターできます。
数値フィルター タイプは、"range" フィルター操作をサポートします。 たとえば、API 要求は"Size" > 40 で品目をフィルターできます。
同じフィルターに複数のフィルター値を割り当てることができます。 たとえば、"Color" フィルターの場合、"Green" や "Blue" などの複数の値を指定できます。 この例では、関連品目は "Color" フィルターに 2 つの値を持ち、"Green" 品目または "Blue" 品目のいずれかをフィルターすると返されます。 同じフィルターに複数の値を割り当てるには、同じ FilterName 値と FilterType 値を使用して、割り当てるフィルター値ごとにエントリを追加します。
各 FilterName に対して、品目バリアントは、その親フィルター値を継承するか、上書きすることができます。 2 つの結合はサポートされていません。 既定では、バリアントがフィルターに値を割り当てていない場合、親品目のフィルター値を継承します。 少なくとも 1 つのフィルター値が品目バリアントのフィルターに割り当てられている場合、上書きモードがオンになり、バリアント フィルター値のみが有効になります (特定のフィルターのみ)。 この値は、"merge" 動作を実現するには、品目バリアントがその親フィルター値を繰り返す必要があることを意味します。 たとえば、品目は青と緑の 2 色をサポートします。 バリアントが別の色である赤をサポートしている場合、バリアントは、バリアント ID に割り当てられている 3 つの色 (青、緑、赤) をすべて一覧表示する必要があります。 この例では、品目バリアントは "Color" フィルターの値を上書きしましたが、その親アイテムから他のフィルターの値を継承できます。
サポートされていないフィルター タイプのエントリは無視されます。
最大 20 個の異なる FilterName を指定できます。
同じ FilterName で異なる FilterType を持つ複数のエントリを指定すると、intelligent recommendations データ取り込みプロセスに失敗します。
品目または品目バリアントにフィルターを指定することはできません。 API 要求でフィルターを指定した場合、指定したフィルターを持たない品目または品目バリアントがフィルターで除外されます。
サンプル データ:
ヘッダーは便宜上表示されるものであり、実際のデータの一部ではありません。
| ItemId | ItemVariantId | FilterName | FilterValue | FilterType |
|---|---|---|---|---|
| アイテム 1 | Color | 赤 | テキスト | |
| アイテム 1 | Item1Var1 | Color | 赤紫色 | テキスト |
| アイテム 1 | Item1Var2 | スタイル | 長方形 | テキスト |
| アイテム 2 | 規模 | 38 | 数値 | |
| アイテム 2 | カラー | 青 | テキスト | |
| アイテム 2 | カラー | 緑 | テキスト |
品目とバリアントの利用可能性
データ エンティティ名:Reco_ItemAndVariantAvailabilities
説明: すべての品目と品目バリアントの利用可能性
属性:
| 件名 | データ型 | 必須 | 規定値 | 無効な値の動作 | Comments |
|---|---|---|---|---|---|
| ItemId | String(16) | 有効 | エントリをドロップ | 品目 ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| ItemVariantId | String(16) | 番号 | エントリをドロップ | 品目バリアント ID については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 | |
| StartDate | DateTime | 番号 | 0001-01-01T00:00:00.000Z | ガイドラインを参照 | DateTime 値については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 |
| EndDate | DateTime | 番号 | 9999-12-31T23:59:59.999Z | ガイドラインを参照 | DateTime 値については、レコメンデーション シナリオごとに必要なデータ エンティティ を参照してください。 |
| 倍精度浮動小数点属性 | 倍精度浮動小数点 | 番号 | ビジネスのニーズに応じて使用でき、モデリング プロセスに影響を与えない二重属性。 | ||
| Channel | String(64) | いいえ | 0 | 値のトリミング | 長さは 64 文字に制限されています。 |
| Catalog | String(64) | 番号 | 12 | 値のトリミング | 長さは 64 文字に制限されています。 |
ガイドライン:
アラーム: 利用可能性 は、推奨結果の候補とみなされる品目または品目バリアントをシステムに通知します。
品目バリアントの利用可能性は、品目マスターの利用可能性と品目バリアント自体の利用可能性を結合したものです。 エントリがない品目バリアントでも、品目マスターの利用可能性を継承します。
このデータ エンティティにない品目は、既定のチャネルとカタログで常に利用可能であると見なされます。 具体的には、Intelligent Recommendations は、その品目がすべての属性の既定値でデータに表示されているかのように動作します。
ItemIds は ItemVariantIds と 一対多 の関連付けを持ちます。 ItemId に ItemVariantId を含める必要はありませんが、複数の ItemVariantId を 1 つの ItemId にマッピングすることは可能です。 たとえば、特定の ItemId と ItemVariantId の組み合わせのエントリを、ItemId (および空の ItemVariantId) の別のエントリを明示的に追加せずに追加できます。 品目バリアントに有効な利用可能性があるかどうかを判断するために、指定された品目バリアントのみが、(各バリアントごとに指定された時間間隔で) 利用可能とみなされます。
カタログ は、チャネル のコンテキストでのみ関連します (カタログはチャネルのサブセットです)。 例えば、channel=Europe の catalog=MySale は、channel=Asia の catalog=MySale とは異なるカタログです。
データセットに複数のチャネルとカタログが含まれている場合は、関連する品目と品目バリエーションごとの、関連するチャネルとカタログの組み合わせごとに、エントリを追加する必要があります。
利用可能日は、指定された特定のチャネルとカタログにのみ関連します。 異なるチャネルとカタログに同じ利用可能日を指定する場合は、チャネルとカタログごとにエントリを明示的に追加する必要があります。
属性 StartDate または EndDate のいずれかに無効な値がある場合、エントリ全体が変更され、利用できない品目を示します。 StartDate と EndDate の両方の値が、過去の DateTime 値で上書きされます。
「倍精度浮動小数点属性」は空のままにすることができます。
"Channel" の値として "0" を使用しないでください。 この値はシステム用に予約されています。 "0" を使用すると、処理エラーが発生します。
サンプル データ:
ヘッダーは便宜上表示されるものであり、実際のデータの一部ではありません。
| ItemId | ItemVariantId | StartDate | EndDate | 倍精度浮動小数点属性 | Channel | カタログCatalog |
|---|---|---|---|---|---|---|
| アイテム 1 | 2020-08-20T10:00:00.000Z | |||||
| アイテム 1 | Item1Var1 | 2020-08-01T12:00:00.000Z | ||||
| アイテム 2 | 2020-04-01T10:00:00.000Z | 2020-04-15T23:59:59.999Z | 15.0 | |||
| アイテム 2 | 2020-04-01T10:00:00.000Z | 9.76 | ||||
| Item3 | 2020-05-01T12:00:00.000Z | 欧州 | MySale |
参照
データ コントラクトの概要
データ エンティティ マッピング テーブル
対話データ エンティティ
Reco 構成データ エンティティ
オプトアウト済みユーザー データ エンティティ
外部リスト データ エンティティ
レコメンデーション エンリッチメント
データ エンティティ画像から品目へのマッピング データ エンティティ
Intelligent Recommendations API
クイック スタート ガイド: サンプル データで Intelligent Recommendations を設定し、実行する