스크립트 기반 REST API
스크립트 기반 REST API 기능을 사용하면 애플리케이션 개발자가 사용자 지정 웹 서비스 API를 빌드할 수 있습니다.
스크립팅된 REST API에 대한 서비스 엔드포인트, 쿼리 매개변수 및 헤더는 물론 요청 및 응답을 관리하는 스크립트를 정의할 수 있습니다.
스크립트 기반 REST API는 일반적으로 REST 아키텍처를 따르지만 다른 규칙을 사용하도록 사용자 지정할 수 있습니다. 스크립트 기반 웹 서비스→ 스크립트 기반 REST API에 있는 스크립트 기반 REST 서비스 양식을 사용하여 스크립트 기반 REST API를 정의합니다.
스크립팅된 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 리소스의 오류 개체를 사용하여 요청하는 클라이언트에 오류를 경고할 수 있습니다. 오류 개체를 사용하여 들어오는 요청에 응답하고 서버 측 코드 내에서 오류를 catch하지 않습니다.
오류 응답 형식
응답의 콘텐츠 유형은 요청 수락 헤더에 따라 달라집니다. Accept 헤더가 지원되지 않는 형식(예: 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에 대한 교육을 찾을 수 있습니다.