Overzicht van gegevenscontract

In dit artikel wordt uitgelegd hoe u gegevens kunt delen met Intelligent Recommendations, zodat u dit kunt inschakelen en zinvolle aanbevelingen kunt doen.

De bijbehorende Intelligent Recommendations-API voor de beschreven gegevenscontracten is Intelligent Recommendations-API.

Download het nieuwste model.json-bestand voor gegevenscontracten voor Intelligent Recommendations: model.json.

Vereisten

Voor gegevensintegratie gebruikt Intelligent Recommendations Microsoft Azure Data Lake Storage. In dit artikel wordt de logische structuur van de gegevens beschreven die Intelligent Recommendations verwacht te verbruiken uit uw Azure Data Lake Storage-account.

Om ervoor te zorgen dat Intelligent Recommendations uw gegevens gemakkelijk kan vinden in het Azure Data Lake Storage-account, moet u een speciale map maken binnen het Azure Data Lake Storage-account en het mappad (Intelligent Recommendations-hoofdmap) opgeven aan Intelligent Recommendations.

Ga voor informatie over onboarding en het maken van uw Data Lake Storage-account naar Intelligent Recommendations implementeren of bezoek onze Snelstartgids.

Gegevenscontracten

Gegevenscontracten zijn een reeks definities en beperkingen voor de structuur van de gegevens die Intelligent Recommendations gebruikt. Als u wilt dat Intelligent Recommendations de gegevens die ermee worden gedeeld, kan opnemen en aanbevelingen kan doen, moet u zich houden aan de gegevenscontracten zoals beschreven in dit artikel.

Model JSON-bestand

Intelligent Recommendations-gegevenscontracten zijn logisch verdeeld in een set gegevensentiteiten. Elke gegevensentiteit omvat nul of meer invoer-CSV-bestanden, ook wel partities genoemd. Een apart JSON-tekstbestand met de naam model.json beschrijft de verzameling gegevensentiteiten. Het model-JSON-bestand is vooraf geconfigureerd en kan onmiddellijk worden toegevoegd aan de hoofdmap van Intelligent Recommendations.

Het standaardmodel downloaden

Download het nieuwste standaardmodel-JSON-bestand voor Intelligent Recommendations-gegevenscontracten: model.json.

[!NOTE]

Het model.json-bestand moet worden opgenomen in de hoofdmap van de Intelligent Recommendations naast de bestanden van de gegevensentiteit. U kunt leren over het maken van aanpassingen aan de model.json onder de sectie Het standaardbestand wijzigen van dit gegevenscontract.

Het standaardbestand wijzigen

Het wordt niet aanbevolen om het verstrekte model-JSON-bestand aan te passen, totdat u bekend bent met de Intelligent Recommendations-service en alleen wanneer u een van de volgende functies gebruikt:

  • Numerieke invoerindeling. Het kenmerk cultuur specificeert wat Intelligent Recommendations zal gebruiken als de invoerindeling voor numerieke waarden. Het decimaalteken kan een punt (.) of komma (,) zijn in verschillende culturen. Als u een ander decimaalteken dan een punt (.) wilt gebruiken, specificeer dan de juiste cultuur in het kenmerk cultuur.

    Notitie

    Als u een komma (,) gebruikt als decimaalteken, moet u op elke decimale waarde correcte escaping uitvoeren in het invoer-CSV-bestand. Voor meer informatie over het escapen van tekens in CSV-invoerbestanden, gaat u naar de sectie Gegevensindeling.

  • Expliciete partitielocaties. Om expliciete locaties van de partitiebestanden van de gegevensentiteit op te geven, kunt u het kenmerk partities gebruiken. Standaard is de waarde van het kenmerk partities null, wat betekent dat Intelligent Recommendations automatisch zoekt naar de relevante partitiebestanden voor gegevensentiteiten. Ga voor meer informatie naar Gegevensindeling. Het kenmerk partities is een matrix van partities. Elke partitie bevat de volgende kenmerken:

    • naam: een tekenreeksweergave van de partitie, die niet door Intelligent Recommendations wordt gebruikt voor een specifieke logica.
    • locatie: volledige URI naar het gegevensbestand (CSV) van de partitie. De URI moet toegankelijk zijn voor Intelligent Recommendations (alleen-lezen), waarvoor u mogelijk de juiste machtigingen moet opgeven voor Intelligent Recommendations. Ga voor meer informatie over hoe u Intelligent Recommendations toegang kunt geven tot gegevens naar Azure Data Lake Storage instellen.
    • fileFormatSettings: bevat het volgende kenmerk:
      • columnsHeaders : een booleaanse waarde die aangeeft of de partitiegegevens een kopregel bevatten. Kopregels worden automatisch weggegooid door Intelligent Recommendations tijdens het opnemen van invoergegevens. Standaardwaarde is false, wat betekent dat er geen kopregels zijn.

