Udostępnij za pośrednictwem


Omówienie kontraktu danych

W tym artykule wyjaśniono, jak udostępniać dane za pomocą Intelligent Recommendations, aby można je było włączyć i dostarczać sensowne rekomendacje.

Odpowiedni interfejs API Intelligent Recommendations dla opisanych kontraktów danych to interfejs API Intelligent Recommendations.

Pobierz najnowszy plik model.json na temat Intelligent Recommendations dotyczących kontraktów danych: model.json.

Wymagania wstępne

Do integracji danych Intelligent Recommendations wykorzystują Microsoft Azure Data Lake Storage. W tym artykule opisano logiczną strukturę danych, które Intelligent Recommendations mają zużywać się z konta Azure Data Lake Storage .

Aby umożliwić usłudze Intelligent Recommendations łatwe znajdowanie danych na koncie Azure Data Lake Storage, należy utworzyć dedykowany folder na koncie Azure Data Lake Storage i podać ścieżkę do folderu (folder główny usługi Intelligent Recommendations) do usługi Intelligent Recommendations.

Aby uzyskać informacje dotyczące rozpoczynania pracy i tworzenia konta Data Lake Storage, przejdź do wdrożenia Intelligent Recommendations lub odwiedź przewodnik Szybki start.

Kontakty dot. danych

Kontrakty danych to zestaw definicji i ograniczeń struktury danych, które są wykorzystywane w Intelligent Recommendations. Aby umożliwić Intelligent Recommendations pozyskiwanie udostępnionych im danych i dostarczanie rekomendacji, musisz przestrzegać umów dotyczących danych opisanych w tym artykule.

Plik modelu JSON

Kontrakty danych Intelligent Recommendations są logicznie podzielone na zestaw obiektów danych. Każdy obiekt danych składa się z zera lub większej liczby wejściowych plików CSV, które są również nazywane partycjami. Oddzielny plik tekstowy JSON o nazwie model.json opisuje zestaw encji danych. Plik JSON modelu jest wstępnie skonfigurowany i można go natychmiast dodać do folderu głównego Intelligent Recommendations.

Pobieranie modelu domyślnego

Pobierz najnowszy domyślny plik JSON modelu na temat Intelligent Recommendations dotyczących kontraktów danych: model.json.

[!UWAGA]

Plik model.json musi zostać dołączony do folderu Intelligent Recommendations Root oprócz plików Data Entity. Informacje na temat modyfikowania pliku model.json można znaleźć w sekcji Modyfikowanie pliku domyślnego w ramach kontraktu danych.

Zmodyfikuj plik domyślny

Modyfikowanie dostarczonego pliku JSON modelu nie jest zalecane, dopóki nie zapoznasz się z usługą Intelligent Recommendations i tylko podczas korzystania z jednej z następujących funkcji:

  • Format wprowadzania numerycznego. Atrybut kultury określa, czego funkcja Intelligent Recommendations używa jako formatu wejściowego dla wartości liczbowych. Separatorem dziesiętnym może być kropka (.) lub przecinek (,) w różnych kulturach. Aby użyć separatora dziesiętnego innego niż kropka (.), określ odpowiednią kulturę w atrybucie culture.

    Uwaga

    Jeśli użytkownik używa przecinka (,) jako separatora dziesiętnego, musi prawidłowo oddzielać każdą wartość dziesiętną w wejściowym pliku CSV. Więcej informacji na temat znaków znaków w plikach wejściowych CSV można znaleźć w sekcji Format danych.

  • Jawne lokalizacje partycji. Aby określić jawne lokalizacje plików partycji encji danych, można użyć atrybutu partycji. Domyślnie wartość atrybutu partycji to null, co oznacza, że funkcja Intelligent Recommendations automatycznie wyszukuje odpowiednie pliki partycji encji danych. Aby uzyskać więcej informacji, przejdź do tematu Format danych. Atrybut partycji to tablica partycji. Każda partycja zawiera następujące atrybuty:

    • nazwa: reprezentacja ciągów partycji, która nie jest używana przez Intelligent Recommendations w celu określonej logiki.
    • lokalizacja: pełny adres URI do pliku danych partycji (CSV). Muszą być dostępne dla usługi Intelligent Recommendations (tylko do odczytu), co może wymagać zapewnienia odpowiednich uprawnień do Intelligent Recommendations. Więcej informacji na temat dawać Intelligent Recommendations dostęp do danych można znaleźć w Konfiguracja Azure Data Lake Storage.
    • fileFormatSettings: Zawiera następujący atrybut:
      • columnsHeaders: wartość logiczna określająca, czy dane partycji zawierają wiersz nagłówka. Funkcja Intelligent Recommendations automatycznie odrzuca wiersze nagłówka podczas pozyskiwania danych wejściowych. Wartość domyślna to fałsz, czyli brak nagłówków.

