REST 웹 서비스 활동 작성

릴리스 버전: Zurich

업데이트 날짜 2025년 07월 31일

소요 시간: 13분

다음 절차에 따라 사용자 지정 REST 웹 서비스 오케스트레이션 활동을 작성하십시오.

시작하기 전에

필요한 역할: web_service_admin, activity_admin, activity_creator

이 태스크 정보

REST 웹 서비스 워크플로우 활동을 작성하고 사용하려면

적절한 메시지가 아직 구성되지 않은 경우 REST 메시지를 생성합니다 .
사용자 지정 REST 활동을 만들거나 편집해야 하는 사용자에게 web_service_admin 역할을 할당합니다.
이 활동에 대한 애플리케이션 또는 애플리케이션 범위를 결정합니다.
활동에 사용할 REST 메시지 작성 을 결정합니다. 이 값을 사용하여 REST 메시지에 구성된 엔드포인트를 재정의합니다.
필요한 경우 기본 인증 자격 증명을 생성합니다. 이 값을 사용하여 SOAP 메시지에 구성된 자격 증명을 재정의합니다.

프로시저

사용자 지정 활동을 생성합니다.
이 작업은 템플릿을 사용하여 사용자 지정 활동을 생성합니다.

일반 속성을 설정하고 입력 변수를 만든 후 REST 웹 서비스 실행 명령을 구성합니다.

옵션	설명
입력 변수를 매핑합니다.	만든 변수를 사용하여 오케스트레이션에서 실행하는 명령을 구성합니다.
REST 메시지	이 활동에 사용할 기존 REST 메시지의 이름입니다.
REST 메시지 함수	이 활동에 사용할 REST 메시지 함수입니다.
엔드포인트	이 활동에서 사용하는 REST 웹 서비스의 엔드포인트 URL입니다. REST 메시지에 구성된 엔드포인트를 재정의하려면 이 필드에 엔드포인트를 입력합니다. 잠금을 클릭하여 입력 필드를 엽니다.
변수 치환	REST 엔드포인트에 전달할 이름-값 쌍입니다. 이러한 매개변수를 수동으로 생성하거나 입력 변수를 매개변수 필드로 끌어온 다음 값을 할당할 수 있습니다. ${}을(를) 사용하는 REST 메시지에 정의된 매개변수는 이 활동 템플릿의 데이터를 할당할 수 있습니다. 추가 속성 열을 사용하여 텍스트를 이스케이프하지 않도록 시스템을 구성합니다. 기본적으로 REST 메시지로 전송된 텍스트는 이스케이프됩니다. 사용자가 REST 메시지의 아웃바운드 REST 메시지에서 변수 대체 를 사용하여 변수를 제공한 경우 이름 열이 자동으로 채워집니다.
추가 헤더	선택한 REST 메시지에 대한 추가 HTTP 헤더 매개변수입니다. 이러한 값을 사용하여 REST 메시지에서 상속된 매개변수를 재정의할 수도 있습니다.
추가 쿼리 매개변수	선택한 REST 메시지에 대한 추가 쿼리 매개변수입니다. 이러한 값을 사용하여 REST 메시지에서 상속된 매개변수를 재정의할 수도 있습니다.
MID 서버 사용	REST 웹 서비스를 호출하는 데 MID 서버를 사용해야 하는지 여부를 결정하는 확인란입니다. 주: REST 웹 서비스 메시지 함수가 MID 서버를 정의하는 경우 여기에서 선택한 MID 서버 대신 해당 MID 서버가 사용됩니다.
필요한 MID 서버 역량	REST 엔드포인트에 연결하기 위한 적절한 MID 서버 역량 을 갖춘 MID 서버. 기본적으로 시스템은 REST 기능이 있는 MID 서버를 선택합니다. MID 서버 사용 확인란을 선택한 경우 이 필드를 사용할 수 있습니다.
시간 제한	시간이 초과되기 전에 REST 웹 서비스 요청의 허용 기간(초)입니다. 기본값은 10입니다.
인증	엔드포인트에 필요한 인증 유형을 결정합니다. 옵션은 다음과 같습니다. REST 메시지의 기존 자격 증명 사용: REST 메시지 정의의 자격 증명 정의를 사용합니다. 기본 인증 자격 증명으로 재정의: 아웃바운드 SOAP 자격 증명에 기본 인증 사용을 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. 기본 인증 자격 증명을 프로비저닝해야 선택할 수 있습니다. 인증서 인증 자격 증명으로 재정의: 개인 키와 같은 인증서를 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. 기본 및 인증 인증 자격 증명으로 재정의: 기본 인증과 인증서 인증을 모두 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. OAuth 인증 자격 증명으로 재정의: OAuth 2.0 자격 증명을 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. 이 활동에 대해 선택된 REST 메시지에는 OAuth 2.0 학습서 - OAuth 2.0으로 설정된 REST 메시지 작성과 적절하게 구성된 OAuth 프로파일 및 범위가 있어야 합니다.
자격 증명	REST 엔드포인트 기본 인증 자격 증명이 필요합니다. 이 필드는 인증 필드에서 기본 인증 자격 증명으로 재정의를 선택한 경우에 사용할 수 있습니다. 인스턴스에 저장된 자격 증명과 외부 저장소 시스템의 자격 증명 ID를 포함하는 기본 인증 자격 증명만 선택 목록에 나타납니다. CyberArk 금고에 저장된 자격 증명을 사용하는 경우 MID 서버 구성 파일에 정의된 기본 금고를 무효화할 수 있습니다. 자세한 내용은 CyberArk에 대한 MID 서버 구성의 내용을 참조하십시오. 다른 금고의 이름을 콜론으로 구분된 자격 증명 ID에 접두사로 추가합니다. 예를 들어, newsafe:orch-test-f5을(를) 선택합니다.
프로토콜 프로파일	사용할 인증서 인증입니다. 이 필드는 인증의 선택 항목이 인증 인증 자격 증명으로 재정의 또는 기본 및 인증 인증 자격 증명으로 재정의되는 경우에 사용할 수 있습니다.
OAuth 프로파일	이 REST 메시지의 OAuth 제공자 프로파일입니다. 자세한 내용은 OAuth 프로파일 지정을 참조하세요.

