Share via

資料合約概觀

  • 發行項

本文說明如何與智慧建議共用資料，如此即可啟用此功能並提供有意義的建議。

所述資料合約對應的智慧建議 API 是智慧建議 API。

下載智慧建議資料合約的最新 model.json 檔案：model.json。

先決條件

為了進行資料整合，智慧建議使用 Microsoft Azure Data Lake Storage。 本文說明智慧建議預計會從您的 Azure Data Lake Storage 帳戶取用之資料的邏輯結構。

若要讓智慧建議可以輕鬆地在 Azure Data Lake Storage 帳戶中尋找您的資料，您必須在 Azure Data Lake Storage 帳戶中建立專用資料夾，並將資料夾路徑 (智慧建議根資料夾) 提供給智慧建議。

如需有關安裝和建立 Data Lake Storage 帳戶的詳細資訊，請移至部署智慧建議和快速入門手冊。

資料合約

資料合約是智慧建議所取用之資料結構的一組定義和約束條件。 若要讓智慧建議內嵌與其共用的資料並提供建議，您必須遵循本文中所述的資料合約。

模型 JSON 檔案

智慧建議資料合約在邏輯上分成一組資料實體。 每個資料實體都包含零個或多個 CSV 輸入檔，這也稱為資料分割。 另一個名為 model.json 的JSON 文字檔描述一組資料實體。 模型 JSON 檔案已預先設定，可立即新增至智慧建議根資料夾。

下載預設模型

下載智慧建議資料合約的最新預設模型 JSON 檔案：model.json。

[!注意]

除了資料實體檔案之外，還需要將 model.json檔案包含在智慧建議根資料夾中。 您可以在此資料合約的修改預設檔案區段中，了解如何對 model.json 進行調整。

修改預設檔案

在您熟悉智慧建議服務之前，不建議修改提供的模型 JSON 檔案，而且也只有在使用下列其中一項功能時，才能進行修改：

  • 數值輸入格式。 文化特性屬性指定智慧建議使用什麼來做為數值的輸入格式。 在不同的文化特性中，小數分隔符號可能是句號 (.) 或逗號 (,)。 若要使用句號 (.) 以外的小數分隔符號，請在文化特性屬性中指定適當的文化特性。

    注意

    如果小數分隔符號使用的是逗號 (,)，您需要正確逸出 CSV 輸入檔中的每個小數值。 如需有關如何逸出 CSV 輸入檔中字元的詳細資訊，請移至資料格式一節。

  • 明確分割位置。 若要指定資料實體分割檔案的明確位置，您可以使用資料分割屬性。 資料分割屬性值預設為 null，表示智慧建議會自動搜尋相關的資料實體分割檔案。 如需詳細資訊，請移至資料格式。 資料分割屬性是資料分割的陣列。 每個資料分割都包含下列屬性：

    • 名稱：資料分割的字串表示，智慧建議未用於任何特定邏輯。
    • 位置：資料分割資料檔 (CSV) 的完整 URI。 URI 必須可供智慧建議存取 (唯讀)，這可能需要您提供適當的權限給智慧建議。 如需有關如何提供資料存取權給智慧建議的詳細資訊，請移至設定 Azure Data Lake Storage。
    • fileFormatSettings：包含下列屬性：
      • columnsHeaders：指定資料分割資料是否包含標題行的布林值。 擷取輸入資料時，智慧建議會自動捨棄標題行。 預設值為 false，表示無標題。

以下是資料分割屬性的範例：

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

升級輸入資料的最佳做法

避免同時對資料建立模型和進行更新的情況，否則可能會導致對混合資料集版本建立模型並產生不可取的建議結果。 一些更新輸入資料的最佳做法如下：

  1. 將所有資料實體寫入不同的資料夾。 此資料夾不一定要位於目前輸入資料所在的同一個容器或儲存體帳戶中。 請務必提供智慧建議權限，以便從更新的輸入資料的容器中讀取資料。 如需詳細資訊，請移至設定 Azure Data Lake Storage。
  2. 對於您要使用的每個資料實體，將 [資料分割] 屬性新增至模型 Json 檔案。 對於每個資料分割，更新 [位置] 屬性，使其指向新的資料位置。 有關如何新增和編輯 [資料分割] 屬性的說明可在這裡找到
  3. 如果不再使用舊資料，您可以將其刪除。 建議在估計的模型週期期間 (至少 36 小時) 之後刪除舊資料，並使用一些緩衝區以避免在建立資料的模型時將資料刪除。
  4. 每次要更新輸入資料時，請重複步驟 1-3。

資料實體

資料實體是一組有一個或多個資料文字檔的集合，每個檔案都有欄 (也稱為屬性) 和包含實際資料值之列的清單。

