Übersicht über den Datenvertrag

  • Artikel

Dieser Artikel erklärt, wie Sie Daten mit Intelligenten Empfehlungen austauschen, damit Sie sie aktivieren und sinnvolle Empfehlungen aussprechen können.

Die entsprechende API für Intelligent Recommendations für die beschriebenen Datenverträge lautet Intelligent Recommendations API.

Laden Sie die neueste model.json-Datei für Datenverträge mit Intelligent Recommendations herunter: model.json.

Anforderungen

Für die Datenintegration verwendet Intelligent Recommendations Microsoft Azure Data Lake Storage. Dieser Artikel beschreibt die logische Struktur der Daten, die Intelligent Recommendations von Ihrem Azure Data Lake Storage-Konto erwarten.

Um Intelligent Recommendations zu erlauben, Ihre Daten innerhalb des Azure Data Lake Storage-Kontos zu finden, müssen Sie einen eigenen Ordner innerhalb des Azure Data Lake Storage-Kontos erstellen und Intelligent Recommendations den Ordnerpfad (Stammordner von Intelligent Recommendations) zur Verfügung stellen.

Informationen zum Onboarding und zum Erstellen Ihres Data Lake Storage-Kontos finden Sie unter Intelligent Recommendations bereitstellen oder in unserer Schnellstart-Anleitung.

Datenverträge

Datenverträge sind eine Reihe von Definitionen und Beschränkungen für die Struktur der Daten, die Intelligent Recommendations verbraucht. Damit Intelligent Recommendations die mit ihnen geteilten Daten einbinden und Empfehlungen aussprechen können, müssen Sie sich an die in diesem Artikel beschriebenen Datenverträge halten.

JSON-Datei des Modells

Die Datenverträge von Intelligent Recommendations sind logisch in ein Set von Entitäten festgelegt. Jede Entität besteht aus null oder mehr CSV-Eingabedateien, die auch Partitionen genannt werden. Eine separate JSON-Textdatei namens model.json beschreibt die Entitäten der Daten. Die Modell-JSON-Datei ist vorkonfiguriert und kann sofort in den Stammordner der intelligenten Empfehlungen eingefügt werden.

Laden Sie das Standardmodell herunter

Laden Sie die neueste Standardmodell-JSON-Datei für Datenverträge für Intelligent Recommendations herunter: model.json.

[!NOTE]

Die Datei model.json muss zusätzlich zu den Dateien der Datenentitäten in den Stammordner der Intelligent Recommendations aufgenommen werden. Wie Sie Anpassungen an der model.json vornehmen können, erfahren Sie im Abschnitt Die Standarddatei ändern dieses Datenvertrags.

Ändern Sie die Standarddatei

Es wird nicht empfohlen, die bereitgestellte Modell-JSON-Datei zu ändern, bis Sie sich mit dem Dienst „Intelligent Recommendations“ vertraut gemacht haben und nur, wenn Sie eine der folgenden Funktionen verwenden:

  • Numerisches Eingabeformat. Das Attribut Kultur gibt an, was intelligente Empfehlungen als Eingabeformat für numerische Werte verwenden. Das Dezimaltrennzeichen kann in verschiedenen Kulturen ein Punkt (.) oder ein Komma (,) sein. Um ein anderes Dezimaltrennzeichen als einen Punkt (.) zu verwenden, geben Sie die entsprechende Kultur im Attribut Kultur an.

    Notiz

    Wenn Sie ein Komma (,) als Dezimaltrennzeichen verwenden, müssen Sie jeden Dezimalwert in der CSV-Eingabedatei ordnungsgemäß trennen. Weitere Informationen darüber, wie Sie Zeichen in CSV-Eingabedateien umgehen, finden Sie im Abschnitt Datenformat.

  • Orte explizit aufteilen. Um explizite Speicherorte für die Partitionsdateien der Datenentitäten anzugeben, können Sie das Attribut Partitionen verwenden. Standardmäßig ist der Wert des Attributs partitions gleich Null, was bedeutet, dass die Intelligenten Empfehlungen automatisch nach den entsprechenden Partitionsdateien für Datenentitäten suchen. Weitere Informationen finden Sie unter Datenformat. Das Attribut Partien ist ein Array von Partien. Jede Partition enthält die folgenden Attribute:

    • Name: Eine String-Darstellung der Partition, die von Intelligent Recommendations nicht für eine bestimmte Logik verwendet wird.
    • Speicherort: Vollständige URI zur Datei der Partitionsdaten (CSV). Die URI muss für Intelligent Recommendations (schreibgeschützt) zugreifbar sein, sodass Sie möglicherweise die entsprechenden Berechtigungen für Intelligent Recommendations erteilen müssen. Weitere Informationen darüber, wie Sie Intelligent Recommendations Zugriff auf Daten gewähren, finden Sie unter Azure Data Lake Storage einrichten.
    • fileFormatSettings: Enthält das folgende Attribut:
      • columnsHeaders: Ein boolescher Wert, der angibt, ob die Partitionsdaten eine Zeile mit Kopfzeilen enthalten. Intelligente Empfehlungen verwerfen automatisch Kopfzeilen, wenn Eingabedaten eingebunden werden. Der Standardwert ist falsch, d.h. keine Kopfzeilen.

