REST 웹 서비스 활동 작성

  • 릴리스 버전: Xanadu
  • 업데이트 날짜 2024년 08월 01일
  • 읽기13분

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

    시작하기 전에

    필요한 역할: web_service_admin, activity_admin, activity_creator

    이 태스크 정보

    REST 웹 서비스 워크플로우 활동을 만들고 사용하려면 다음을 수행합니다.
    • 적절한 항목이 아직 구성되지 않은 경우 REST 메시지 만들기 를 작성합니다.
    • 사용자 지정 REST 활동을 만들거나 편집해야 하는 모든 사용자에게 web_service_admin 역할을 할당합니다.
    • 이 활동에 대한 애플리케이션 또는 애플리케이션 범위를 결정합니다.
    • 활동에 사용할 REST 메시지 작성 을 판별하십시오. 이 값을 사용하여 REST 메시지에 구성된 엔드포인트를 재정의합니다.
    • 필요에 따라 기본 인증 자격 증명을 만듭니다. 이 값을 사용하여 SOAP 메시지에 구성된 자격 증명을 무효화합니다.

    프로시저

    1. 사용자 지정 활동을 생성합니다.
      이 작업은 템플릿을 사용하여 사용자 지정 활동을 작성합니다.
    2. 일반 속성을 설정하고 입력 변수를 생성한 후 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

    이 태스크 정보

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

    프로시저

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

    REST 템플릿 실행 매개변수

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

    REST 웹 서비스 명령 필드에 대한 설명은 을 참조하십시오 REST 실행 명령 구성.
    주:
    이 테이블의 모든 변수에 executionParam. 접두사를 사용해야 합니다.
    표 1. REST 템플릿 실행 매개변수
    이름 변수 유형 사용법
    웹 서비스 메시지 web_service_message 참조 해당 웹 서비스 메시지의 sys_id입니다.
    웹 서비스 메시지 기능 web_service_message_function 참조 REST 메시지 함수의 sys_id입니다.
    웹 서비스 끝점 web_service_endpoint 문자열 REST 엔드포인트의 URL입니다.
    매개변수 매개변수 JavaScript 객체의 배열 executionParam으로 표현된 JavaScript 객체의 배열입니다. 접두사입니다. 이 매개 변수를 사용하여 배열을 만드는 방법에 대한 자세한 내용은 을 참조하십시오 REST 템플릿에서 JavaScript 배열 작성.
    MID 서버 사용 use_mid_server 부울 MID 서버를 사용할지 여부를 선택합니다. 예 값은 MID 서버를 사용하고 아니오 값은 MID 서버를 사용하지 않습니다.
    미드역량 midCapabilities 문자열(쉼표로 구분) 필요한 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_type basic_auth_pick_credentials될 때 이 REST 메시지에 사용할 자격 증명을 포함합니다.

    REST 템플릿에서 JavaScript 배열 작성

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

    시작하기 전에

    필요한 역할: web_service_admin, activity_admin, activity_creator

    이 태스크 정보

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

    프로시저

    1. 다음 구문을 사용하여 JavaScript 개체를 만들고 executionParam.parameter 배열에 추가합니다. 
      var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; 
executionParam.parameters.push(newParameter);

      새 매개 변수 JavaScript 개체를 배열에 추가하면 배열에서 이미 사용할 수 있는 모든 요소가 영향을 받지 않습니다.

    2. REST 메시지 매개변수 입력 필드의 추가 속성 열에 있는 값을 텍스트를 이스케이프하지 않음으로 설정해야 합니다.

      이 경우 시스템은 value 속성에 지정된 값을 이스케이프하지 않습니다. 예를 들면 다음과 같습니다.

      var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; 
executionParam.parameters.push(newParameter);
      주:
      additional_attribute 필드의 값이 None이면, 시스템은 value 어트리뷰트에 의해 지정된 값을 이스케이프합니다. 첫 번째 예제에서는 parameterValue 가 이스케이프됩니다.

    REST 템플릿 후처리 매개변수

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

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

    REST 실행 명령 구성

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

    시작하기 전에

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

    필요한 역할: web_service_admin, activity_admin, activity_creator

    주:
    워크플로우 컨텍스트에서 활성화를 실행할 필요 없이 MID 서버와 엔드포인트 간의 REST 연결을 테스트할 수 있습니다. 자세한 내용은 테스트 템플릿 출력을 참조하십시오.

    프로시저

    1. 입력 목록에서 변수를 끌어 명령 필드에 놓습니다.
      시스템은 명령에 적합한 구문으로 변수 형식을 지정합니다.
      그림 1. REST 실행 명령
      REST 실행 명령
    2. 테이블에 표시된 필드를 모두 채우십시오.
      표 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 프로파일 지정을 참조하십시오.
    3. 저장을 클릭합니다.
    4. Continue(계속)를 클릭하여 Outputs(출력) 단계로 이동합니다.