Speichern und Abrufen von Sitzungsstatus mit Cloud Datastore in Jitterbit Studio

Einführung

Cloud Datastore ist Jitterbitâs integriertes Cloud-Speichersystem. Es ermöglicht Studio-Operationen, Daten zwischen Ausführungen zu speichern und abzurufen, ohne dass eine externe Datenbank erforderlich ist. Dieses Handbuch behandelt das häufige Muster zum Speichern von Sitzungsstatus (z. B. Konversationsverlauf, Benutzerflags oder konversationsübergreifender Kontext) mithilfe eines Cloud Datastore Schlüsselspeichers.

Schlüsselspeicher ist der geeignete Speichertyp für Sitzungsstatus. Daten in einem Schlüsselspeicher werden beibehalten, bis sie explizit gelöscht werden, was bedeutet, dass Datensätze unbegrenzt über Sitzungen hinweg bestehen bleiben. Statuspeicher ist dagegen für die Verfolgung von Operationsstatus konzipiert und wird nach 90 Tagen automatisch gelöscht, was ihn für dauerhafte Sitzungsdatensätze ungeeignet macht.

Entwurfsmuster

Drei Operationen implementieren das Sitzungsstatus-Muster:

Die Query-Operation sucht nach dem Sitzungsdatensatz anhand eines eindeutigen Schlüssels (normalerweise einer Benutzer-ID oder Sitzungs-ID) und prüft, ob bereits ein Datensatz für diesen Schlüssel vorhanden ist. Eine Transformation vor der Aktivität Query Items legt den Abfragefilter fest, und ein Skript danach liest totalItems aus der Abfrageantwort: Wenn der Wert 0 ist, wird die Insert-Operation ausgeführt, um einen neuen Datensatz zu erstellen; wenn der Wert größer als 0 ist, wird die Update-Operation ausgeführt, um den vorhandenen Datensatz mit neuen Sitzungsdaten zu überschreiben.

Teil 1: Erstelle den Schlüsselspeicher

Vor der Konfiguration des Connectors in Studio müssen einen Schlüsselspeicher und ein Zugriffstoken in der Management Console erstellen.

1. Navigiere im Harmony-Portal zu Harmony-Portalmenü > Management Console > Cloud Datastore.

2. Klicke auf der Registerkarte Storages auf Speicher hinzufügen und wähle dann Schlüsselspeicher erstellen.

3. Speichername: Gebe einen Namen für den Speicher ein (z. B. ConversationHistory).

4. Umgebung: Wähle die Umgebung aus, die diesen Speicher verwenden soll. Dieses Feld kann nach dem Speichern nicht mehr geändert werden.

5. Beschreibung: Gib optional eine Beschreibung ein.

6. Klicke unter Fields auf Field hinzufügen für jedes benutzerdefinierte Feld, das zum Speichern von Sitzungsdaten benötigt wird. Für den Konversationsverlauf füge ein Feld namens ConversationHistory mit dem Typ Big Text hinzu. Die integrierten Felder Key, Alternative Key und Value sind immer vorhanden und müssen nicht hinzugefügt werden.

   Hinweis

   Pro Speicher sind maximal 20 benutzerdefinierte Felder zulässig, und jedes Element ist auf 25.000 Byte begrenzt.

7. Klicke auf Save.

8. Navigiere zu Harmony-Portalmenü > Management Console > Access Tokens und erstelle ein neues Zugriffstoken für dieselbe Umgebung. Kopiere den Token-Wert.

   Tipp

   Speichere das Zugriffstoken als Projektvariable mit verborgenem Wert und referenziere es dann in der Verbindungskonfiguration. Dies ermöglicht ein einfaches Rotieren des Tokens ohne direkte Bearbeitung der Verbindung.

Teil 2: Konfiguriere die Cloud Datastore-Verbindung

1. Öffne dein Projekt in Studio und klicke auf die Registerkarte Project endpoints and connectors in der Design-Komponentenpalette.

2. Klicke auf den Cloud Datastore-Connector, um die Verbindungskonfiguration zu öffnen.

3. Connection Name: Gebe einen Namen für die Verbindung ein (z. B. Cloud Datastore).

4. Access token: Gebe das in Teil 1 generierte Zugriffstoken ein oder referenziere es mithilfe einer Projektvariable.

5. Klicke auf Test, um die Verbindung zu überprüfen, und klicke dann auf Save Changes.

Teil 3: Abfrage eines vorhandenen Sitzungsdatensatzes

Die Query-Operation bestimmt, ob bereits ein Sitzungsdatensatz für den aktuellen Benutzer vorhanden ist.

Query Items-Aktivität konfigurieren

1. Erweitern Sie auf der Komponentenpalette des Designs den erstellten Cloud Datastore-Endpunkt. Ziehen Sie den Aktivitätstyp Query Items auf die Design-Canvas.

2. Doppelklicken Sie auf die Aktivität, um ihre Konfiguration zu öffnen.

3. Name: Geben Sie einen Namen für die Aktivität ein (beispielsweise Query Session).

4. Speicher auswählen: Wählen Sie Vorhandenen Speicher auswählen und klicken Sie in der Tabelle auf den in Teil 1 erstellten Speicher.

5. Klicken Sie auf Weiter, um die Datenschemas zu überprüfen, und klicken Sie dann auf Fertig.

Abfragefilter in einer Transformation zuordnen

Platzieren Sie eine Transformation vor der Aktivität Query Items, um zu definieren, welcher Datensatz gesucht werden soll. In der Transformation:

