는 ServiceNow AI Platform 기본적으로 활성화되는 다양한 REST API를 제공합니다. 이러한 API는 애플리케이션 내의 다양한 ServiceNow 기능과 상호 작용할 수 있는 기능을 제공합니다. 이러한 기능에는 기존 테이블(테이블 API)에서 생성, 읽기, 업데이트 및 삭제(CRUD) 작업을 수행하고, MetricBase 데이터베이스(MetricBase 시계열 API 등)에 데이터를 삽입하고 정보를 검색하고, 데이터베이스에 대해 변환을 실행하는 기능이 포함됩니다.

사용 가능한 REST API 목록은 REST API 참조를 참조하십시오.

REST URI 형식 및 사용 가능한 매개변수

ServiceNow REST API는 표준 REST API 프로토콜을 따릅니다. 또한 이전 버전과의 호환성을 보장하고 긴 결과 목록의 페이지 매김과 같은 추가 기능을 제공하기 위해 "사용자 지정" URI 및 쿼리 매개변수를 제공합니다. 다음 섹션에서는 모두 선택 사항인 이러한 사용자 지정 매개변수의 기능에 대해 설명합니다.

REST API 버전 관리

ServiceNow REST API URI에는 /api/now/v1/table/{tableName}과 같은 버전 번호가 포함될 수 있습니다. 버전 번호는 URI가 액세스하는 엔드포인트 버전을 식별합니다. URI에 버전 번호를 지정하면 REST API에 대한 향후 업데이트가 통합에 부정적인 영향을 미치지 않도록 할 수 있습니다.

URI에 버전 번호를 지정하지 않은 URI( 예: /api/now/table/{tableName})는 인스턴스 버전에 대한 최신 REST 엔드포인트를 사용합니다.

지원되는 HTTP 요청 메서드

이러한 방법에 대한 자세한 내용은 RFC-2616 하이퍼텍스트 전송 프로토콜 문서를 참조하십시오.

데이터 형식 헤더

REST API에는 요청 본문 또는 응답 본문이 포함된 요청에 대한 적절한 데이터 형식을 위해 및 Content-Type 요청 헤더가 필요합니다Accept. POST, PUT, PATCH 및 DELETE 작업의 경우 헤더를 모두 제공해야 합니다. GET 및 HEAD 작업에는 헤더만 Accept 필요합니다. 필수 헤더를 제공하지 않으면 400 잘못된 요청 오류가 발생합니다.

대부분의 ServiceNow REST API에서 이러한 요청 헤더는 다음 값을 지원합니다.

• 수용: application/json, application/xml
• 콘텐츠 유형: application/json, application/xml

각 엔드포인트에서 지원하는 특정 값의 목록은 REST API 참조를 참조하십시오.

기타 헤더

모든 요청에는 인증에 사용할 사용자 자격 증명을 지정하는 인증 헤더가 포함될 수 있습니다.

헤더를 설정하여 GET 또는 POST와 같은 HTTP 메서드를 재정의할 수도 있습니다 X-http-method-override .

특수 데이터 처리

다음은 REST API 내의 몇 가지 데이터 처리 미묘한 차이에 대해 설명합니다.

• 데이터 필드를 지우는 방법: 선택 필드를 제외하고 매개변수에 빈 값을 전달하여 데이터베이스의 값을 지울 수 있습니다. 예를 들어, {"short description":""} 를 전송하면 지정된 기록의 필드가 short_description 지워집니다.
• 통화 필드 처리 방법: 반환된 통화 값은 사용자의 로캘을 기준으로 현지 통화로 변환됩니다. 데이터를 삽입할 때 변환은 수행되지 않습니다. 이 동작은 통화 또는 가격 유형의 필드에 적용됩니다.

  예를 들어 영국 로캘의 사용자가 통화 값이 USD인 기록을 쿼리하면 반환된 값이 GBP로 변환됩니다. 그러나 이 사용자가 통화 필드 값이 GBP인 새 기록을 추가하면 값은 USD로 변환되지 않고 GBP로 저장됩니다. 이 GBP 값은 미국 로캘의 사용자가 쿼리한 경우 USD로 표시됩니다.

