Externe Datenquellen external-data-sources
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. Im Gegensatz zur 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 sowie einfache und benutzerdefinierte Authentifizierungsmodi werden unterstützt.
Nehmen wir als Beispiel einen Wetter-API-Dienst, mit dem ich das Verhalten meiner Journey an Echtzeit-Wetterdaten anpassen möchte.
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 den Breiten- und Längengrad) und dem API-Schlüssel (appid).
Im Folgenden finden Sie die wichtigsten Schritte zum Erstellen und Konfigurieren einer neuen externen Datenquelle:
-
Klicken Sie in der Liste der Datenquellen auf Datenquelle erstellen, um eine neue externe Datenquelle zu erstellen.
Dadurch wird der Konfigurationsbereich für die Datenquelle auf der rechten Seite des Bildschirms geöffnet.
-
Geben Sie einen Namen für Ihre Datenquelle ein.
note note NOTE Es sind nur alphanumerische Zeichen und Unterstriche zulässig. Die maximale Länge beträgt 30 Zeichen. -
Fügen Sie Ihrer Datenquelle eine Beschreibung hinzu. Dieser Schritt ist optional.
-
Fügen Sie die URL des externen Dienstes hinzu. In unserem Beispiel: https://api.adobeweather.org/weather.
note caution CAUTION Aus Sicherheitsgründen wird die Verwendung von HTTPS dringend empfohlen. Beachten Sie auch, dass wir die Verwendung von nicht öffentlich zugänglichen Adobe-Adressen und die Verwendung von IP-Adressen nicht zulassen. 
-
Konfigurieren Sie die Authentifizierung je nach Konfiguration des externen Dienstes: Keine Authentifizierung, Einfach, Benutzerdefiniert oder API-Schlüssel.
Für den einfachen Authentifizierungsmodus müssen Sie einen Benutzernamen und ein Kennwort eingeben.
note note NOTE Wenn der Authentifizierungsaufruf erfolgt, wird die in base64 kodierte Zeichenfolge <username>:<password>in den Authentifizierungs-Header eingefügt.Weitere Informationen zum benutzerdefinierten Authentifizierungsmodus finden Sie in diesem Abschnitt. In unserem Beispiel wählen wir den Authentifizierungsmodus „API-Schlüssel“:
- Typ: „API-Schlüssel“
- Name: „appid“ (dies ist der Name des API-Schlüsselparameters)
- Wert: „1234“ (dies ist der Wert unseres API-Schlüssels)
- Standort: „Abfrageparameter“ (der API-Schlüssel befindet sich in der URL)
-
Fügen Sie für jeden festgelegten API-Parameter eine neue Feldergruppe hinzu, indem Sie auf Neue Feldergruppe hinzufügen klicken. Im Namen der Feldergruppe sind nur alphanumerische Zeichen und Unterstriche zulässig. Die maximale Länge beträgt 30 Zeichen. In unserem Beispiel müssen wir zwei Feldergruppen erstellen, eine für jeden Parametersatz (city und long/lat).
Für den Parametersatz „long/lat“ erstellen wir eine Feldergruppe mit folgenden Informationen:
-
Verwendet in: zeigt die Anzahl der Journeys an, die eine Feldergruppe verwenden. Sie können auf das Symbol Journeys anzeigen klicken, um die Liste der Journeys anzuzeigen, die diese Feldergruppe verwenden.
-
Methode: Wählen Sie die POST- oder GET-Methode aus. In unserem Beispiel wählen wir die GET-Methode aus.
-
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
-
Antwort-Payload: Klicken Sie in das Feld Payload und fügen Sie ein Beispiel für die Payload ein, die vom Aufruf zurückgegeben wird. 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 Neue Payload einfügen klicken können, wenn Sie die aktuell übergebene Payload ändern möchten.
-
Gesendete Payload: Dieses Feld wird in unserem Beispiel nicht 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 einem GET-Aufruf, der Parameter erfordert, geben Sie die Parameter in das Feld Dynamische Werte ein und sie werden automatisch am Ende des Aufrufs hinzugefügt. Bei einem POST-Aufruf müssen Sie:
-
die beim Zeitpunkt des Aufrufs 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 unten stehenden Syntax:
code language-none {"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 eine bestimmte Mitteilung versenden.
Benutzerdefinierter Authentifizierungsmodus custom-authentication-mode
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 überprüfen, ob die Payload der benutzerdefinierten Authentifizierung korrekt konfiguriert ist.
Wenn der Test erfolgreich ist, wird die Schaltfläche grün.
Bei dieser Authentifizierung erfolgt die Aktionsausführung in zwei Schritten:
- Rufen Sie den Endpunkt auf, um das Zugriffstoken zu generieren.
- Rufen Sie die REST-API auf, indem Sie das Zugriffstoken ordnungsgemäß einfügen.
Die Definition des Endpunkts, der aufgerufen werden soll, um das Zugriffs-Token zu generieren custom-authentication-endpoint
-
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 Haupttextteil 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 Zugriffs-Token in die HTTP-Anfrage der Aktion eingefügt werden muss custom-authentication-access-token
-
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 der Autorisierungskopfzeile eingefügt werden muss, z. B.: Authorization: Bearer <access token>
- header: gibt an, dass das Zugriffstoken als Kopfzeile eingefügt werden muss, wobei der Kopfzeilenname durch die Eigenschaft „tokenTarget“ definiert wird. Wenn das tokenTarget z. B. myHeader ist, wird das Zugriffstoken wie folgt als Kopfzeile eingefügt: myHeader: <access token>
- queryParam: gibt an, dass das Zugriffstoken als queryParam eingefügt werden muss, wobei der Abfrageparametername durch die Eigenschaft „tokenTarget“ definiert wird. Wenn das tokenTarget beispielsweise myQueryParam ist, lautet die URL des Aktionsaufrufs: <url>?myQueryParam=<access token>
-
tokenInResponse: Gibt an, wie das Zugriffstoken aus dem Authentifizierungsaufruf extrahiert wird. Diese Eigenschaft kann Folgendes sein:
- 'response': gibt an, dass die HTTP-Antwort das Zugriffstoken ist
- eine Auswahl in einer JSON-Datei (es wird vorausgesetzt, die Antwort ist eine JSON-Datei, und andere Formate wie XML werden nicht unterstützt). Das Format dieser Auswahl ist json://<Pfad zur Zugriffstoken-Eigenschaft>. Wenn die Antwort des Aufrufs zum Beispiel folgendermaßen lautet: { "access_token": "theToken", "timestamp": 12323445656 }, wird die tokenInResponse Folgendes sein: json: //access_token
Das Format dieser Authentifizierung lautet:
{
"type": "customAuthorization",
"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>'",
"cacheDuration": {
(optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
(optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
"timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
},
"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'>",
}
Sie können die Aufbewahrungsfrist im Cache des Tokens 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.
Im Folgenden finden Sie ein Beispiel für den Bearer-Authentifizierungstyp:
{
"authentication": {
"type": "customAuthorization",
"authorizationType": "Bearer",
"endpoint": "https://<your_auth_endpoint>/epsilon/oauth2/access_token",
"method": "POST",
"headers": {
"Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
},
"body": {
"bodyType": "form",
"bodyParams": {
"scope": "cn mail givenname uid employeeNumber",
"grant_type": "password",
"username": "<epsilon User Name>",
"password": "<epsilon User Password>"
}
},
"tokenInResponse": "json://access_token",
"cacheDuration": {
"duration": 5,
"timeUnit": "minutes"
}
}
}
Im Folgenden finden Sie ein Beispiel für den Kopfzeilen-Authentifizierungstyp:
{
"type": "customAuthorization",
"authorizationType": "header",
"tokenTarget": "x-auth-token",
"endpoint": "https://myapidomain.com/v2/user/login",
"method": "POST",
"headers": {
"x-retailer": "any value"
},
"body": {
"bodyType": "form",
"bodyParams": {
"secret": "any value",
"username": "any value"
}
},
"tokenInResponse": "json://token",
"cacheDuration": {
"expiryInResponse": "json://expiryDuration",
"timeUnit": "minutes"
}
}
Im Folgenden finden Sie ein Beispiel für die Antwort des Anmeldungs-API-Aufrufs:
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}