Hier is een voorbeeld van het kenmerk partities:

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

Gegevensentiteiten

Een gegevensentiteit is een set van een of meer gegevenstekstbestanden, elk met een lijst met kolommen (ook wel kenmerken genoemd) en rijen die de werkelijke gegevenswaarden bevatten.

Intelligent Recommendations definieert logische groepen gegevensentiteiten, elk met een eigen doel. Houd er rekening mee dat gegevensentiteiten als optioneel worden beschouwd (tenzij expliciet anders vermeld), wat betekent dat hun gegevens leeg kunnen zijn (of helemaal ontbreken).

Intelligent Recommendations gebruikt de volgende groepen gegevensentiteiten:

Groeperen Gegevensentiteiten
Entiteiten met catalogusgegevens Artikelen en varianten
Artikelcategorieën
Artikel- en variantafbeeldingen
Artikel- en variantfilters
Artikel- en variantbeschikbaarheid
Gegevensentiteiten voor interacties Interacties
Gegevensentiteiten voor reco-configuratie Reco-configuratie
Gegevensentiteiten voor afgemelde gebruikers Afgemelde gebruikers
Gegevensentiteiten voor verrijking van aanbevelingen Verrijking van seeded aanbevelingen
Verrijking van aanbevelingen
Gegevensentiteiten voor toewijzing van afbeelding aan artikel Afbeeldingenvoorraad
Toewijzingen van afbeelding aan artikel

Gegevensopmaak

