Del via

Oversigt over datakontrakt

  • Artikel

I denne artikel forklares, hvordan du kan dele data med Intelligent Recommendations, så du kan aktivere dem og komme med meningsfulde anbefalinger.

Den tilsvarende API for Intelligent Recommendations til de beskrevne datakontrakter er API'en for Intelligent Recommendations.

Download den nyeste model.json-fil til datakontrakter for Intelligent Recommendations: model.json.

Forudsætninger

I forbindelse med dataintegration bruger Intelligent Recommendations Microsoft Azure Data Lake Storage. I denne artikel beskrives den logiske struktur for de data, som Intelligent Recommendations forventer at bruge via din Azure Data Lake Storage-konto.

For at sikre, at Intelligent Recommendations nemt kan finde dine data på Azure Data Lake Storage-kontoen, skal du oprette en særlig mappe under Azure Data Lake Storage-kontoen og angive mappestien (rodmappen til Intelligent Recommendations) til Intelligent Recommendations.

Du kan få oplysninger om onboarding og oprettelse af din Data Lake Storage-konto ved at gå til Installation af Intelligent Recommendations eller gå til vores Vejledning til hurtig start.

Datakontrakter

Datakontrakter er et sæt definitioner af og begrænsninger for strukturen af de data, der bruges af Intelligent Recommendations. For at sikre, at Intelligent Recommendations kan anvende de data, der deles med tjenesten, og komme med anbefalinger, skal du overholde datakontrakterne som beskrevet i denne artikel.

JSON-modelfil

Datakontrakter for Intelligent Recommendations er logisk opdelt i et sæt dataobjekter. Hvert dataobjekt består af nul eller flere CSV-inputfiler, der også kaldes partitioner. En separat JSON-tekstfil med navnet model.json beskriver dataobjektsættet. JSON-modelfilen er forudkonfigureret og kan føjes til rodmappen for Intelligent Recommendations med det samme.

Download standardmodellen

Download den nyeste JSON-standardmodelfil til datakontrakter for Intelligent Recommendations: model.json.

[Bemærk!]

Filen model.json skal inkluderes i rodmappen for Intelligent Recommendations sammen med dataobjektfilerne. Du kan få mere at vide om, hvordan du foretager justeringer i model.json, under afsnittet Rediger standardfilen i denne datakontrakt.

Rediger standardfilen

Det anbefales ikke at redigere den medfølgende JSON-fil, før du bliver fortrolig med tjenesten Intelligent Recommendations, og kun, når du bruger en af følgende funktioner:

  • Numerisk inputformat. Attributten culture angiver, hvad intelligente anbefalinger anvender som inputformat for numeriske værdier. Decimalseparatoren kan være et punktum (.) eller et komma (,) i forskellige kulturer. Hvis du vil bruge en anden decimalseparator end et punktum (.), skal du angive den relevante kultur i attributten culture.

    Bemærk

    Hvis du bruger et komma (,) som decimalseparator, skal du slette alle decimalværdier i CSV-inputfilen. Du kan finde flere oplysninger om, hvordan du sletter tegn i CSV-inputfiler, i afsnittet Dataformat .

  • Eksplicitte partitionsplaceringer. Hvis du vil angive eksplicitte placeringer for partitionsfilerne med dataobjekter, kan du bruge partitionsattributten. Værdien for partitionsattributten er som standard null, hvilket betyder, at intelligente anbefalinger automatisk søger efter de relevante filer til partitionsfiler for dataobjekter. Du kan finde flere oplysninger under Dataformat. Partitionsattributten er en matrix med partitioner. Hver partition indeholder følgende attributter:

    • name: En strengbaseret gengivelse af partitionen, der ikke bruges af Intelligent Recommendations til en bestemt logik.
    • location: Komplet URI til partitionsdatafilen (CSV). URI'en skal være tilgængelig for Intelligent Recommendations (skrivebeskyttet), hvilket muligvis kræver, at du angiver de rette tilladelser til Intelligent Recommendations. Du kan finde flere oplysninger om, hvordan du giver Intelligent Recommendations adgang til data, ved at gå til Konfigurer Azure Data Lake Storage.
    • fileFormatSettings: Indeholder følgende attribut:
      • columnsHeaders: En boolesk værdi, der angiver, om partitionsdataene indeholder en overskriftslinje. Intelligent Recommendations fjerner automatisk overskriftslinjer, når inputdata indtages. Standardværdien er false, hvilket betyder, at der ikke er nogen overskrifter.

