스크립팅된 REST API - ServiceNow Fluent

  • 릴리스 버전: Yokohama
  • 업데이트 날짜 2025년 01월 30일
  • 읽기10분

    • 스크립팅된 REST API에는 스크립팅된 REST 서비스[sys_ws_definition]에 대한 엔드포인트, 쿼리 매개변수 및 헤더를 정의하는 객체가 포함되어 있습니다.

    RestApi 객체

    스크립트된 REST API [sys_ws_definition]를 작성하여 웹 서비스 엔드포인트를 정의합니다.

    표 1. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 다음 형식으로 제공되는 메타데이터 개체의 고유 ID입니다. 여기서 <value> 는 문자열 또는 숫자입니다.
    $id: Now.ID[<value>]

    애플리케이션을 빌드할 때 이 ID는 고유한 sys_ID로 해시됩니다.
    이름 문자열 필수 API 문서에 사용되는 API의 이름입니다.
    service_id 문자열 필수 URI 경로에서 이 API를 구분하는 데 사용되는 API 식별자입니다. API 네임스페이스 내에서 고유해야 합니다.
    활성 부울 API가 요청을 서비스할 수 있는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: API가 요청을 서비스할 수 있습니다.
    • false: API가 요청을 처리할 수 없습니다.

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

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

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

    enforce_acl: ['sys_id', acl_variable_identifier]

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

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

    버전을 지정하면 API의 여러 버전과 해당 상태(예: 활성 여부, 기본 버전 또는 사용되지 않음)를 관리할 수 있습니다.

    		 
    import { RestApi } from '@servicenow/sdk/core'
import { process } from '../server/handler.js'

RestApi({
    $id: Now.ID['rest1'],
    name: 'customAPI',
    service_id: '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' }],
            enforce_acl: [acl],
            version: 1,
        },
    ],
    enforce_acl: [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,
    admin_overrides: false,
    operations: ['execute'],
})

    경로 객체

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

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

    표 2. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 다음 형식으로 제공되는 메타데이터 개체의 고유 ID입니다. 여기서 <value> 는 문자열 또는 숫자입니다.
    $id: Now.ID[<value>]

    애플리케이션을 빌드할 때 이 ID는 고유한 sys_ID로 해시됩니다.
    이름 문자열 API 문서에 사용되는 API 자원의 이름입니다.

    기본값: 경로 속성의 값
    스크립트 스크립트 필수 스크립트 태그가 앞에 오는 함수 또는 인라인 스크립트입니다. 사용자 지정 스크립트는 작업이 요청을 구문 분석하고 응답하는 방법을 정의합니다.

    함수의 경우 JavaScript 모듈에서 익스포트하여 .now.ts 파일로 가져온 함수, 함수 식 또는 기본 함수의 이름을 사용합니다. JavaScript 모듈에 대한 자세한 내용은 다음을 참조하십시오 JavaScript 모듈 및 타사 라이브러리.

    인라인 스크립트는 다음과 같은 형식으로 스크립트 태그를 사용합니다.
    script: script`gs.info('info')`,
    활성 부울 자원이 사용되는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 자원이 사용됩니다.
    • false: 자원이 사용되지 않습니다.

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

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

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

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

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

    enforce_acl: ['sys_id', acl_variable_identifier]

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

    기본값: RestApi 객체의 produce 속성 값
    request_example 문자열 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 개체에서 사용되는 경우 이 속성이 필요합니다.

    이 속성으로 지정된 버전은 버전이 있는 URI를 자동으로 생성하는 데 사용됩니다(예: /api/management/v1/table/{tableName}). 버전 번호는 URI가 액세스하는 엔드포인트 버전을 식별합니다. 버전 번호를 지정하면 기존 통합에 영향을 주지 않고 변경 사항을 테스트하고 배포할 수 있습니다.

    		 
    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' }],
      enforce_acl: [acl],
      version: 1,
   },
],

    매개변수 및 헤더 객체

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

    routes 객체 내에서 parameters 및 headers 객체를 사용합니다.

    표 3. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 다음 형식으로 제공되는 메타데이터 개체의 고유 ID입니다. 여기서 <value> 는 문자열 또는 숫자입니다.
    $id: Now.ID[<value>]

    애플리케이션을 빌드할 때 이 ID는 고유한 sys_ID로 해시됩니다.
    이름 문자열 필수 API 문서에 사용되는 매개변수 또는 헤더의 이름입니다.
    필수 부울 매개변수 또는 헤더가 필요한지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 매개변수 또는 헤더가 필요합니다.
    • false: 매개변수 또는 헤더가 필요하지 않습니다.

    기본값: false
    example_value 문자열 API 문서에 사용되는 매개변수 또는 헤더의 유효한 값의 예입니다.
    short_description 문자열 API 문서에 사용되는 매개변수 또는 헤더에 대한 간략한 설명입니다. 
    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입니다. 여기서 <value> 는 문자열 또는 숫자입니다.
    $id: Now.ID[<value>]

    애플리케이션을 빌드할 때 이 ID는 고유한 sys_ID로 해시됩니다.
    버전 번호 필수 REST API의 버전입니다.
    활성 부울 REST API의 버전이 요청을 서비스할 수 있는지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: API 버전이 요청을 처리할 수 있습니다.
    • false: API 버전에서 요청을 처리할 수 없습니다.

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

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

    기본값: false

    		 
    versions: [
 {
   $id: Now.ID['v1'],
   version: 1,
 },
],