지식 관리 REST API

릴리스 버전: Xanadu

업데이트 날짜 2024년 08월 01일

읽기43분

지식 관리 API는 최다 조회 및 추천 지식 문서의 목록을 검색, 보기 및 가져오기 위한 엔드포인트를 제공합니다.

Knowledge API(sn_km_api) 플러그인이 활성화된 경우에만 이 API를 사용할 수 있습니다. 지식 관리 REST API는 원래 OrlandoServiceNow Store.

주:

지식 관리 REST API는 공개적으로 액세스할 수 있으며 공개적으로 액세스할 수 있는 모든 지식베이스를 인증되지 않은 사용자를 포함한 모든 사용자가 사용할 수 있도록 합니다. 버전 1.0.1 이상에서는 API를 편집할 수 있게 되어 관리자가 API와 연관된 Scripted REST Service Security 탭에서 인증 필요 플래그를 선택하여 인증되지 않은 액세스를 허용하지 않도록 각 엔드포인트를 구성할 수 있습니다.

다른 도메인에서 지식 관리 REST API 엔드포인트를 사용할 수 있도록 하려면 CORS(교차 원본 자원 공유) 규칙을 정의합니다. 자세한 내용은 CORS 규칙 정의를 참조하세요.

이 REST API를 사용하여 범위가 지정된 지식베이스에서 문서를 보려면 제한된 호출자 액세스 권한[sys_restricted_caller_access] 테이블의 요청 범위에서 sn_km_api 범위 읽기 액세스를 허용하십시오. 자세한 내용은 Define cross-scope access to an application resource를 참조하십시오.

기본적으로 이 API에는 인증되지 않은 사용자와 snc_external 사용자에 대한 시간당 500개의 속도 제한이 있습니다. 속도 제한에 대한 자세한 내용은 인바운드 REST API 속도 제한을 참조하세요.

지식 관리 - GET /knowledge/articles

다양한 매개변수를 사용하여 검색하고 필터링할 수 있는 KB(지식베이스) 문서 목록을 반환합니다.

URL 형식

버전이 지정된 URL: /api/sn_km_api/{api_version}/knowledge/articles

기본 URL: /api/sn_km_api/knowledge/articles

지원되는 요청 매개변수

표 1. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열

