データ契約の概要

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

この記事では、Intelligent Recommendations とデータを共有して有効にし、意味のあるレコメンデーションを提供できるようにする方法について説明します。

記述されているデータコントラクトに対応する Intelligent Recommendations API は、Intelligent Recommendations API です。

Intelligent Recommendations データコントラクトに対する最新の model.json ファイルをダウンロードします: model.json。

前提条件

データ統合の場合、Intelligent Recommendations は Microsoft Azure Data Lake Storage を使用します。この記事では、Intelligent Recommendations が Azure Data Lake Storage アカウントから使用すると予想されるデータの論理構造について説明します。

Intelligent Recommendations が Azure Data Lake Storage アカウント内のデータを簡単に見つけられるようにするには、Azure Data Lake Storage アカウント内に専用フォルダーを作成し、Intelligent Recommendations へのフォルダーパス (Intelligent Recommendations ルートフォルダー) を指定する必要があります。

Data Lake Storage アカウントのオンボードと作成については、Intelligent Recommendations の展開に移動するか、クイックスタートガイドにアクセスします。

データコントラクト

データコントラクト とは、Intelligent Recommendations が使用するデータ構造に関する一連の定義と制約です。 Intelligent Recommendations が共有されているデータを取り込み、レコメンデーションを提供できるようにするには、この記事で説明するデータコントラクトを遵守する必要があります。

モデル JSON ファイル

Intelligent Recommendations のデータコントラクトは、一連のデータエンティティに論理的に分割されます。各データエンティティは、パーティション とも呼ばれる 0 個以上の入力 CSV ファイルで構成されます。 model.json という名前の別個 JSON テキストファイルは、データエンティティのセットを記述します。モデル JSON ファイルは事前構成されており、Intelligent Recommendations ルートフォルダーにすぐに追加できます。

既定モデルのダウンロード

Intelligent Recommendations データコントラクトに対する最新の既定モデル JSON ファイルをダウンロードします: model.json。

[!注意]

model.json ファイルは、データエンティティファイルに加えて、Intelligent Recommendations ルートフォルダーに含まれている必要があります。このデータ契約のデフォルトファイルの変更セクションで model.json を調整する方法を確認できます。

既定ファイルの変更

提供されているモデル JSON ファイルを変更することは、Intelligent Recommendations サービスに精通しており、次の機能のいずれかを使用する場合にのみお勧めします。

数値入力形式。 culture 属性は、Intelligent Recommendations が数値の入力形式として使用するものを指定します。小数点は、異なるカルチャでピリオド (.) またはコンマ (,) にすることができます。ピリオド (.) 以外の小数点を使用するには、culture 属性で適切なカルチャを指定します。

Note

コンマを (,) を小数点として使用している場合は、入力 CSV ファイルで各小数値を適切にエスケープする必要があります。 CSV 入力ファイルの文字をエスケープする方法の詳細については、データ形式セクションに移動します。
明示的なパーティションの場所。データエンティティパーティションファイルの明示的な場所を指定するには、partitions 属性を使用します。既定では、partitions 属性値が null で、Intelligent Recommendations が関連するデータエンティティパーティションファイルを自動的に検索することを意味します。詳細については、データ形式を参照してください。 partitions 属性はパーティションの配列です。各パーティションには、次の属性が含まれます:
- name: パーティションを示す文字列。特定ロジックの Intelligent Recommendations では使用されません。
- location: パーティションデータファイル (CSV) へのフル URI。 URI は Intelligent Recommendations (読み取り専用) にアクセスできる必要があり、Intelligent Recommendations に適切なアクセス許可を付与する必要がある場合があります。 Intelligent Recommendations にデータへのアクセスを許可する方法の詳細については、Azure Data Lake Storage の設定にアクセスしてください。
- fileFormatSettings: 次の属性が含まれます:
  - columnsHeaders: パーティションデータにヘッダー行が含まれるかどうかを指定するブール値。 Intelligent Recommendation は、入力データを取り込む際に、ヘッダー行を自動で破棄します。既定値は false で、ヘッダーはありません。

以下に partitions 属性の例を示します:

"partitions": [
        {
            "name": "Partition1",
            "location": "https://myStorageAcount.blob.core.windows.net/intelligent-recommnedations-container/intelligent-recommendations-root-folder/partition1.csv",
            "fileFormatSettings": {
                "columnHeaders": true
            }
        }
    ]

