Externe databronnen external-data-sources
Met externe databronnen kunt u een verbinding maken met externe systemen, bijvoorbeeld als u een hotelboekingssysteem gebruikt om te controleren of de persoon een kamer heeft besproken. In tegenstelling tot de ingebouwde databron van het Adobe Experience Platform kunt u zoveel externe databronnen maken als u wilt.
REST-API’s die gebruikmaken van POST of GET en JSON retourneren, worden ondersteund. API-sleutel, standaard en aangepaste verificatiemodi worden ondersteund.
Laten we bijvoorbeeld kijken naar een API-weerservice die ik wil gebruiken om de gedragingen van mijn journey aan te passen aan real-timeweerdata.
Hier volgen twee voorbeelden van de API-aanroep:
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
De aanroep bestaat uit een hoofd-URL (https://api.adobeweather.org/weather), twee parameterreeksen (‘city’ voor de stad en ‘lat/long’ voor de breedtegraad en de lengtegraad) en de API-sleutel (appid).
Hier volgen de belangrijkste stappen voor het maken en configureren van een nieuwe externe databron:
-
Klik in de lijst van databronnen op Create Data Source om een nieuwe externe databron te maken.
Hiermee opent u het configuratiedeelvenster voor de databron aan de rechterkant van het scherm.
-
Voer een naam in voor de databron.
note note NOTE Alleen alfanumerieke tekens en onderstrepingstekens zijn toegestaan. De maximumlengte is 30 tekens. -
Voeg een beschrijving aan de databron toe. Deze stap is optioneel.
-
Voeg de URL van de externe service toe. In ons voorbeeld: https://api.adobeweather.org/weather.
note caution CAUTION We raden u uit beveiligingsoverwegingen sterk aan om HTTPS te gebruiken. Bedenk ook dat we het gebruik van Adobe-adressen die niet openbaar beschikbaar zijn en het gebruik van IP-adressen niet toestaan. 
-
Vorm de authentificatie afhankelijk van de externe de dienstconfiguratie: No authentication, Basic, Custom of API key.
Voor de basisauthentificatiemodus, moet u een gebruikersbenaming en een wachtwoord invullen.
note note NOTE Wanneer de authentificatievraag wordt uitgevoerd, <username>:<password>string, gecodeerd in base64, wordt toegevoegd in de header Authentication.Voor meer informatie over de wijze van de douaneauthentificatie, zie deze sectie. In ons voorbeeld kiezen we de API-sleutelverificatiemodus:
- Type: ‘API-sleutel’
- Name: ‘appid’ (dit is de parameternaam van de API-sleutel)
- Value: ‘1234’ (dit is de waarde van onze API-sleutel)
- Location: ‘Query-parameter’ (de API-sleutel bevindt zich in de URL)
-
Voeg een nieuwe veldengroep toe voor elke API-parameterreeks door te klikken op Add a New Field Group. Alleen alfanumerieke tekens en onderstrepingstekens zijn toegestaan in de naam van de veldgroep. De maximumlengte is 30 tekens. In ons voorbeeld moeten we twee veldengroepen maken, één voor elke parameterreeks (city en long/lat).
Voor de parameterreeks ‘long/lat’ maken we een veldengroep met de volgende informatie:
-
Used in: geeft het aantal journey’s weer dat een veldengroep gebruikt. U kunt klikken op het pictogram View journeys om de lijst weer te geven met journey’s die deze veldengroep gebruiken.
-
Method: selecteer de methode POST of GET. In ons geval selecteren we de methode GET.
-
Dynamic Values: voer de verschillende parameters in, gescheiden door een komma, in het voorbeeld ‘long,lat’. Aangezien de parameterwaarden afhankelijk zijn van de uitvoeringscontext, worden ze tijdens de journey’s gedefinieerd. Meer informatie
-
Response Payload: klik in het veld Payload en plak een voorbeeld van de payload die door de aanroep is geretourneerd. Voor ons voorbeeld hebben we een payload gebruikt van een API-weerwebsite. Controleer of de veldtypen correct zijn. Telkens wanneer de API wordt aangeroepen, haalt het systeem alle velden op die in het payloadvoorbeeld zijn opgenomen. U kunt klikken op Paste a new payload als u de huidige payload wilt wijzigen.
-
Sent Payload: dit veld staat niet in ons voorbeeld. Deze optie is alleen beschikbaar als u de methode POST selecteert. Plak de payload die naar het externe systeem wordt verzonden.
Bij een GET-aanroep die parameter(s) vereist, voert u de parameter(s) in het veld Dynamic Values in en worden deze automatisch toegevoegd aan het eind van de aanroep. Bij een POST-aanroep doet u het volgende:
-
lijst van de parameters die bij vraagtijd in Dynamic Values veld (in het onderstaande voorbeeld: "identifier").
-
geef ze ook volgens precies dezelfde syntaxis op in de hoofdtekst van de verzonden payload. Hiervoor moet u het volgende toevoegen: "param": "name of your parameter" (in het onderstaande voorbeeld: "identifier"). Volg de onderstaande syntaxis:
code language-none {"id":{"param":"identifier"}}
Klik op Save.
De databron is nu geconfigureerd en klaar om te worden gebruikt in uw journey’s, bijvoorbeeld in uw voorwaarden of om een e-mail te personaliseren. Als de temperatuur boven 30 °C ligt, kunt u besluiten een bepaalde mededeling te sturen.
Aangepaste verificatiemodus custom-authentication-mode
Deze verificatiemodus wordt gebruikt voor complexe verificatie, die vaak wordt gebruikt om API-wrappingprotocollen aan te roepen zoals OAuth2, voor het ophalen van een toegangstoken die moet worden geïnjecteerd in de echte HTTP-aanvraag voor de actie.
Wanneer u de aangepaste verificatie configureert, kunt u op de onderstaande knop klikken om te controleren of de payload van de aangepaste verificatie correct is geconfigureerd.
Als de test is geslaagd, wordt de knop groen.
Bij deze verificatie is de uitvoering van de actie een proces dat uit twee stappen bestaat:
- Roep het eindpunt aan om de toegangstoken te genereren.
- Roep de REST-API aan door de toegangstoken op de juiste manier te injecteren.
Definitie van het eindpunt dat moet worden geroepen om het toegangstoken te produceren custom-authentication-endpoint
-
endpoint: URL om het eindpunt te genereren
-
methode van de HTTP-aanvraag bij het eindpunt (GET of POST)
-
kopballen: sleutel-waarde paren die als kopballen in deze vraag moeten worden ingespoten indien vereist
-
body: beschrijft de hoofdtekst van de aanroep als de methode POST is. Wij steunen een beperkte lichaamsstructuur, die in bodyParams (zeer belangrijke-waardeparen) wordt bepaald. Het bodyType beschrijft de indeling en versleuteling van de hoofdtekst in de aanroep:
- 'form': betekent dat het inhoudstype application/x-www-form-urlencoded (charset UTF-8) is en dat de sleutelwaardeparen serieel worden geordend zoals: key1=value1&key2=value2&…
- 'json': betekent dat het inhoudstype application/json (charset UTF-8) is en dat de sleutelwaardeparen als een JSON-object worden geserialiseerd: { "key1": "value1", "key2": "value2", …}
Definitie van de manier waarop het toegangstoken in het HTTP- verzoek van de actie moet worden ingespoten custom-authentication-access-token
-
authorizationType: bepaalt hoe de gegenereerde toegangstoken in de HTTP-aanroep voor de actie moet worden geïnjecteerd. De mogelijke waarden zijn:
- bearer: geeft aan dat de toegangstoken moet worden geïnjecteerd in de Authorization-koptekst, bijvoorbeeld: Authorization: Bearer <toegangstoken>
- header: geeft aan dat de toegangstoken moet worden geïnjecteerd als een koptekst, de header-naam gedefinieerd door de eigenschap tokenTarget. Als de tokenTarget bijvoorbeeld myHeader is, wordt de toegangstoken geïnjecteerd als koptekst als: myHeader: <toegangstoken>
- queryParam: geeft aan dat de toegangstoken moet worden geïnjecteerd als een queryParam, de queryparam-naam gedefinieerd door de eigenschap tokenTarget. Als de tokenTarget bijvoorbeeld myQueryParam is, is de URL van de actieaanroep: <url>?myQueryParam=<access token>
-
tokenInResponse: geeft aan hoe de toegangstoken uit de verificatieaanroep moet worden gehaald. Deze eigenschap kan zijn:
- response: geeft aan dat de HTTP-reactie de toegangstoken is
- een selectietool in een json (ervan uitgaande dat de reactie een json is, we ondersteunen geen andere indelingen zoals XML). De indeling van deze selector is json://<pad naar de toegangstoken-eigenschap>. Als de reactie van de aanroep bijvoorbeeld { “access_token”: “theToken”, “timestamp”: 12323445656 } is, is de tokenInResponse: json: //access_token
De indeling van deze verificatie is:
{
"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'>",
}
U kunt de cachetermijn van de token wijzigen voor een databron met aangepaste verificatie. Hieronder ziet u een voorbeeld van een payload met aangepaste verificatie. De cachetermijn wordt gedefinieerd in de parameter cacheDuration. Hiermee wordt de retentieduur van de gegenereerde token in de cache opgegeven. De eenheid kan milliseconden, seconden, minuten, uren, dagen, maanden of jaren zijn.
Hier is een voorbeeld voor het dragerauthentificatietype:
{
"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"
}
}
}
Hier ziet u een voorbeeld van het type headerverificatie:
{
"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"
}
}
Hier is een voorbeeld van de reactie van de login API vraag:
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}