표 2. 쿼리 매개변수
이름	설명
필터	결과 집합을 필터링하는 데 사용할 인코딩된 쿼리입니다. 구문: `filter=<attr><operator><value>`. `<attr>`: 테이블 열의 이름입니다. `<operator>`: 유효한 값은 다음과 같습니다. =: 정확히 <value>와 일치합니다. !=: <value>와 일치하지 않습니다. ^: 둘 이상의 조건과 논리적으로 AND를 지정할 수 있습니다. ^OR: 둘 이상의 조건을 논리적으로 OR로 지정할 수 있습니다. LIKE: <attr>에는 지정된 문자열이 포함되어 있습니다. 데이터 유형이 문자열인 <attr> 필드에만 작동합니다. STARTSWITH: <attr>은 지정된 문자열로 시작합니다. 데이터 유형이 문자열인 <attr> 필드에만 작동합니다. ENDSWITH: <attr>은 지정된 문자열로 끝납니다. 데이터 유형이 문자열인 <attr> 필드에만 작동합니다. `<value>`: 일치시킬 값입니다. 모든 매개변수는 대/소문자를 구분합니다. 쿼리에는 다음과 같은 항목이 두 개 이상 포함될 수 있습니다. `filter=<attr><operator><value>[<operator><attr><operator><value>]`. 데이터 유형: 문자열 기본값: 비어 있음
필드	결과에 상세 정보를 표시하기 위한 지식 [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
KB	결과를 제한할 지식베이스 [kb_knowledge_base] 테이블에서 sys_ids 쉼표로 구분된 지식베이스 목록입니다. 데이터 유형: 문자열
언어	결과를 제한할 두 글자 ISO 639-1 언어 코드 형식의 쉼표로 구분된 언어 목록입니다. 또는 인스턴스에 설치된 모든 유효한 언어로 검색하려면 'all'을 입력하십시오. 데이터 유형: 문자열 기본값: 사용자의 세션 언어 또는 en
제한	반환할 최대 기록 수입니다. 이례적으로 큰 limit 값은 시스템 성능에 영향을 미칠 수 있습니다. 이 기록 수를 초과하는 요청의 경우 매개변수를 offset 사용하여 기록 검색을 페이지 매김합니다. 데이터 유형: 숫자 기본값: 30
오프셋	기록 검색을 시작할 시작 기록 인덱스입니다. 이 값을 사용하여 기록 검색을 페이지 매김합니다. 이 기능을 사용하면 기록 수와 관계없이 관리 가능한 작은 청크로 모든 기록을 검색할 수 있습니다. 예를 들어 이 엔드포인트가 처음 호출 offset 될 때 "0"으로 설정됩니다. 사용 가능한 모든 레코드를 페이징하려면 모든 레코드의 끝에 도달할 때까지 `offset=offset+limit` 를 사용합니다. 데이터 유형: 숫자 기본값: 0
쿼리	검색할 텍스트는 비워둘 수 있습니다. 데이터 유형: 문자열

표 3. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
없음

헤더

다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에서 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

표 4. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

표 5. 응답 헤더
헤더	설명
없음

상태 코드

다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

표 6. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.
401	승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
500	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다.

응답 본문 매개변수(JSON 또는 XML)


이름	설명
문서	응답으로 반환된 문서 목록입니다. 데이터 유형: 배열 `"articles": [ { "fields": {Object}, "link": "String", "id": "String", "number": "String", "rank": Number, "score": Number, "snippet": "String", "title": "String" } ]`
문서.필드	요청된 필드의 값입니다(있는 경우). 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
문서.필드.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "label": "String", "name": "String", "type": "String", "value": "String" }`
문서.필드.<field_name>.display_value	요청된 필드의 값을 표시합니다. 데이터 유형: 문자열
문서.필드.<field_name>.레이블	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
articles.fields.<field_name>.name	요청된 필드의 이름입니다. 일치 <field_name>. 데이터 유형: 문자열
문서.필드.<field_name>.유형	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
문서.필드.<field_name>.값	요청된 필드의 값입니다. 데이터 유형: 문자열
articles.id	지식 [kb_knowledge] 테이블에서 sys_id 지식 문서입니다. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
기사.번호	지식 문서 번호입니다. 데이터 유형: 문자열
기사.순위	이 검색과 관련된 문서의 검색 순위입니다. 데이터 형식: 숫자(부동)
기사.스니펫	지식 문서의 작은 부분을 보여주는 텍스트입니다. 데이터 유형: 문자열
기사.점수	관련성 점수, 점수에 따라 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
기사.제목	지식 문서에 대한 짧은 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수에 대한 메타 정보입니다. 데이터 유형: 객체 `"meta": { "count": Number, "end": Number, "fields": "String", "filter": "String", "kb": "String", "language": "String", "query": "String", "start": Number, "status": {Object}, "ts_query_id": "String" }`
meta.count (메타.카운트)	사용 가능한 KB 문서 수입니다. 데이터 유형: 숫자
메타.end	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
meta.fields	문서의 필드입니다. 데이터 유형: 문자열
meta.filter	데이터를 가져오는 데 사용되는 필터입니다. 데이터 유형: 문자열
meta.kb 님	지식베이스 문서 sys_ids 목록입니다. 데이터 유형: 문자열
meta.language (메타 언어)	요청된 KB 문서의 쉼표로 구분된 언어 목록입니다. 데이터 유형: 문자열
meta.query (메타 쿼리)	지정된 요청 쿼리입니다. 데이터 유형: 문자열
meta.start (메타 시작)	결과 집합의 시작 인덱스입니다. 데이터 유형: 숫자
meta.status (메타 상태)	호출의 상태입니다. 데이터 유형: 문자열
meta.ts_query_id입니다.	쿼리의 Sys_id입니다. 데이터 유형: 문자열

cURL 요청

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/articles?query=Windows&limit=2&fields=short_description&fields=sys_class_name" \
--request GET \
--header "Accept:application/xml" \
--user "username":"password"

{
  "result": {
    "meta": {
      "start": 0,
      "end": 2,
      "fields": "short_description,sys_class_name",
      "query": "Windows",
      "filter": "",
      "kb": "",
      "language": "en",
      "count": 19,
      "ts_query_id": "7976f36129c30410f877796e70786991",
      "status": {
        "code": 200
      }
    },
    "articles": [
      {
        "link": "?sys_kb_id=9e528db1474321009db4b5b08b9a71a6&id=kb_article_view&sysparm_rank=1&sysparm_tsqueryId=7976f36129c30410f877796e70786991",
        "rank": 1,
        "id": "kb_knowledge:9e528db1474321009db4b5b08b9a71a6",
        "title": "Windows: Should I upgrade to Windows 8.x?",
        "snippet": "    Should I upgrade to <B>Windows</B> 8.x? <B>Windows</B> 8.x is designed for using touch, mouse, and keyboard the <B>Windows</B> Store and access apps such as Calendar, Mail, and Messaging. By most accounts, <B>Windows</B> boot times, smaller memory footprint, and more free memory for the programs you run. <B>Windows</B>",
        "score": 14.869,
        "number": "KB0000020",
        "fields": {
          "short_description": {
            "display_value": "Windows: Should I upgrade to Windows 8.x?\n\t\t",
            "name": "short_description",
            "label": "Short description",
            "type": "string",
            "value": "Windows: Should I upgrade to Windows 8.x?\n\t\t"
          },
          "sys_class_name": {
            "display_value": "Knowledge",
            "name": "sys_class_name",
            "label": "Class",
            "type": "sys_class_name",
            "value": "kb_knowledge"
          }
        }
      },
      {
        "link": "?sys_kb_id=3b07857187032100deddb882a2e3ec20&id=kb_article_view&sysparm_rank=2&sysparm_tsqueryId=7976f36129c30410f877796e70786991",
        "rank": 2,
        "id": "kb_knowledge:3b07857187032100deddb882a2e3ec20",
        "title": "What is the Windows key?",
        "snippet": "What is the <B>Windows</B> key? The <B>Windows</B> key is a standard key on most keyboards on computers built to use a <B>Windows</B> operating system. It is labeled with a <B>Windows</B> logo, and is usually placed between on the right side as well. Pressing Win (the <B>Windows</B> key) on its own will do the following: <B>Windows</B> 8.x: Toggle",
        "score": 13.4826,
        "number": "KB0000017",
        "fields": {
          "short_description": {
            "display_value": "What is the Windows key?\t\t",
            "name": "short_description",
            "label": "Short description",
            "type": "string",
            "value": "What is the Windows key?\t\t"
          },
          "sys_class_name": {
            "display_value": "Knowledge",
            "name": "sys_class_name",
            "label": "Class",
            "type": "sys_class_name",
            "value": "kb_knowledge"
          }
        }
      }
    ]
  }
}

지식 관리 - GET /knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

지식 문서 첨부 파일을 파일로 반환합니다.

URL 형식

버전이 지정된 URL: /api/sn_km_api/{api_version}/knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

기본 URL: /api/sn_km_api/knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

지원되는 요청 매개변수

표 7. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열
article_sys_id	검색하려는 첨부 파일이 있는 지식 문서의 Sys_id입니다. 지식베이스 [kb_knowledge] 테이블에 있습니다. 데이터 유형: 문자열
attachment_sys_id	첨부 파일이 속한 기록의 Sys_id입니다. 데이터 유형: 문자열

표 8. 쿼리 매개변수
이름	설명
없음

표 9. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
없음

헤더

표 10. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

표 11. 응답 헤더
헤더	설명
컨텐츠-형식	응답의 콘텐츠 유형(예: `image/gif` 또는 `/`)입니다.

상태 코드

다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

표 12. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.
401	승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
404	찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
500	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

응답 본문 매개변수


이름	설명
파일이 응답으로 반환됩니다.

샘플 cURL 요청

curl "https://instance.service-now.com/api/sn_km_api/knowledge/articles/0b48fd75474321009db4b5b08b9a71c2/attachments/fedf5614294f4010f877796e70786956" \
--request GET \
--header "Accept:*/*" \
--user "username":"password"

Binary response not shown (file is returned as a response).

지식 관리 - GET /knowledge/articles/featured

가장 많이 본 지식 문서와 추천 지식 문서 목록을 반환합니다.

URL 형식

버전이 지정된 URL: /api/sn_km_api/{api_version}/knowledge/articles/featured

기본 URL: /api/sn_km_api/knowledge/articles/featured

지원되는 요청 매개변수

표 13. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열

표 14. 쿼리 매개변수
이름	설명
필드	결과에 상세 정보를 표시하기 위한 지식 [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
KB	결과를 제한할 지식베이스 [kb_knowledge_base] 테이블에서 sys_ids 쉼표로 구분된 지식베이스 목록입니다. 데이터 유형: 문자열
언어	결과를 제한할 두 글자 ISO 639-1 언어 코드 형식의 쉼표로 구분된 언어 목록입니다. 또는 인스턴스에 설치된 모든 유효한 언어로 검색하려면 'all'을 입력하십시오. 데이터 유형: 문자열 기본값: 사용자의 세션 언어 또는 en
제한	반환할 최대 기록 수입니다. 이례적으로 큰 limit 값은 시스템 성능에 영향을 미칠 수 있습니다. 이 기록 수를 초과하는 요청의 경우 매개변수를 offset 사용하여 기록 검색을 페이지 매김합니다. 데이터 유형: 숫자 기본값: 30
오프셋	기록 검색을 시작할 시작 기록 인덱스입니다. 이 값을 사용하여 기록 검색을 페이지 매김합니다. 이 기능을 사용하면 기록 수와 관계없이 관리 가능한 작은 청크로 모든 기록을 검색할 수 있습니다. 예를 들어 이 엔드포인트가 처음 호출 offset 될 때 "0"으로 설정됩니다. 사용 가능한 모든 레코드를 페이징하려면 모든 레코드의 끝에 도달할 때까지 `offset=offset+limit` 를 사용합니다. 데이터 유형: 숫자 기본값: 0

표 15. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
없음

헤더

표 16. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

표 17. 응답 헤더
헤더	설명
없음

상태 코드

다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

표 18. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.
401	승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
500	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다.

응답 본문 매개변수(JSON 또는 XML)


이름	설명
문서	응답으로 반환된 문서 목록입니다. 데이터 유형: 배열 `"articles":[ { "fields": {Object}, "id": "String", "link": "String", "number": "String", "rank": Number, "score": Number, "snippet": "String", "title": "String" } ]`
문서.필드	요청된 필드의 값입니다(있는 경우). 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
문서.필드.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "name": "String", "label": "String", "type": "String", "value": "String" }`
문서.필드.<field_name>.display_value	요청된 필드의 값을 표시합니다. 데이터 유형: 문자열
articles.fields.<field_name>.name	요청된 필드의 이름입니다. 일치 <field_name>. 데이터 유형: 문자열
문서.필드.<field_name>.레이블	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
문서.필드.<field_name>.유형	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
문서.필드.<field_name>.값	요청된 필드의 값입니다. 데이터 유형: 문자열
articles.id	지식 [kb_knowledge] 테이블에서 sys_id 지식 문서입니다. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
기사.번호	지식 문서 번호입니다. 데이터 유형: 문자열
기사.순위	이 검색과 관련된 문서의 검색 순위입니다. 데이터 형식: 숫자(부동)
기사.점수	관련성 점수, 점수에 따라 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
기사.스니펫	지식 문서의 작은 부분을 보여주는 텍스트입니다. 데이터 유형: 문자열
기사.제목	지식 문서에 대한 짧은 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수에 대한 메타 정보입니다. 데이터 유형: 객체 `"meta": { "count": Number, "end": Number, "fields": "String", "filter": "String", "kb": "String", "language": "String", "query": "String", "start": Number, "status": {Object}, "ts_query_id": "String" }`
meta.count (메타.카운트)	사용 가능한 KB 문서 수입니다. 데이터 유형: 숫자
메타.end	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
meta.fields	문서의 필드입니다. 데이터 유형: 문자열
meta.filter	데이터를 가져오는 데 사용되는 필터입니다. 데이터 유형: 문자열
meta.kb 님	지식베이스 문서 sys_ids 목록입니다. 데이터 유형: 문자열
meta.language (메타 언어)	요청된 KB 문서의 쉼표로 구분된 언어 목록입니다. 데이터 유형: 문자열
meta.query (메타 쿼리)	지정된 요청 쿼리입니다. 데이터 유형: 문자열
meta.start (메타 시작)	결과 집합의 시작 인덱스입니다. 데이터 유형: 숫자
meta.status (메타 상태)	호출의 HTTP 상태입니다. 데이터 유형: 문자열
meta.ts_query_id입니다.	쿼리의 Sys_id입니다. 데이터 유형: 문자열

