DokumentationJourney OptimizerAnvändarhandbok om Journey Optimizer

Externa datakällor external-data-sources

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

Skapat för:

  • Mellanliggande
  • Erfaren
  • Utvecklare
  • Administratör

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.

NOTE
Garantier visas på den här sidan när du arbetar med externa system.
NOTE
Eftersom svaren nu stöds bör du använda anpassade åtgärder i stället för datakällor för externa datakällor som användningsfall. Mer information om svar finns i avsnittet

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:

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

  2. Ange ett namn för datakällan.

    note note
    NOTE
    Endast alfanumeriska tecken och understreck tillåts. Maximala längden är 30 tecken.

  3. Lägg till en beskrivning om datakällan. Det här steget är valfritt.

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

  5. 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)

  6. 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-json 
    {"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:

  1. Anropa slutpunkten för att generera en åtkomsttoken.
  2. Anropa REST API:et genom att injicera åtkomsttoken på rätt sätt.
NOTE
Den här autentiseringen består av två delar.

Definition av slutpunkten som ska anropas för att generera åtkomsttoken custom-authentication-endpoint

  • endpoint: URL som ska användas för att generera slutpunkten

  • HTTP-begärans metod på slutpunkten (GET eller POST)

  • headers: nyckelvärdepar som ska injiceras som huvuden i det här anropet om det behövs

  • body: beskriver brödtexten för anropet 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 kommer att vara application/x-www-form-urlencoded (charset UTF-8) och nyckelvärdepar kommer att serialiseras som: key1=value1&key2=value2&…
    • json: 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

  • permissionType: definierar hur den genererade åtkomsttoken måste injiceras i HTTP-anropet för åtgärden. Möjliga värden är:

    • bearer: anger att åtkomsttoken måste injiceras i auktoriseringshuvudet, till exempel: Auktorisering: Bearer <åtkomsttoken>
    • header: anger att åtkomsttoken måste matas in som ett huvud, det rubriknamn som definieras av egenskapen tokenTarget. Om till exempel tokenTarget är myHeader kommer åtkomsttoken att matas in som en rubrik som: myHeader: <åtkomsttoken>
    • queryParam: anger att åtkomsttoken måste matas in som queryParam, frågeparameternamnet som definieras av egenskapen tokenTarget. Om till exempel tokenTarget är myQueryParam blir webbadressen för åtgärdsanropet: <url>?myQueryParam=<åtkomsttoken>

  • tokenInResponse: anger hur åtkomsttoken ska extraheras 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, stöder vi inte 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'>",
}
NOTE
Encode64 är den enda funktionen som är tillgänglig i autentiseringsnyttolasten.

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:

{
    "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
Autentiseringstoken cachelagras per resa: om två resor använder samma anpassade åtgärd har varje resa en egen token cachelagrad. Denna token delas inte mellan dessa resor.
Cachens varaktighet hjälper till att undvika för många anrop till slutpunkterna för autentisering. Kvarhållande av autentiseringstoken cachelagras i tjänster, det finns ingen beständighet. Om en tjänst startas om börjar den med en ren cache. Cachevaraktigheten är som standard 1 timme. I den anpassade autentiseringsnyttolasten kan den anpassas genom att ange en annan kvarhållningstid.

Här är ett exempel på autentiseringstypen för sidhuvud:

{
  "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"
}

Här är ett exempel på svaret på inloggnings-API-anropet:

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