Intelligent Recommendations verwacht dat alle invoerbestanden voor partities van gegevensentiteiten voldoen aan de volgende indeling:

  • De inhoud in het partitie-invoerbestand moet in CSV-indeling (door komma's gescheiden) zijn, met alleen met UTF-8-gecodeerde tekst.

  • CSV-bestanden mogen alleen gegevens bevatten, conform RFC 4180.

Hier zijn enkele veelvoorkomende voorbeelden van het gedrag van CSV-gegevensindelingen in verschillende gevallen:

  • Elk veld kan al dan niet tussen dubbele aanhalingstekens staan.

    Bijvoorbeeld: aaa, "bbb", ccc

  • Velden met regeleinden (CRLF), dubbele aanhalingstekens en komma's moeten tussen dubbele aanhalingstekens worden geplaatst.

    Bijvoorbeeld: aaa, "bbCRLFb", "c,cc"

  • Een dubbel aanhalingsteken dat in een veld verschijnt, moet van een escape-teken worden voorzien door er een ander dubbel aanhalingsteken voor te zetten.

    Bijvoorbeeld: aaa, "b""bb", ccc

Indien u niet expliciet het kenmerk partities vermeldt (in het model-JSON-bestand) voor een gegevensentiteit, zoekt Intelligent Recommendations naar de partitiebestanden van de gegevensentiteit in een submap (onder de hoofdmap van Intelligent Recommendations) met dezelfde naam als de gegevensentiteit.

In dit geval moeten alle partitie-invoerbestanden in de submap van de gegevensentiteit een CSV-bestandsextensie hebben, zoals: MyData.csv en mogen deze geen gegevensregel voor headers bevatten.

Intelligent Recommendations zoekt en verzamelt gegevens uit alle bestanden die de CSV-extensie gebruiken, terwijl de bestandsnaam zelf wordt genegeerd.

Voorbeeld van Intelligent Recommendations-mapstructuur

Hier is een schermopnamevoorbeeld van een Intelligent Recommendations-hoofdmapstructuur. Csv's hoeven niet overeen te komen met de mapnamen:

Example structure of an Intelligent Recommendations root folder.

Vereiste gegevensentiteiten voor elk aanbevelingsscenario

Aanbevelingensscenario's kunnen afhankelijk zijn van verschillende gegevensentiteiten om goed te kunnen functioneren. Als u een volledige tabel met scenario's en gegevensentiteiten wilt zien, bekijk dan onze Toewijzingstabel voor gegevensentiteiten.

Vereisten en beperkingen voor gegevensinhoud

Alle inhoud van gegevensentiteiten moet voldoen aan de volgende vereisten en beperkingen.

Elke gegevensrij die niet aan deze vereisten voldoet, wordt behandeld zoals gespecificeerd in de kolom Ongeldig gedrag van waarde voor de betreffende gegevensentiteit en kenmerken:

  • Alle artikel- en artikelvariant-id's moeten aan precies een van deze beperkingen voldoen (u kunt de indelingen voor artikel-id's van beide opties niet combineren):

    • De lengte moet 16 tekens of minder zijn en mag alleen de volgende tekens bevatten: A-Z, 0-9, _, -, ~, ..
    • In GUID-indeling: een tekenreeks van precies 36 tekens met hexadecimale tekens en streepjes; bijvoorbeeld 12345678-1234-5678-90ab-1234567890ab. Als u deze GUID-indeling wilt gebruiken, moet u ook de volgende handeling uitvoeren. Anders zal Intelligent Recommendations geen aanbevelingen genereren.
      • Voeg een invoer toe aan de gegevensentiteit Reco_Config met de volgende gegevens: Key=ItemIdAsGuid, Value=True (dat wil zeggen, ItemIdAsGuid,True).
  • Artikelvariant-id's moeten algemeen uniek zijn (voor alle artikelen en artikelvarianten).

  • Artikelvariant-id moet leeg worden gelaten voor gegevensrijen die gegevens vertegenwoordigen over een artikelmodel of een zelfstandig artikel.

  • Artikel-id's en artikelvariant-id's zijn niet-hoofdlettergevoelig, wat betekent dat:

    • Id's ABCD1234, abcd1234 en AbCd1234 allemaal als hetzelfde worden beschouwd.
    • In API-respons voor aanbevelingen zijn de geretourneerde id's allemaal in hoofdletters.
  • Tekenreekskenmerken hebben een lengtelimiet. Tekenreekswaarden die langer zijn dan hun limiet, worden ingekort tot hun lengtelimiet (overtollige tekens worden verwijderd) of de hele gegevensrij wordt verwijderd (exact gedrag wordt vermeld in de gegevensentiteitstabel voor elk kenmerk).

  • Alle waarden voor DateTime moeten in UTC zijn, in de volgende indeling: jjjj-MM-ddTHH:mm:ss.fffZ.

  • Alle tekenreeksen, met uitzondering van titel van artikel en beschrijving van artikel, zijn niet-hoofdlettergevoelig. Zo worden filternamen Kleur en kleur als hetzelfde beschouwd en is filterwaarde Rood hetzelfde als filterwaarde rood.

  • Voor elk niet-verplicht kenmerk dat leeg is, wordt de standaardwaarde gebruikt (als er een standaardwaarde is opgegeven).

  • Booleaanse waarden moeten ofwel true of false zijn en zijn niet-hoofdlettergevoelig (wat betekent dat true als hetzelfde als True wordt gezien).

Wijzigingen ten opzichte van de vorige versie

Hier is de lijst met wijzigingen in het gegevenscontract tussen versie 1.3 en versie 1.4:

Gegevensentiteit Overzicht van wijzigingen
Reco_ItemCategories Gegevensentiteit wordt nu ondersteund en mag niet leeg zijn.
Reco_ItemAndVariantFilters FilterName ondersteunt aangepaste filternaam.
Filters ondersteunen nu filteren met meerdere waarden (meer dan één filterwaarde).
Reco_ItemAndVariantAvailabilities Kanaal en Catalogus ondersteunen nu elke tekenreekswaarde (niet alleen 0).
Reco_Interactions Kanaal en Catalogus ondersteunen nu elke tekenreekswaarde (niet alleen 0).
Reco_ImagesInventory Nieuwe gegevensentiteit.
Reco_ImageToItemMappings Nieuwe gegevensentiteit.

Zie ook

Intelligent Recommendations-API
Snelstartgids: Intelligent Recommendations instellen en uitvoeren met voorbeeldgegevens
Toewijzingstabel voor gegevensentiteiten
Gegevensentiteiten voor catalogus
Gegevensentiteiten voor interacties
Gegevensentiteiten voor Reco-configuratie
Gegevensentiteiten voor afgemelde gebruikers
Gegevensentiteiten voor verrijking van aanbevelingen
Gegevensentiteiten voor toewijzing van afbeelding aan artikel