Hier sehen Sie ein Beispiel für das Attribut Partitionen:

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

Bewährte Verfahren für das Aktualisieren Ihrer Eingabedaten

Vermeiden Sie eine Situation, in der Daten gleichzeitig modelliert und aktualisiert werden, da dies zu einer Modellierung von Daten aus gemischten Dataset-Versionen und unerwünschten Empfehlungsergebnissen führen kann. Einige bewährte Verfahren für die Aktualisierung Ihrer Eingabedaten lauten wie folgt:

  1. Schreiben Sie alle Entitäten der Daten in einen anderen Ordner. Dieser Ordner muss sich nicht in demselben Container oder Speicherkonto befinden, in dem sich Ihre aktuellen Eingabedaten befinden. Vergewissern Sie sich, dass Sie die Berechtigung „Intelligente Empfehlungen“ zum Lesen von Daten aus dem Container Ihrer aktualisierten Eingabedaten erteilen. Weitere Informationen finden Sie unter Einrichten von Azure Data Lake Storage.
  2. Fügen Sie für jede der von Ihnen verwendeten Entitäten das Attribut 'partitions' zu Ihrer Model.json-Datei hinzu. Aktualisieren Sie für jede Partition das Attribut „location“, so dass es auf den neuen Datenspeicherort verweist. Eine Erklärung, wie Sie das Attribut 'partitions' hinzufügen und bearbeiten können, finden Sie hier
  3. Sie können die alten Daten löschen, wenn sie nicht mehr verwendet werden. Wir empfehlen, alte Daten nach der geschätzten Dauer des Modellierungszyklus (mindestens 36 Stunden) zu löschen, mit einem gewissen Puffer, um zu vermeiden, dass Daten gelöscht werden, während sie modelliert werden.
  4. Wiederholen Sie die Schritte 1-3 jedes Mal, wenn Sie Ihre Eingabedaten aktualisieren möchten.

Datenentitäten

Eine Daten Entität ist eine Menge von einer oder mehreren Daten Textdateien, die jeweils eine Liste von Spalten (auch Attribute genannt) und Zeilen mit den eigentlichen Datenwerten enthalten.

Intelligent Recommendations definieren logische Gruppen von Entitäten, von denen jede ihren eigenen Zweck hat. Datenentitäten gelten als optional (sofern nicht ausdrücklich anders angegeben), was bedeutet, dass ihre Daten leer sein können (oder ganz fehlen).

Intelligente Empfehlungen definieren die folgenden Gruppen von Entitäten:

