DocumentatieJourney OptimizerHandleiding voor Journey Optimizer

Externe databronnen external-data-sources

Last update: Wed Aug 21 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Gemaakt voor:

  • tussenpersoon
  • Ervaren
  • Ontwikkelaar
  • Beheerder

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.

NOTE
De begeleiding wanneer het werken met externe systemen is vermeld in deze pagina.
NOTE
Aangezien de reacties nu worden gesteund, zou u douaneacties in plaats van gegevensbronnen voor externe gegevensbronnen moeten gebruiken-gevallen. Voor meer informatie over reacties, zie deze sectie

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:

  1. 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.

  2. Voer een naam in voor de databron.

    note note
    NOTE
    Alleen alfanumerieke tekens en onderstrepingstekens zijn toegestaan. De maximumlengte is 30 tekens.

  3. Voeg een beschrijving aan de databron toe. Deze stap is optioneel.

  4. 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.

  5. Configureer de verificatie afhankelijk van de externe serviceconfiguratie: No authentication, Basic , Custom of API key .

    Voor de basisauthentificatiemodus, moet u een gebruikersbenaming en een wachtwoord invullen.

    note note
    NOTE
    Wanneer de verificatieaanroep wordt uitgevoerd, wordt de <username>:<password> -tekenreeks, gecodeerd in base64, toegevoegd aan de verificatieheader.

    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)

  6. 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:

  • geeft een lijst weer van de parameters die tijdens de aanroep moeten worden doorgegeven in het veld Dynamic Values (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-json 
    {"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:

  1. Roep het eindpunt aan om de toegangstoken te genereren.
  2. Roep de REST-API aan door de toegangstoken op de juiste manier te injecteren.
NOTE
Deze authentificatie heeft twee delen.

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 het HTTP- verzoek op het eindpunt (GET of POST)

  • headers: sleutel-waarde paren die als kopballen in deze vraag moeten worden geïnjecteerd 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) zal zijn en de sleutel-waardeparen zullen in series worden vervaardigd zoals is: key1=value1&key2=value2&…
    • json: betekent dat het inhoudstype application/json (charset UTF-8) zal zijn en de sleutel-waardeparen als json voorwerp zullen in series worden vervaardigd zoals is: { "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

  • authenticationType: bepaalt hoe het geproduceerde toegangstoken in de vraag van HTTP voor de actie moet worden ingespoten. De mogelijke waarden zijn:

    • bearer: wijst erop dat het toegangstoken in de kopbal van de Vergunning moet worden ingespoten, zoals: Vergunning: Drager <access token>
    • header: geeft aan dat het toegangstoken moet worden geïnjecteerd als een header, de headernaam gedefinieerd door de eigenschap tokenTarget . Bijvoorbeeld, als tokenTarget myHeader is, zal het toegangstoken als kopbal als worden ingespoten: myHeader: <access token>
    • queryParam: wijst erop dat het toegangstoken als queryParam moet worden ingespoten, de naam van het vraagparam die door het bezit tokenTarget wordt bepaald. Als de tokenTarget bijvoorbeeld myQueryParam is, is de URL van de actieaanroep: <url>?myQueryParam=<access token>

  • tokenInResponse: wijst erop hoe te om het toegangstoken uit de authentificatievraag te halen. Deze eigenschap kan zijn:

    • response: geeft aan dat het HTTP-antwoord het toegangstoken is
    • een kiezer in een json (ervan uitgaande dat de reactie een json is, ondersteunen we 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'>",
}
NOTE
Encode64 is de enige functie beschikbaar in de authentificatielading.

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 duur van de cache 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:

{
    "type": "customAuthorization",
    "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"
    },
  },
NOTE
Het verificatietoken wordt per reis in de cache opgeslagen: wanneer twee reizen dezelfde aangepaste handeling gebruiken, heeft elke reis een eigen token in de cache. Deze token wordt niet tussen deze reizen gedeeld.
De duur van het geheime voorgeheugen helpt om teveel vraag aan de authentificatieeindpunten te vermijden. Het symbolenbehoud van de authentificatie wordt caching in de diensten, er is geen persistentie. Als de dienst opnieuw wordt begonnen, begint het met een schone geheime voorgeheugen. De cache-duur is standaard 1 uur. In de lading van de douaneauthentificatie, kan het worden aangepast door een andere bewaarduur te specificeren.

Hier ziet u een voorbeeld van het type headerverificatie:

{
  "type": "customAuthorization",
  "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"
  },
  "authorizationType": "header",
  "tokenTarget": "x-auth-token"
}

Hier is een voorbeeld van de reactie van de login API vraag:

{
  "token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
  "expiryDuration" : 5
}
recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76