Dela via

Översikt över datakontrakt

  • Artikel

I den här artikeln finns information om hur du delar data med Intelligent Recommendations så att du kan aktivera den och ge meningsfulla rekommendationer.

API för Intelligent Recommendations för de beskrivna datakontrakten är Intelligent Recommendations API .

Hämta den senaste filen model.json för datakontrakt för Intelligent Recommendations: model.json.

Förutsättningar

För dataintegrering använder Intelligent Recommendations Microsoft Azure Data Lake Storage. I den här artikeln beskrivs den logiska strukturen för de data som förväntar sig att Intelligent Recommendations ska förbrukas av ditt Azure Data Lake Storage-konto.

Om du vill tillåta Intelligent Recommendations att enkelt hitta dina data i Azure Data Lake Storage-kontot måste du skapa en dedikerad mapp i Azure Data Lake Storage-kontot och ange mappsökvägen (rotmappen Intelligent Recommendations) till Intelligent Recommendations.

För information om registrera och skapa ditt Data Lake Storage-konto, gå till Distribuera Intelligent Recommendations eller besök Snabbstartsguide.

Datakontrakt

Datakontrakt är en uppsättning definitioner och begränsningar för strukturen för de data som används i Intelligent Recommendations. För att Intelligent Recommendations ska mata in den data som delas med den och ge rekommendationer måste du följa datakontrakten enligt beskrivningen i den här artikeln.

Modell JSON-fil

Datakontrakt för Intelligent Recommendations är logiskt indelade i en uppsättning dataentiteter. Varje dataenhet omfattar noll eller fler indata CSV-filer, som också kallas partitioner. En separat JSON-textfil med namnet model.json beskriver dataentiteterna. Modellens JSON-fil är förkonfigurerad och kan läggas till direkt i rotmappen för Intelligent Recommendations.

Hämta standardmodelen

Hämta den senaste model JSON-standardfilen för datakontrakt för Intelligent Recommendations: model.json.

[!OBS]

Filen model.json krävs för att kunna finnas i rotmappen för Intelligent Recommendations tillsammans med filerna för dataentitet. Du lär dig mer om att göra ändringar i model.json under Ändra avsnittet om standardfil i detta datakontrakt.

Ändra standardfilen

Du bör inte ändra den medföljande JSON-filen förrän du har bekantat dig med tjänsten Intelligent Recommendations och endast när du använder någon av följande funktioner:

  • Numeriskt indataformat. Attributet kultur anger vilka Intelligent Recommendations som ska användas som indataformat för numeriska värden. Decimalavgränsaren kan vara en punkt (.) eller komma (,) i olika kulturer. Om du vill använda en annan decimalavgränsare än en punkt (.), anger du lämplig avgränsning i attributet kultur.

    Kommentar

    Om du använder komma (,) som decimalavgränsare måste du ange decimalvärdet i CSV-filen. Mer information om hur tecken kan visas i CSV-indatafiler finns i avsnittet Dataformat.

  • Explicita platser för partitioner. Om du vill ange explicita platser för partitionsfilerna för dataentitet kan du använda attributet partitioner. Som standard är attributvärdet för partitioner lika med "null", vilket innebär att Intelligent Recommendations automatiskt söker efter relevanta partitionsfiler för dataentitet. Mer information finns i Dataformat. Attributet partitioner är en matris med partitioner. Varje partition innehåller följande attribut:

    • namn: En strängrepresentation av partitionen, som inte används i Intelligent Recommendations för all specifik logik.
    • plats: Fullständig URI till partitionsdatafilen (CSV). URI måste vara tillgängligt för Intelligent Recommendations (skrivskyddade), vilket kan kräva att du har rätt behörighet för Intelligent Recommendations. Mer information om hur du ger Intelligent Recommendations åtkomst till data finns i Konfigurera Azure Data Lake Storage.
    • fileFormatSettings: Innehåller följande attribut:
      • columnsHeaders: Ett booleskt värde som anger om partitionsdata innehåller en rubrikrad. Intelligent Recommendations ignorerar automatiskt rubrikrader när indata matas in. Standardvärdet är falskt, alltså inga rubriker.

