REST Web Services package

API에 요청을 보내고 응답을 받으려면 REST Web Services package의 actions을 메서드(DELETE, GET, PATCH, POST, PUT)로 사용합니다.

설정

REST Web Services actions에 대해 다음 설정을 사용할 수 있습니다. REST 요청을 보내고 응답을 받으려면 적절한 설정을 구성하십시오. 각 메서드에는 특정 매개변수가 필요합니다.

주: macOS 플랫폼에서 자동화를 생성하고 actions(DELETE, GET, PATCH, POST, PUT)을 사용할 경우 다음 인증 모드는 지원되지 않습니다.
  • NTLM 인증(AD 사용자)
  • 로그인한 AD 사용자
URI
API 리소스에 대한 URI를 입력합니다. 다음 옵션 중 하나를 선택하고 그에 따라 설정을 구성하십시오.
  • URI 입력: URI를 직접 입력하거나 문자열 변수로 저장된 URI를 선택합니다.
  • URI로 자격증명 선택: 이 옵션을 사용하여 Credential Vault에 자격증명으로 저장된 URI를 선택합니다. 자격증명 > 선택을 사용하여 자격증명을 직접 선택합니다. 변수 옵션을 사용하여 자격증명 변수에 매핑된 자격증명을 선택할 수도 있습니다. 이 옵션을 사용하면 인증 코드나 API 키와 같은 민감한 정보를 포함하는 URI를 숨길 수 있습니다.
프록시 구성
REST Web Services 작업에 대한 프록시 설정을 구성합니다. 다음 옵션 중 하나를 선택하고 그에 따라 설정을 구성하십시오.
  • 시스템: Bot Agent가 시스템 프록시를 사용하도록 설정하려면 이 옵션을 선택합니다. 시스템 프록시는 자동화가 실행되는 bot Runner 머신에 구성하는 프록시입니다.
  • 사용자 정의: 자동화를 위한 사용자 정의 프록시 설정을 구성하려면 이 옵션을 선택합니다. 다음 설정을 구성합니다.
    • 호스트: 프록시 서버의 호스트 이름 또는 IP 주소.
    • 포트: 프록시 서버의 포트 번호.
    • 사용자 이름(선택 사항): 프록시 서버를 인증하기 위한 사용자 이름.
    • 비밀번호(선택 사항): 프록시 서버를 인증하기 위한 비밀번호.
    주: 인증된 프록시 서버의 경우 사용자 이름 및 비밀번호를 구성해야 합니다.
    자격증명, 변수, 또는 안전하지 않은 문자열 옵션 중 하나를 사용하여 프록시 설정을 구성할 수 있습니다.
    • 자격증명: Credential Vault에서 사용 가능한 값을 선택합니다.
    • 변수: 값에 매핑된 자격증명 변수를 선택합니다.
    • 안전하지 않은 문자열: 값을 수동으로 입력하거나 미리 정의된 문자열 변수에 매핑된 값을 선택합니다.
인증 모드
REST Web Services 작업에 대한 인증 설정을 구성합니다. 다음 옵션 중 하나를 선택하고 그에 따라 설정을 구성하십시오.
  • 인증 없음: 서버에 접근하는 데 인증이 필요하지 않은 엔드포인트에 액세스하려면 이 옵션을 선택합니다.
  • Control Room 사용자 토큰: Control Room에 로그인할 때 생성되는 토큰을 사용하려면 이 옵션을 선택합니다.
  • 기본: 사용자 이름 및 비밀번호를 입력하고 REST Web Services API 호출을 인증하려면 이 옵션을 선택합니다. 이 옵션은 API 호출에 사용자 이름 및 비밀번호를 base64로 인코딩한 문자열 표현을 포함하는 Authorization이라는 헤더를 추가합니다.
  • 로그인한 AD 사용자: AD(Active Directory) 기반 인증을 하려면 이 옵션을 선택합니다. 관련 API에 액세스할 권한이 있는 AD 사용자는 AD를 통해 인증됩니다. 요청에는 자격증명이 필요하지 않습니다.
  • Windows NTLM(NT LAN 관리자) 인증(AD 사용자): 챌린지-응답 NTLM 인증을 하려면 이 옵션을 선택합니다. 다음 설정을 구성합니다.
    • 도메인: API 호출이 인증되어야 하는 도메인을 입력합니다. 도메인 또는 호스트에 매핑된 문자열 변수를 선택할 수도 있습니다.
    • 사용자 이름(선택 사항): API 호출을 인증하기 위한 사용자 이름.
    • 비밀번호(선택 사항): API 호출을 인증하기 위한 비밀번호.
    자격증명, 변수, 또는 안전하지 않은 문자열 옵션 중 하나를 사용하여 사용자 이름과 비밀번호를 구성할 수 있습니다. Credential Vault에서 자격증명을 선택하는 자격증명 옵션을 사용하거나 자격증명 변수를 사용하는 것을 권장합니다.
  • OAuth2 - Control Room 관리: 인증 옵션으로 Control Room에서 관리하는 OAuth 연결을 사용하려면 이 옵션을 선택합니다. 자세한 내용은 Configure OAuth connections in Control Room 항목을 참조하십시오.

    다음 비디오에서 OAuth의 REST Web Services 연결을 사용하는 방법을 확인할 수 있습니다.