cURL 요청

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/articles/featured?fields=short_description&limit=3" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "meta": {
      "start": 0,
      "end": 3,
      "fields": "short_description",
      "query": "homepage",
      "filter": "",
      "kb": "",
      "language": "en",
      "status": {
        "code": 200
      },
      "count": 2
    },
    "articles": [
      {
        "link": "?id=kb_article_view&sys_kb_id=f27d7f79c0a8011b0018f9d700d2b9aa",
        "id": "kb_knowledge:f27d7f79c0a8011b0018f9d700d2b9aa",
        "title": "Email Interruption Tonight at 11:00 PM Eastern",
        "snippet": " If the site is UP but you cant access the page, try one of the below solutions: Browser Related Problems Force a full refresh for the site. This can be achieved by pressing CTRL + F5 keys at the same time on your favourite browser (Firefox, Chrome, Explorer, etc.) Try alternative urls such as m.outlook.com Clear the temporary cache and cookies ",
        "score": -1,
        "number": "KB0000002",
        "fields": {
          "short_description": {
            "display_value": "Email Interruption Tonight at 11:00 PM Eastern\n\t\t",
            "name": "short_description",
            "label": "Short description",
            "type": "string",
            "value": "Email Interruption Tonight at 11:00 PM Eastern\n\t\t"
          }
        }
      },
      {
        "link": "?id=kb_article_view&sys_kb_id=f2765f9fc0a8011b0120ec1b352bf09b",
        "id": "kb_knowledge:f2765f9fc0a8011b0120ec1b352bf09b",
        "title": "Sales Force Automation is DOWN",
        "snippet": "  On Friday, January 20th, we experienced a widespread outage that affected all Zoho services. The outage started around 8:13 am Pacific Time. Zoho services started coming back online for customer use at 3:49 pm, and all services were fully restored at 6:22 pm PST. We absolutely realize how important our services are for businesses and users who",
        "score": -1,
        "number": "KB0000001",
        "fields": {
          "short_description": {
            "display_value": "Sales Force Automation is DOWN",
            "name": "short_description",
            "label": "Short description",
            "type": "string",
            "value": "Sales Force Automation is DOWN"
          }
        }
      }
    ]
  }
}