주:

테스트 페이로드의 매개변수 값을 출력 탭의 변수에 자동으로 매핑할 수 있습니다. 자동 매핑 출력 변수의 내용을 참조하십시오.

다음에 수행할 작업

출력 변수를 작성하거나, 구문 분석 규칙을 작성하거나, 조건을 작성하여 REST 웹 서비스 활동 작성을 마칩니다. 템플릿 옵션을 알아보려면 사용자 지정 활동 생성 주제를 참조하십시오.

REST 활동 출력 변수 자동 매핑

활동 디자이너를 ServiceNow 사용하면 REST 테스트 페이로드의 매개변수 값을 출력 단계의 변수에 자동으로 매핑할 수 있습니다.

시작하기 전에

필요한 역할: web_service_admin, activity_admin, activity_creator

이 태스크 정보

주:

오케스트레이션이 엔드포인트에 연결하고 데이터를 반환할 수 있도록 충분한 정보를 제공했다면 활동 디자이너의 모든 스테이지에서 입력 변수를 테스트할 수 있습니다. 일반적으로 명령 실행 단계는 입력을 테스트할 준비가 되는 시점입니다.

프로시저

활동 디자이너에서 명령 실행 단계로 진행합니다.
요청 시 적절한 MID 서버를 정의합니다.
MID 서버를 찾을 수 없거나 대상에 연결할 수 없는 경우 테스트가 실패합니다.
테스트 활동을 클릭하여 입력 매개변수를 테스트합니다.
매개변수와 필드에 실제 값을 추가한 경우 시스템은 지정된 대상에 대해 해당 값을 실행하고 결과 페이로드를 반환합니다. 입력 변수를 필드와 매개변수에 매핑한 경우, 시스템은 해당 변수에 테스트 값을 할당하기 위한 대화 상자를 표시합니다.
요청 시 테스트 값을 제공하고 확인을 클릭하여 페이로드를 표시합니다.
전체 페이로드가 응답 양식의 원시 출력 탭에 나타납니다.
이러한 자동 매핑 옵션 중 하나를 선택합니다.
- 로컬에 자동 매핑: 활동 내에서 사용할 로컬 변수에 값을 직접 매핑합니다.
- 출력에 자동 매핑: 값을 출력 변수에 직접 매핑하여 워크플로우의 다른 활동에 전달합니다. 출력 변수에 대한 자동 매핑은 각각 쿼리 결과의 열 이름을 포함하는 객체 배열을 생성합니다.

REST 템플릿 실행 매개변수

실행 매개변수를 사용하여 활동 디자이너의 전처리 양식에서 입력 프로세스 스크립트를 생성합니다.

REST 웹 서비스 명령 필드에 대한 설명은 문서를 참조하십시오 REST 실행 명령 구성.

주:

이 테이블의 모든 변수에 executionParam. 접두사를 사용해야 합니다.