Gruppieren Datenentitäten
Katalog-Daten Entitäten Elemente und Varianten
Elementkategorien
Element- und Variantenbilder
Element- und Variantenfilter
Verfügbarkeit von Elementen und Varianten
Interactions Daten Entitäten Interaktionen
Entitäten für Reco-Konfigurationsdaten Reco-Konfiguration
Abgemeldete Benutzer Daten Entitäten Abgemeldete Benutzer
Empfehlungsanreicherungs-Daten Entitäten Empfehlungen anreichern
Empfehlungen anreichern
Bild zu Element Zuordnung Datenzuordnung Entitäten Bilder Bestand
Bild zu Element Zuordnungen
Datenentitäten externer Listen Externe Empfehlungslisten
Externe Empfehlungsartikel

Datenformat

Intelligent Recommendations erwarten, dass alle Entitäten, die die Eingabedateien partitionieren, dem folgenden Format entsprechen:

  • Der Inhalt der Partitionseingabedatei sollte im Format einer kommagetrennten Textdatei (CSV) vorliegen, wobei nur UTF-8 kodierter Text verwendet wird.

  • Jede CSV-Datei sollte alle Felder enthalten, die im Datenvertrag der relevanten Datenentität angegeben sind. Außerdem sollten die Felder gemäß der in diesem Vertrag beschriebenen Reihenfolge angezeigt werden.

  • CSV-Dateien sollten nur Dateneinträge enthalten, gemäß RFC 4180.

Hier finden Sie einige allgemeine Beispiele für das Verhalten des CSV-Datenformats in verschiedenen Fällen:

  • Jedes Feld kann in doppelte Anführungszeichen eingeschlossen sein, muss es aber nicht.

    Zum Beispiel: aaa, „bbb“, ccc

  • Felder, die Zeilenumbrüche (CRLF), doppelte Anführungszeichen und Kommas enthalten, müssen in doppelte Anführungszeichen gesetzt werden.

    Zum Beispiel: aaa, „bbCRLFb“, „c, cc“

  • Ein doppeltes Anführungszeichen, das innerhalb eines Feldes erscheint, muss durch ein weiteres doppeltes Anführungszeichen ersetzt werden.

    Zum Beispiel: aaa, "b""bb", ccc

Für den Fall, dass Sie das Attribut Partitionen (in der Modell-JSON-Datei) für eine Entität nicht explizit angegeben haben, suchen die intelligenten Empfehlungen nach den Partitionsdateien der Entitäten in einem Unterordner (unter dem Stammordner der intelligenten Empfehlungen), der den gleichen Namen wie die Entität hat.

In diesem Fall sollten alle Partitions-Eingabedateien innerhalb des Unterordners für die Entitäten eine CSV-Dateierweiterung haben, wie z.B. MeineDaten.csv, und keine Kopfdatenzeile enthalten.

Intelligente Empfehlungen suchen und aggregieren Daten aus allen Dateien, die die CSV-Erweiterung verwenden, wobei der Dateiname selbst ignoriert wird.

Beispiel für die Ordnerstruktur von Intelligent Recommendations

Hier sehen Sie einen Screenshot eines Beispiels für die Struktur eines Stammordners für Intelligent Recommendations. CSV-Dateien müssen nicht mit den Ordnernamen übereinstimmen:

Beispiel für die Struktur eines Stammordners für Intelligent Recommendations.

Erforderliche Entitäten für jedes Empfehlungsszenario

Empfehlungsszenarien können auf verschiedene Entitäten angewiesen sein, um richtig zu funktionieren. Eine vollständige Tabelle mit der Zuordnung von Szenarien und Entitäten finden Sie in unserer Zuordnungstabelle für Datenentitäten.

Anforderungen an den Dateninhalt und Einschränkungen

Alle Inhalte der Entitäten müssen die folgenden Anforderungen und Einschränkungen einhalten.

