데이터 작업을 위한 속도 매크로

참고: 이 문서는 AWS Lambda, Genesys Cloud, Google, Microsoft Dynamics 365, Salesforce, 웹 서비스 및 Zendesk 데이터 작업 통합에 적용됩니다.

데이터 작업 통합을 통해 사용자 지정 작업을 만들 수 있습니다. 이러한 사용자 지정 작업에는 Velocity 템플릿 언어를 사용하는 템플릿이 있는 요청 구성 및 응답 구성이 포함됩니다. 이러한 템플릿은 다양한 Velocity 매크로를 지원합니다.

주의: 내에서 입력 또는 출력 변수의 사용을 피하십시오. 요청 템플릿, 성공템플릿, 또는 요청 URL 템플릿. 특수 문자로 변수를 적절히 이스케이프하지 않으면 데이터 작업이 실행되지 않습니다.

사용 esc.json인코드 JSON 본문 내부의 문자열을 이스케이프합니다. 보다 esc.json인코드 .
사용 esc.url() 또는 urlTool.ionalQueryParam() 경로 또는 쿼리 매개변수를 이스케이프하려면 requestUrlTemplate 또는 요청 템플릿 사용하는 경우 x-www.form-urlencoded 가치. 보다 문자열 이스케이프 라이브러리 그리고 데이터 작업을 위한 URL 양식 인코딩 .

속도 템플릿은 다음 필드에 유효합니다.

요청 URL 템플릿
헤더
요청 템플릿
성공템플릿

자세한 내용은 사용자 지정 작업 만들기, 구성 요청, 그리고 응답 구성.

참고: 형식 대 무음 형식 표기법

공식 표기법: ${변수}
변수가 null이면 형식 표기법은 변수 이름을 출력합니다.
묵음 공식 표기법: $!{변하기 쉬운}
변수가 null인 경우 자동 표기법은 빈 문자열을 출력합니다.

수학 라이브러리
문자열 이스케이프 라이브러리
인코딩.base64
esc.json인코드
esc.json디코드
successTemplateUtils.firstFromArray
successTemplateUtils.moveKeysIntoArrayOfObjects
urlTool.OptionalQueryParam
자바 문자열 메소드 매크로
Microsoft Dynamics 365
Salesforce 매크로

수학 라이브러리

접두사: 수학

이러한 수학 매크로를 사용하여 기본 수학 연산을 수행합니다. 자세한 내용은 클래스 MathTool 속도 문서에서.

문자열 이스케이프 라이브러리

접두사: ESC

EscapeTool을 사용하여 Velocity 템플릿에서 문자열을 이스케이프합니다. EscapeTool은 Java, JSON, JavaScript, HTML, XML 및 SQL에 대한 출력을 이스케이프하는 방법을 제공합니다. EscapeTool은 Velocity Template Language 문자를 이스케이프하는 방법도 제공합니다. 자세한 내용은 클래스 탈출 도구 속도 문서에서.

특히 다음 방법이 매우 유용합니다.

$esc.urlFormEncode() : URL 양식 코딩 규칙을 준수하기 위해 문자를 이스케이프하려면 이 방법을 사용하십시오. 이 방법에서는 공백이 "+"로 인코딩됩니다. urlTemplate에는 사용되지 않을 가능성이 높습니다. 참조 $esc.uriEncode() 방법.
$esc.url(): 별칭 $esc.urlFormEncode() 동일한 기능을 가지고 있습니다.
$esc.uriEncode() : URI(예: URL) 규칙을 준수하기 위해 문자를 이스케이프하려면 이 메서드를 사용합니다. 이 메소드는 urlTemplate의 문자를 이스케이프하는 데 사용해야 합니다. 이 방법을 사용하면 공백이 '%20'으로 인코딩됩니다.
$esc.jsonEncode() : 출력에서 JSON의 예약 문자를 이스케이프하려면 이 방법을 사용하십시오. JSON을 문자열 형식으로 저장할 수 있습니다.
$esc.jsonString() : 별칭 $esc.jsonEncode() 동일한 기능을 가지고 있습니다.
$esc.jsonDecode() : 이 방법을 사용하여 JSON의 예약 문자를 이스케이프 해제하여 원본 JSON을 생성합니다.
$esc.d(): 달러 기호($)를 포함하려면 이 방법을 사용합니다.

