스크립트 기반 REST API
스크립트 기반 REST API 기능을 사용하면 애플리케이션 개발자가 사용자 지정 웹 서비스 API를 빌드할 수 있습니다.
스크립트된 REST API에 대한 서비스 엔드포인트, 쿼리 매개변수 및 헤더뿐만 아니라 요청 및 응답을 관리하는 스크립트를 정의할 수 있습니다.
스크립트 기반 REST API는 일반적으로 REST 아키텍처를 따르지만 다른 규칙을 사용하도록 사용자 지정할 수 있습니다. 스크립트 기반 REST API는 스크립트 기반 웹 서비스 → 스크립트 기반 REST API에 있는 스크립트 기반 REST 서비스 양식을 사용하여 정의합니다.
스크립팅된 REST API URI
스크립팅된 REST API URI의 형식은 다음과 같습니다.
https://<instance.service-now.com>/api/<name_space>/<version>/<api_id>/<relative_path>
- <instance.service-now.com>: 사용자가 스크립트 기반 REST API에 액세스하는 인스턴스의 경로 ServiceNow 입니다.
- <name_space>: 전역 범위에 있는 웹 서비스의 경우, 네임스페이스는 속성의 glide.appcreator.company.code값입니다. 범위가 지정된 애플리케이션의 웹 서비스의 경우, 네임스페이스는 범위 이름(예: x_company_appname)입니다. 네임스페이스에 대한 자세한 내용은 애플리케이션 범위를 참조하세요.
- <version>:선택적. API가 버전 관리를 사용하는 경우 액세스할 엔드포인트의 버전입니다(예: v1). 버전 번호 없이 URI를 지정하여 버전이 지정된 API의 기본 버전에 액세스할 수 있습니다.
- <api_id>: 스크립팅된 REST 서비스 양식의 API ID 필드 값입니다. 기본적으로 이 값은 서비스 이름을 기반으로 합니다.
- <relative_path>: 스크립팅된 REST 서비스 양식에서 자원에 대해 정의된 상대 경로입니다. 상대 자원 경로를 지정하면 하나의 웹 서비스에서 GET과 같은 동일한 HTTP 메서드를 사용하는 여러 자원을 사용할 수 있습니다. 예를 들어 웹 서비스에 GET 리소스가 하나만 있는 경우 리소스에서
/{id}경로를 지정하거나, 웹 서비스에 요청 사용자 및 메시지 레코드에 대해 서로 다른 리소스가 있는 경우/user/{id} 및 /message/{id}를 지정할 수 있습니다.
스크립팅된 REST API 버전 관리
스크립팅된 REST API URI에는 버전 번호( 예: /api/management/v1/table/{tableName})가 포함될 수 있습니다. 버전 번호는 URI가 액세스하는 엔드포인트 버전을 식별합니다. URI에 버전 번호를 지정하면 기존 통합에 영향을 주지 않고 변경 내용을 테스트하고 배포할 수 있습니다.
기본 API 버전
버전이 기본값으로 표시될 수 있습니다. 기본 버전을 지정하면 사용자가 버전 번호 없이 스크립팅된 REST 엔드포인트를 사용하여 해당 버전에 액세스할 수 있습니다. 기본값으로 표시된 버전이 없으면 최신 버전이 기본값으로 사용됩니다.
스크립팅된 REST API 자원
스크립팅된 REST API 자원은 REST 엔드포인트와 동일합니다. 실행할 HTTP 메서드, 처리 스크립트 및 상위 API의 재정의 설정을 정의합니다. API당 하나 이상의 자원을 정의할 수 있습니다.
스크립팅된 REST API 쿼리 매개변수
쿼리 매개변수는 요청 사용자가 요청에 전달할 수 있는 값을 정의합니다. 스크립트 기반 REST API를 만들 때 사용할 수 있는 매개변수와 각 요청에 필수적인 매개변수를 지정할 수 있습니다. 쿼리 매개변수를 여러 자원과 연결할 수도 있습니다.
요청 객체 queryParams 필드를 사용하여 스크립트에서 요청 매개변수에 액세스합니다.
스크립팅된 REST API 역할
요청 및 응답 형식
기본적으로 API의 모든 자원은 application/json, application/xml 및 text/xml의 요청 및 응답 형식을 지원합니다. API 수준에서 기본 형식을 재정의할 수 있습니다. 개별 자원이 기본값을 재정의하지 않는 한 새 형식은 API에 속하는 모든 자원에 적용됩니다.
스크립팅된 REST API 보안
필요한 보안 수준으로 스크립트된 REST API를 구성할 수 있습니다. 보안이 필요하지 않은 공용 API/엔드포인트에서 모든 리소스에 대한 엄격한 액세스 제어를 통해 사용자 인증이 필요한 매우 안전한 API/엔드포인트에 이르기까지.
API 접근 정책 기능을 사용하여 API의 인증 방법을 제어합니다. 자세한 내용은 API access policy 문서를 참조하십시오.
스크립팅된 REST API 접근 제어
접근 제어 목록(ACL)은 필요한 역할 및 스크립트된 REST API 또는 엔드포인트에 액세스하기 위해 사용자가 충족해야 하는 조건과 같은 기준을 정의합니다. 요청 사용자는 하나 이상의 ACL을 만족해야 합니다. 선택한 모든 ACL을 충족할 필요는 없습니다. 전체 REST API 또는 개별 엔드포인트에 대해 단일 ACL을 정의할 수 있습니다.
스크립팅된 REST API ACL을 정의할 때는 유형 값이 REST_Endpoint 있어야 합니다.
ACL에 대한 자세한 내용은 접근 제어 목록 규칙 및 ACL을 요구하도록 스크립트 기반 REST API 자원 구성를 참조하십시오.
스크립팅된 REST API 보안 매트릭스
스크립트 기반 REST API에 대해 여러 가지 보안 구성을 사용할 수 있습니다. 이 테이블을 사용하여 요구 사항에 가장 적합한 스크립팅된 REST API 보안 구성과 해당 구성을 구현하기 위한 필드 값을 식별합니다.
| 구성 | Scripted REST APIs | 스크립팅된 REST 자원 | ||
|---|---|---|---|---|
| 기본 ACL | 인증 필요 | ACL 권한 필요 | ACL | |
| 자원이 공용입니다. 인증 또는 ACL이 필요하지 않습니다. | 모든 값 | 아니요 | 모든 값 | 모든 값 |
| 자원에는 기본 인증만 필요합니다. ACL은 필요하지 않습니다. | 모든 값 | 예 | 아니요 | 모든 값 |
| 자원에는 기본 인증만 필요합니다. ACL이 필요합니다. | 선택한 ACL 없음 | 예 | 예 | 선택한 ACL 없음 |
| 자원 기록에서 선택한 ACL이 필요합니다. | 모든 값 | 예 | 예 | 하나 이상의 ACL 선택됨 |
| 스크립팅된 REST API 기록에서 선택한 ACL이 필요합니다. | 하나 이상의 ACL 선택됨 | 예 | 예 | 선택한 ACL 없음 |
스크립팅된 REST API 오류 객체
스크립트 기반 REST API에는 요청 처리 중에 오류가 발생할 때 표준 HTTP 오류 메시지로 요청에 응답할 수 있는 오류 개체가 포함되어 있습니다. 스크립트된 REST API 자원의 오류 객체를 사용하여 요청 클라이언트에 오류를 경고할 수 있습니다. 오류 객체를 사용하여 서버 측 코드 내에서 오류를 포착하는 것이 아니라 들어오는 요청에 응답합니다.
오류 응답 형식
응답의 콘텐츠 유형은 요청 수락 헤더에 따라 달라집니다. 수락 헤더가 지원되지 않는 형식(예: image/jpeg)을 지정하면 오류 응답에 JSON이 사용됩니다.
{
"error": {
"message": "My error message",
"detail": "My details"
},
"status": "failure"
}Automated Test Framework 지원
Automated Test Framework(ATF)는 인바운드 REST 테스트 단계를 지원합니다. 사용자가 만든 사용자 지정 인바운드 REST API에 대한 자동화된 테스트를 만들 수 있습니다. 사용자 지정 REST API에 대한 테스트를 만들면 업그레이드 테스트가 간소화되고 REST API에 대한 수정 사항이 이전 버전과 호환되는지 확인할 수 있습니다. REST 테스트 단계 구성 및ATF REST 테스트 단계 구성 관리를 참조하십시오.
개발자 교육
ServiceNow® 개발자 사이트에서 스크립트 기반 REST API에 대한 교육을 찾을 수 있습니다.