Alle Datenzeilen, die diese Anforderungen nicht erfüllen, werden so behandelt, wie in der Spalte Ungültiges Wertverhalten für die entsprechende Entität und die Attribute angegeben:

  • Alle Element- und Elementvarianten-IDs müssen genau einer dieser Einschränkungen entsprechen (Sie können nicht zwischen Element-ID-Formaten beider Optionen mischen):

    • Die Länge muss 16 Zeichen oder weniger betragen und darf nur die folgenden Zeichen enthalten: A-Z, 0-9, _, -, ~,.
    • Im GUID-Format - eine Zeichenkette aus genau 36 Zeichen, die hexadezimale Zeichen und Bindestriche enthält; zum Beispiel 12345678-1234-5678-90ab-1234567890ab. Wenn Sie dieses GUID-Format verwenden möchten, fügen Sie der Datenentität Reco_Config einen Eintrag mit den folgenden Daten hinzu: Key=ItemIdAsGuid, Value=True (also ItemIdAsGuid,True). Andernfalls können die intelligenten Empfehlungen keine Empfehlungen generieren.

  • Element-Varianten-IDs sollten global eindeutig sein (für alle Elemente und Elementvarianten).

  • Die Element-Varianten-ID sollte bei Datenzeilen, die Daten über einen Artikelstamm oder einen eigenständigen Artikel enthalten, leer bleiben.

  • Die IDs von Elementen und Elementvarianten unterscheiden nicht zwischen Groß- und Kleinschreibung, was bedeutet, dass:

    • Die IDs ABCD1234, abcd1234 und AbCd1234 werden alle als gleich angesehen.
    • In den Antworten der Empfehlungs-API sind die zurückgegebenen IDs alle in Großbuchstaben.

  • String-Attribute haben ein Längenlimit. Zeichenfolgen, die den Grenzwert überschreiten, werden abgeschnitten (überschüssige Zeichen werden entfernt) oder die gesamte Datenzeile wird gelöscht (das genaue Verhalten ist in der Tabelle der Datenentitäten für jedes Attribut aufgeführt).

  • Alle DateTime-Werte sollten in UTC sein, im folgenden Format: yyyy-MM-ddTHH:mm:ss.fffZ.

  • Bei allen Zeichenketten, mit Ausnahme von Element Titel und Element Beschreibung, wird die Groß- und Kleinschreibung nicht berücksichtigt. Zum Beispiel werden die Filternamen Farbe und Farbe als gleich angesehen und der Filterwert Rot ist der gleiche wie der Filterwert Rot.

  • Für jedes nicht obligatorische Attribut, das leer ist, wird der Standardwert verwendet (wenn ein Standardwert angegeben ist).

  • Boolesche Werte sollten entweder Wahr oder Falsch sein und unterscheiden nicht zwischen Groß- und Kleinschreibung (was bedeutet, dass Wahr als dasselbe wie Wahr angesehen wird).

Änderungen gegenüber der vorherigen Version

Hier ist die Liste der Änderungen am Datenvertrag zwischen Version 1.3 und Version 1.4:

Datenentität Zusammenfassung der Änderungen
Reco_ItemCategories Data Entitäten werden jetzt unterstützt und können nicht leer sein.
Reco_ItemAndVariantFilters FilterName unterstützt angepasste Filternamen.
Filter unterstützen jetzt die Filterung von mehreren Werten (mehr als ein Filterwert).
Reco_ItemAndVariantAvailabilities Kanal und Katalog unterstützen jetzt jeden String-Wert (nicht nur 0).
Reco_Interactions Kanal und Katalog unterstützen jetzt jeden String-Wert (nicht nur 0).
Reco_ImagesInventory Neue Entität für Daten.
Reco_ImageToItemMappings Neue Entität für Daten.

Siehe auch

Intelligent Recommendations API
Schnellstarthandbuch: Intelligent Recommendations mit Beispieldaten festlegen und ausführen
API-Statuscodes
Zuordnungstabelle der Datenentitäten
Katalogdatenentitäten
Interaktionsdatenentitäten
Reco-Konfigurationsdatenentitäten
Datenentitäten externer Listen
Abgewählte Benutzer-Datenentitäten
Empfehlungsanreicherungs-Datenentitäten
Datenentitäten zu Bild-zu-Artikel-Zuordnung