지식 관리 - GET /knowledge/articles/{id}

특정 지식 문서 컨텐츠와 해당 필드 값을 반환합니다.

URL 형식

버전이 지정된 URL: /api/sn_km_api/{api_version}/knowledge/articles/{id}

기본 URL: /api/sn_km_api/knowledge/articles/{id}

지원되는 요청 매개변수

표 19. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열
id	지식 [kb_knowledge] 테이블에 있는 지식 문서의 Sys_id 또는 KB(지식베이스) 번호입니다. 데이터 유형: 문자열

표 20. 쿼리 매개변수
이름	설명
필드	결과에 상세 정보를 표시하기 위한 지식 [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
언어	두 글자 ISO 639-1 언어 코드; 예를 들어 프랑스어의 경우 "fr"입니다. 검색에서 지식 문서 KB 번호를 id 사용하고 문서의 번역된 버전이 지정된 언어로 제공되는 경우에만 결과가 표시됩니다. 주: 매개변수를 id KB 번호(sys_id 아님)로 설정할 때만 유효합니다. 데이터 유형: 문자열
search_id	를 사용하지 search_rank않는 한 선택 사항입니다. 이 문서를 반환한 검색의 고유 식별자입니다. 요소를 반환하는 다음 API 중 하나를 사용하여 검색할 search_id 수 있습니다.articles.id 지식 관리 - GET /knowledge/articles 지식 관리 - GET /knowledge/articles/featured 지식 관리 - 지식/문서/most_viewed 가져오기 and search_rank 매개변수를 search_id 전달하면 문서 뷰 수가 증가하고 지식 사용 [kb_use] 테이블에 문서에 대한 항목이 기록됩니다. 지식베이스 [kb_view2] 페이지에서 증가된 조회수를 확인할 수도 있습니다. 데이터 유형: 문자열
search_rank	를 사용하지 search_id않는 한 선택 사항입니다. 요소를 반환하는 다음 API 중 하나를 사용하여 검색할 수 있는 클릭률에 따른 문서 검색 순위입니다.articles.rank 지식 관리 - GET /knowledge/articles 지식 관리 - GET /knowledge/articles/featured 지식 관리 - 지식/문서/most_viewed 가져오기 데이터 유형: 숫자
update_view	지식 사용 [kb_use] 테이블의 문서 조회 수를 업데이트하고 항목을 기록합니다. True는 독립 실행형 매개 변수로 존재하거나 true로 설정되어 있는지 여부입니다. 주: 및 search_rankupdate_view 와 함께 search_id 전달 update_view 하면 조회수가 이미 증가하므로 무시됩니다. 데이터 형식: `"true"`, `"false"` 또는 전혀 설정하지 않았는지에 관계없이 전달될 때 항상 true로 처리되는 부울입니다.

표 21. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
없음

헤더

표 22. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

표 23. 응답 헤더
헤더	설명
없음

상태 코드

다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

표 24. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.
401	승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
500	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다.

응답 본문 매개변수(JSON 또는 XML)


이름	설명
첨부 파일	첨부 파일이 있는 경우 각 인스턴스에 대한 첨부 파일 상세 정보를 제공합니다. `display_attachments = true`인 경우에만 표시됩니다. 데이터 유형: 배열 `"attachments": [ { "file_name": "String", "size_bytes": "String", "state": "String", "sys_id": "String" } ]`
attachments.file_name	첨부 파일의 파일 이름입니다. 데이터 유형: 문자열
attachments.size_bytes	파일 크기입니다. 데이터 유형: 문자열 단위: 바이트
첨부 파일.상태	상태 가능한 값: 사용 가능 available_conditionally not_available 보류 중 데이터 유형: 문자열
attachments.sys_id	첨부 파일의 Sys_id입니다. 데이터 유형: 문자열
컨텐츠	문서의 전체 HTML 콘텐츠입니다. 데이터 유형: 문자열
display_attachments	해당 문서에 대한 플래그가 display_attachments 활성 상태인지 여부를 나타내는 플래그입니다. 첨부 파일은 지식 문서 기록에서 true(활성)인 경우에만 display_attachments 반환됩니다. true: display_attachments 활성 상태입니다. false: display_attachments 비활성 상태입니다. 데이터 유형: 부울
embedded_content	포함된 콘텐츠가 포함된 각 첨부 파일을 sys_id별로 나열하고 관련 첨부 파일 정보를 포함합니다. `display_attachments = true`인 경우에만 표시됩니다. 데이터 유형: 배열 `"attachments": [ { "file_name": "String", "size_bytes": "String", "state": "String", "sys_id": "String" } ]`
embedded_content.파일_이름	첨부 파일의 이름입니다. 데이터 유형: 문자열
embedded_content.크기_바이트	첨부 파일의 크기입니다. 데이터 유형: 문자열 단위: 바이트
embedded_content.state	첨부 파일의 상태입니다. 가능한 값: 사용 가능 available_conditionally not_available 보류 중 데이터 유형: 문자열
embedded_content.sys_id	첨부 파일의 Sys_id입니다. 데이터 유형: 문자열
필드	요청된 필드의 값(있는 경우)입니다. 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
fields.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "label": "String", "name": "String", "type": "String", "value": "String" }`
fields.<field_name>.display_value	요청된 필드의 값을 표시합니다. 데이터 유형: 문자열
fields.<field_name>.label	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
필드.<field_name>.이름	요청된 필드의 이름입니다. 일치 <field_name>. 데이터 유형: 문자열
필드.<field_name>.유형	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
fields.<field_name>.value	요청된 필드의 값입니다. 데이터 유형: 문자열
언어	현재 문서에 대한 두 글자 ISO 639-1 언어 코드(번역이 가능한 경우). 데이터 유형: 문자열
언어	지식 문서의 번역된 각 버전(번역된 경우)에 대해 `"languages": [ { "label": "String", "language": "String", "sys_id": "String" } ]` 데이터 유형: 배열
languages.레이블	언어에 대한 문자열 표현입니다. 데이터 유형: 문자열
languages.language	두 글자 ISO 639-1 코드 언어. 데이터 유형: 문자열
languages.sys_id	지식 문서의 번역된 버전의 고유 식별자입니다. 데이터 유형: 문자열
번호	문서 번호입니다. 데이터 유형: 문자열
short_description	지식 문서에 대한 짧은 설명 또는 제목입니다. 데이터 유형: 문자열
sys_id	지식 [kb_knowledge] 테이블에서 sys_id 지식 문서입니다. 데이터 유형: 문자열
템플릿	반환된 문서가 템플릿인지 여부를 나타내는 플래그입니다. 가능한 값: true: 문서가 템플릿입니다. false: 문서가 템플릿이 아닙니다. 데이터 유형: 부울
template_table	템플릿 테이블의 이름으로, 지식 문서가 템플릿인 경우에만 반환됩니다. 데이터 유형: 문자열

cURL 요청

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/articles/0b48fd75474321009db4b5b08b9a71c2?search_id=spam&search_rank=26.426" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "content": "<p><span style=\"font-size: 18pt;\"><strong>How to Deal with Spam</strong></span></p>\r\n<p>Spam has increasingly become a problem on the Internet. While every Internet user receives some spam, email  addresses posted to web sites or in newsgroups and chat rooms attract the most spam.</p>\r\n<p>To reduce the amount of spam you receive:</p>\r\n<p>
    "template": false,
    "number": "KB0000011",
    "sys_id": "0b48fd75474321009db4b5b08b9a71c2",
    "short_description": "How to Deal with Spam",
    "display_attachments": true,
    "attachments": [
      {
        "sys_id": "dc27ae18294f4010f877796e707869c8",
        "file_name": "image.jpg",
        "size_bytes": "66792",
        "state": "available_conditionally"
      },
      {
        "sys_id": "fedf5614294f4010f877796e70786956",
        "file_name": "attachment.txt",
        "size_bytes": "75",
        "state": "available_conditionally"
      }
    ],
    "embedded_content": []
  }
}

샘플 cURL 요청(update_view)

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/KB0000020?update_view=' \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "content": "<p> </p>\r\n<p> </p>\r\n<p><strong><span style=\"font-size: 18pt;\">Should I upgrade to Windows 8.x?</span></strong></p>\r\n<p>Windows 8.x is designed for using touch, mouse, and keyboard together, on hardware ranging from touch-enabled tablets and laptops to PCs and all-in-one computers...(intentionally truncated)</p>",
    "template": false,
    "number": "KB0000020",
    "sys_id": "9e528db1474321009db4b5b08b9a71a6",
    "short_description": "Windows: Should I upgrade to Windows 8.x?\t\t",
    "display_attachments": true,
    "attachments": [],
    "embedded_content": []
  }
}

지식 관리 - 지식/문서/most_viewed 가져오기

최다 조회수가 우선순위가 지정된 지식 문서 목록을 반환합니다.

URL 형식

버전이 지정된 URL: /api/sn_km_api/{api_version}/knowledge/articles/most_viewed

기본 URL: /api/sn_km_api/knowledge/articles/most_viewed

지원되는 요청 매개변수

표 25. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열

표 26. 쿼리 매개변수
이름	설명
필드	결과에 상세 정보를 표시하기 위한 지식 [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
KB	결과를 제한할 지식베이스 [kb_knowledge_base] 테이블에서 sys_ids 쉼표로 구분된 지식베이스 목록입니다. 데이터 유형: 문자열
언어	결과를 제한할 두 글자 ISO 639-1 언어 코드 형식의 쉼표로 구분된 언어 목록입니다. 또는 인스턴스에 설치된 모든 유효한 언어로 검색하려면 'all'을 입력하십시오. 데이터 유형: 문자열 기본값: 사용자의 세션 언어 또는 en
제한	반환할 최대 기록 수입니다. 이례적으로 큰 limit 값은 시스템 성능에 영향을 미칠 수 있습니다. 이 기록 수를 초과하는 요청의 경우 매개변수를 offset 사용하여 기록 검색을 페이지 매김합니다. 데이터 유형: 숫자 기본값: 30
오프셋	기록 검색을 시작할 시작 기록 인덱스입니다. 이 값을 사용하여 기록 검색을 페이지 매김합니다. 이 기능을 사용하면 기록 수와 관계없이 관리 가능한 작은 청크로 모든 기록을 검색할 수 있습니다. 예를 들어 이 엔드포인트가 처음 호출 offset 될 때 "0"으로 설정됩니다. 사용 가능한 모든 레코드를 페이징하려면 모든 레코드의 끝에 도달할 때까지 `offset=offset+limit` 를 사용합니다. 데이터 유형: 숫자 기본값: 0

표 27. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
없음

헤더

표 28. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

표 29. 응답 헤더
헤더	설명
없음

상태 코드

다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

표 30. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.
401	승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
500	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다.

응답 본문 매개변수(JSON 또는 XML)


이름	설명
문서	응답으로 반환된 문서 목록입니다. 데이터 유형: 배열 `[ { "fields": {Object}, "id": "String", "link": "String", "number": "String", "rank": Number, "score": Float, "snippet": "String", "title": "String" } ]`
문서.필드	요청된 필드의 값(있는 경우)입니다. 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
문서.필드.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "label": "String", "name": "String", "type": "String", "value": "String" }`
문서.필드.<field_name>.display_value	요청된 필드의 값을 표시합니다. 데이터 유형: 문자열
문서.필드.<field_name>.레이블	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
articles.fields.<field_name>.name	요청된 필드의 이름입니다. 일치 <field_name>. 데이터 유형: 문자열
문서.필드.<field_name>.유형	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
문서.필드.<field_name>.값	요청된 필드의 값입니다. 데이터 유형: 문자열
articles.id	지식 [kb_knowledge] 테이블에서 sys_id 지식 문서입니다. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
기사.번호	지식 문서 번호입니다. 데이터 유형: 문자열
기사.순위	이 검색과 관련된 문서의 검색 순위입니다. 데이터 형식: 부동 소수점
기사.점수	관련성 점수, 점수에 따라 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
기사.스니펫	지식 문서의 작은 부분을 보여주는 텍스트입니다. 데이터 유형: 문자열
기사.제목	지식 문서에 대한 짧은 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수에 대한 메타 정보입니다. 데이터 유형: 객체 `"meta": { "count": Number, "end": Number, "fields": "String", "filter": "String", "kb": "String", "language": "String", "query": "String", "start": Number, "status": {Object}, "ts_query_id": "String" }`
meta.count (메타.카운트)	사용 가능한 KB 문서 수입니다. 데이터 유형: 숫자
메타.end	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
meta.fields	문서의 필드입니다. 데이터 유형: 문자열
meta.filter	데이터를 가져오는 데 사용되는 필터입니다. 데이터 유형: 문자열
meta.kb 님	지식베이스 문서 sys_ids 목록입니다. 데이터 유형: 문자열
meta.language (메타 언어)	요청된 KB 문서의 쉼표로 구분된 언어 목록입니다. 데이터 유형: 문자열
meta.query (메타 쿼리)	지정된 요청 쿼리입니다. 데이터 유형: 문자열
meta.start (메타 시작)	결과 집합의 시작 인덱스입니다. 데이터 유형: 숫자
meta.status (메타 상태)	호출의 HTTP 상태입니다. 데이터 유형: 문자열
meta.ts_query_id입니다.	쿼리의 Sys_id입니다. 데이터 유형: 문자열