Oto przykład atrybutu partycji :

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

Najlepsze praktyki dotyczące aktualizowania danych wejściowych

Unikaj sytuacji, w której dane są modelowane i aktualizowanie jednocześnie, ponieważ może doprowadzić do modelowania danych z różnych wersji zestawów danych i niepożądanych wyników dotyczących rekomendacji. Oto niektóre najlepsze praktyki dotyczące aktualizowania danych wejściowych:

  1. Zapisuj wszystkie encje danych w różnych folderach. Ten folder nie musi być umieszczony w tym samym kontenerze lub na tym samym koncie magazynu, w którym znajdują się bieżące dane wejściowe. Upewnij się, że funkcja Intelligent Recommendations ma uprawnienia do odczytu danych z kontenera zaktualizowanych danych wejściowych. Aby uzyskać więcej informacji, przejdź do tematu Konfigurowanie usługi Azure Data Lake Storage.
  2. Dla każdej z encji danych, których używasz, dodaj atrybut „partycje” w pliku JSON modelu. Dla każdej partycji zaktualizuj atrybut „lokalizacja”, tak aby wskazywał nową lokalizację danych. Objaśnienie dotyczące dodawania i edytowania atrybutu „partycje” można znaleźć tutaj
  3. Możesz usunąć stare dane, jeśli nie są już potrzebne. Zaleca się usunięcie starych danych po szacowanym czasie trwania cyklu modelowania (co najmniej 36 godzin), z użyciem bufora umożliwiającego uniknięcie usunięcia danych podczas ich modelowania.
  4. Powtarzaj kroki 1–3 zawsze, gdy chcesz zaktualizować dane wejściowe.

Encje danych

Jednostka danych to zestaw plików tekstowych dotyczących danych zawierający listę kolumn (nazywanych również atrybutami) oraz wiersze zawierające wartości rzeczywistych danych.

Intelligent Recommendations definiują grupy logiczne obiektów danych, z których każdy ma własny cel. Encje danych są opcjonalne (chyba że określono inaczej), co oznacza, że ich dane mogą być puste lub (całkowicie brakujące).

Funkcja Intelligent Recommendations definiuje następujące grupy encji danych:

Grupowy Encje danych
Encje katalogu danych Przedmioty i warianty
Kategorie przedmiotów
Obrazy przedmiotów i wariantów
Filtry przedmiotów i wariantów
Możliwości przedmiotów i wariantów
Encje danych interakcji Interakcje
Jednostki danych konfiguracji Reco Konfiguracja Reco
Encje danych użytkowników, z których nie można zrezygnować Użytkownicy, którzy nie wyrazili zgody
Rekomendacje wzbogacania encji danych Wzbogacenie zaleceń podstawowych
Wzbogacanie zaleceń
Odwzorowanie obrazu na elementy danych Spis zdjęć
Mapowanie obrazu na element
Encje danych list zewnętrznych Zewnętrzne listy rekomendacji
Zewnętrzne elementy rekomendacji

Format danych

Intelligent Recommendations oczekują, że wszystkie pliki wejściowe partycji obiektów danych będą zgodne z następującym formatem:

  • Zawartość w pliku wejściowym partycji powinna być w formacie plików tekstowych rozdzielanych przecinkami (CSV), przy użyciu wyłącznie tekstu zakodowanego w formacie UTF-8.

  • Każdy plik CSV powinien zawierać wszystkie pola określone w kontrakcie danych odpowiedniego obiektu danych. Dodatkowo pola powinny być wyświetlane zgodnie z zamówieniem opisanym w kontrakcie.

  • W plikach TEGO pliku powinny być przechowywać tylko pozycje danych, zgodnie z RFC 4180.

Oto kilka typowych przykładów zachowania formatu danych CSV w różnych przypadkach:

  • Każde pole może być albo nieujmowane w cudzysłów.

    Na przykład: aaa, „bbb”, ccc

  • Pola zawierające podziały wierszy (CRLF), podwójne cudzysłowy i przecinki muszą być ujęte w podwójne cudzysłowy.

    Na przykład: aaa, „bbCRLFb”, „c, cc”

  • Podwójny cudzysłów występujący wewnątrz pola musi być poprzedzony innym podwójnym cudzysłowem.

    Na przykład: aaa, „b””bb”, ccc

Jeśli nie określono jasno atrybutu partycji (w pliku JSON modelu) dla encji danych, funkcja Intelligent Recommendations wyszuka pliki partycji encji danych w podfolderze (w folderze głównym funkcji Intelligent Recommendations), który ma taką samą nazwę jak encja danych.

W takim przypadku wszystkie pliki wejściowe do partycji w podfolderze encji danych powinny mieć rozszerzenie CSV, takie jak MyData.csv, i nie powinny zawierać wiersza danych nagłówków.

