Externe Datenquellen

Mit externen Datenquellen können Sie eine Verbindung zu Drittanbietersystemen herstellen, z. B. wenn Sie ein Hotelbuchungssystem verwenden, um zu überprüfen, ob die Person ein Zimmer gebucht hat. Anders als bei der integrierten Adobe Experience Platform-Datenquelle können Sie beliebig viele externe Datenquellen erstellen.

REST-APIs, die POST oder GET verwenden und JSON zurückgeben, werden unterstützt. API-Schlüssel, einfache und benutzerdefinierte Authentifizierungsmodi werden unterstützt.

Nehmen wir das Beispiel eines Wetter-API-Dienstes, mit dem das Verhalten einer Journey anhand von Echtzeit-Wetterdaten angepasst werden soll.

Im Folgenden finden Sie zwei Beispiele für den API-Aufruf:

• https://api.adobeweather.org/weather?city=London,uk&appid=1234
• https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234

Der Aufruf besteht aus einer Haupt-URL (https://api.adobeweather.org/weather), zwei Parametersätzen („city“ für die Stadt und „lat/long“ für Breiten- und Längengrad) und dem API-Schlüssel (appid).

Im Folgenden werden die wichtigsten Schritte zum Erstellen und Konfigurieren einer neuen externen Datenquelle beschrieben:

1. Klicken Sie in der Liste der Datenquellen auf Datenquelle erstellen, um eine neue externe Datenquelle zu erstellen.

   

   Dadurch wird der Konfigurationsbereich für die Datenquellen auf der rechten Seite des Bildschirms geöffnet.

   

2. Geben Sie einen Namen für Ihre Datenquelle ein.

   HINWEIS

   Verwenden Sie keine Leerzeichen oder Sonderzeichen. Verwenden Sie nicht mehr als 30 Zeichen.

3. Fügen Sie Ihrer Datenquelle eine Beschreibung hinzu. Dieser Schritt ist optional.

4. Fügen Sie die URL des externen Dienstes hinzu. In unserem Beispiel: https://api.adobeweather.org/weather.

   VORSICHT

   Aus Sicherheitsgründen wird die Verwendung von HTTPS dringend empfohlen. Beachten Sie außerdem, dass die Verwendung nicht öffentlich zugänglicher Adobe-Adressen und die Verwendung von IP-Adressen nicht zulässig sind.

   

5. Konfigurieren Sie die Authentifizierung je nach Konfiguration des externen Dienstes: Keine Authentifizierung, Einfach, Benutzerdefiniert oder API-Schlüssel. Weitere Informationen zum benutzerdefinierten Authentifizierungsmodus finden Sie in diesem Abschnitt. In unserem Beispiel wählen wir:

   • Typ: „API-Schlüssel“
   • Wert: „1234“ (dies ist der Wert unseres API-Schlüssels)
   • Name: „appid“ (dies ist der Name des API-Schlüsselparameters)
   • Position: „Abfrageparameter“ (der API-Schlüssel befindet sich in der URL)

   

6. Fügen Sie für jeden API-Parametersatz eine neue Feldergruppe hinzu, indem Sie auf Neue Feldergruppe hinzufügen klicken. Verwenden Sie keine Leerzeichen oder Sonderzeichen im Namen der Feldergruppe. In unserem Beispiel müssen wir zwei Feldergruppen erstellen, eine für jeden Parametersatz („city“ und „lang/lat“).

Für den Parametersatz „long/lat“ erstellen wir eine Feldergruppe mit den folgenden Informationen:

• Verwendet in: zeigt die Anzahl der Journeys an, die eine Feldergruppe verwenden. Sie können auf Customer Journeys anzeigen klicken, um die Liste der Journeys mit dieser Feldergruppe anzuzeigen.
• Methode: Wählen Sie die POST- oder GET-Methode aus. In unserem Fall wählen wir die GET-Methode.
• Antwort-Payload: Klicken Sie in das Feld Payload und fügen Sie ein Beispiel der vom Aufruf zurückgegebenen Payload ein. Für unser Beispiel haben wir eine Payload verwendet, die auf einer Wetter-API-Website gefunden wurde. Überprüfen Sie, ob die Feldtypen korrekt sind. Jedes Mal, wenn die API aufgerufen wird, ruft das System alle im Payload-Beispiel enthaltenen Felder ab. Beachten Sie, dass Sie auf Fügen Sie eine neue Payload ein klicken können, wenn Sie die aktuell übergebene Payload ändern möchten.
• Dynamische Werte: Geben Sie die verschiedenen Parameter getrennt durch ein Komma ein, in unserem Beispiel „long,lat“. Da die Parameterwerte vom Ausführungskontext abhängen, werden sie in den Journeys definiert. Weitere Informationen finden Sie auf dieser Seite.
• Gesendete Payload: Dieses Feld wird nicht in unserem Beispiel angezeigt. Es ist nur verfügbar, wenn Sie die POST-Methode auswählen. Fügen Sie die Payload ein, die an das Drittanbietersystem gesendet wird.

Bei einer GET-Anfrage, die Parameter erfordert, geben Sie die Parameter in das Feld Dynamische Werte ein und sie werden automatisch am Ende der Anfrage hinzugefügt. Bei einer POST-Anfrage müssen Sie:

• die bei der Anfrage zu übergebenden Parameter im Feld Dynamische Werte auflisten (im Beispiel unten: „identifier“).

• diese auch mit exakt derselben Syntax im Hauptteil der gesendeten Payload angeben. Dazu müssen Sie Folgendes hinzufügen: „param“: „Name Ihres Parameters“ (im folgenden Beispiel: „identifier“). Folgen Sie der Syntax unten:

  {"id":{"param":"identifier"}}
  

Klicken Sie auf Speichern.

Die Datenquelle ist jetzt konfiguriert und kann in Ihren Journeys verwendet werden, z. B. in Ihren Bedingungen oder zur Personalisierung einer E-Mail. Wenn die Temperatur über 30° C liegt, können Sie sich entscheiden, eine bestimmte Mitteilung zu senden.

Benutzerdefinierter Authentifizierungsmodus

Dieser Authentifizierungsmodus wird für die komplexe Authentifizierung verwendet, die häufig zum Aufrufen von API-Wrapping-Protokollen wie OAuth2 verwendet wird, um ein Zugriffstoken abzurufen, das in die eigentliche HTTP-Anfrage für die Aktion eingefügt werden soll.

Wenn Sie die benutzerdefinierte Authentifizierung konfigurieren, können Sie auf die Schaltfläche unten klicken, um zu prüfen, ob die Payload der benutzerdefinierten Authentifizierung korrekt konfiguriert ist.

Ist der Test erfolgreich, wird die Schaltfläche grün.

Bei dieser Authentifizierung erfolgt die Aktionsausführung in zwei Schritten:

1. Rufen Sie den Endpunkt auf, um das Zugriffstoken zu generieren.
2. Rufen Sie die REST-API auf, indem Sie das Zugriffstoken ordnungsgemäß einfügen.

Diese Authentifizierung besteht aus zwei Teilen.

Die Definition des Endpunkts, der aufgerufen werden soll, um das Zugriffstoken zu generieren:

• endpoint: URL zum Generieren des Endpunkts
• Methode der HTTP-Anfrage am Endpunkt (GET oder POST)
• headers: Schlüssel/Wert-Paare, die bei Bedarf als Kopfzeilen in diesen Aufruf eingefügt werden sollen
• body: beschreibt den Haupttextteil des Aufrufs, wenn die Methode POST ist. Für den Hauptteil unterstützen wir eine begrenzte Struktur, die in bodyParams definiert ist (Schlüssel/Wert-Paare). Der bodyType beschreibt Format und Codierung des Haupttextteils (body) im Aufruf:
  • 'form': bedeutet, dass der Inhaltstyp application/x-www-form-urlencoded (Zeichensatz UTF-8) lautet und die Schlüssel/Wert-Paare wie folgt serialisiert werden: Schlüssel1=Wert1&Schlüssel2=Wert2& …
  • 'json': bedeutet, dass der Inhaltstyp application/json (Zeichensatz UTF-8) ist und die Schlüssel/Wert-Paare wie folgt als JSON-Objekt serialisiert werden: { "Schlüssel1": "Wert1", "Schlüssel2": "Wert2", …}

Die Definition der Art und Weise, wie das Zugriffstoken in die HTTP-Anfrage der Aktion eingefügt werden muss:

• authorizationType: definiert, wie das generierte Zugriffstoken in den HTTP-Aufruf für die Aktion eingefügt werden muss. Die möglichen Werte sind:

  • bearer: gibt an, dass das Zugriffstoken in die Autorisierungskopfzeile eingefügt werden muss, z. B.: Autorisierung: bearer <Zugriffstoken>
  • header: gibt an, dass das Zugriffstoken als Kopfzeile eingefügt werden muss, der Kopfzeilenname wird von der Eigenschaft tokenTarget definiert. Wenn tokenTarget beispielsweise myHeader ist, wird das Zugriffstoken als Kopfzeile wie folgt eingefügt: myHeader: <Zugriffstoken>
  • queryParam: gibt an, dass das Zugriffstoken als queryParam eingefügt werden muss, der queryParam-Name wird von der Eigenschaft tokenTarget definiert. Wenn tokenTarget beispielsweise myQueryParam ist, lautet die URL des Aktionsaufrufs wie folgt: <URL>?myQueryParam=<Zugriffstoken>

• tokenInResponse: zeigt an, wie das Zugriffstoken aus dem Authentifizierungsaufruf extrahiert wird. Diese Eigenschaft kann Folgendes sein:

  • 'response': gibt an, dass die HTTP-Antwort das Zugriffstoken ist
  • ein Selektor in einem json (vorausgesetzt, dass die Antwort ein json ist, werden andere Formate wie XML nicht unterstützt). Das Format dieses Selektors ist json://<Pfad zur Zugriffstoken-Eigenschaft>. Beispiel: Wenn die Antwort des Aufrufs: { "access_token": "theToken", "timestamp": 12323445656 } ist, dann ist tokenInResponse: json: //access_token

Das Format dieser Authentifizierung ist:

{
    "type": "customAuthorization",
    "authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
    (optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
    "endpoint": "<URL of the authentication endpoint>",
    "method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
    (optional) "headers": {
        "<header name>": "<header value>",
        ...
    },
    (optional, mandatory if method is 'POST') "body": {
        "bodyType": "<'form'or 'json'>,
        "bodyParams": {
            "param1": value1,
            ...

        }
    },
    "tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'"
}

Sie können die Aufbewahrungsfrist des Tokens im Cache für eine benutzerdefinierte Authentifizierungsdatenquelle ändern. Nachstehend finden Sie ein Beispiel für eine benutzerdefinierte Authentifizierungs-Payload. Die Aufbewahrungsfrist im Cache wird im Parameter „cacheDuration“ definiert. Sie gibt die Aufbewahrungsdauer des generierten Tokens im Cache an. Die Einheit kann Millisekunden, Sekunden, Minuten, Stunden, Tage, Monate oder Jahre sein.

"authentication": {
    "type":"customAuthorization",
    "authorizationType":"Bearer",
    "endpoint":"http://localhost:${port}/epsilon/oauth2/access_token",
    "method":"POST",
    "headers": {
        "Authorization":"Basic EncodeBase64(${epsilonClientId}:${epsilonClientSecret})"
        },
    "body": {
        "bodyType":"form",
        "bodyParams": {
             "scope":"cn mail givenname uid employeeNumber",
             "grant_type":"password",
             "username":"${epsilonUserName}",
             "password":"${epsilonUserPassword}"
             }
        },
    "tokenInResponse":"json://access_token",
    "cacheDuration":
             { "duration":5, "timeUnit":"seconds" }
    }