智慧建議定義資料實體的邏輯群組，每個群組都各有本身用途。 將資料實體視為選用實體 (除非另外明確指出)，這表示其資料可以空的 (或完全遺缺)。

智慧建議定義下列資料實體群組：

群組 資料實體
目錄資料實體 項目和變體
項目類別
項目和變體影像
項目和變體篩選
項目和變體可用性
互動資料實體 互動
Reco 設定資料實體 Reco 設定
退出宣告使用者資料實體 退出宣告使用者
建議擴充資料實體 植入的建議擴充
建議擴充
影像至項目對應資料實體 影像詳細目錄
影像至項目對應
外部清單資料實體 外部建議清單
外部建議項目

資料格式

智慧建議需要所有資料實體資料分割輸入檔符合下列格式：

  • 資料分割輸入檔中的內容應為逗號分隔文字檔 (CSV) 格式，僅使用 UTF-8 編碼文字。

  • 每個 CSV 檔案都必須包含相關資料實體資料合約中指定的所有欄位。 此外，欄位也必須依照該合約中述的順序來顯示。

  • 根據 RFC 4180，CSV 檔案必須只保留資料項目。

以下是 CSV 資料格式行為在不同情況下的一些常見範例：

  • 每個欄位可以用雙引號括住，也可以不用雙引號括住。

    例如：aaa, “bbb”, ccc

  • 包含分行符號 (CRLF)、雙引號和逗號的欄位必須以雙引號括住。

    例如：aaa, “bbCRLFb”, “c, cc”

  • 出現在欄位中的雙引號，前面必須加上另一個雙引號來逸出。

    例如：aaa, “b””bb”, ccc

如果未明確聲明資料實體的資料分割屬性 (在模型 JSON 檔案中)，則智慧建議會在子資料夾中搜尋與資料實體同名的資料實體資料分割檔案 (在智慧建議根資料夾底下)。

在這種情況下，資料實體子資料夾中的所有資料分割輸入檔都必須有 CSV 副檔名 (MyData.csv)，並且不能包含標題資料行。

智慧建議會搜尋並彙總所有使用 CSV 副檔名之檔案中的資料，同時忽略檔案名稱本身。

智慧建議資料夾結構範例

以下是智慧建議根資料夾結構的螢幕擷取畫面範例。 不要求 CSV 必須與資料夾名稱相符：

智慧建議資料夾的範例結構。

每個建議案例所需的資料實體

建議案例可能需要使用不同的資料實體，才能正確運作。 若要查看完整的資料表對應案例和資料實體，請參閱我們的資料實體對應資料表。

資料內容需求和限制

所有資料實體內容都必須遵守下列需求和限制。

任何不符合這些需求的資料列，都會依照相關資料實體及屬性之無效值行為欄中所指定的方式來處理：

  • 所有項目及項目變體識別碼都必須正好符合這其中一項限制 (不能混用兩個選項的項目識別碼格式)：

    • 長度必須小於或等於 16 個字元，且僅包含下列字元：A-Z、0-9、_、-、~、.
    • 使用 GUID 格式 (含十六進位字元和破折號正好 36 個字元的字串)；例如，12345678-1234-5678-90ab-1234567890ab。 如果您想要使用此 GUID 格式，請使用下列介面將項目新增至 Reco_Config 資料實體：Key=ItemIdAsGuid、Value=True (即 ItemIdAsGuid,True)。 否則，智慧建議無法產生建議。

  • 項目變體識別碼必須是全域唯一 (在所有項目和項目變體中)。

  • 對於表示項目主支或獨立項目相關資料的資料列，項目變體識別碼應保持空白。

  • 項目識別碼和項目變體識別碼不區分大小寫，這表示：

    • 識別碼 ABCD1234、abcd1234 和 AbCd1234 全都會視為相同。
    • 在建議 API 回覆中，傳回的識別碼全部都是大寫。

  • 字串屬性有長度限制。 長度超過其限制的字串值會進行修剪 (移除多餘的字元)，或是捨棄整個資料列 (確切的行為會在每個屬性的資料實體資料表中列出)。

  • 所有日期時間值都必須採用 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 管道和目錄現在支援任何字串值 (不只是 0)。
Reco_Interactions 管道和目錄現在支援任何字串值 (不只是 0)。
Reco_ImagesInventory 新增資料實體。
Reco_ImageToItemMappings 新增資料實體。

請參閱

智慧建議 API
快速入門手冊：使用範例資料設定並執行智慧建議
API 狀態碼
資料實體對應資料表
目錄資料實體
互動資料實體
Reco 設定資料實體
External lists data entities
退出宣告使用者資料實體
建議擴充資料實體
影像至項目對應資料實體