共用方式為

目錄資料實體

  • 發行項

本文提供有關如何在智慧建議資料合約中設定目錄資料實體的指引。

資料實體檢閱

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

智慧建議定義資料實體的邏輯群組，每個群組都各有本身用途。

注意

資料實體為選擇性實體 (除非明確指出)，這表示其資料可以空白或遺失。

移至資料實體完整清單

目錄資料實體簡介

目錄資料實體表示所有做為候選項出現在建議結果中的項目和項目變體 候選項目是藉由將可用性套用至項目所判定，即告訴系統將項目納入建議結果的日期。 傳回結果時，如果未含有效可用性，則忽略項目。

智慧建議支援下列功能及案例：

  • 有多種變化 (例如，不同大小或色彩的襯衫) 或根本沒有變化的項目。 我們將這些變化稱為變體。 不含變體的項目稱為獨立項目，而至少有一個變體的項目稱為項目主支。

  • 將篩選值指派給項目 (例如，類別、色彩或大小)。 稍後在查詢建議時，您可以依據這些篩選值進行篩選。

  • 將影像指派給項目。

  • 項目可能在組織內的不同邏輯實體中提供。 智慧建議支援兩個層級的階層：

    • 管道：項目可受指派至管道，允許智慧建議提供範圍僅限於特定管道中所包含產品的建議。 所有項目都會自動與預設管道建立關聯，而此管道使用字串 0 (零) 做為保留的管道識別碼。

      範例：

      在此範例中，資料集只包含三個項目：X、Y 和 Z。這三個項目會自動指派給預設管道 (管道 = 0)。 您也可以將這些項目指派至您自己的自訂管道。 例如，您可以將項目 X 和 Y 指派至管道=C1，以及將項目 Y 和 Z 指派至管道=C2。

      因此，要求建議時，您可以傳遞下列其他查詢參數：

      • 無管道參數(等於預設管道)：所有三個項目都可在回覆中傳回
      • 管道=0：與無參數相同，因為這是預設管道
      • 管道=C1：只有屬於 C1 管道的項目 (項目 X 和 Y) 可能在回覆中傳回
      • 管道=C2：只有屬於 C2 管道的項目 (項目 Y 和 Z) 可能在回覆中傳回
      • 管道=SomethingElse：空的回覆，因為沒有定義此管道，且未指派任何項目給它

    • 目錄：目錄是另一個等級更精細的可用性細微性。 可讓您在管道中定義多個目錄，並取得特定目錄的建議。 與管道相似，所有項目都會自動與管道中的預設目錄建立關聯，而此目錄使用字串 0 (零) 做為保留的目錄識別碼。

      範例：

      繼續使用管道範例，您有項目 X、Y 和 Z。您已將項目 X 與 Y 指派至管道 C1，系統自動將這些項目指派給管道中的預設目錄 (使用目錄=0)。 您可以將這些項目指派至管道中的自訂目錄，取得進一步的細微性。 讓我們將項目 X 指派給目錄=A，並將項目 X 和 Y 指派給目錄= B。

      因此，要求建議時，您可以傳遞下列其他查詢參數：

      • 管道=C1：無目錄參數，等於預設目錄。 項目 X 和 Y 都可以在回覆中傳回。
      • 管道=C1 和目錄=0：與無目錄參數相同，因為這是預設目錄。
      • 管道=C1 和目錄=A：只有屬於管道 C1 中 A 目錄的項目 (只有項目 X) 可能在回覆中傳回。
      • 管道=C1 和目錄=B：只有屬於管道 C1 中 B 目錄的項目 (項目 X 和 Y) 可能在回覆中傳回。
      • 管道=C1 和目錄=SomethingElse：空的回覆，因為管道 C1 中沒有定義此目錄，且未指派任何項目給它。

  • 宣告項目可用性：

    • 可用性開始/結束日期：超出其可用性時間範圍的項目將會從建議回覆中排除。
    • 精細的可用性細微性：定義特定管道/目錄識別碼中的開始/結束日期。

目錄是由數個資料實體所組成、全都可選用 (取決於您要使用的功能)，並且可在智慧建議根資料夾一直空著 (或遺失)。 如果您不希望提供此資料實體，請遵循下述 Reco_ItemsAndVariants 資料實體中的指導方針。

目錄資料實體清單

下列資料實體是目錄的一部分：

移至資料實體完整清單

項目和變體

資料實體名稱：Reco_ItemsAndVariants

描述：所有項目與項目變體

屬性：

