웹 서비스 호출 web-service-calls
일반 정보 general-information
모든 API 메서드는 웹 서비스 형식으로 표시됩니다. 이렇게 하면 Adobe Campaign 애플리케이션 서버의 기본 진입점인 SOAP 호출을 통해 모든 Adobe Campaign 기능을 관리할 수 있습니다. Adobe Campaign 콘솔 자체는 SOAP 호출만 사용합니다.
웹 서비스를 사용하면 서드파티 시스템에서 많은 애플리케이션을 만들 수 있습니다.
- 백오피스 또는 트랜잭션 시스템에서 동기식 경고, 알림 및 실시간 게재 템플릿 실행
- 단순화된 기능(웹 인터페이스 등)을 갖춘 특수 인터페이스 개발
- 거래 규칙을 관찰하고 기본 물리적 모델과 분리된 상태로 데이터베이스에 있는 데이터의 공급 및 조회.
웹 서비스의 정의 definition-of-web-services
Adobe Campaign 애플리케이션 서버에 구현된 웹 서비스의 정의는 데이터 스키마에서 사용할 수 있습니다.
웹 서비스는 데이터 스키마의 문법에 설명되어 있으며 <methods> 요소에서 사용할 수 있습니다.
<methods>
<method name="GenerateForm" static="true">
<help>Generates the form in Mail or Web mode</help>
<parameters>
<param name="formName" type="string" desc="Name of form"/>
<param name="mailMode" type="boolean" desc="Generate a form of type Mail"/>
<param name="result" type="string" inout="out" desc="Result "/>
</parameters>
</method>
</methods>
다음은 GenerateForm 메서드의 정의에 대한 예입니다.
서비스 설명은 <method> 요소로 시작합니다. <parameters> 요소에서 메서드의 매개 변수 목록이 완료되었습니다. 각 매개 변수는 이름, 유형(부울, 문자열, DOMElement 등)으로 지정됩니다. 설명. "out" 값이 있는 "inout" 속성을 사용하면 "result" 매개 변수가 SOAP 호출 출력에 있다고 지정할 수 있습니다.
"static" 속성(값 "true"가 있음)은 이 메서드를 static으로 설명하므로 메서드의 모든 매개 변수를 선언해야 합니다.
"const" 메서드는 암시적으로 연결된 스키마 형식의 XML 문서를 해당 입력으로 가지고 있습니다.
Adobe Campaign 스키마의 <method> 요소에 대한 전체 설명은 메서드의 "스키마 참조" 장에서 확인할 수 있습니다.
"xtk:queryDef" 스키마의 "const" 유형 "ExecuteQuery" 메소드의 예:
<method name="ExecuteQuery" const="true">
<help>Retrieve data from a query</help>
<parameters>
<param desc="Output xml document" name="output" type="DOMDocument" inout="out"/>
</parameters>
</method>
이 메서드의 입력 매개 변수는 "xtk:queryDef" 스키마 형식의 XML 문서입니다.
웹 서비스 설명: WSDL web-service-description--wsdl
WSDL(웹 서비스 설명 라이브러리) 파일은 각 서비스에 사용할 수 있습니다. 이 XML 파일은 금속어를 사용하여 서비스를 설명하고 서비스 실행을 위해 연락할 사용 가능한 메서드, 매개 변수 및 서버를 지정합니다.
WSDL 파일 생성 wsdl-file-generation
WSDL 파일을 생성하려면 웹 브라우저에서 다음 URL을 입력해야 합니다.
https://<server>/nl/jsp/schemawsdl.jsp?schema=<schema>
포함:
<server>: Adobe Campaign 응용 프로그램 서버(nlserver 웹)<schema>: 스키마 식별 키(namespace:schema_name)
스키마 "xtk:queryDef"의 "ExecuteQuery" 메서드에 대한 예 example-on-the--executequery--method-of-schema--xtk-querydef-
WSDL 파일은 URL에서 생성됩니다.
https://localhost/nl/jsp/schemawsdl.jsp?schema=xtk:queryDef
WSDL 설명은 웹 서비스를 구성하는 "바인딩"에 의해 프로토콜에 연결된 "포트"에 연결된 메시지를 구성하는 데 사용되는 형식을 정의함으로써 시작합니다.
유형 types
유형 정의는 XML 스키마를 기반으로 합니다. 이 예제에서 "ExecuteQuery" 메서드는 "s:string" 문자열과 XML 문서(<s:complextype>)를 매개 변수로 사용합니다. 메서드("ExecuteQueryResponse")의 반환 값이 XML 문서(<s:complextype>)입니다.
<types>
<s:schema elementFormDefault="qualified" targetNamespace="urn:xtk:queryDef">
<s:element name="ExecuteQuery">
<s:complexType>
<s:sequence>
<s:element maxOccurs="1" minOccurs="1" name="sessiontoken" type="s:string"/>
<s:element maxOccurs="1" minOccurs="1" name="entity">
<s:complexType>
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
<s:element name="ExecuteQueryResponse">
<s:complexType>
<s:sequence>
<s:element maxOccurs="1" minOccurs="1" name="pdomOutput">
<s:complexType mixed="true">
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
메시지 messages
<message>은(는) 보낼 필드 집합의 이름과 형식을 설명합니다. 메서드는 두 개의 메시지를 사용하여 매개 변수("ExecuteQueryIn")와 반환 값("ExecuteQueryOut")으로 전달합니다.
<message name="ExecuteQueryIn">
<part element="tns:ExecuteQuery" name="parameters"/>
</message>
<message name="ExecuteQueryOut">
<part element="tns:ExecuteQueryResponse" name="parameters"/>
</message>
PortType porttype
<porttype>은(는) 응답("output")을 생성하는 쿼리("input")에 의해 트리거된 "ExecuteQuery" 작업의 메시지를 연결합니다.
<portType name="queryDefMethodsSoap">
<operation name="ExecuteQuery">
<input message="tns:ExecuteQueryIn"/>
<output message="tns:ExecuteQueryOut"/>
</operation>
</portType>
바인딩 binding
<binding> 부분은 SOAP 통신 프로토콜( <soap:binding> ), HTTP의 데이터 전송("전송" 특성 값) 및 "ExecuteQuery" 작업의 데이터 형식을 지정합니다. SOAP Envelope의 본문에는 변형 없이 메시지 세그먼트가 직접 포함됩니다.
<binding name="queryDefMethodsSoap" type="tns:queryDefMethodsSoap">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="ExecuteQuery">
<soap:operation soapAction="xtk:queryDef#ExecuteQuery" style="document"/>
<input>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:xtk:queryDef" use="literal"/>
</input>
<output>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:xtk:queryDef" use="literal"/>
</output>
</operation>
</binding>
서비스 service
<service> 부분은 Adobe Campaign 응용 프로그램 서버의 URL에서 해당 URI를 사용하여 "XtkQueryDef" 서비스를 설명합니다.
<service name="XtkQueryDef">
<port binding="tns:queryDefMethodsSoap" name="queryDefMethodsSoap">
<soap:address location="https://localhost/nl/jsp/soaprouter.jsp"/>
</port>
</service>
연결 connectivity
Adobe Campaign은 보안 영역 및 세션 관리 설정을 도입하여 인증 메커니즘에 대한 보안을 강화했습니다.
두 가지 인증 모드를 사용할 수 있습니다.
- logon 메서드() 호출을 통해. 이 모드는 세션 토큰과 보안 토큰을 생성합니다. 가장 안전한 모드이므로 가장 권장됩니다.
또는
- 세션 토큰을 만드는 Adobe Campaign 로그인 + 암호를 통해. 세션 토큰은 설정된 기간 후에 자동으로 만료됩니다. 이 모드는 권장되지 않으며 일부 영역 설정(allowUserPassword="true" 및 sessionTokenOnly="true")에 대한 응용 프로그램 보안 설정을 줄여야 합니다.
세션 토큰 특성 session-token-characteristics
세션 토큰에는 다음과 같은 특성이 있습니다.
-
X시간 라이프 사이클(라이프 사이클은 'serverConf.xml' 파일에서 구성할 수 있으며 기본 기간은 24시간입니다.)
-
임의 구성(더 이상 사용자 로그인 및 암호가 포함되지 않음)
-
웹을 통해 액세스할 경우:
- 세션 토큰은 영구 토큰이 되며 브라우저가 닫히면 삭제되지 않습니다
- HTTP 전용 쿠키에 배치됩니다(운영자에 대해 쿠키가 활성화되어야 함)
보안 토큰 특성 security-token-characteristics
보안 토큰에는 다음과 같은 특성이 있습니다.
-
세션 토큰에서 생성됩니다.
-
이 파일에는 24시간 수명 주기가 있습니다('serverConf.xml' 파일에서 구성 가능, 기본 기간은 24시간).
-
Adobe Campaign 콘솔에 저장됩니다
-
웹을 통해 액세스할 경우:
- 문서에 저장됩니다.__securityToken 속성
- 보안 토큰을 업데이트하기 위해 페이지 URL이 업데이트됩니다
- 토큰이 포함된 숨겨진 필드를 통해 양식도 업데이트됩니다
보안 토큰 이동 security-token-movement
콘솔을 통해 액세스할 경우 다음과 같은 이점이 있습니다.
- 로그온 응답(HTTP 헤더)에서 전송됨
- 각 쿼리(HTTP 헤더)에 사용됨
POST 및 GET HTTP에서:
- 서버가 토큰으로 링크를 완료합니다.
- 서버가 양식에 숨겨진 필드를 추가합니다.
SOAP 호출에서:
- 호출 헤더에 추가됩니다.
호출 예 call-examples
- HttpSoapConnection/SoapService 사용:
var cnx = new HttpSoapConnection("https://serverURL/nl/jsp/soaprouter.jsp");
var session = new SoapService(cnx, 'urn:xtk:session');
session.addMethod("Logon", "xtk:session#Logon",
["sessiontoken", "string", "Login", "string", "Password", "string", "Parameters", "NLElement"],
["sessionToken", "string", "sessionInfo", "NLElement", "securityToken", "string"]);
var res = session.Logon("", "admin", "pwd", <param/>);
var sessionToken = res[0];
var securityToken = res[2];
cnx.addTokens(sessionToken, securityToken);
var query = new SoapService(cnx, 'urn:xtk:queryDef');
query.addMethod("ExecuteQuery", "xtk:queryDef#ExecuteQuery",
["sessiontoken", "string", "entity", "NLElement"],
["res", "NLElement"]);
var queryRes = query.ExecuteQuery("", <queryDef operation="select" schema="nms:recipient">
<select>
<node expr="@email"/>
<node expr="@lastName"/>
<node expr="@firstName"/>
</select>
<where>
<condition expr="@email = 'joe.doe@aol.com'"/>
</where>
</queryDef>);
logInfo(queryRes[0].toXMLString())
- HttpServletRequest 사용:
로그온 실행():
var req = new HttpClientRequest("https://serverURL/nl/jsp/soaprouter.jsp");
req.header["Content-Type"] = "text/xml; charset=utf-8";
req.header["SOAPAction"] = "xtk:session#Logon";
req.method = "POST";
req.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:session">' +
'<soapenv:Header/>' +
'<soapenv:Body>' +
'<urn:Logon>' +
'<urn:sessiontoken></urn:sessiontoken>' +
'<urn:strLogin>LOGIN_HERE</urn:strLogin>' +
'<urn:strPassword>PASSWORD_HERE</urn:strPassword>' +
'<urn:elemParameters></urn:elemParameters>' +
'</urn:Logon>' +
'</soapenv:Body>' +
'</soapenv:Envelope>';
req.execute();
var resp = req.response;
var xmlRes = new XML(String(resp.body).replace("<?xml version='1.0'?>",""));
var sessionToken = String(xmlRes..*::pstrSessionToken);;
var securityToken = String(xmlRes..*::pstrSecurityToken);
쿼리 실행:
var req2 = new HttpClientRequest("https://serverURL/nl/jsp/soaprouter.jsp");
req2.header["Content-Type"] = "text/xml; charset=utf-8";
req2.header["SOAPAction"] = "xtk:queryDef#ExecuteQuery";req2.header["X-Security-Token"] = securityToken;
req2.header["cookie"] = "__sessiontoken="+sessionToken;
req2.method = "POST";
req2.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:queryDef">' +
'<soapenv:Header/><soapenv:Body><urn:ExecuteQuery><urn:sessiontoken/><urn:entity>' +
'<queryDef operation="select" schema="nms:recipient">' +
'<select><node expr="@email"/><node expr="@lastName"/><node expr="@firstName"/></select>' +
'<where><condition expr="@email = \'john.doe@aol.com\'"/></where>' +
'</queryDef>' +
'</urn:entity></urn:ExecuteQuery></soapenv:Body></soapenv:Envelope>';
req2.execute();
var resp2 = req2.response;
logInfo(resp2.body)