헤더
API 요청에 추가 메타데이터를 포함하려면 사용자 정의 헤더를 추가합니다. 모든 메서드에 헤더가 필요한 것은 아닙니다. Authorization, Accept-Charset, Content-Type, Cache-Control, User-Agent 등과 같은 헤더를 추가할 수 있습니다.

헤더 추가를 클릭하고, 사용자 정의 헤더 모달의 안내에 따라 필요한 헤더를 추가합니다. Credential Vault에 저장된 자격증명 또는 자격증명 변수를 선택하거나, 안전하지 않은 문자열로 헤더를 직접 입력할 수 있습니다.

콘텐츠 유형
콘텐츠 유형 헤더는 요청 본문에 있는 콘텐츠의 미디어 유형을 정의합니다. REST Web Services actions은 다음과 같은 콘텐츠 유형을 지원합니다.
  • application/x-www-form-urlencoded의 경우: URL 쿼리 문자열 형식으로 매개변수를 인코딩합니다.
  • JSON (application/json): JSON 형식으로 요청 본문을 입력합니다.
  • XML (application/xml): XML 형식으로 요청 본문을 입력합니다.
  • 텍스트 (text/plain) 일반 텍스트 형식으로 텍스트 유형 요청 본문을 입력합니다.
  • XML (text/xml): XML 형식으로 텍스트 유형 요청 본문을 입력합니다.
  • HTML (text/html) HTML 형식으로 텍스트 유형 요청 본문을 입력합니다.
  • multipart/form-data: 요청 본문에 텍스트와 파일을 모두 포함할 수 있습니다. 이 콘텐츠 유형은 API가 지원하는 모든 파일 형식을 지원합니다. 일반적으로 텍스트 데이터(예: 양식 필드)와 파일 업로드 등 단일 요청에 여러 부분을 전송하는 경우에 사용할 수 있습니다. 이 콘텐츠 유형은 파일 스트리밍도 지원합니다.
    파일 스트림을 파일 유형 변수에 할당하면 읽을 수 있습니다. 예를 들어 OneDrive 위치의 변수에 할당된 파일 스트림을 읽을 수 있습니다. 자세한 내용은 파일 할당 action 항목을 참조하십시오.
    Rest 웹 서비스 FileStream
  • 바이너리: 바이너리는 이미지, 비디오 및 오디오 파일과 같은 RAW 파일을 보내는 데 사용합니다. 다음 옵션 중 하나를 사용하여 파일을 업로드할 수 있습니다.
    • 변수: 바탕화면 또는 Control Room에 있는 파일을 업로드하려면 파일 변수를 할당합니다. 이 옵션을 사용하면 스토리지 위치에서 파일을 스트리밍할 수도 있습니다.
    • Control Room 파일: Control Room 스토리지에서 사용 가능한 파일을 업로드합니다.
    • 바탕화면 파일: 바탕화면에서 파일을 직접 업로드합니다.
  • 사용자 정의
    사용자 정의: 표준 콘텐츠 유형에 속하지 않는 사용자 정의 콘텐츠를 추가합니다. 예를 들어 v.11.x에서 Automation 360로 마이그레이션하는 경우 다음 값은 어떤 표준 콘텐츠 유형에도 속하지 않습니다. application/vnd.whispir.message-v1+json

application/x-www-form-urlencoded 및 multipart/form-data의 경우, 매개변수 추가를 클릭하고 매개변수 모델의 안내에 따라 필요한 헤더 매개변수를 추가하면 됩니다.

다른 콘텐츠 유형의 경우, 매개변수 입력 옵션 또는 매개변수로 자격증명을 선택 옵션을 사용하여 매개변수를 추가할 수 있습니다. 매개변수로 자격증명 선택 옵션을 사용하면 민감한 데이터를 요청 헤더로 추가할 수 있습니다.