名稱 資料類型 必要 預設值 無效值行為 意見
ItemId 字串 (16) .是 置放項目 如需項目識別碼，請參閱每個建議案例所需的資料實體。
ItemVariantId 字串 (16) 無 置放項目 如需項目變體識別碼，請參閱每個建議案例所需的資料實體。
名稱 字串 (256) 無 修剪值 長度限制為 256 個字元。
名稱 字串 (2048) 無 修剪值 長度限制為 2048 個字元。
ReleaseDate 日期時間 無 1970-01-01T00:00:00.000Z 置放項目 如需日期時間值，請參閱每個建議案例所需的資料實體。

指導方針：

  • 專案變體會繼承其項目主支的屬性。 例如，如果項目變體沒有標題，則繼承其項目主支的標題 (也就是，ItemId 相同但 ItemVariantId 空白的那一列) (若有)。

  • ItemIds 可能與 ItemVariantIds 有一對多關聯。 可以將單一 ItemId 對應至多個 ItemVariantId，以擷取從項目主支到其項目變體之間的關聯。 沒有將其他 ItemId 指定為 ItemVariantId 組合，也能產生特定 ItemId 與 ItemVariantId 組合的單一項目。

  • ReleaseDate 屬性代表過去在市場上發行 (發佈、引進) 項目的日期。 這與項目的可用性 (當項目/產品可以在 API 呼叫中傳回時) 不同，但是 ReleaseDate可能會在案例 (例如「新潮流」) 中使用，而這些類案例需要使用日期進行項目排序。

  • 如果此資料實體為空白 (或遺失)，則智慧建議會自動使用所有在 Reco_Interactions 資料實體中找到的項目及項目變體做為目錄項目的集合，並將每個項目及項目變體指定為預設標題、描述及發行日期。 除非已在 Reco_ItemAndVariantAvailabilities 資料實體中指派明確的可用性給項目，否則會將這些項目視為隨時可用。

  • 智慧建議可以使用標題和描述屬性來提供關聯式建議。 因為智慧建議的關聯式建議目前僅支援 en-us 地區設定，提供任何其他地區設定的標題和描述可能會降低文字建議品質。

範例資料：

標題只是為了方便起見而出現，不應成為實際資料的一部分。

ItemId ItemVariantId 名稱 名稱 ReleaseDate
Item1 2018-05-15T13:30:00.000Z
Item1 Item1Var1 黑色太陽眼鏡 兒童用黑色太陽眼鏡 2018-08-01T10:45:00.000Z
Item1 Item1Var2 棕色太陽眼鏡 成人用棕色太陽眼鏡
Item2 眼鏡清潔布 2019-09-20T18:00:00.000Z
Item3 Item3Var1

返回目錄資料實體

項目類別

資料實體名稱：Reco_ItemCategories

描述：所有項目類別。

屬性：

名稱 資料類型 必要 預設值 無效值行為 意見
ItemId 字串 (16) .是 置放項目 如需項目識別碼，請參閱每個建議案例所需的資料實體。
目錄 字串 (64) .是 修剪值 長度限制為 64 個字元。

指導方針：

  • 每個 ItemId可以有多個類別，表示這可以出現在資料的多個項目中。

  • 如果您的資料是使用類別樹狀目錄所建構，則必須為每個項目提供完整的一組類別 (扁平化)。

範例資料：

標題只是為了方便起見而出現，不應成為實際資料的一部分。

ItemId 目錄
Item1 Category1
Item1 Category1_subCategoryX
Item1 Category1_subCategoryY
Item2 Category1_subCategoryX

返回目錄資料實體

項目和變體影像

資料實體名稱：Reco_ItemAndVariantImages

描述：所有項目與項目變體影像

屬性：

名稱 資料類型 必要 預設值 無效值行為 意見
ItemId 字串 (16) .是 置放項目 如需項目識別碼，請參閱每個建議案例所需的資料實體。
ItemVariantId 字串 (16) 無 置放項目 如需項目變體識別碼，請參閱每個建議案例所需的資料實體。
ImageFullUrl 字串 (2048) .是 置放項目 必須是絕對 URL。 URL 必須正確編碼 (使用百分比編碼)。 長度限制為 2048 個字元。
IsPrimaryImage Bool .是 請參閱指導方針 如需布林值，請參閱每個建議案例所需的資料實體。

