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

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

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

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

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

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

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

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

  • 공식 표기법: ${변수}

    변수가 null이면 형식 표기법은 변수 이름을 출력합니다.

  • 묵음 공식 표기법: $!{변하기 쉬운}

    변수가 null인 경우 자동 표기법은 빈 문자열을 출력합니다.

수학 라이브러리

접두사: 수학

이러한 수학 매크로를 사용하여 기본 수학 연산을 수행합니다. 자세한 내용은 클래스 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} 찾기

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

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