Her er et eksempel på partitionsattributten:

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

Bedste fremgangsmåder for opdatering af inputdata

Undgå, at data modelleres og opdateres på samme tid, da det kan føre til modellering af data fra versioner af blandede datasæt og uønskede anbefalingsresultater. Nogle af de bedste fremgangsmåder for opdatering af inputdata er følgende:

  1. Skriv alle dataobjekterne til en anden mappe. Denne mappe behøver ikke at være placeret i den samme objektbeholder eller lagerkonto, som dine aktuelle inputdata findes i. Sørg for at give Intelligent Recommendation tilladelse til at læse data fra objektbeholder med dine opdaterede inputdata. Du kan finde flere oplysninger ved at gå til Konfigurere Azure Data Lake Storage-integration.
  2. Føj attributten 'partitioner' til Json-modelfilen for hvert af de dataobjekter, du bruger. I forbindelse med de enkelte partitioner skal du opdatere attributten 'placering', så den peger på den nye dataplacering. Du kan finde en forklaring på, hvordan du tilføjer og redigerer attributten 'partitioner', her
  3. Du kan slette de gamle data, hvis de ikke længere er i brug. Det anbefales, at du sletter gamle data efter den anslåede varighed af modelleringcyklussen (mindst 36 timer) med en vis buffer for at undgå, at data slettes, mens de modelleres.
  4. Gentag trin 1-3, hver gang du vil opdatere inputdataene.

Dataobjekter

Et dataobjekt er et sæt af en eller flere datatekstfiler, der hver især har en liste over kolonner (også kaldet attributter) og rækker, der indeholder de faktiske dataværdier.

Intelligent Recommendations definerer logiske grupper af dataobjekter, som har deres egne formål. Dataobjekter er valgfrie (medmindre andet udtrykkeligt er angivet), hvilket betyder, at deres data kan være tomme (eller helt mangle).

Følgende dataobjektgrupper defineres af Intelligent Recommendations:

Gruppe Dataobjekter
Katalogdataobjekter Varer og varianter
Varekategorier
Vare- og variantbilleder
Vare- og variantfiltre
Tilgængeligheder af varer og varianter
Interaktionsdataobjekter Interaktioner
Dataobjekter for konfigurationer af anbefalinger Konfiguration af anbefaling
Dataobjekter for fravalgte brugere Fravalgte brugere
Dataobjekter for forbedring af anbefalinger Forbedring af anbefalinger med adgang
Forbedring af anbefalinger
Dataobjekter for tilknytning af billede til vare Billedlager
Tilknytning af billede til vare
Dataobjekter for eksterne lister Lister over eksterne anbefalinger
Varer til eksterne anbefalinger

Dataformat

Intelligent Recommendations forventer, at alle dataobjekters partitionsinputfiler overholder følgende format:

  • Indholdet i partitionsinputfilen skal være i CSV-format (kommaseparerede tekstfiler) og kun indeholde UTF-8-kodet tekst.

  • De enkelte CSV-filer skal indeholde alle de felter, der er angivet i datakontrakten for det relevante dataobjekt. Felterne skal desuden vises i henhold til den rækkefølge, der er beskrevet i kontrakten.

  • CSV-filer bør kun indeholde dataposter i henhold til RFC 4180.

Her er nogle almindelige eksempler på funktionsmåder for CSV-dataformater i forskellige tilfælde:

  • De enkelte felter kan være markeret med dobbelte anførselstegn.

    Eksempel: aaa, "bbb", ccc

  • Felter, der indeholder linjeskift (CRLF), dobbelte anførselstegn og kommaer, skal angives i dobbelte anførselstegn.

    Eksempel: aaa, "bbCRLFb", "c, cc"

  • Et dobbelt anførselstegn, der vises i et felt, skal slettes ved at sætte et andet dobbelt anførselstegn foran det.

    Eksempel: aaa, "b""bb", ccc

Hvis du ikke eksplicit har angivet partitionsattributten (i JSON-modelfilen) for et dataobjekt, søger Intelligent Recommendations efter partitionsfilerne til dataobjekter i en undermappe (under rodmappen til Intelligent Recommendations), der har samme navn som dataobjektet.

I så fald skal alle partitionsinputfiler i dataobjektundermappen have filtypenavnet CSV, f.eks. MyData.csv, og de skal ikke indeholde en overskriftsdatalinje.

