스크립팅된 REST API - ServiceNow Fluent

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 13분

    • 스크립팅된 REST API는 스크립팅된 REST 서비스[sys_ws_definition]에 대한 엔드포인트, 쿼리 매개변수 및 헤더를 정의합니다.

    스크립트된 REST 서비스에 대한 일반적인 정보는 다음 문서를 참조하십시오 Scripted REST APIs.

    RestApi 객체

    스크립트된 REST API [sys_ws_definition]를 만들어 웹 서비스 엔드포인트를 정의합니다.

    표 1. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 API 설명서에 사용되는 API의 이름입니다.
    serviceId 문자열 필수 URI 경로에서 이 API를 구분하는 데 사용되는 API 식별자입니다. API 네임스페이스 내에서 고유해야 합니다.
    활성 부울 API가 요청을 처리할 수 있는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: API가 요청을 서비스할 수 있습니다.
    • false: API가 요청을 서비스할 수 없습니다.

    기본값: true
    shortDescription 문자열 API 설명서에 사용되는 API에 대한 간략한 설명입니다.
    소비 문자열 API의 자원에서 사용할 수 있는 미디어 유형의 목록입니다.

    기본값: application/json,application/xml,text/xml
    문서 링크 문자열 API에 대한 정적 문서로 연결되는 URL입니다.
    enforceAcl 배열 자원 [sys_security_acl]에 접근할 때 적용할 ACL 개체 또는 ACL sys_ids의 변수 식별자 목록입니다. 자세한 내용은 접근 제어 목록 API - ServiceNow Fluent 문서를 참조하십시오.

    ACL을 적용하지 않으려면 이 속성을 빈 배열([])으로 설정합니다.

    기본값: 스크립팅된 REST 외부 기본값
    생산 문자열 API의 자원이 생산할 수 있는 미디어 유형의 목록입니다.

    기본값: application/json,application/xml,text/xml
    경로 배열 API에 대한 자원 [sys_ws_operation]입니다. 자세한 내용은 경로 객체 문서를 참조하십시오.
    정책 문자열 다운로드 또는 설치 시 애플리케이션 파일의 보호 방법에 대한 정책입니다.
    유효한 값은 다음과 같습니다.
    • 읽기: 파일만 볼 수 있습니다.
    • 보호됨: 암호 권한이 있는 사용자가 파일을 편집할 수 있습니다.
    버전 배열 API 버전 [sys_ws_version] 목록입니다. 자세한 내용은 버전 객체 문서를 참조하십시오.

    버전을 지정하면 다양한 버전의 API와 해당 상태(예: 활성, 기본 버전 또는 사용되지 않음 여부)를 관리할 수 있습니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    import { RestApi } from '@servicenow/sdk/core'
import { process } from '../server/handler.js'

RestApi({
    $id: Now.ID['rest1'],
    name: 'customAPI',
    serviceId: 'custom_api',
    consumes: 'application/json',
    routes: [
        {
            $id: Now.ID['route1'],
            path: '/home/{id}',
            script: process,
            parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
            headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],
            enforceAcl: [acl],
            version: 1,
        },
    ],
    enforceAcl: [acl],
    versions: [
        {
            $id: Now.ID['v1'],
            version: 1,
        },
    ],
})
    참조된 ACL은 ACL 객체를 사용하여 정의됩니다.
    import { Acl } from "@servicenow/sdk/core";

