외부 데이터 소스 external-data-sources
외부 데이터 소스를 사용하면 서드파티 시스템에 대한 연결을 정의할 수 있습니다. 호텔 예약 시스템을 사용하여 특정인의 객실 투숙 여부를 확인하는 경우를 예로 들 수 있습니다. 기본 제공 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)가 포함되어 있습니다.
새 외부 데이터 소스를 만들고 구성하는 주요 단계는 다음과 같습니다.
-
데이터 원본 목록에서 데이터 Source 만들기 를 클릭하여 새 외부 데이터 원본을 만듭니다.
화면 오른쪽에 데이터 소스 구성 창이 열립니다.
-
데이터 소스의 이름을 입력합니다.
note note NOTE 영숫자와 밑줄만 허용됩니다. 최대 길이는 30자입니다. -
원하는 경우 데이터 소스에 이벤트에 설명을 추가합니다.
-
외부 서비스의 URL을 추가합니다. 이 예제에서는 https://api.adobeweather.org/weather 를 추가합니다.
note caution CAUTION 보안상 HTTPS를 사용하는 것이 좋습니다. 또한 공개적으로 제공되지 않는 Adobe 주소 및 IP 주소는 사용할 수 없습니다. 
-
외부 서비스 구성에 따라 인증을 구성합니다. 인증 없음, 기본, 사용자 지정 또는 API 키.
기본 인증 모드의 경우 사용자 이름과 암호를 입력해야 합니다.
note note NOTE 인증 호출이 수행되면 base64로 인코딩된 <username>:<password>문자열이 Authentication 헤더에 추가됩니다.사용자 지정 인증 모드에 대한 자세한 내용은 이 섹션을 참조하십시오. 이 예제에서는 API 키 인증 모드를 선택합니다.
- 유형: "API 키"
- 이름: "appid"(API 키 매개 변수 이름)
- 값: "1234"(API 키의 값)
- 위치: "쿼리 매개 변수"(API 키가 URL에 있음)
-
새 필드 그룹 추가 를 클릭하여 각 API 매개 변수 집합에 대한 새 필드 그룹을 추가합니다. 필드 그룹 이름에는 영숫자와 밑줄만 허용됩니다. 최대 길이는 30자입니다. 이 예제에서는 각 매개 변수 세트(city, long/lat)용으로 하나씩 두 개의 필드 그룹을 만들어야 합니다.
"long/lat" 매개 변수 세트의 경우 다음 정보를 사용하여 필드 그룹을 만듭니다.
-
다음에서 사용: 필드 그룹을 사용하는 여정 수를 표시합니다. 여정 보기 아이콘을 클릭하여 이 필드 그룹을 사용하는 여정 목록을 표시할 수 있습니다.
-
메서드: POST 또는 GET 메서드를 선택합니다. 여기서는 GET 메서드를 선택합니다.
-
동적 값: 각 매개 변수를 쉼표로 구분하여 입력합니다. 이 예제에서는 "long,lat"를 입력합니다. 매개 변수 값은 실행 컨텍스트에 따라 달라지므로 여정에서 정의됩니다. 자세히 알아보기
-
응답 페이로드: 페이로드 필드 내부를 클릭하고 호출에서 반환된 페이로드의 예제를 붙여 넣습니다. 이 예제에서는 날씨 API 웹 사이트의 페이로드를 사용했습니다. 필드 유형이 올바른지 확인합니다. API를 호출할 때마다 시스템은 페이로드 예제에 포함된 모든 필드를 검색합니다. 현재 전달된 페이로드를 변경하려는 경우 새 페이로드 붙여넣기 를 클릭할 수 있습니다.
-
페이로드 전송됨: 이 예제에서는 이 필드가 표시되지 않습니다. POST 메서드를 선택해야 이 필드를 사용할 수 있습니다. 서드파티 시스템으로 전송할 페이로드를 붙여넣습니다.
매개 변수가 필요한 GET 호출의 경우 동적 값 필드에 매개 변수를 입력하면 호출 끝에 매개 변수가 자동으로 추가됩니다. POST 호출의 경우에는 다음을 수행해야 합니다.
-
호출 시 전달할 매개 변수의 목록을 동적 값 필드에 포함합니다. 아래 예제에서는 매개 변수가 "identifier"입니다.
-
전송되는 페이로드 본문에서도 정확히 동일한 구문을 사용하여 매개 변수를 지정합니다. 이렇게 하려면 "param": "매개 변수의 이름"(아래 예제에서는 "identifier")을 추가해야 합니다. 아래 구문을 따르십시오.
code language-none {"id":{"param":"identifier"}}
저장 을 클릭합니다.
이제 데이터 소스가 구성되었으며 여정에서 사용할 수 있는 상태가 되었습니다. 예를 들어 조건이나 이메일 개인화 등에 데이터 소스를 사용할 수 있습니다. 가령 기온이 섭씨 30도를 넘으면 특정 메시지를 보내도록 지정할 수 있습니다.
사용자 정의 인증 모드 custom-authentication-mode
이 인증 모드는 작업의 실제 HTTP 요청에 삽입할 액세스 토큰을 검색하기 위한 복잡한 인증(대개 OAuth2 등의 API 래핑 프로토콜을 호출하는 데 사용됨)에 사용됩니다.
사용자 지정 인증을 구성할 때는 아래 버튼을 클릭하여 사용자 지정 인증 페이로드가 올바르게 구성되어 있는지 확인할 수 있습니다.
테스트가 정상적으로 완료되면 버튼이 녹색으로 바뀝니다.
이 인증을 사용할 때는 작업이 다음의 두 단계로 실행됩니다.
- 끝점을 호출하여 액세스 토큰을 생성합니다.
- 올바른 방식으로 액세스 토큰을 삽입하여 REST API를 호출합니다.
액세스 토큰을 생성하기 위해 호출할 끝점의 정의 custom-authentication-endpoint
-
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 요청에 액세스 토큰을 삽입해야 하는 방식의 정의 custom-authentication-access-token
-
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",
"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'>",
}
사용자 지정 인증 데이터 소스에 대해 토큰의 캐시 기간을 변경할 수 있습니다. 아래는 사용자 지정 인증 페이로드의 예입니다. 캐시 기간은 "cacheDuration" 매개 변수에서 정의됩니다. 캐시에서 생성된 토큰의 보존 기간을 지정합니다. 단위는 밀리초, 초, 분, 시간, 일, 개월, 년일 수 있습니다.
다음은 전달자 인증 유형의 예입니다.
{
"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"
}
}
}
다음은 헤더 인증 유형의 예입니다.
{
"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"
}
}
다음은 로그인 API 호출의 응답의 예입니다.
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}