외부 데이터 소스 concept_t2s_kqt_52b
외부 데이터 소스를 사용하면 서드파티 시스템에 대한 연결을 정의할 수 있습니다. 호텔 예약 시스템을 사용하여 특정인의 객실 투숙 여부를 확인하는 경우를 예로 들 수 있습니다. 기본 제공 Adobe Experience Platform 데이터 소스와는 달리 외부 데이터 소스는 필요한 수만큼 만들 수 있습니다.
POST 또는 GET을 사용하며 JSON을 반환하는 REST API가 지원됩니다. 그리고 API 키와 기본/사용자 지정 인증 모드가 지원됩니다.
실시간 날씨 데이터에 따라 여정 동작을 사용자 지정하는 데 사용하려는 날씨 API 서비스의 예제를 살펴보겠습니다.
아래에 API 호출의 두 가지 예제가 나와 있습니다.
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
이 호출에는 기본 URL(https://api.adobeweather.org/weather), 매개 변수 세트 2개(도시에 해당하는 "city"와 위도/경도에 해당하는 "lat/long"), 그리고 API 키(appid)가 포함되어 있습니다.
새 외부 데이터 소스를 만들고 구성하는 주요 단계는 다음과 같습니다.
-
새 외부 데이터 원본을 만들려면 데이터 원본 목록에서 Create data source 을(를) 클릭하십시오.
화면 오른쪽에 데이터 소스 구성 창이 열립니다.
-
데이터 소스의 이름을 입력합니다.
note note NOTE 공백이나 특수 문자는 사용하지 말고 이름은 30자까지만 입력하십시오. -
원하는 경우 데이터 소스에 이벤트에 설명을 추가합니다.
-
외부 서비스의 URL을 추가합니다. 이 예제에서는 https://api.adobeweather.org/weather 를 추가합니다.
note caution CAUTION 보안상 HTTPS를 사용하는 것이 좋습니다. 또한 공개적으로 제공되지 않는 Adobe 주소 및 IP 주소는 사용할 수 없습니다. 
-
외부 서비스 구성에 따라 인증을 구성합니다. No authentication, Basic, Custom, API key 중에서 선택할 수 있습니다. 사용자 지정 인증 모드에 대한 자세한 내용은 이 섹션을 참조하십시오. 이 예제에서는 다음 옵션을 선택합니다.
- Type: "API 키"
- Value: "1234"(API 키의 값)
- Name: "appid"(API 키 매개 변수 이름)
- Location: "쿼리 매개 변수"(API 키가 URL에 포함됨)
-
Add a New Field Group 를 클릭하여 각 API 매개 변수용 새 필드 그룹을 추가합니다. 필드 그룹 이름에는 공백이나 특수 문자를 사용하지 마십시오. 이 예제에서는 각 매개 변수 세트(city, long/lat)용으로 하나씩 두 개의 필드 그룹을 만들어야 합니다.
"long/lat" 매개 변수 세트의 경우 다음 정보를 사용하여 필드 그룹을 만듭니다.
- Used in: 필드 그룹을 사용하는 여정 수를 표시합니다. View journeys 아이콘을 클릭하여 이 필드 그룹을 사용하는 여정 목록을 표시할 수 있습니다.
- Method: POST 또는 GET 메서드를 선택합니다. 여기서는 GET 메서드를 선택합니다.
- Response Payload: Payload 필드 안을 클릭하여 호출에서 반환된 페이로드의 예제를 붙여넣습니다. 이 예제에서는 날씨 API 웹 사이트의 페이로드를 사용했습니다. 필드 유형이 올바른지 확인합니다. API를 호출할 때마다 시스템은 페이로드 예제에 포함된 모든 필드를 검색합니다. 현재 전달된 페이로드를 변경하려는 경우 Paste a new payload 를 클릭하면 됩니다.
- Dynamic Values: 각 매개 변수를 쉼표로 구분하여 입력합니다. 이 예제에서는 "long,lat"를 입력합니다. 매개 변수 값은 실행 컨텍스트에 따라 달라지므로 여정에서 정의됩니다. 이 페이지를 참조하십시오.
- Sent Payload: 이 예제에서는 이 필드가 표시되지 않습니다. POST 메서드를 선택해야 이 필드를 사용할 수 있습니다. 서드파티 시스템으로 전송할 페이로드를 붙여넣습니다.
매개 변수가 필요한 GET 호출의 경우 Dynamic Values 필드에 매개 변수를 입력하면 호출 끝에 매개 변수가 자동으로 추가됩니다. POST 호출의 경우에는 다음을 수행해야 합니다.
-
호출 시 전달할 매개 변수의 목록을 Dynamic Values 필드에 포함합니다. 아래 예제에서는 매개 변수가 "identifier"입니다.
-
전송되는 페이로드 본문에서도 정확히 동일한 구문을 사용하여 매개 변수를 지정합니다. 이렇게 하려면 "param": "매개 변수 이름"(아래 예제에서는 "identifier")을 추가해야 합니다. 아래 구문을 따르십시오.
code language-none {"id":{"param":"identifier"}}
Save 을(를) 클릭합니다.
이제 데이터 소스가 구성되었으며 여정에서 사용할 수 있는 상태가 되었습니다. 예를 들어 조건이나 이메일 개인화 등에 데이터 소스를 사용할 수 있습니다. 가령 기온이 섭씨 30도를 넘으면 특정 메시지를 보내도록 지정할 수 있습니다.
사용자 정의 인증 모드 section_wjp_nl5_nhb
이 인증 모드는 작업의 실제 HTTP 요청에 삽입할 액세스 토큰을 검색하기 위한 복잡한 인증(대개 OAuth2 등의 API 래핑 프로토콜을 호출하는 데 사용됨)에 사용됩니다.
사용자 지정 인증을 구성할 때는 아래 버튼을 클릭하여 사용자 지정 인증 페이로드가 올바르게 구성되어 있는지 확인할 수 있습니다.
테스트가 정상적으로 완료되면 버튼이 녹색으로 바뀝니다.
이 인증을 사용할 때는 작업이 다음의 두 단계로 실행됩니다.
- 끝점을 호출하여 액세스 토큰을 생성합니다.
- 올바른 방식으로 액세스 토큰을 삽입하여 REST API를 호출합니다.
이 인증은 두 부분으로 구성되어 있습니다.
액세스 토큰 생성을 위해 호출할 끝점의 정의:
-
endpoint: 끝점을 생성하는 데 사용할 URL
-
끝점에 대한 HTTP 요청 메서드(GET 또는 POST)
-
header: 필요한 경우 이 호출에서 헤더로 삽입할 키/값 쌍
-
body: 메서드가 POST인 경우 호출의 본문을 설명하는 요소. bodyParams(키/값 쌍)에 정의된 제한된 본문 구조가 지원됩니다. bodyType은 호출 본문의 형식과 인코딩을 설명합니다.
- 'form': 콘텐츠 유형은 application/x-www-form-urlencoded(charset UTF-8)이며 키/값 쌍이 그대로 일련화됩니다(예: key1=value1&key2=value2&…).
- 'json': 콘텐츠 유형은 application/json(charset UTF-8)이며 키/값 쌍이 json 개체 그대로 일련화됩니다(예: { "key1": "value1", "key2": "value2"…}).
작업의 HTTP 요청에서 액세스 토큰을 삽입해야 하는 방식의 정의:
-
authorizationType: 생성된 액세스 토큰을 작업의 HTTP 호출에 삽입해야 하는 방법을 정의합니다. 가능한 값은 다음과 같습니다.
- bearer: Authorization: Bearer <액세스 토큰> 과 같이 액세스 토큰을 권한 부여 헤더에 삽입해야 함을 나타냅니다.
- header: 액세스 토큰을 header(tokenTarget 속성으로 정의된 헤더 이름)로 삽입해야 함을 나타냅니다. 예를 들어 tokenTarget이 myHeader이면 액세스 토큰은 myHeader: <액세스 토큰> 과 같이 헤더로 삽입됩니다.
- queryParam: access 토큰을 queryParam(tokenTarget 속성으로 정의되는 쿼리 매개 변수 이름)으로 삽입해야 함을 나타냅니다. 예를 들어 tokenTarget이 myQueryParam이면 작업 호출의 URL은 <url>?myQueryParam=<액세스 토큰> 이 됩니다.
-
tokenInResponse: 인증 호출에서 액세스 토큰을 추출하는 방법을 나타냅니다. 이 속성은 다음 중 하나일 수 있습니다.
- 'response': HTTP 응답이 액세스 토큰임을 나타냅니다.
- json의 선택기. 응답이 json이면 XML 등의 기타 형식은 지원되지 않습니다. 이 선택기의 형식은 json://<액세스 토큰 속성의 여정> 입니다. 예를 들어 호출의 응답이 { "access_token": "theToken", "timestamp": 12323445656 } 이면 tokenInResponse는 json: //access_token 이 됩니다.
이 인증의 형식은 다음과 같습니다.
{
"type": "customAuthorization",
"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'>",
"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" 매개 변수에서 정의됩니다. 캐시에서 생성된 토큰의 보존 기간을 지정합니다. 단위는 밀리초, 초, 분, 시간, 일, 개월, 년일 수 있습니다.
"authentication": {
"type":"customAuthorization",
"authorizationType":"Bearer",
"endpoint":"http://localhost:${port}/epsilon/oauth2/access_token",
"method":"POST",
"headers": {
"Authorization":"Basic EncodeBase64(${epsilonClientId}:${epsilonClientSecret})"
},
"body": {
"bodyType":"form",
"bodyParams": {
"scope":"cn mail givenname uid employeeNumber",
"grant_type":"password",
"username":"${epsilonUserName}",
"password":"${epsilonUserPassword}"
}
},
"tokenInResponse":"json://access_token",
"cacheDuration":
{ "duration":5, "timeUnit":"seconds" }
}