• UI 데이터 표시와 REST 엔드포인트에 전달된 값: UI에는 조작된 데이터인 데이터베이스 표시 값이 표시됩니다. REST 엔드포인트는 기본적으로 표시 값과 다를 수 있는 실제 값을 삽입하고 업데이트합니다. REST 엔드포인트에서 sysparm_input_display_value 요청 매개변수를 true로 설정하여 전달된 값을 표시 값으로 처리하도록 강제할 수 있습니다.

사용자 지정 쿼리 매개변수

REST API는 ServiceNow 사용 가능한 여러 API에서 다음 쿼리 매개변수를 사용하여 API 전반에 걸쳐 일관된 동작을 제공합니다. 이러한 매개변수를 사용하여 대규모 기록 세트의 페이지를 매김하고, 결과를 필터링하고, 단일 쿼리에서 반환되는 기록 수를 제한합니다.

REST API 요청의 닷워킹

해당 매개변수를 지원하는 REST API에 대한 요청에서 or sysparm_fields 매개변수를 sysparm_query 지정할 때 닷워킹을 사용할 수 있습니다.

sysparm_query의 닷워킹

매개변수에서 닷워킹으로 관련 기록 값을 사용하여 쿼리를 sysparm_query 필터링할 수 있습니다. 예를 들어 인시던트 회사 에 특정 종목 코드 값이 있는 모든 인시던트 기록을 검색할 수 있습니다.

https://<인스턴스>.service-now.com/api/now/table/incident?sysparm_query=company.stock_symbol=NYX

sysparm_fields의 닷워킹

매개변수에서 sysparm_fields 닷워킹을 수행하여 여러 테이블의 필드 값을 볼 수 있습니다. 예를 들어 특정 역할을 가진 각 사용자의 이름, Sys_id 및 부서 와 역할 이름을 검색할 수 있습니다.

요청은 사용자와 역할 간의 다대다 관계를 정의하는 사용자 역할 [sys_user_has_role] 테이블에서 실행됩니다. 응답에는 사용자 [sys_user] 및 역할 [sys_user_role] 테이블의 필드 값이 포함됩니다.

https://<인스턴스>.service-now.com/api/now/table/sys_user_has_role?sysparm_fields=role%2Crole.name%2Cuser%2Cuser.name%2Cuser.sys_id%2Cuser.department&sysparm_query=role%3D3d43716d0f6002003a2d47bce1050e0d%5EORrole%3Dac73b52d0f6002003a2d47bce1050eec&sysparm_display_value=true

{
"result": [
  {
   "user.name": "Fred Johnson",
   "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
   "role.name": "support",
   "user.department": {
      "display_value": "Accounting",
      "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
    },
   "role": {
      "display_value": "support",
      "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/3d43716d0f6002003a2d47bce1050e0d"
    },
   "user": {
      "display_value": "Fred Johnson",
      "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
    }
  },
  {
   "user.name": "Fred Johnson",
   "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
   "role.name": "asset_mgmt",
      "user.department": {
      "display_value": "Accounting",
      "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
     },
    "role": {
       "display_value": "asset_mgmt",
       "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/ac73b52d0f6002003a2d47bce1050eec"
      },
    "user": {
       "display_value": "Fred Johnson",
       "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
       }
    }
  ]
}

REST API HTTP 응답 코드

REST 엔드포인트에 대한 호출은 HTTP 응답 코드를 반환합니다. 이러한 응답 코드를 사용하여 REST API가 제대로 실행되었는지 확인할 수 있습니다. 그렇지 않은 경우 엔드포인트는 오류 응답 코드를 반환합니다. 오류 응답의 정보를 사용하여 통화 형식과 관련된 문제를 해결합니다. 엔드포인트가 반환할 수 있는 표준 응답 코드 목록은 다음 문서를 참조하십시오 REST API HTTP 응답 코드. 특정 ServiceNow REST API에서 반환되는 응답 코드 목록은 REST API 참조를 참조하십시오.

REST API 보안

기본적으로 ServiceNow REST API는 기본 인증 또는 OAuth를 사용하여 REST API/엔드포인트에 대한 사용자 액세스 권한을 부여합니다. 다단계 인증을 사용하여 REST API에 액세스하도록 인스턴스를 구성할 수도 있습니다.

