Overzicht van gegevenscontract

  • Artikel

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 maakt Intelligent Recommendations gebruik van 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 verbruikt. 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 bij 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
            }
        }
    ]

Best practices voor het bijwerken van uw invoergegevens

Voorkom een situatie waarin gegevens tegelijkertijd worden gemodelleerd en bijgewerkt, omdat dit kan leiden tot het modelleren van gegevens uit gemengde gegevenssetversies en ongewenste aanbevelingsresultaten. Hieronder ziet u een paar best practices voor het bijwerken van uw invoergegevens:

  1. Schrijf alle gegevensentiteiten weg naar een andere map. Deze map hoeft zich niet in dezelfde container of hetzelfde opslagaccount te bevinden als waarin uw huidige invoergegevens zich bevinden. Zorg ervoor dat u Intelligent Recommendations-machtigingen opgeeft om gegevens uit de container met uw bijgewerkte invoergegevens te lezen. Zie Azure Data Lake Storage instellen voor meer informatie.
  2. Voeg voor elk van de gegevensentiteiten die u gebruikt het kenmerk 'partitions' toe aan uw Model Json-bestand. Werk voor elke partitie het kenmerk 'location' bij zodat het verwijst naar de nieuwe gegevenslocatie. Een uitleg over het toevoegen en bewerken van het kenmerk 'partitions' vindt u hier
  3. U kunt de oude gegevens verwijderen als deze niet meer in gebruik zijn. We raden aan om oude gegevens te verwijderen na de geschatte duur van de modelleringscyclus (ten minste 36 uur), met enige buffer om te voorkomen dat gegevens worden verwijderd terwijl ze worden gemodelleerd.
  4. Herhaal stap 1-3 elke keer dat u uw invoergegevens wilt bijwerken.

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. Gegevensentiteiten worden als optioneel beschouwd (tenzij expliciet anders vermeld), wat betekent dat hun gegevens leeg kunnen zijn (of helemaal ontbreken).

Intelligent Recommendations definieert 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
Externe gegevensentiteiten voor lijsten Lijsten met externe aanbevelingen
Externe aanbevelingsitems

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.

  • Elk CSV-bestand moet alle velden bevatten die zijn gespecificeerd in het gegevenscontract van de relevante gegevensentiteit. Bovendien moeten de velden worden weergegeven in de volgorde die in dat contract wordt beschreven.

  • 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:

Voorbeeld van een Intelligent Recommendations-hoofdmapstructuur.

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, voegt u een vermelding toe aan de gegevensentiteit Reco_Config met de volgende gegevens: Key=ItemIdAsGuid, Value=True (dat wil zeggen, ItemIdAsGuid,True). Anders zal Intelligent Recommendations geen aanbevelingen genereren.

  • 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 (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
Aan de slag: Intelligent Recommendations instellen en uitvoeren met voorbeeldgegevens
API-statuscodes
Toewijzingstabel voor gegevensentiteiten
Entiteiten met catalogusgegevens
Gegevensentiteiten voor interacties
Gegevensentiteiten voor reco-configuratie
Externe gegevensentiteiten voor lijsten
Gegevensentiteiten voor afgemelde gebruikers
Gegevensentiteiten voor verrijking van aanbevelingen
Gegevensentiteiten voor toewijzing van afbeelding aan artikel