표 1. REST 템플릿 실행 매개변수
이름	변수	유형	사용법
웹 서비스 메시지	web_service_message	참조	해당 웹 서비스 메시지의 sys_id입니다.
웹 서비스 메시지 기능	web_service_message_function	참조	REST 메시지 함수의 sys_id입니다.
웹 서비스 엔드포인트	web_service_endpoint	문자열	REST 엔드포인트의 URL입니다.
매개변수	parameters	JavaScript 객체의 배열	`executionParam.` 접두사로 표현되는 JavaScript 객체의 배열입니다. 이 매개 변수를 사용하여 배열을 만드는 방법은 다음 문서를 참조하십시오 REST 템플릿에 JavaScript 배열 만들기.
MID 서버 사용	use_mid_server	부울	MID 서버를 사용할지 여부를 선택합니다. true 값은 MID 서버를 사용하고 false 값은 MID 서버를 사용하지 않습니다.
MID 역량	MID 역량	문자열(쉼표로 구분)	필수 MID 서버 역량에 대한 참조 목록입니다.
시간 제한	시간 제한	문자열	허용 제한 시간(초)입니다.
ValueCapabilities	값 역량	해시 맵 배열	MID 서버를 선택하는 데 사용되는 역량 값입니다. 자세한 내용은 MID 서버 기능을 참조하십시오. 값별로 할당되는 추가 역량이 있는 경우 다음 예시를 사용하여 MID 서버 선택을 사용자 지정합니다. `var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability);`
인증 유형	인증 유형	부울	사용할 자격 증명의 유형입니다. 선택 항목은 다음과 같습니다. basic_auth_pick_credentials use_existing_credentials
자격 증명	자격 증명	참조	선택한 auth_typebasic_auth_pick_credentials될 때 이 REST 메시지에 사용할 자격 증명을 포함합니다.

REST 템플릿에 JavaScript 배열 만들기

REST 실행 매개변수를 사용하여 JavaScript 배열을 만들기 위한 지침입니다.

시작하기 전에

필요한 역할: web_service_admin, activity_admin, activity_creator

이 태스크 정보

파라미터의 배열에 더 많은 이름-값 쌍을 추가하려면 기존 배열에 값을 추가하십시오.

프로시저

다음 구문을 사용하여 JavaScript 객체를 생성하고 executionParam.parameter 배열에 추가합니다.
```
var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; 
executionParam.parameters.push(newParameter);
```
새 매개변수 JavaScript 객체를 배열에 추가하면 배열에서 이미 사용할 수 있는 요소가 영향을 받지 않습니다.
REST 메시지 매개변수 입력 필드의 추가 속성 열에서 텍스트를 이스케이프 안 함으로 값을 설정해야 합니다.
이 경우 시스템은 값 속성에 지정된 값을 이스케이프하지 않습니다. 이에 대한 예는 다음과 같습니다.
```
var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; 
executionParam.parameters.push(newParameter);
```
주:
additional_attribute 필드의 값이 없음이면 시스템은 값 속성에 지정된 값을 이스케이프합니다. 첫 번째 예제에서는 parameterValue 가 이스케이프됩니다.

REST 템플릿 후처리 매개변수

이러한 매개변수를 사용하여 후처리 스크립트를 생성합니다.

표 2. 활동 디자이너 후처리 매개변수
이름	변수	유형	사용법
상태 코드	status_code	정수	REST 웹 서비스에서 반환된 상태 코드를 포함합니다.
머리글	머리글	JavaScript 객체의 해시맵	웹 서비스에 전달된 헤더 값과 연결된 키 값 쌍의 해시 맵입니다. `executionResult.header[keyName]`을 사용하여 각 값에 액세스할 수 있습니다.
본문	본문	문자열	REST 메시지의 출력을 나타내는 문자열 값을 포함합니다.
오류	오류	문자열	오류가 없는 경우Null을 반환하지 않는 한 REST 웹 서비스에서 오류 문자열을 반환합니다.

REST 실행 명령 구성

생성한 입력 변수를 사용하여 오케스트레이션이 REST 엔드포인트에서 실행하는 명령을 구성합니다.

시작하기 전에

명령 실행 단계로 진행하기 전에 입력 양식에 필요한 입력 변수를 생성합니다.

필요한 역할: web_service_admin, activity_admin, activity_creator

주:

워크플로우 컨텍스트에서 기능을 실행하지 않고도 MID 서버와 엔드포인트 간의 REST 연결을 테스트할 수 있습니다. 자세한 내용은 테스트 템플릿 출력을 참조하십시오.

프로시저

입력 목록에서 변수를 끌어와 명령 필드에 놓습니다.
시스템은 명령에 적합한 구문으로 변수의 형식을 지정합니다.
그림 1. REST 실행 명령

테이블에 표시된 필드를 모두 채우십시오.