Här är ett exempel på attributet partitioner:

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

Bästa praxis för att uppdatera dina indata

Undvik situationer där data modelleras och uppdateras samtidigt, eftersom detta kan leda till att datan då modelleras från blandade datauppsättningsversioner och oönskade rekommendationsresultat. Här följer metodtips för hur du uppdaterar dina indata:

  1. Skriv alla dataentiteter till en annan mapp. Den här mappen behöver inte finnas i samma behållare eller lagringskonto som dina aktuella indata finns i. Se till att ge Intelligent Recommendations behörighet att läsa data från den behållare där dina uppdaterade indata finns. Mer information finns under Konfigurera Azure Data Lake Storage.
  2. För alla dataentiteter du använder lägger du till attributet "partitioner" i Model Json-filen. Uppdatera attributet "plats" för varje partition så att det pekar mot den nya dataplatsen. En förklaring till hur du lägger till och redigerar attributet "partitioner" finns här
  3. Du kan ta bort gamla data om de inte används. Vi rekommenderar att du tar bort gamla data efter den beräknade varaktigheten för modelleringscykeln (minst 36 timmar), med viss marginal för att undvika att data tas bort medan den modelleras.
  4. Upprepa steg 1 till 3 varje gång du vill uppdatera dina indata.

Dataentiteter

En dataentitet är en uppsättning med en eller flera datatextfiler som var och en har en lista med kolumner (kallas även attribut) och rader som innehåller faktiska datavärden.

Intelligent Recommendations definierar logiska grupper av dataentiteter, alla med sina egna syften. Dataentiteter anses vara valfria (om inget annat uttryckligen anges), vilket innebär att deras data kan vara tomma (eller helt saknas).

Intelligent Recommendations definierar följande grupper dataentiteter:

Grupp Dataentiteter
Entiteter för katalogdata Artikel och varianter
Artikelkategorier
Artikel och variantbilder
Artikel och variantfilter
Artikel och varianttillgängligheter
Dataentiteter för interaktioner Interaktioner
Dataentiteter för reco-konfiguration Reco-konfiguration
Entiteter för avanmälda användardata Avanmälda användare
Rekommendationer för berikning dataentiteter Förpopulerade rekommendationer för berikning
Rekommendationer för berikning
Bild till artikelmappning för dataentiteter Bildlager
Bild till artikelmappningar
Externa listor över dataentiteter Extern rekommendationslista
Extern rekommendationslista

Dataformat

Intelligent Recommendations förväntar sig att alla indatafiler för dataentiteter ska överensstämma med följande format:

  • Innehållet i indatafilen för partitionen ska vara i CSV-format (kommaavgränsade textfiler) och endast UTF-8 kodad text.

  • Varje CSV-fil bör innehålla alla fält som anges i datakontraktet för den relevanta dataentiteten. Dessutom ska fälten visas enligt den order som beskrivs i det kontraktet.

  • CSV-filer bör endast innehålla dataposter, enligt RFC 4180.

Här följer några vanliga exempel på hur CSV-dataformat fungerar i olika fall:

  • Varje fält kan eller kanske inte omges av dubbla citattecken.

    Till exempel: aaa, “bbb”, ccc

  • Fält som innehåller radbrytningar (CRLF), dubbla citattecken och kommatecken måste omges av dubbla citattecken.

    Till exempel: aaa, “bbCRLFb”, “c, cc”

  • Ett dubbelt citattecken som visas i ett fält måste föregås av ett annat dubbla citattecken.

    Till exempel: aaa, “b””bb”, ccc

I det fall du inte uttryckligen anger attributet partitioner (i model JSON-filen) för en dataentitet kommer Intelligent Recommendations att söka efter partitionsfilerna för dataentiteten i en undermapp (under rotmappen Intelligent Recommendations) som har samma namn som dataentiteten.

I det här fallet bör alla indatafiler för partitioner i dataentitetens undermapp ha en CSV-filtillägg, till exempel MyData.csv, och ska inte innehålla någon datarad för rubriker.

Intelligent Recommendations söker efter och ställer samman data från alla filer som använder CSV-tillägget, men ignorerar själva filnamnet.