• Ordnen Sie fields.item.key der Literalzeichenkette "Key" zu. Dies ist der integrierte Name des Schlüsselfelds in einem Schlüsselspeicher und berücksichtigt die Groß- und Kleinschreibung.
• Ordnen Sie fields.item.value der Sitzungskennung zu (beispielsweise der Benutzer-ID oder Kanal-ID aus der eingehenden Anfrage-Payload).
• Ordnen Sie limit zu 1 zu. Pro Sitzungsschlüssel wird nur ein Datensatz erwartet.

Wenn beispielsweise die eingehende Anfrage die Benutzer-ID in einer Variable userId bereitstellt:

<trans>
$userId
</trans>

Ordnen Sie diesen Skriptknoten in der Transformation zu fields.item.value zu.

Abfrageergebnis in einem Skript überprüfen

Fügen Sie nach der Aktivität Query Items einen Skript-Schritt zur Operation hinzu. Das Skript liest totalItems aus der Abfrageantwort und leitet die Ausführung entweder zur Insert- oder zur Update-Operation:

<trans>
if(Source.json.pagination.totalItems == 0,
  RunOperation("<TAG>Operations/Insert Session</TAG>"),
  RunOperation("<TAG>Operations/Update Session</TAG>")
);
</trans>

Ersetzen Sie Insert Session und Update Session durch die tatsächlichen Namen, die Sie diesen Operationen in Teil 4 und Teil 5 geben. Die Syntax <TAG> löst die Operation zur Laufzeit nach Name auf.

Teil 4: Datensatz für eine neue Sitzung einfügen

Die Insert-Operation wird ausgeführt, wenn kein Datensatz für den Sitzungsschlüssel vorhanden ist.

Insert Items-Aktivität konfigurieren

1. Ziehen Sie den Aktivitätstyp Insert Items auf eine neue Operation-Canvas.

2. Doppelklicken Sie auf die Aktivität, um ihre Konfiguration zu öffnen.

3. Name: Geben Sie einen Namen für die Aktivität ein (beispielsweise Insert Session).

4. Speicher auswählen: Wählen Sie denselben Speicher aus, der in Teil 3 verwendet wurde.

5. Klicken Sie auf Weiter, um die Datenschemas zu überprüfen, und klicken Sie dann auf Fertig.

Sitzungsdaten zuordnen

In der Transformation, die der Aktivität Insert Items vorausgeht, ordnen Sie die folgenden Anfragfelder zu:

• Key: Ordnen Sie der Sitzungskennung zu (beispielsweise userId). Dies ist der Wert, der in zukünftigen Abfragen zum Nachschlagen des Datensatzes verwendet wird.
• ConversationHistory (oder alle benutzerdefinierten Felder, die Ihr Speicher definiert): Ordnen Sie den anfänglichen Sitzungsdaten zu, die gespeichert werden sollen.

Lassen Sie AlternativeKey und Value nicht zugeordnet, es sei denn, Ihr Anwendungsfall erfordert dies.

Teil 5: Vorhandenen Sitzungsdatensatz aktualisieren

Die Update-Operation wird ausgeführt, wenn bereits ein Datensatz für den Sitzungsschlüssel vorhanden ist.

Update Items-Aktivität konfigurieren

1. Ziehen Sie den Aktivitätstyp Update Items auf eine neue Operation-Canvas.

2. Doppelklicken Sie auf die Aktivität, um ihre Konfiguration zu öffnen.

3. Name: Geben Sie einen Namen für die Aktivität ein (beispielsweise Update Session).

4. Speicher auswählen: Wählen Sie denselben Speicher aus, der in Teil 3 verwendet wurde.

5. Klicken Sie auf Weiter, um die Datenschemas zu überprüfen, und klicken Sie dann auf Fertig.

Aktualisierte Sitzungsdaten zuordnen

In der Transformation, die der Aktivität Update Items vorausgeht, ordnen Sie die folgenden Anfragfelder zu:

• Key: Ordnen Sie der Sitzungskennung zu. Dieses Feld gibt an, welcher Datensatz aktualisiert werden soll; es muss mit dem Wert übereinstimmen, der beim Einfügen des Datensatzes verwendet wurde.
• ConversationHistory (oder alle benutzerdefinierten Felder, die Ihr Speicher definiert): Ordnen Sie den aktualisierten Sitzungsdaten zu. Alle zugeordneten Felder werden überschrieben.

Integration überprüfen

1. Stellen Sie die Query-Operation bereit und führen Sie sie aus, indem Sie einen Sitzungsidentifikator übergeben, der noch nicht im Speicher vorhanden ist.

2. Bestätigen Sie im Operationsprotokoll, dass totalItems den Wert 0 aufweist und dass die Insert-Operation ausgelöst wurde.

3. Öffnen Sie in Management Console > Cloud Datastore die Speicherdetails und bestätigen Sie, dass ein neuer Datensatz mit dem erwarteten Schlüssel und den Feldwerten angezeigt wird.

4. Stellen Sie die Query-Operation erneut bereit und führen Sie sie mit demselben Sitzungsidentifikator aus.

5. Bestätigen Sie im Operationsprotokoll, dass totalItems den Wert 1 aufweist und dass die Update-Operation ausgelöst wurde.

6. Bestätigen Sie in Management Console > Cloud Datastore, dass die benutzerdefinierten Felder des Datensatzes die aktualisierten Werte widerspiegeln.

7. Falls die Aktivität Query mit einem Authentifizierungsfehler fehlschlägt, überprüfen Sie das Zugriffstoken in der Cloud Datastore-Verbindung und bestätigen Sie, dass das Token der gleichen Umgebung wie der Speicher zugeordnet ist.

Cloud Datastore kann auch zur Deduplizierung zwischen Läufen bei hohem Volumen verwendet werden, als Alternative zu Cache-Funktionen. Siehe Datensätze mithilfe von Hash-Funktionen erkennen und deduplizieren.