入力データを更新する場合のベストプラクティス

混合したデータセットのバージョンからデータをモデリングし、不適切なレコメンデーション結果が生成される可能性があるため、データのモデリングと更新を同時に実行する状況は避けてください。入力データを更新する際のベストプラクティスを次に示します。

すべてのデータエンティティを別のフォルダーに書き込みます。現在の入力データを配置しているのと同じコンテナーやストレージアカウントに、このフォルダーを配置する必要はありません。更新した入力データのコンテナーからデータを読み取るために、Intelligent Recommendation アクセス許可を必ず付与してください。詳細については Azure Data Lake Storage の設定を参照してください。
使用しているデータエンティティごとに、'partitions' 属性をモデルの Json ファイルに追加します。新しいデータの場所を指すように、パーティションごとに 'location' 属性を更新します。 'partitions' 属性の追加や編集を行う方法については、こちらを参照してください
もう使用しない場合は古いデータを削除できます。モデリングによるデータの削除を防ぐために、ある程度のバッファーを確保して、推定モデリングサイクル期間 (少なくとも 36 時間) が経過してから古いデータを削除することを推奨します。
入力データを更新するたびに手順 1 ～ 3 を繰り返します。

データエンティティ

データエンティティ は、1 つ以上のデータテキストファイルのセットであり、それぞれに実際のデータ値を含む列 (または属性) と行の一覧があります。

Intelligent Recommendations は、それぞれ独自の目的を持つデータエンティティの論理グループを定義します。データエンティティは、特に明記されていない限り、オプションと見なされることに注意してください。つまり、データが空 (または完全に欠落) になる可能性があります。

Intelligent Recommendations は、次のデータエンティティグループを定義します。

Group	データエンティティ
カタログデータエンティティ	品目とバリアント品目カテゴリ品目とバリアントの画像品目とバリアントのフィルター品目とバリアントの利用可能性
対話データエンティティ	対話
Reco 構成データエンティティ	Reco 構成
オプトアウト済みユーザーデータエンティティ	オプトアウト済みユーザー
レコメンデーションエンリッチメントデータエンティティ	シードレコメンデーションエンリッチメントレコメンデーションエンリッチメント
画像から品目へのマッピングデータエンティティ	画像インベントリ画像から品目へのマッピング
外部リストデータエンティティ	外部レコメンデーションリスト外部レコメンデーションアイテム

データの書式

Intelligent Recommendations では、すべてのデータエンティティのパーティション入力ファイルが次の形式に準拠していることを前提としています:

パーティション入力ファイル内のコンテンツは、UTF-8 エンコードテキストのみを使用して、コンマ区切りテキストファイル (CSV) 形式である必要があります。
各 CSV ファイルには、関連するデータエンティティのデータコントラクトで指定されたすべてのフィールドを含める必要があります。さらに、フィールドは、その契約に記載されている順序に従って表示する必要があります。
RFC 4180 に従って、CSV ファイルはデータエントリのみを保持する必要があります。

さまざまな場合における CSV データ形式の動作の一般的な例を次に示します:

各フィールドは、二重引用符で囲まれている場合と囲まれていない場合があります。

例: aaa、"bbb"、ccc
改行 (CRLF)、二重引用符、コンマを含むフィールドは、二重引用符で囲む必要があります。

例: aaa、“bbCRLFb”、“c, cc”
フィールド内に表示される二重引用符は、その前に別の二重引用符を付けてエスケープする必要があります。

例: aaa、“b””bb”、ccc

データエンティティの partitions 属性 (モデル JSON ファイル内) を明示的に指定しなかった場合、Intelligent Recommendations は、データエンティティと同じ名前のサブフォルダ (Intelligent Recommendations ルートフォルダの下) 内のデータエンティティパーティションファイルを検索します。

この場合、データエンティティサブフォルダー内のすべてのパーティション入力ファイルには、MyData.csv などの CSV ファイル拡張子が必要で、ヘッダーのデータ行を含めることはできません。

Intelligent Recommendations は、ファイル名自体を無視して、CSV 拡張子を使用するすべてのファイルからデータを検索して集計します。

Intelligent Recommendations フォルダー構造の例

次のスクリーンショットは、Intelligent Recommendations ルートフォルダー構造の例を示します。 CSV がフォルダー名と一致する必要はありません。

Intelligent Recommendations ルートフォルダーの構造例。