指導方針：

  • 您必須將影像明確指派至 ItemId，並指派至每個相關的 ItemVariantId。 指派至項目的影像並不會自動指派給所有項目變體，反之亦然。 指派至項目變體的影像並不會自動指派給該變體的項目主支，反之亦然。

  • 如果為同一個 <ItemId, ItemVariantId> 組合指定多個主要影像，則這些影像中只有一個會用於視覺建議推斷步驟，而其他影像則只會在訓練整個視覺模型時使用。

  • 至於智慧建議無法存取的任何影像，影像 URL 都會遭忽略，而不用於建議模型。

  • 如果 IsPrimaryImage 值無效，則使用 false 的值 (例如，非主要影像)。

  • 如果項目或項目變體僅指定了非主要影像，則智慧建議會使用其中一個指定的影像做為主要影像，仍然為該項目或項目變體提供視覺化建議。

  • 支援的 URL 有兩種類型：

    • 公開可用的 HTTPS URL：不需要授權標頭。 此 URL 不包括公用/匿名可用 Azure Blob 的 URL，這不受支援。
    • 需要驗證的 Azure Blob 儲存體 URL：不是公用/匿名可用。 應將讀取影像 Blob 的權限授與智慧建議 (如部署智慧建議 中所述)。 Blob URL 必須以下列首碼開頭：https://<StorageAccountName>.blob.core.windows.net/。

  • 單一影像支援的大小上限為 512 KB。 系統會忽略任何大於 512 KB 的影像。

  • 影像的 ContentType 必須有影像內容類型 (應以 image 開頭)。 此需求適用於所有影像，皆可透過 HTTPS 和影像 Blob (透過 blob ContentType屬性) 使用。

範例資料：

標題只是為了方便起見而出現，不應成為實際資料的一部分。

ItemId ItemVariantId ImageFullUrl IsPrimaryImage
Item1 https://my.server.org/images/Item1_primary.jpg True
Item1 https://my.server.org/images/Item1_secondary.jpg False
Item1 Item1Var1 https://my.server.org/images/Item1Var1.jpg True
Item2 https://my.server.org/images/Item2.jpg True

返回目錄實體類型清單

項目和變體篩選

資料實體名稱：Reco_ItemAndVariantFilters

描述：用於執行階段結果篩選的項目及項目變體屬性

屬性：

名稱 資料類型 必要 預設值 無效值行為 意見
ItemId 字串 (16) .是 置放項目 如需項目識別碼，請參閱每個建議案例所需的資料實體。
ItemVariantId 字串 (16) 無 置放項目 如需項目變體識別碼，請參閱每個建議案例所需的資料實體。
FilterName 字串 (64) .是 修剪值
FilterValue 字串 (64) .是 修剪值 長度限制為 64 個字元。
FilterType 字串 .是 置放項目 可能的值包括：文字、數值。

指導方針：

  • 項目與項目變體有上下層關聯。 此指導方針表示項目變體將會繼承其項目主支的篩選條件。 例如，如果特定 ItemId 已宣告「色彩」篩選，除非項目變體指定了不同的「色彩」值，否則同一個 ItemId 的所有項目變體都會取得相同的「色彩」篩選值。

  • 文字篩選類型支援「等於」篩選作業。 例如，API 要求可以篩選 [色彩] = "藍色" 的項目。

  • 數值篩選類型支援「範圍」篩選作業。 例如，API 要求可以篩選 [大小] > 40 的項目。

  • 您可以將多個篩選值指派至相同的篩選。 例如，對於「色彩」篩選，您可以提供多個值，例如 "綠色" 和 "藍色"。 在此範例中，相關項目有兩個「色彩」篩選值，將會在您篩選「綠色」項目或「藍色」項目時傳回。 若要將多個值指派至相同的篩選，請使用相同的 FilterName 與 FilterType 值，為每個要指派的篩選值各新增一個項目。

  • 對於每個 FilterName，項目變體可以繼承其上層篩選值，也可加以覆寫。 不支援將兩者合併。 如果變體未指派任何值給篩選，則預設會繼承上層項目篩選值。 如果至少將一個篩選值指派給項目變體的篩選，則會開啟覆寫模式，並且只有變體篩選值有效 (僅適用於特定篩選)。 這個值表示，若要達成「合併」行為，項目變體就必須重複其上層篩選值。 例如，項目支援兩種色彩：藍色和綠色。 如果變體支援其他色彩 (紅色)，則變體必須列出所有已指派至變體識別碼的三種色彩：藍色、綠色和紅色。 在此範例中，專案變體已覆寫「色彩」篩選的值，但是仍然可以從其上層項目繼承其他篩選的值。

  • 將會忽略具有不受支援之篩選類型的項目。

  • 您最多可以提供 20 個不同的 FilterName。

  • 提供多個有相同 FilterName 但 FilterType 不同的項目將無法進行智慧建議資料內嵌程序。

  • 項目或項目變體可以不指定任何篩選。 如果在 API 要求中指定任何篩選條件，則會篩選掉未指定篩選的項目或項目變體。