대체 추가
대체 추가 옵션을 사용하면 REST 요청 본문에 변수를 입력할 수 있습니다. 이 옵션은 JSON (application/json), XML (application/xml), 텍스트 (text/plain), XML (text/xml), HTML (text/html), 그리고 사용자 정의 콘텐츠 유형 헤더에 사용할 수 있습니다.
변수는 데이터의 상징적 표현이며, 필요할 때마다 수동으로 입력하지 않고도 변수를 통해 값에 액세스할 수 있습니다. 예를 들어 다음 REST 본문 요청을 생각해 보십시오.
{
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
위의 요청 본문에서 대체 추가를 클릭하고 필요한 값을 추가하여 이중 중괄호로 묶인 변수를 바꿀 수 있습니다.
고급 옵션
실패 응답 캡처: 성공/확인 응답을 제외하고 실패 응답을 캡처하려면 확인란을 선택합니다. 시스템은 응답 본문에 실패 응답 세부 정보를 캡처합니다. 이 옵션은 DELETE, GET, PATCH, POST, PUT 메서드 작업에서 사용할 수 있습니다.
https를 사용할 때 안전하지 않은 연결 허용: https 프로토콜을 사용할 때 안전하지 않은 연결을 허용하려면 확인란을 선택합니다. 이 옵션은 모든 작업에서 사용할 수 있습니다.
쿠키 허용: 서버 응답에서 세션 쿠키를 자동으로 캡처하려면 확인란을 선택합니다. 이 확인란을 선택하면 다음 기능이 백그라운드에서 활성화됩니다.
  • 캡처: 시스템에서 서버가 응답에 포함하는 세션 쿠키를 캡처합니다.
  • 안전한 저장 공간: 시스템은 캡처된 쿠키를 프로세스 메모리 내에서 암호화하여 영구적으로 저장되지 않고 자동화 세션 외부에서 액세스할 수 없도록 합니다.
  • 재사용: 시스템에서 자동으로 후속 REST 호출에 쿠키를 포함하므로 수동 쿠키 처리가 필요 없고 자동화 안정성이 향상됩니다.
  • 다중 쿠키 처리: 시스템은 서버가 반환하는 여러 쿠키를 자동으로 처리하여 필요한 모든 인증 자격증명이 포함되도록 합니다.
  • 파괴: 시스템은 자동화 세션이 종료되거나 봇 실행이 완료되면 캡처된 쿠키를 자동으로 삭제하여 데이터 보안과 개인정보 보호를 보장합니다.

이 옵션은 DELETE, GET, PATCH, POST, PUT 메서드 작업에서 사용할 수 있습니다.

주: 캡처된 쿠키는 해당 쿠키가 생성된 도메인에 한정되며 다른 도메인으로의 후속 REST 호출에는 자동으로 사용되지 않습니다. 즉, domainA.com에서 캡처한 쿠키는 domainB.com에 대한 요청에 활용되지 않습니다.
파일 다운로드: 이 확인란을 선택하여 URI에 있는 바이너리 파일을 특정 위치에 다운로드합니다. 원하는 파일 경로를 이름 및 확장자와 함께 입력해야 합니다. 예: <C:/Users/Downloads/image01.jpg>

이 옵션은 GET 메서드 작업에서만 사용할 수 있습니다. 다음과 같은 상황이 발생하면 시스템에서 오류 메시지를 표시합니다.

  • 잘못된 URI: 제공된 URI가 올바르지 않은 경우입니다.
  • 파일을 찾을 수 없음: 지정된 위치에 파일이 존재하지 않아 API 응답이 비어 있는 경우입니다.
  • 권한 불충분: 다운로드 위치에 대한 쓰기 권한이 없는 경우입니다.
  • 파일 확장자 불일치: 파일 확장자가 예상 유형과 일치하지 않는 경우입니다.

새 버전으로 기존 파일을 덮어쓰려면 파일이 이미 있는 경우 덮어쓰기 확인란을 활성화합니다.

작업 완료 대기
REST 요청을 보내고 응답을 받을 때 타임아웃 값을 설정할 수 있습니다. POST, PUT, DELETE, PATCH, GET과 같은 actions을 수행할 때, 작업 완료 대기 필드에 대기 시간(밀리초 단위)을 지정하십시오. 기본적으로 대기 시간은 60,000밀리초입니다.
SSL/TLS 구성
이 옵션을 사용하여 인증서 파일을 비밀번호와 함께 또는 비밀번호 없이 업로드하면 REST API 호출 시 추가적인 인증을 제공합니다.

SSL/TLS 구성은 상호 TLS(mTLS) 프로토콜을 사용하여 API URI와 클라이언트 간의 통신을 암호화하고, 인증하며, 보호합니다. mTLS는 두 엔터티가 인증서를 교환하여 서로를 인증하도록 요구합니다. 데이터 전송은 양쪽 엔터티가 교환된 인증서를 성공적으로 인증할 경우에만 이루어집니다.

REST Web Services는 Windows 컴퓨터에 대해 .p12 형식의 인증서를 지원하고, 비-Windows 컴퓨터에 대해서는 .pfx 형식을 지원합니다.

  • 키 저장소 파일 경로(선택 사항): 변수, Control Room 파일 또는 데스크톱 파일 옵션을 사용하여 인증서 파일을 업로드합니다.
  • 키 저장소 비밀번호(선택 사항): 인증서가 비밀번호로 보호되어 있는 경우, 자격증명, 변수, 또는 안전하지 않은 string 옵션을 사용하여 인증서 비밀번호를 인증할 수 있습니다. 자격증명 보관함에 비밀번호를 안전하게 저장하는 방법에 대한 자세한 내용은 Credential Vault의 자격증명 및 lockers 항목을 참조하십시오.
변수에 출력을 할당합니다.
응답 출력은 사전 변수에 캡처됩니다. 사전 변수는 키-값 쌍입니다. 응답 헤더 이름을 키로 이용하여 헤더 값을 반환하거나 ‘본문\'을 키로 이용하여 응답 본문을 반환합니다.

이 옵션은 DELETE, GET, PATCH, POST, PUT 메서드 작업에서 사용할 수 있습니다.

주: 값이 있는 응답 키는 사전 변수에서 REST API의 응답 상태를 표시하는 데 이용할 수 있습니다.
API 리소스의 헤더 이름 목록을 가져오려면 다음 단계를 수행합니다.
  1. REST Web Services action 후에 Loop action을 삽입합니다.
  2. 사전 안의 각 키에 대해 반복자를 선택합니다.
  3. 사전 변수 필드에서 REST Web Services action 출력을 포함하는 변수를 선택합니다.
  4. 각 키의 값을 $prompt-assignment$에 지정합니다.
  5. 텍스트를 파일에 기록 action을 삽입합니다.
  6. 헤더 이름 목록을 유지할 텍스트 파일의 파일 경로를 제공합니다.
  7. 로그할 텍스트 입력 필드에 $prompt-assignment$를 삽입합니다.
  8. 기존 파일 덮어쓰기 옵션을 선택합니다.
  9. 저장을 클릭합니다.

    bot을 실행하면 API 리소스에서 선택한 파일로 헤더 이름을 인쇄합니다.

파일을 변수에 할당
이 옵션은 파일 스트림 가져오기 작업에서만 사용할 수 있습니다. 파일 스트림 가져오기 작업을 통해 URI에 있는 파일에 파일 변수를 할당할 수 있습니다. 그런 다음 이 파일 변수를 세션 내의 후속 작업에서 사용할 수 있습니다. 파일 변수 할당에 대한 자세한 내용은 파일 스트림 가져오기 작업 사용 항목을 참조하십시오.

안전하게 값 전달

다음의 지원되는 Credential Vault 필드에서 locker, 자격증명 및 속성을 지정하여 action에서 웹 서비스로 값을 안전하게 전달할 수 있습니다.
  • URI
  • 사용자 정의 헤더
  • 본문: application/x-www-form-urlencoded 콘텐츠 유형의 경우 매개변수 추가를 클릭하여 Credential Vault에서 값을 선택합니다.

    다른 모든 콘텐츠 유형의 경우, 매개변수로 자격증명 선택 옵션을 선택하고 선택을 클릭합니다.

Actions REST Web Services의 package

Action 설명
DELETE 메서드 URI에 의해 식별된 리소스를 제거합니다.
GET 메소드 URI에 포함된 매개변수로 식별된 정보를 검색합니다. 모든 매개변수는 URI의 일부로 전달되므로, GET 메서드에 대한 콘텐츠 유형이 없습니다.

GET 메서드의 한계와 특징은 다음과 같습니다.

  • URI 길이는 2,048자로 제한됩니다.
  • 모든 매개변수는 URI로 전달됩니다.
  • GET 메서드는 URI에 있는 데이터를 노출하므로 POST 메서드보다 덜 안전합니다.
  • GET은 어떤 데이터도 변경하지 않기 때문에 권한 부여에 관계없이 모든 사용자가 사용에 안전합니다.

Get 메소드 사용 항목을 참조하십시오.
PATCH 메서드 URI에 의해 식별된 리소스를 수정합니다.
POST 메서드 URI에 새 리소스를 만듭니다.
  • 매개변수는 요청 본문에서 전달됩니다.
  • 요청 본문의 길이에는 제한이 없습니다.

Post 메소드 사용 항목을 참조하십시오.
PUT 메서드 URI 또는 본문에 전달된 매개변수를 기반으로 리소스를 업데이트하거나 대체합니다. Put 메소드 사용 항목을 참조하십시오.

Proxy support

If your device is configured with a proxy, all outbound requests from this package are routed through the proxy server. See 프록시를 사용하여 Bot Agent를 기기에 연결.