Funkcja Intelligent Recommendations wyszukuje i agreguje dane ze wszystkich plików, które korzystają z rozszerzenia CSV, ignorując samą nazwę pliku.

Przykład struktury folderów Intelligent Recommendations

Poniżej znajduje się przykładowy zrzut ekranu przedstawiający strukturę folderu głównego Intelligent Recommendations. Pliki CSV nie muszą pasować do nazw folderów:

Przykładowa struktura folderu głównego Intelligent Recommendations.

Wymagane jednostki danych dla każdego scenariusza rekomendacji

Scenariusze rekomendacji mogą polegać na różnych encji danych, aby działały prawidłowo. Aby zobaczyć scenariusze pełnego mapowania tabeli i encji danych, zobacz tabelę mapowania encji danych.

Wymagania i ograniczenia dotyczące zawartości danych

Cała zawartość encji danych musi spełniać następujące wymagania i ograniczenia.

Każdy wiersz danych, który nie spełnia tych wymagań, jest traktowany jako określony w kolumnie Nieprawidłowe zachowanie wartości dla odpowiednich encji danych i atrybutów:

  • Wszystkie identyfikatory elementów i wariantów elementów muszą być zgodne z dokładnie jednym z tych ograniczeń (nie można łączyć między formatami identyfikatorów elementów obu opcji):

    • Długość nie może mieć więcej niż 16 znaków i zawierać tylko następujące znaki: A-Z, 0-9, _, -, ~, .
    • W formacie GUID — ciąg dokładnie 36 znaków zawierający znaki szesnastkowe i myślniki; na przykład: 12345678-1234-5678-90ab-1234567890ab. Jeśli chcesz użyć tego formatu GUID, dodaj wpis do encji danych Reco_Config o następujących danych: Key=ItemIdAsGuid, Value=True (czyli ItemIdAsGuid,True). W przeciwnym razie funkcja Intelligent Recommendations nie generuje rekomendacji.
  • Identyfikatory wariantów elementów powinny być unikatowe globalnie (we wszystkich elementach i w różnych elementach).

  • Identyfikator wariantu elementu powinien być pusty w przypadku wierszy danych reprezentujących dane o pozycji głównej lub pozycji samodzielnej.

  • Identyfikatory elementów i identyfikatory wariantów elementów to case-insensityczny, co oznacza, że:

    • Wszystkie identyfikatory ABCD1234, abcd1234 i AbCd1234 są traktowane jako takie same.
    • W przypadku rekomendacji odpowiedzi interfejsu API identyfikatory zwracane są małymi literami.
  • Atrybuty ciągów mają ograniczenie długości. Wartości ciągów przekraczające ich limit są przycinane (nadmiarowe znaki są usuwane) lub cały wiersz danych jest usuwany (dokładne zachowanie jest opisane w tabeli encji danych dla każdego atrybutu).

  • Wszystkie wartości daty i godziny powinny być w formacie UTC w następującym formacie: yyyy-MM-ddTHH:mm:ss.fffZ.

  • We wszystkich ciągach,, z wyjątkiem tytułu elementu i opisu elementu, nie jest rozróżniana wielkość liter. Na przykład nazwy filtrów Kolor i kolor są uważane za takie same, a wartość filtra Czerwony jest taka sama jak wartość filtra czerwony.

  • W przypadku każdego atrybutu innego niż obowiązkowy, który jest pusty, jest używana wartość domyślna (jeśli podano wartość domyślną).

  • Wartości logiczne powinny być prawda lub fałsz i nie uwzględniają wielkości liter (oznacza to, że prawda jest uważana za to samo coPrawda).

Zmiany w poprzedniej wersji

Oto lista zmian kontraktu danych z wersji 1.3 do 1.4:

Encja danych Zmień podsumowanie
Reco_ItemCategories Encja danych jest teraz obsługiwana i może być niepusta.
Reco_ItemAndVariantFilters FilterName obsługuje niestandardową nazwę filtru.
Filtry obsługują teraz filtrowanie wielu wartości (więcej niż jedną wartość filtru).
Reco_ItemAndVariantAvailabilities Kanał i katalog obsługują teraz każdą wartość ciągu (nie tylko 0).
Interakcje Reco Kanał i katalog obsługują teraz każdą wartość ciągu (nie tylko 0).
Reco_ImagesInventory Nowa jednostka danych.
Reco_ImageToItemMappings Nowa jednostka danych.

Zobacz też

Intelligent Recommendations API
Przewodnik szybkiego startu: Skonfiguruj i uruchom Intelligent Recommendations z przykładowymi danymi
Kody statusu API
Tabela mapowania encji danych
Encje katalogu danych
Encje danych interakcji
Jednostki danych konfiguracji Reco
Encje danych list zewnętrznych
Encje danych użytkowników, z których nie można zrezygnować
Rekomendacje wzbogacania encji danych
Odwzorowanie obrazu na elementy danych