cURL 요청

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/articles/most_viewed?limit=5" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "meta": {
      "start": 0,
      "end": 5,
      "fields": "",
      "query": "",
      "filter": "workflow_state=published^valid_to>=javascript:gs.beginningOfToday()^active=true^sys_class_name!=kb_knowledge_block^sys_view_count>0^ORDERBYDESCsys_view_count^ORDERBYshort_description",
      "kb": "",
      "count": 2,
      "status": {
        "code": 200
      },
      "language": "en"
    },
    "articles": [
      {
        "link": "?id=kb_article_view&sys_kb_id=0b48fd75474321009db4b5b08b9a71c2",
        "id": "kb_knowledge:0b48fd75474321009db4b5b08b9a71c2",
        "title": "How to Deal with Spam",
        "snippet": "How to Deal with Spam Spam has increasingly become a problem on the Internet. While every Internet user receives some spam, email addresses posted to web sites or in newsgroups and chat rooms attract the most spam. To reduce the amount of spam you receive: Don't reply to spam Be careful releasing your email address, and know how it will be used ",
        "score": 7,
        "tags": [],
        "number": "KB0000011"
      },
      {
        "link": "?id=kb_article_view&sys_kb_id=c85cd2519f77230088aebde8132e70c2",
        "id": "kb_knowledge:c85cd2519f77230088aebde8132e70c2",
        "title": "Microsoft Outlook Issues",
        "snippet": "Microsoft Outlook Issues This article explains how to use automatic replies in Outlook 2010 for Exchange accounts. Setting Up Automatic Replies Click the File tab. Click Automatic Replies. Select Send automatic replies. If desired, select the Only send during this time range check box to schedule when your out of office replies are active. If yo",
        "score": 6,
        "tags": [],
        "number": "KB99999999"
      }
    ]
  }
}