Exempel på mappstruktur för Intelligent Recommendations

Här är ett skärmbildsexempel på en rotmappsstruktur med Intelligent Recommendations. CSV:er krävs inte för att matcha mappnamnen:

Exempelstruktur för rotmappen för Intelligent Recommendations.

Obligatoriska dataenheter för varje rekommendationsscenario

Rekommendationsscenarier kan vara beroende av olika dataentiteter för att kunna fungera korrekt. En fullständig tabellmappningsscenarier och dataentiteter finns i mappningstabellen för dataentiteter.

Datainnehållskrav och begränsningar

Alla dataentiteters innehåll måste uppfylla följande krav och begränsningar.

Alla datarader som inte uppfyller dessa krav behandlas som angivna i kolumnen Ogiltigt värdebeteende för relevant dataentitet och relevanta attribut:

  • Alla artiklar- och artikelvariant-ID:n måste uppfylla exakt ett av dessa begränsningar (du kan inte mixa mellan artikel-ID:er i båda alternativen):

    • Längden måste bestå av 16 tecken eller mindre och endast innehålla följande tecken: A-Z, 0-9, _, -, ~,.
    • I GUID-formaten – sträng med exakt 36 tecken som innehåller hexadecimala tecken och streck, till exempel 12345678-1234-5678-90ab-1234567890ab. Om du vill använda detta GUID-format lägger du till en post i dataentiteten Reco_Config med följande data: Key=ItemIdAsGuid, Value=True (det vill säga ItemIdAsGuid,True). I annat fall kommer Intelligent Recommendations inte att kunna generera rekommendationer.

  • Artikelvariant-ID:n ska vara globalt unika (för alla artiklar och artikelvarianter).

  • Artikelvariant-ID ska lämnas tomt för datarader som representerar data om huvudartikel eller ett fristående artikel.

  • Artikel-ID och artikelvariant-ID är skiftlägesokänslig, vilket innebär att:

    • ID:er ABCD1234, abcd1234 och AbCd1234 anses vara samma.
    • I rekommendations-API-svar är de returnerade ID:n alla med versaler.

  • Strängattribut har en längdbegränsning. Strängvärden som överskrider sin gräns trimmas (överflödiga tecken tas bort), eller också kommer hela dataraden att tas bort (exakt beteende anges i dataenhetstabellen för respektive attribut).

  • Alla DateTime-värden ska vara i UTC i följande format: yyyy-MM-ddTHH:mm:ss.fffZ.

  • Alla strängar, förutom rubrik och rubrik beskrivning är skiftlägesokänslig. Till exempel filternamn Färg och färg betraktas som samma och filtervärdet Röd är samma som filtervärdet röd.

  • För alla icke-obligatoriska attribut som är tomma används standardvärdet (om ett standardvärde anges).

  • Booleska värden ska vara antingen sant eller falskt och vara skiftlägesokänslig (det vill säga att sant betraktas som Sant).

Ändringar från tidigare version

Här är listan med datakontraktsändringar mellan version 1.3 och version 1.4:

Dataentitet Ändringssammanfattning
Reco_ItemCategories Dataentiteter stöds nu och kan vara ifyllda.
Reco_ItemAndVariantFilters FilterName har stöd för anpassade filternamn.
Filtrer har nu stöd för filtrering flera värden (fler än ett filtervärde).
Reco_ItemAndVariantAvailabilities Kanal och katalog har nu stöd för alla strängvärden (inte bara 0).
Reco_Interactions Kanal och katalog har nu stöd för alla strängvärden (inte bara 0).
Reco_ImagesInventory Ny dataentitet.
Reco_ImageToItemMappings Ny dataentitet.

Se även

Intelligent Recommendations API
Snabbstartsguide: Konfigurera och köra Intelligent Recommendations med exempeldata
API-statuskoder
Mappningstabell för dataenheter
Entiteter för katalogdata
Dataentiteter för interaktioner
Dataentiteter för reco-konfiguration
Externa listor över dataentiteter
Entiteter för avanmälda användardata
Rekommendationer för berikning dataentiteter
Bild till artikelmappning för dataentiteter