REST 엔드포인트 호출에서 지정하는 사용자 ID는 대화형 사용자와 동일한 방식으로 접근 통제의 대상이 됩니다. 각 요청에는 사용자 이름 및 암호와 같은 적절한 인증 정보가 필요합니다. 각 엔드포인트 요청에 엔드포인트에 액세스하기 위한 충분한 자격 증명이 있는 인증 헤더가 포함되어 있는지 확인합니다.

ServiceNow REST API는 기존 세션에 바인딩할 수 있는 쿠키도 지원합니다.

인증서를 사용하여 API 및 상호 인증에 대한 정보를 호출하려면 인증서 기반 인증을 참조하세요.

IP, 역할, 그룹과 같은 필터 기준이 있는 REST API 접근 정책을 사용하고 사용할 수 있는 API의 범위를 제한합니다.REST API Auth Scope REST API 접근 정책에 대한 자세한 내용은 REST API 접근 정책을 참조하십시오.

신뢰할 수 있는 외부 네트워크의 REST API 액세스 정책과 기본 REST 인증 수준을 사용하여 전역 REST API 수준에서 들어오는 요청을 차단하는 단일 정책을 만들 수 있습니다.

REST API 역할

사용자 인증 외에도 각 REST 엔드포인트는 엔드포인트에 액세스하는 데 필요한 역할에 대한 요구 사항이 다를 수 있습니다. 일부는 관리자 역할이 필요하며 다른 일부는 API 특정 역할이 필요합니다. 역할 요구 사항은 REST API/엔드포인트와 연결된 ACL(접근 제어 목록)에 지정됩니다. 각 REST API/엔드포인트의 유효한 역할에 대한 자세한 내용은 REST API 참조 를 참조하거나 시스템 보안> 접근 제어(ACL)를 통해 인스턴스 내에서 API/엔드포인트에 대한 연결된 ACL을 찾습니다.

REST API ACL

REST API ACL은 REST API 또는 엔드포인트에 액세스하기 위해 사용자가 충족해야 하는 필요한 역할 및 조건과 같은 기준을 정의합니다 ServiceNow . 테이블 API 및 첨부 파일 API ACL과 같은 전체 REST API 또는 PUT 메서드에만 MetricBase 적용되는 clotho_rest_put ACL과 같은 개별 엔드포인트에 대해 단일 ACL을 정의할 수 있습니다.

다음 ServiceNow REST API ACL은 기본 시스템에서 사용할 수 있지만 기본적으로 비활성화되어 있습니다. 다른 ServiceNow 모든 REST API ACL은 기본적으로 활성화됩니다.

• 테이블 API
• API 집계
• 임포트 세트 API
• 첨부 파일 API

ACL에 대한 자세한 내용은 접근 제어 목록 규칙을 참조하십시오.

REST API 테이블 접근

기본적으로 기본 시스템 테이블, 전역 테이블 및 범위가 지정된 테이블을 포함한 모든 테이블은 웹 서비스를 통해 액세스할 수 있습니다. 웹 서비스를 통해 테이블에 액세스하려면 기본 인증 및 ACL과 같은 웹 서비스 보안 요구 사항을 충족해야 합니다. ACL 때문에 호출 엔터티에 대한 권한이 없는 필드는 REST 쿼리 응답에 반환되지 않습니다.

인증이나 권한 부여 없이 테이블에 대한 액세스를 허용하려면 활성 상태인 공용 페이지 [sys_public] 테이블에 테이블 이름을 추가합니다. REST 인터페이스는 여전히 연결된 테이블에 정의된 모든 ACL을 적용합니다. ACL 적용이 원하는 동작이 아닌 경우 테이블에서 ACL을 비활성화해야 합니다. 그러나 API를 공개하면 공개 액세스가 인스턴스의 데이터를 업데이트할 수 있으므로 사용하지 않는 것이 좋습니다.

테이블 애플리케이션 액세스 설정의 웹 서비스를 통해 이 테이블에 대한 액세스 허용 확인란을 사용하여 테이블에 대한 직접 웹 서비스 액세스를 제어할 수도 있습니다. 테이블과 웹 서비스 상호작용을 활성화하려면 이 확인란을 선택해야 합니다.

인바운드 REST에 대한 다단계 인증

Yokohama 릴리스부터는 기본 인증을 사용하는 REST API 인증에 MFA(Multi-factor Authentication)가 기본적으로 필요하지 않습니다. 자세한 내용은 이 KB 문서를 참조하십시오.