다음 표는 다양한 매크로의 입력 및 출력 예를 보여줍니다.

주의: JavaScript 인코딩을 사용하지 마십시오. $esc.javascript($입력) 작업을 중단하는 잘못된 JSON을 만들 수 있습니다.

매크로	입력	출력
$esc.java($입력)	그는 하지 않았다`'`말, `"`중지!`"`	그는 하지 않았다`'`t 말, \`"`중지!\`"`
$esc.html($입력)	`"`빵`"` & `"`버터`"`	"빵" & "버터"
$esc.xml($입력)	`"`빵`"` & `"`버터`"`	"빵" & "버터"
$esc.sql($입력)	맥헤일`'`s 네이비	맥헤일`''`s 네이비
$esc.urlFormEncode($input) 또는 $esc.url($input)	여기 저기 안녕~	안녕하세요+여기+%26+저기~
$esc.uriEncode($input)	여기 저기 안녕~	안녕하세요%20여기%20%26%20여기%7E
$esc.dollar	—	$
$esc.hash		#
$esc.backslash		\
$esc.quote		`"`
$esc.singleQuote		`'`
$esc.exclamation		!

인코딩.base64

Base64는 제공한 문자열을 인코딩합니다.

템플릿 이름

The encoded field is $encoding.base64(\"${first} and ${second}\")

템플릿 예시 결과

입력	해결된 템플릿
첫 번째 == 고양이 두 번째 == 개	인코딩된 필드는 Y2F0IGFuZCBkb2c=입니다.

esc.json인코드

POST, PUT 및 PATH 요청에 대한 JSON 본문을 작성할 때 모든 문자열에서 예약된 문자를 이스케이프해야 합니다. 이 매크로는 JSON 인코딩 규칙에 따라 따옴표 및 기타 문자를 이스케이프합니다.

메모 : esc.json인코드 유니코드 문자를 다음과 다르게 처리합니다. EscapeTool.javascript() 하다.

템플릿 이름

$esc.jsonEncode(${input.json})

인코딩 예시

입력	출력
{ “foo”:”바” }	{\n\t\”foo\”:\”바\”\n}
Null	Null
“”(빈 문자열)	“”(빈 문자열)

esc.json디코드

JSON으로 인코딩된 문자열이 있고 이를 JSON 형식으로 사용하려는 경우 다음을 사용할 수 있습니다. esc.json디코드() 매크로. 이 매크로는 JSON 인코딩 규칙을 기반으로 따옴표 및 기타 문자를 이스케이프 해제합니다.

템플릿 이름

$esc.jsonDecode(${input.escapedjson})

디코딩 예시

입력	출력
{\n\t\”foo\”:\”바\”\n}	{ “foo”:”바” }

successTemplateUtils.firstFromArray

이 매크로는 제공된 JSON 배열 문자열에서 첫 번째 요소를 추출하고 두 개의 매개변수가 있습니다. 추출된 값의 입력 배열인 첫 번째 매개변수가 필요합니다. 배열이 비어 있을 때 반환되는 응답을 지정하는 두 번째 매개변수는 선택 사항이며 기본적으로 아무 것도 반환하지 않습니다. 배열이 비어 있지 않으면 두 번째 매개변수는 무시됩니다.

에 대한 입력의 경우 처음부터배열 TranslationMap JSONPath를 통해 추출된 데이터이므로 문자열 이스케이프가 필요하지 않습니다. 다음 템플릿 예제에서는 아이디 다음과 같은 translationMap 항목에서 올 수 있습니다. "아이디": "$.idArray".

템플릿 예 및 결과

템플릿 예시	입력	해결된 템플릿
${successTemplateUtils.firstFromArray(`"`${ids}`"`)}	아이디 == `"`[1, 2, 3]`"`	1
	아이디 == `"`[{\`"`ID\`"`:1}, {\`"`ID\`"`:2}, {\`"`ID\`"`:삼}, {\`"`ID\`"`:4}]`"`	{\`"`ID\`"`:1}
	아이디 == `"`[]`"`
	아이디 == `""`	이 입력은 오류를 발생시킵니다.
${successTemplateUtils.firstFromArray(\`"`${ID}\`"`, \`"`{}\`"`)}	아이디 == `"`[1, 2, 3]`"`	1
	아이디 == `"`[{\`"`ID\`"`:1}, {\`"`ID\`"`:2}, {\`"`ID\`"`:삼}, {\`"`ID\`"`:4}]`"`	{\`"`ID\`"`:1}
	아이디 == `"`[]`"`	{}
	아이디 == `""`	이 입력은 오류를 발생시킵니다.
${successTemplateUtils.firstFromArray(\`"`${ID}\`"`, \`"`$esc.quote $esc.quote\`"`)}*	아이디 == `"`[1, 2, 3]`"`	1
	아이디 == `"`[{\`"`ID\`"`:1}, {\`"`ID\`"`:2}, {\`"`ID\`"`:삼}, {\`"`ID\`"`:4}]`"`	{\`"`ID\`"`:1}
	아이디 == `"`[]`"`	`""`
	아이디 == `""`	이 입력은 오류를 발생시킵니다.

* 이 템플릿 예제는 EscapeTool을 사용하여 문자를 이스케이프합니다. 자세한 내용은 문자열 이스케이프 라이브러리.

successTemplateUtils.moveKeysIntoArrayOfObjects

이 매크로는 데이터를 Architect와 호환되고 두 개의 필수 매개변수가 있는 형식으로 변환합니다. 첫 번째 매개변수는 원래 응답의 입력입니다. 두 번째 매개변수는 매크로가 개체에 추가하는 키 이름이고 값은 원래 응답의 동적 필드입니다.

참고: 매크로가 데이터를 변환할 수 없는 경우 데이터 작업은 오류 또는 빈 배열을 반환합니다.

변환된 데이터를 반환하려면 다음을 구성하십시오. 번역지도 그리고 성공템플릿 다음 예를 기반으로 데이터 작업에서.

데이터 작업 예

"config": {
  "request": {
    "requestUrlTemplate": "https://some.website.com/with/normalized/data",
    "requestType": "GET",
    "headers": {
    },
    "requestTemplateDefault": true
  },
  "response": {
    "translationMap": {
      "entitySegmentMembershipUps": "$.*.path.to.dynamic.key"
    },
    "translationMapDefaults": {},
    "successTemplate": "{\"segments\": ${successTemplateUtils.moveKeysIntoArrayOfObjects(${entitySegmentMembershipUps})},\"segmentId\")}}"
  }
}

원래 답변에서, GUID는 동적 키이고 올바르게 평면화할 수 없기 때문에 액세스할 수 없습니다.

원래 반환된 응답

"segmentMembership": { 
  "ups": { 
    "a959c128-d6d9-4a42-a307-c5d278cfcbe2": { 
      "lastQualificationTime": "2020-11-16T03:23:31Z", 
      "status": "realized" 
    } 
  }
}

매크로는 ID를 개체로 이동하고 다음과 같이 반환합니다. 세그먼트 ID.

매크로 반환 응답

"segments": [
  {
    "lastQualificationTime": "2020-11-16T03:23:31Z",
    "status": "realized",
    "segmentId": "a959c128-d6d9-4a42-a307-c5d278cfcbe2"
  }
]

urlTool.OptionalQueryParam

이 매크로는 값이 비어 있지 않는 한 키-값 쌍을 쿼리 매개변수로 형식화합니다. 그렇지 않으면 매크로가 빈 문자열을 반환합니다. 템플릿에 앰퍼샌드(&)를 포함하지 마십시오. 매크로는 자동으로 앰퍼샌드를 추가합니다. 템플릿 예제 결과를 참조하십시오. 하나 이상의 필수 쿼리 매개변수 뒤에만 매크로를 사용하세요. 다음 템플릿 예에서 필수 쿼리 매개변수는 ${input.AMOUNT}.

참고: 묵음 형식 표기법 사용: $!{변하기 쉬운}.

템플릿 이름

amount=${input.AMOUNT}$urlTool.optionalQueryParam(\"description\", $!{input.DESCRIPTION})

템플릿 예시 결과

입력	해결된 템플릿
입력 금액 == 30 input.DESCRIPTION == 감자	amount=30&description=감자
입력 금액 == 30 입력.설명 == `""`	금액=30

자바 문자열 메소드 매크로

Velocity 템플릿에서 Java 문자열 메서드를 사용하여 값의 대소문자 변경 또는 문자열에서 값 추출과 같은 문자열 변수를 조작합니다. 자세한 내용은 Java 17 문서의 클래스 문자열을 참조하세요.

다음 예에서는 to대문자() 메소드는 변수 $a의 문자열 값을 대문자로 변환합니다. NS 나뉘다() 메소드는 변수 $b를 문자열 배열로 분할합니다. 변수 $d는 변수 $a, 변수 $b 및 변수 $c에 대한 배열의 첫 번째 항목의 값을 연결합니다.

템플릿 이름

#set($a = ${input1.string1} )
#set($a = $a.toUpperCase() )
#set($b = ${input1.string2} )
#set($c = $b.split("\+") )
#set($d = "We are using ""${a}"" ""${b}"" ""$c[1]"" to render this." )
$d

템플릿 예시 결과

입력	해결된 템플릿
input.string1 = 값1 input.string2 = 값1+값2	우리는 사용하고 있습니다 `"`VALUE1`"` `"`값1+값2`"` `"`가치2`"` 이것을 렌더링합니다.

Microsoft Dynamics 365

msdynamics.field검색 필터

이 매크로는 검색하려는 필드 목록과 값이 제공된 검색 필터를 작성합니다. 매크로는 값을 목록의 각 필드와 비교합니다.

템플릿 이름

$msdynamics.fieldSearchFilter(\"$input.EMAIL_ADDRESS\", [\"emailaddress1\", \"emailadress2\"]

템플릿 예시 결과

입력	해결된 템플릿
input.EMAIL_ADDRESS = TestMail@example.com	이메일 주소1 eq `'`TestMail@example.com`'` 또는 이메일 주소2 eq `'`TestMail@example.com`'`

msdynamics.phoneNumberFilter

이 매크로는 전화번호와 검색하려는 필드 목록이 제공된 검색 필터를 만듭니다. 매크로는 전화 번호에서 지원되지 않는 문자와 숫자가 아닌 값(예: + 및 괄호)을 제거하고 각 필드 사이에 "또는"을 추가합니다. 이 검색 필터는 전화번호를 계정 레코드의 여러 전화번호와 비교하는 데 유용합니다.

템플릿 이름

$msdynamics.phoneNumberFilter(\"$input.PHONE_NUMBER\", [\"telephone1\", \"telephone2\"])

템플릿 예시 결과

입력	해결된 템플릿
입력.PHONE_NUMBER = +1 (555) 555-0123	전화1 eq `'`+1 (555) 555-0123`'` 또는 전화2 eq `'`+1 (555) 555-0123`'` 또는 전화1 eq `'`15555550123`'` 또는 전화2 eq `'`15555550123`'`

Salesforce 매크로

Salesforce.esc예약됨

이 매크로는 URL에서 만들어진 Salesforce SOQL/SOSL 쿼리에서 예약된 문자를 이스케이프합니다. Salesforce는 다음 문자를 예약합니다. ? & | ! { } [ ] ( ) ^ ~ * : \ " ' + -. 이 매크로는 문자가 제대로 이스케이프되도록 합니다. 자세한 내용은 {검색 쿼리} 찾기 Salesforce 문서에서.

템플릿 이름

FIND {$salesforce.escReserved(${input.PHONE_NUMBER})} IN PHONE FIELDS

템플릿 예시 결과

입력	해결된 템플릿
입력.PHONE_NUMBER == (555) 555-5555	전화 분야에서 {$555$ 555\-5555} 찾기

자세한 내용은 통합을 위한 사용자 지정 작업 정보.

통합에 대한 자세한 내용은 다음을 참조하십시오. 데이터 작업 통합 정보.