範例資料：

標題只是為了方便起見而出現，不應成為實際資料的一部分。

ItemId ItemVariantId FilterName FilterValue FilterType
Item1 色彩 紅 文字
Item1 Item1Var1 色彩 紫紅色 文字
Item1 Item1Var2 樣式 矩形 文字
Item2 Size 38 數值
Item2 Color 藍色 文字
Item2 Color 綠 文字

返回目錄實體類型清單

項目和變體可用性

資料實體名稱：Reco_ItemAndVariantAvailabilities

描述：所有項目與項目變體可用性

屬性：

名稱 資料類型 必要 預設值 無效值行為 意見
ItemId 字串 (16) .是 置放項目 如需項目識別碼，請參閱每個建議案例所需的資料實體。
ItemVariantId 字串 (16) 無 置放項目 如需項目變體識別碼，請參閱每個建議案例所需的資料實體。
StartDate 日期時間 無 0001-01-01T00:00:00.000Z 請參閱指導方針 如需日期時間值，請參閱每個建議案例所需的資料實體。
EndDate 日期時間 無 9999-12-31T23:59:59.999Z 請參閱指導方針 如需日期時間值，請參閱每個建議案例所需的資料實體。
雙重屬性 雙重 無 可以根據業務需求使用且不影響建立模型程序的雙重屬性。
通道 字串 (64) 無 0 修剪值 長度限制為 64 個字元。
目錄 字串 (64) 無 12 修剪值 長度限制為 64 個字元。

指導方針：

  • 提醒：可用性告訴系統將哪些項目或項目變體視為建議候選結果。

  • 項目變體的可用性是其項目主支可用性與項目變體本身可用性的聯集。 即使是不含任何項目的項目變體，也會繼承其項目主支可用性。

  • 此資料實體遺失的任何項目都會視為在預設管道及目錄中隨時可用。 更明確地說，智慧建議會表現得就好像該項目是以所有屬性的預設值出現在資料中。

  • ItemIds 與 ItemVariantIds 有一對多關聯。 當 ItemId 不需要有 ItemVariantId 時，可以將多個 ItemVariantId 對應至單一 ItemId。 例如，您可以新增特定 ItemId 與 ItemVariantId 組合的項目，無需為 ItemId (以及空的 ItemVariantId) 明確新增另一個項目。 判斷項目變體是否存在有效的可用性時，只會將指定的項目變體將視為可用 (按照每個變體所指定的時間間隔)。

  • 目錄僅在管道的內容中相關 (目錄是管道的子集)。 例如，管道=歐洲中的目錄=MySale，與管道=亞洲中的目錄=MySale不同。

  • 如果您的資料集包含多個管道和目錄，則必須為每個相關項目及項目變體的每個相關管道與目錄組合各新增一個項目。

  • 可用性日期僅與指定的特定管道及目錄相關。 如果您想要為不同的管道及目錄指定相同的可用性日期，則必須為每個管道及目錄明確新增一個項目。

  • 如果 StartDate 或 EndDate 的屬性有無效的值，則會修改整個項目來表示無法使用的項目。 StartDate 和 EndDate 值都會覆寫為過去的日期時間值。

  • 「雙重屬性」可以留空白。

  • 不要使用 "0" 做為 [管道] 的值。 此值已保留給系統。 使用 "0" 將會導致處理錯誤。

範例資料：

標題只是為了方便起見而出現，不應成為實際資料的一部分。

ItemId ItemVariantId StartDate EndDate 雙重屬性 通道 目錄
Item1 2020-08-20T10:00:00.000Z
Item1 Item1Var1 2020-08-01T12:00:00.000Z
Item2 2020-04-01T10:00:00.000Z 2020-04-15T23:59:59.999Z 15.0
Item2 2020-04-01T10:00:00.000Z 9.76
Item3 2020-05-01T12:00:00.000Z 歐洲 MySale

返回目錄實體類型清單

另請參閱

資料合約概觀
資料實體對應資料表
互動資料實體
Reco 設定資料實體
退出宣告使用者資料實體
外部清單資料實體
建議擴充資料實體
影像至項目對應資料實體
智慧建議 API
快速入門手冊：使用範例資料設定並執行智慧建議