Intelligent Recommendations søger efter og sammenlægger data fra alle filer, der bruger CSV-filtypenavnet, mens selve filnavnet ignoreres.

Eksempel på mappestruktur til Intelligent Recommendations

Her er et eksempel på et skærmbillede af en struktur for rodmappen til Intelligent Recommendations. Der kræves ikke CSV'er for at matche mappenavnene:

Eksempel på struktur af en Intelligent Recommendations-rodmappe.

Påkrævede dataobjekter for hvert anbefalingsscenarie

Anbefalingsscenarier kan være afhængige af forskellige dataobjekter for at kunne fungere korrekt. Du kan se en komplet tabel over tilknytningen af scenarier og dataobjekter i Tabel over tilknytning af dataobjekter.

Krav til og begrænsninger for dataindhold

Alle dataobjekters indhold skal overholde følgende krav og begrænsninger.

Alle datarækker, der ikke overholder disse krav, behandles som angivet i kolonnen Ugyldig værdifunktionsmåde for det relevante dataobjekt og de relevante attributter:

  • Alle vare- og varevariant-id'er skal overholde præcis én af disse begrænsninger (du kan ikke skifte mellem vare-id-formater for begge indstillinger):

    • Længden skal være på 16 tegn eller mindre, og det må kun indeholde følgende tegn: A-Z, 0-9, _, -, ~, .
    • I GUID-format – en streng på præcis 36 tegn, der indeholder hexadecimale tegn og tankestreger; f.eks. 12345678-1234-5678-90ab-1234567890ab. Hvis du vil bruge dette GUID-format, skal du føje en post til Reco_Config-dataobjektet med følgende data: Key=ItemIdAsGuid, Value=True (dvs. ItemIdAsGuid,True). Ellers genererer Intelligent Recommendations ikke anbefalinger.

  • Varevariant-id'er skal være globalt entydige (på tværs af alle varer og varevarianter).

  • Varevariant-id'et skal stå tomt for datarækker, der repræsenterer data om en varemaster eller en enkeltstående vare.

  • Der er ikke forskel på store og små bogstaver i vare-id'er og varevariant-id'er, hvilket betyder følgende:

    • Id'erne ABCD1234, abcd1234 og AbCd1234 betragtes som ens.
    • I anbefalings-API-svar er alle de returnerede id'er angivet med store bogstaver.

  • Strengattributter har en længdebegrænsning. Strengværdier, der overstiger deres grænse, bliver afkortet (overskydende tegn fjernes), eller hele datarækken udelades (den nøjagtige funktionsmåde vises i dataobjekttabellen for hver attribut).

  • Alle DateTime-værdier skal være i UTC i følgende format: åååå-MM-ddTTT:mm:ss.fffZ.

  • Der er ikke forskel på store og små bogstaver i nogen strenge, undtagen varens titel og beskrivelse. Filternavnene Farve og farve opfattes f.eks. som ens, og filterværdien Rød er den samme som filterværdien rød.

  • For alle ikke-obligatoriske attributter, der er tomme, bruges standardværdien (hvis der angives en standardværdi).

  • Booleske værdier skal enten være sande eller falske, og der skeldes ikke mellem store og små bogstaver (dvs. sand opfattes som det samme som Sand).

Ændringer i forhold til tidligere version

Her er listen over ændringer i datakontrakten mellem version 1.3 og version 1.4:

Dataobjekt Oversigt over ændringer
Reco_ItemCategories Dataobjektet understøttes nu og må ikke være tomt.
Reco_ItemAndVariantFilters FilterName understøtter brugerdefineret filternavn.
Filtre understøtter nu filtrering efter flere værdier (mere end én filterværdi).
Reco_ItemAndVariantAvailabilities Kanal og katalog understøtter nu alle strengværdier (ikke kun 0).
Reco_Interactions Kanal og katalog understøtter nu alle strengværdier (ikke kun 0).
Reco_ImagesInventory Nyt dataobjekt.
Reco_ImageToItemMappings Nyt dataobjekt.

Se også

Intelligent Recommendations-API
Startvejledning: Konfigurer og kør Intelligent Recommendations med prøvedata
API-statuskoder
Tabel over tilknytning af dataobjekter
Katalogdataobjekter
Interaktionsdataobjekter
Dataobjekter for konfigurationer af anbefalinger
Dataobjekter for eksterne lister
Dataobjekter for fravalgte brugere
Dataobjekter for forbedring af anbefalinger
Dataobjekter for tilknytning af billede til vare