표 3. REST 실행 명령 필드
필드	설명
입력	입력 변수 작성기입니다. 입력 변수 생성 사용 가능한 필드에 매핑합니다.
REST 메시지	이 활동에 사용할 기존 REST 메시지의 이름입니다. 이 필드를 구성하려면 사용자에게 web_service_admin 역할이 있어야 합니다.
REST 메시지 함수	이 활동에 사용할 REST 메시지 함수입니다. 이 필드를 구성하려면 사용자에게 web_service_admin 역할이 있어야 합니다.
엔드포인트	이 활동에서 사용하는 REST 웹 서비스의 엔드포인트 URL입니다. REST 메시지에 구성된 엔드포인트를 재정의하려면 이 필드에 엔드포인트를 입력합니다. 잠금을 클릭하여 입력 필드를 엽니다.
변수 치환	REST 엔드포인트에 전달할 이름-값 쌍입니다. 이러한 매개변수를 수동으로 생성하거나 입력 변수를 매개변수 필드로 끌어서 놓은 다음 값을 할당할 수 있습니다. ${}을(를) 사용하는 REST 메시지에 정의된 매개변수는 이 활동 템플릿의 데이터를 할당할 수 있습니다. 추가 속성 열을 사용하여 텍스트를 이스케이프하지 않도록 시스템을 구성합니다. 기본적으로 REST 메시지로 전송된 텍스트는 이스케이프됩니다. 사용자가 REST 메시지의 아웃바운드 REST 메시지에서 변수 대체를 사용하여 변수를 제공한 경우 이름 열이 자동으로 채워집니다.
추가 헤더	선택한 REST 메시지에 대한 추가 HTTP 헤더 매개변수입니다. 이러한 값을 사용하여 REST 메시지에서 상속된 매개변수를 재정의할 수도 있습니다.
추가 쿼리 매개변수	선택한 REST 메시지에 대한 추가 쿼리 매개변수입니다. 이러한 값을 사용하여 REST 메시지에서 상속된 매개변수를 재정의할 수도 있습니다.
MID 서버 사용	REST 웹 서비스를 호출하는 데 MID 서버를 사용해야 하는지 여부를 결정하는 확인란입니다. 주: REST 웹 서비스 메시지 함수가 MID 서버를 정의하는 경우 여기에서 선택한 MID 서버 대신 해당 MID 서버가 사용됩니다.
필요한 MID 서버 역량	REST 엔드포인트에 연결하기 위한 적절한 MID 서버 역량 을 갖춘 MID 서버. 기본적으로 시스템은 REST 기능이 있는 MID 서버를 선택합니다. MID 서버 사용 확인란을 선택한 경우 이 필드를 사용할 수 있습니다.
시간 제한	시간이 초과되기 전에 REST 웹 서비스 요청의 허용 기간(초)입니다. 기본값은 10입니다.
인증	엔드포인트에 필요한 인증 유형을 결정합니다. 옵션은 다음과 같습니다. REST 메시지의 기존 자격 증명 사용: REST 메시지 정의의 자격 증명 정의를 사용합니다. 기본 인증 자격 증명으로 재정의: 아웃바운드 SOAP 자격 증명에 기본 인증 사용을 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. 기본 인증 자격 증명을 프로비저닝해야 선택할 수 있습니다. 인증서 인증 자격 증명으로 재정의: 개인 키와 같은 인증서를 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. 기본 및 인증 인증 자격 증명으로 재정의: 기본 인증과 인증서 인증을 모두 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. OAuth 인증 자격 증명으로 재정의: OAuth 2.0 자격 증명을 사용하여 REST 메시지 정의의 자격 증명을 재정의합니다. 이 활동에 대해 선택된 REST 메시지에는 OAuth 2.0 학습서 - OAuth 2.0으로 설정된 REST 메시지 작성과 적절하게 구성된 OAuth 프로파일 및 범위가 있어야 합니다.
자격 증명	REST 엔드포인트 기본 인증 자격 증명이 필요합니다. 이 필드는 인증 필드에서 기본 인증 자격 증명으로 재정의를 선택한 경우에 사용할 수 있습니다. 인스턴스에 저장된 자격 증명과 외부 저장소 시스템의 자격 증명 ID를 포함하는 기본 인증 자격 증명만 선택 목록에 나타납니다. CyberArk 금고에 저장된 자격 증명을 사용하는 경우 다른 금고의 이름을 자격 증명 ID에 프리픽스로 추가하고 콜론으로 구분하여 MID 서버 구성 파일에 정의된 CyberArk에 대한 MID 서버 구성을 재정의할 수 있습니다. 예를 들어, newsafe:orch-test-f5을(를) 선택합니다.
프로토콜 프로파일	사용할 인증서 인증입니다. 이 필드는 인증 필드의 선택 항목이 인증서 인증 자격 증명으로 재정의 또는 기본 및 인증 인증 자격 증명으로 재정의인 경우에 사용할 수 있습니다.
OAuth 프로파일	이 REST 메시지의 OAuth 제공자 프로파일입니다. 자세한 내용은 OAuth 프로파일 지정을 참조하세요.

저장을 클릭합니다.
계속을 클릭하여 출력 단계로 이동합니다.