다단계 인증 REST 응답

MFA 인증 요청에 대한 응답은 제공된 자격 증명 및 MFA 토큰의 유효성에 따라 달라집니다.

REST API CORS 지원

REST API는 CORS(교차 원본 자원 공유) 보안을 지원합니다. CORS 지원을 사용하면 각 REST API에 액세스할 수 있는 도메인을 정의할 수 있습니다. 도메인에 대한 CORS 규칙을 정의하면 해당 도메인의 교차 원본 요청을 허용할 수 있습니다. CORS 규칙이 없는 도메인에서는 교차 원본 요청을 할 수 없습니다.

다른 도메인의 특정 API/엔드포인트, HTTP 메서드 및 헤더에 대한 액세스만 허용하도록 CORS를 구성할 수 있습니다. 예를 들어 GET 작업만 허용하도록 특정 도메인에서 테이블 API에 대한 요청을 제한할 수 있습니다.

인스턴스에 정의된 CORS 규칙을 보려면 다음으로 이동하십시오. 시스템 웹 서비스 > CORS 규칙.

속성을 false로 설정 glide.rest.cors.enabled 하여 인스턴스에 대한 CORS 지원을 사용하지 않도록 설정할 수 있습니다. false인 경우 수신 REST 요청에 대해 CORS 평가가 수행되지 않습니다. 기본적으로 이 속성은 true 입니다.

REST API 탐색기

REST API 탐색기는 인스턴스의 ServiceNow 정보를 사용하여 REST 요청을 빌드하고 보내는 데 사용할 수 있는 엔드포인트, 메서드 및 변수 목록을 제공하는 도구입니다.

요청을 빌드한 후 REST API 탐색기는 요청을 시작하는 데 사용할 수 있는 여러 프로그래밍 언어의 코드 샘플과 자세한 요청 및 응답 정보를 제공합니다.

REST API 탐색기에 액세스하려면 인스턴스에서 시스템 웹 서비스 > REST API 탐색기. REST API 탐색기에 액세스하려면 rest_api_explorer 역할이 있어야 합니다. 자세한 내용은 REST API 탐색기 사용을 참조하십시오.

Automated Test Framework 지원

Automated Test Framework(ATF)는 인바운드 REST 테스트 단계를 지원합니다. 사용자가 만든 사용자 지정 인바운드 REST API에 대한 자동화된 테스트를 만들 수 있습니다. 사용자 지정 REST API에 대한 테스트를 만들면 업그레이드 테스트가 간소화되고 REST API에 대한 수정 사항이 이전 버전과 호환되는지 확인할 수 있습니다.

REST 클라이언트 애플리케이션 예제

REST 웹 서비스를 사용하여 통합을 시연하는 데 몇 가지 예제 REST 클라이언트 애플리케이션 및 소스 코드를 사용할 수 있습니다. 예제 REST 클라이언트 애플리케이션에서는 NodeJS 또는 iOS 애플리케이션과 같은 외부 애플리케이션에서 REST API를 사용하는 ServiceNow 방법을 보여줍니다.

예제는 오픈 소스이며 커뮤니티에서 사용할 수 있습니다. 이러한 예제 애플리케이션을 사용하여 REST 기능에 익숙해지거나 고유한 REST 클라이언트 애플리케이션을 만드는 시작점으로 사용할 수 있습니다.

rest_api_explorer 역할을 가진 사용자는 다음으로 이동하여 사용 가능한 클라이언트 애플리케이션 목록에 액세스할 수 있습니다. 시스템 웹 서비스 > REST > 예제 클라이언트 앱.

애플리케이션 목록을 볼 때 애플리케이션을 클릭하여 GitHub에서 호스팅되는 소스 코드 및 추가 설명서를 봅니다.

개발자 교육

ServiceNow® 개발자 사이트에서 인바운드 REST 통합 및 아웃바운드 REST 통합에 대한 교육을 받을 수 있습니다.

추가 정보

REST API 섹션의 나머지 부분에는 REST API를 사용하는 ServiceNow 특정 구현을 설명하고 REST API에서 사용되는 다양한 데이터 요소를 설명하는 참조 정보를 제공하는 "방법" 주제가 ServiceNow 포함되어 있습니다.