const acl = Acl({
    name: 'My random ACL',
    type: 'rest_endpoint',
    script: `answer = (Math.random() > 0.5)`,
    active: true,
    adminOverrides: false,
    operations: ['execute'],
})

    경로 객체

    HTTP 메서드와 처리 스크립트를 정의하고 상위 서비스의 설정을 재정의하는 스크립팅된 REST 자원 sys_ws_operation]을 만듭니다.

    RestApi 객체 내에서 routes 객체를 사용합니다.

    표 2. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 API 설명서에 사용되는 API 자원의 이름입니다.

    기본값: path 속성의 값
    스크립트 스크립트 필수 사용자 지정 스크립트는 작업이 요청을 구문 분석하고 응답하는 방법을 정의합니다. 이 속성은 JavaScript 모듈의 함수, 스크립트가 포함된 애플리케이션의 다른 파일에 대한 참조 또는 인라인 JavaScript를 지원합니다.
    체재:
    • 함수의 경우 JavaScript 모듈에서 익스포트한 함수, 함수 표현식 또는 기본 함수의 이름을 사용하여 .now.ts 파일로 임포트합니다. JavaScript 모듈에 대한 자세한 내용은 다음 문서를 참조하십시오 JavaScript 모듈 및 타사 라이브러리.
    • 다른 파일의 텍스트 컨텐츠를 사용하려면 Now.include('path/to/file') 형식을 사용하여 애플리케이션의 파일을 참조하십시오. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.
    • 인라인 스크립트를 제공하려면 여러 줄의 코드에 문자열 리터럴 또는 템플릿 리터럴을 사용합니다( 'Script' 또는 'Script').
    매개변수 배열 경로에 대한 쿼리 매개변수 [sys_ws_query_parameter] 목록입니다. 자세한 내용은 매개변수 및 헤더 객체 문서를 참조하십시오.
    헤더 배열 경로에 대한 헤더 [sys_ws_header] 목록입니다. 자세한 내용은 매개변수 및 헤더 객체 문서를 참조하십시오.
    활성 부울 자원이 사용되었는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 자원이 사용됩니다.
    • false: 자원이 사용되지 않습니다.

    기본값: true
    경로 문자열 기본 API 경로를 기준으로 하는 자원의 경로입니다. 상대 URI에는 '/abc/{id}'와 같은 경로 매개변수가 포함될 수 있습니다.

    기본값: /
    shortDescription 문자열 API 문서에 사용되는 자원에 대한 간략한 설명입니다.
    소비 문자열 자원이 사용할 수 있는 미디어 유형의 목록입니다.

    이 속성은 PUT, PATCH 또는 POST 메서드를 사용하여 재정의할 수 있습니다.

    기본값: RestApi 객체의 consumes 속성 값
    enforceAcl 배열 자원 [sys_security_acl]에 접근할 때 적용할 ACL 개체 또는 ACL sys_ids의 변수 식별자 목록입니다. 자세한 내용은 접근 제어 목록 API - ServiceNow Fluent 문서를 참조하십시오.

    ACL을 적용하지 않으려면 이 속성을 빈 배열([])으로 설정합니다.

    기본값: 스크립팅된 REST 외부 기본값
    생산 문자열 자원이 생산할 수 있는 미디어 유형의 목록입니다.

    기본값: RestApi 객체의 produces 속성 값
    요청예시 문자열 API 설명서에 사용되는 자원에 대한 유효한 샘플 요청 본문 페이로드입니다.
    방법 문자열 자원이 구현하는 HTTP 메서드입니다.

    유효한 값: GET, POST, PUT, PATCH, DELETE

    기본값: GET
    권한 부여 부울 사용자가 자원에 액세스하기 위해 인증되어야 하는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 사용자가 자원에 액세스하려면 인증되어야 합니다.
    • false: 자원에 액세스하는 데 인증이 필요하지 않습니다.

    기본값: true
    인증 부울 자원에 액세스할 때 ACL이 적용되는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 자원에 액세스할 때 ACL이 적용됩니다.
    • false: 자원에 액세스할 때 ACL이 적용되지 않습니다.

    기본값: true
    internalRole 부울 경로에 snc_internal 역할이 필요한지 여부를 나타내는 플래그입니다.

    이 속성은 Explicit Roles 플러그인(com.glide.explicit_roles)이 활성화된 경우에만 지원됩니다.

    유효한 값은 다음과 같습니다.
    • true: 경로에 snc_internal 역할이 필요합니다.
    • false: 경로에 snc_internal 역할이 필요하지 않습니다.

    기본값: true
    정책 문자열 다운로드 또는 설치 시 애플리케이션 파일의 보호 방법에 대한 정책입니다.
    유효한 값은 다음과 같습니다.
    • 읽기: 파일만 볼 수 있습니다.
    • 보호됨: 암호 권한이 있는 사용자가 파일을 편집할 수 있습니다.
    버전 번호 API의 버전입니다.

    버전 속성이RestApi 객체에서 사용되는 경우 이 속성이 필요합니다.

    이 속성으로 지정된 버전은 /api/management/v1/table/{tableName}과 같은 버전의 URI를 자동으로 생성하는 데 사용됩니다. 버전 번호는 URI가 액세스하는 엔드포인트 버전을 식별합니다. 버전 번호를 지정하면 기존 통합에 영향을 주지 않고 변경 내용을 테스트하고 배포할 수 있습니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    routes: [
   {
      $id: Now.ID['route1'],
      path: '/home/{id}',
      script: process,
      parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
      headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],
      enforceAcl: [acl],
      version: 1,
   },
],

    매개변수 및 헤더 객체

    스크립팅된 REST API에서 경로에 대한 쿼리 매개변수 [sys_ws_query_parameter] 및 헤더 [sys_ws_header]를 만듭니다. 쿼리 매개변수는 요청 사용자가 요청 URI에 전달할 수 있는 값을 제어합니다. 헤더는 API가 수락하고 응답할 수 있는 항목을 지정합니다.

    routes 객체 내에서 매개변수 및 헤더 객체를 사용합니다.

    표 3. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 API 설명서에 사용되는 매개변수 또는 헤더의 이름입니다.
    필수 부울 매개변수 또는 헤더가 필요한지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 매개변수 또는 헤더가 필요합니다.
    • false: 매개변수 또는 헤더가 필요하지 않습니다.

    기본값: false
    exampleValue 문자열 API 설명서에 사용되는 매개변수 또는 헤더의 유효한 값의 예입니다.
    shortDescription 문자열 API 설명서에 사용되는 매개변수 또는 헤더에 대한 간략한 설명입니다.
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],

    버전 객체

    웹 서비스 엔드포인트를 정의하는 스크립트된 REST API [sys_ws_version]에 대한 버전을 만듭니다.

    RestApi 객체 내에서 versions 객체를 사용합니다.

    표 4. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.

    형식: Now.ID['문자열' 또는 숫자]
    버전 번호 필수 REST API의 버전입니다.
    활성 부울 REST API의 버전이 요청을 처리할 수 있는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: API의 버전이 요청을 처리할 수 있습니다.
    • false: API 버전이 요청을 서비스할 수 없습니다.

    기본값: true
    사용하지 않음 부울 REST API의 버전이 더 이상 사용되지 않는지 여부를 나타내는 플래그입니다. 사용되지 않는 버전에 속하는 자원은 요청을 서비스할 수 있지만 설명서에는 사용되지 않는 것으로 표시됩니다.
    유효한 값은 다음과 같습니다.
    • true: API 버전이 사용되지 않는 것으로 식별됩니다.
    • false: API 버전이 사용되지 않는 것으로 식별되지 않습니다.

    기본값: false
    shortDescription 문자열 API 문서에 나타나는 REST API 버전에 대한 간략한 설명입니다.
    isDefault 부울 REST API의 버전이 기본 버전인지 여부를 나타내는 플래그입니다. 클라이언트는 버전이 있거나 버전이 없는 URI 경로를 사용하여 기본 버전에 액세스할 수 있습니다.
    유효한 값은 다음과 같습니다.
    • true: API 버전이 기본 버전입니다.
    • false: API 버전이 기본 버전이 아닙니다.

    기본값: false
    $meta 객체 애플리케이션 메타데이터의 메타데이터입니다.
    installMethod 속성을 사용하면 애플리케이션 메타데이터를 특정 상황에서만 로드되는 출력 디렉터리에 매핑할 수 있습니다.
    $meta: {
      installMethod: 'String'
}
    installMethod에 유효한 값:
    • demo: 데모 데이터 로드 옵션을 선택한 경우 애플리케이션과 함께 설치할 metadata/unload.demo 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    • 첫 번째 설치: 애플리케이션이 인스턴스에 처음 설치될 때만 설치할 메타데이터 /언로드 디렉터리에 애플리케이션 메타데이터를 출력합니다.
    		 
    versions: [
 {
   $id: Now.ID['v1'],
   version: 1,
 },
],