各レコメンデーションシナリオに必要なデータエンティティ

レコメンデーションシナリオは、正しく機能するためにさまざまなデータエンティティに依存する場合があります。完全なテーブルマッピングシナリオとデータエンティティを確認するには、データエンティティマッピングテーブルを参照してください。

データコンテンツの要件と制限

すべてのデータエンティティのコンテンツは、次の要件と制限を尊重する必要があります。

これらの要件を考慮しないデータ行は、関連するデータエンティティと属性の 無効な値の動作 列で指定されたとおりに処理されます。

すべての品目と品目バリアント ID は、これらの制限の 1 つにのみに準拠する必要があります (両方のオプションの品目 ID 形式を混在させることはできません)。
- 長さは 16 文字以下で、次の文字のみを含む必要があります: A-Z, 0-9, _, -, ~,.
- GUID 形式—16 進文字とダッシュを含む 36 文字の文字列; 例えば、12345678-1234-5678-90ab-1234567890ab。この GUID 形式を使用する場合は、次のデータを持つ Reco_Config データエンティティにエントリを追加します: Key=ItemIdAsGuid、Value=True (つまり、ItemIdAsGuid,True)。そうしないと、Intelligent Recommendations はレコメンデーションの生成に失敗します。
品目バリアント ID は、グローバルに一意である必要があります (すべての品目と品目バリアントにわたって)。
品目バリアント ID は、品目マスターまたはスタンドアロン品目に関するデータを表すデータ行の場合、空のままにしておく必要があります。
品目 ID と品目バリアント ID は大文字と小文字を区別せず、次のようになります:
- ID ABCD1234、abcd1234、AbCd1234 は、すべて同じとみなされます。
- レコメンデーション API 応答では、返される ID はすべて大文字です。
文字列属性には長さ制限があります。制限を超過する文字列値は、切り捨てられるか (余分な文字は削除されます)、データ行全体が削除されます (正確な動作は各属性のデータエンティティテーブルに一覧表示されます)。
すべての DateTime 値は UTC 形式で、次の形式である必要があります: yyyy-MM-ddTHH:mm:ss.fffZ。
品目の タイトル と品目の説明を除く、すべての文字列では大文字と小文字は区別されません。たとえば、フィルター名 Color と color は同じとみなされ、フィルター値 Red はフィルター値 red と同じです。
空の必須でない属性の場合、既定値が使用されます (既定値が指定されている場合)。
ブール値は true または false のいずれかで、大文字と小文字を区別しません (つまり、true は True と同じとみなされます)。

以前のバージョンからの変更

以下に、バージョン 1.3 とバージョン 1.4 の間のデータコントラクトの変更点のリストを示します:

データエンティティ	変更内容の概要
Reco_ItemCategories	データエンティティに対応したため、空でなくてもかまいません。
Reco_ItemAndVariantFilters	FilterName はカスタムフィルター名をサポートします。フィルターは、複数値フィルター (複数のフィルター値) をサポートするようになりました。
Reco_ItemAndVariantAvailabilities	Channel と Catalog は、任意の文字列値 (0だけでなく) をサポートするようになりました。
Reco_Interactions	Channel と Catalog は、任意の文字列値 (0だけでなく) をサポートするようになりました。
Reco_ImagesInventory	新規データエンティティ。
Reco_ImageToItemMappings	新規データエンティティ。

参照

次の方法で共有

データ契約の概要

前提条件

データコントラクト

モデル JSON ファイル

既定モデルのダウンロード

既定ファイルの変更

入力データを更新する場合のベストプラクティス

データエンティティ

データの書式

Intelligent Recommendations フォルダー構造の例

各レコメンデーションシナリオに必要なデータエンティティ

データコンテンツの要件と制限

以前のバージョンからの変更

参照

その他のリソース

次の方法で共有

データ契約の概要

前提条件

データ コントラクト

モデル JSON ファイル

既定モデルのダウンロード

既定ファイルの変更

入力データを更新する場合のベスト プラクティス

データ エンティティ

データの書式

Intelligent Recommendations フォルダー構造の例

各レコメンデーション シナリオに必要なデータ エンティティ

データ コンテンツの要件と制限

以前のバージョンからの変更

参照

その他のリソース

データコントラクト

入力データを更新する場合のベストプラクティス

データエンティティ

各レコメンデーションシナリオに必要なデータエンティティ

データコンテンツの要件と制限