Externa datakällor external-data-sources
Med externa datakällor kan du definiera en anslutning till tredjepartssystem om du till exempel använder ett bokningssystem för hotell som kontrollerar om personen har registrerat ett rum. I motsats till den inbyggda datakällan i Adobe Experience Platform kan du skapa så många externa datakällor som behövs.
Stöd finns för REST API:er som använder POST eller GET och returnerar JSON. API-nyckel samt grundläggande och anpassade autentiseringslägen stöds.
Låt oss använda en API-tjänst för väder som exempel. Jag vill använda den för att anpassa resans beteenden beroende på väderdata i realtid.
Här är två exempel på API-anropet:
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
Anropet består av en huvud-URL (https://api.adobeweather.org/weather), två parameteruppsättningar ("city" för staden och "lat/long" för latitud och longitud) och API-nyckeln (appid).
Här följer de viktigaste stegen för att skapa och konfigurera en ny extern datakälla:
-
Klicka på Create Data Source i listan med datakällor för att skapa en ny extern datakälla.
Detta öppnar konfigurationsfönstret för datakällan till höger på skärmen.
-
Ange ett namn för datakällan.
note note NOTE Endast alfanumeriska tecken och understreck tillåts. Maximala längden är 30 tecken. -
Lägg till en beskrivning om datakällan. Det här steget är valfritt.
-
Lägg till den externa tjänstens URL. I vårt exempel: https://api.adobeweather.org/weather.
note caution CAUTION Vi rekommenderar starkt att HTTPS används av säkerhetsskäl. Observera också att vi endast tillåter att Adobe-adresser som är allmänt tillgängliga samt IP-adresser används. 
-
Konfigurera autentiseringen beroende på den externa tjänstkonfigurationen: No authentication, Basic, Custom eller API key.
För det grundläggande autentiseringsläget måste du fylla i ett användarnamn och ett lösenord.
note note NOTE När autentiseringsanropet utförs läggs strängen <username>:<password>, som är kodad i base64, till i autentiseringshuvudet.Mer information om det anpassade autentiseringsläget finns i det här avsnittet. I det här exemplet väljer vi autentiseringsläget för API-nyckel:
- Type: "API-nyckel"
- Name: "appid" (det här är API-nyckelns parameternamn)
- Value: "1234" (det här är värdet på vår API-nyckel)
- Location: "Frågeparameter" (API-nyckeln finns i webbadressen)
-
Klicka på Add a New Field Group för att lägga till en ny fältgrupp för varje API-parameteruppsättning. Endast alfanumeriska tecken och understreck tillåts i fältgruppsnamnet. Maximala längden är 30 tecken. I vårt exempel behöver vi skapa två fältgrupper. En för varje parameteruppsättning ("city" och "long/lat").
För parameteruppsättningen "long/lat" skapar vi en fältgrupp med följande information:
-
Used in: visar antalet resor som använder en fältgrupp. Du kan klicka på ikonen View journeys för att visa en lista över resor som använder den här fältgruppen.
-
Method: välj metoden POST eller GET. I vårt fall väljer vi metoden GET.
-
Dynamic Values: ange de olika parametrarna avgränsade med kommatecken – "long,lat" i vårt exempel. Eftersom parameterns värden är beroende av körningens sammanhang definieras de i resorna. Läs mer
-
Response Payload: klicka inuti fältet Payload och klistra in ett exempel på nyttolasten som returneras av anropet. Vi har till exempel använt en nyttolast som finns på en API-webbplats för väder. Kontrollera att fälttyperna är korrekta. Varje gång API:et anropas hämtas alla fält som ingår i exemplets nyttolast. Observera att du kan klicka på Paste a new payload för att ändra den nyttolast som för närvarande används.
-
Sent Payload: det här fältet visas inte i vårt exempel. Det är endast tillgängligt om du väljer metoden POST. Klistra in nyttolasten som ska skickas till tredjepartssystemet.
Om ett GET-anrop som kräver parametrar används ska du ange parametrarna i fältet Dynamic Values och de läggs sedan till automatiskt i slutet av anropet. Om ett POST-anrop används måste du:
-
lista de parametrar som ska skickas vid anropet i fältet Dynamic Values (i exemplet nedan: "identifier").
-
även ange dem med exakt samma syntax i brödtexten i den skickade nyttolasten. Om du vill göra det måste du lägga till: "param": "name of your parameter" (i exemplet nedan: "identifier"). Följ syntaxen nedan:
code language-none {"id":{"param":"identifier"}}
Klicka på Save.
Datakällan är nu konfigurerad och redo att användas i dina resor. Du kan till exempel använda den i dina villkor eller för att personalisera ett e-postmeddelande. Om temperaturen är över 30 °C kan du välja att skicka ett visst meddelande.
Anpassat autentiseringsläge custom-authentication-mode
Det här autentiseringsläget används vid komplex autentisering som ofta används för att anropa API-omslutningsprotokoll som OAuth2 och för att hämta en åtkomsttoken som ska injiceras i den faktiska HTTP-begäran för åtgärden.
När du konfigurerar den anpassade autentiseringen kan du klicka på knappen nedan för att kontrollera om den anpassade autentiserade nyttolasten är korrekt konfigurerad.
Om testet godkänns blir knappen grön.
Med den här autentiseringen blir åtgärdskörningen en process med två steg:
- Anropa slutpunkten för att generera en åtkomsttoken.
- Anropa REST API:et genom att injicera åtkomsttoken på rätt sätt.
Definition av slutpunkten som ska anropas för att generera åtkomsttoken custom-authentication-endpoint
-
slutpunkt: URL som ska användas för att generera slutpunkten
-
metoden för HTTP-begäran på slutpunkten (GET eller POST)
-
rubriker: nyckelvärdepar som ska matas in som rubriker i detta anrop om det behövs
-
brödtext: beskriver anropets brödtext om metoden är POST. Vi stöder en begränsad brödstruktur, som definieras i bodyParams (key-value pairs). Brödtextens typ beskriver formatet och kodningen för brödtexten i anropet:
- 'form': innebär att innehållstypen blir application/x-www-form-urlencoded (charset UTF-8) och nyckelvärdepar serialiseras som: key1=value1&key2=value2&…
- json: det innebär att innehållstypen blir application/json (charset UTF-8) och nyckelvärdepar kommer att serialiseras som ett json-objekt som är: { "key1": "value1", "key2": "value2", …}
Definition av hur åtkomsttoken måste matas in i åtgärdens HTTP-begäran custom-authentication-access-token
-
authorizationType: definierar hur den genererade åtkomsttoken måste injiceras i HTTP-anropet för åtgärden. Möjliga värden är:
- innehavare: anger att en åtkomsttoken måste injiceras i auktoriseringsrubriken såsom: behörighet: innehavare <åtkomsttoken>
- rubrik: anger att en åtkomsttoken måste injiceras som en rubrik där dess namn definieras av egenskapen tokenTarget. Om till exempel tokenTarget är myHeader injiceras åtkomsttoken som en rubrik som: myHeader: <åtkomsttoken>
- queryParam: anger att en åtkomsttoken måste injiceras som en queryParam där dess namn definieras av egenskapen tokenTarget. Om till exempel tokenTarget är myQueryParam blir webbadressen för åtgärdsanropet: <url>?myQueryParam=<åtkomsttoken>
-
tokenInResponse: anger hur du extraherar åtkomsttoken från autentiseringsanropet. Den här egenskapen kan vara:
- "response": anger att HTTP-svaret är åtkomsttoken
- en väljare i en json (förutsatt att svaret är en json. Vi har inte stöd för andra format som XML). Den här väljarens format är json://<sökväg till åtkomsttokens egenskap>. Om svaret på anropet till exempel är: { "access_token": "theToken", "timestamp": 12323445656 }, kommer tokenInResponse att vara: json: //access_token
Autentiseringsformatet är:
{
"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'>",
}
Du kan ändra cachevaraktigheten på en token för en anpassad autentiseringsdatakälla. Nedan visas ett exempel på en anpassad autentiseringsnyttolast. Cachevaraktigheten definieras i parametern "cacheDuration". Den anger varaktigheten för den genererade token i cachen. Enheten kan vara millisekunder, sekunder, minuter, timmar, dagar, månader och år.
Här följer ett exempel på autentiseringstypen för innehavare:
{
"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"
}
}
}
Här är ett exempel på autentiseringstypen för sidhuvud:
{
"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"
}
}
Här är ett exempel på svaret på inloggnings-API-anropet:
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}