지식 관리 REST API

릴리스 버전: Yokohama

업데이트 날짜 2025년 01월 30일

읽기43분

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

Knowledge API(sn_km_api) 플러그인이 활성화된 경우에만 이 API를 사용할 수 있습니다. 지식 관리 REST API는 원래 에서 사용할 수 ServiceNow Store있는 지식 API 앱을 사용하여 릴리스 Orlando 되었습니다.

주:

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

다른 도메인에서 지식 관리 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

주:

사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

지원되는 요청 매개변수

표 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_knowledge_base] 테이블에서 쉼표로 구분된 지식베이스 sys_ids 목록입니다. 데이터 유형: 문자열
언어	결과를 제한할 두 글자 ISO 639-1 언어 코드 형식의 쉼표로 구분된 언어 목록입니다. 또는 '모두'를 입력하여 인스턴스에 설치된 모든 유효한 언어로 검색합니다. 데이터 유형: 문자열 기본값: 사용자의 세션 언어 또는 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	요청된 필드의 표시 값입니다. 데이터 유형: 문자열
articles.fields.<field_name>.label	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
articles.fields.<field_name>.name	요청된 필드의 이름입니다. 일치 <field_name>. 데이터 유형: 문자열
articles.fields.<field_name>.type	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
articles.fields.<field_name>.value	요청된 필드의 값입니다. 데이터 유형: 문자열
articles.id	지식 [kb_knowledge] 테이블의 지식 문서 sys_id. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
문서.번호	지식 문서 번호입니다. 데이터 유형: 문자열
문서.순위	이 검색과 관련된 문서의 검색 순위입니다. 데이터 유형: 숫자(부동)
문서.snippet	지식 문서의 일부를 보여주는 텍스트입니다. 데이터 유형: 문자열
문서.점수	관련성 점수, 점수에 따라 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
문서.제목	지식 문서에 대한 간단한 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수에 대한 메타 정보입니다. 데이터 유형: 객체 `"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 문서의 수입니다. 데이터 유형: 숫자
meta.end	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
meta.fields	문서의 필드입니다. 데이터 유형: 문자열
meta.filter	데이터를 획득하는 데 사용되는 필터입니다. 데이터 유형: 문자열
메타.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}

주:

사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

지원되는 요청 매개변수

표 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 /지식/문서/추천

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

URL 형식

버전 URL: /api/sn_km_api/{api_version}/knowledge/articles/featured

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

주:

사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

지원되는 요청 매개변수

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

표 14. 쿼리 매개변수
이름	설명
필드	결과에 상세 정보를 표시하기 위해 지식 [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
킬로바이트	결과를 제한할 지식베이스 [kb_knowledge_base] 테이블에서 쉼표로 구분된 지식베이스 sys_ids 목록입니다. 데이터 유형: 문자열
언어	결과를 제한할 두 글자 ISO 639-1 언어 코드 형식의 쉼표로 구분된 언어 목록입니다. 또는 '모두'를 입력하여 인스턴스에 설치된 모든 유효한 언어로 검색합니다. 데이터 유형: 문자열 기본값: 사용자의 세션 언어 또는 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>. 데이터 유형: 문자열
articles.fields.<field_name>.label	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
articles.fields.<field_name>.type	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
articles.fields.<field_name>.value	요청된 필드의 값입니다. 데이터 유형: 문자열
articles.id	지식 [kb_knowledge] 테이블의 지식 문서 sys_id. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
문서.번호	지식 문서 번호입니다. 데이터 유형: 문자열
문서.순위	이 검색과 관련된 문서의 검색 순위입니다. 데이터 유형: 숫자(부동)
문서.점수	관련성 점수, 점수에 따라 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
문서.snippet	지식 문서의 일부를 보여주는 텍스트입니다. 데이터 유형: 문자열
문서.제목	지식 문서에 대한 간단한 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수에 대한 메타 정보입니다. 데이터 유형: 객체 `"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 문서의 수입니다. 데이터 유형: 숫자
meta.end	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
meta.fields	문서의 필드입니다. 데이터 유형: 문자열
meta.filter	데이터를 획득하는 데 사용되는 필터입니다. 데이터 유형: 문자열
메타.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}

주:

사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

지원되는 요청 매개변수

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

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

표 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.상태	첨부 파일의 상태입니다. 가능한 값: 사용 가능 available_conditionally not_available 보류 중 데이터 유형: 문자열
embedded_content.sys_id	첨부 파일의 Sys_id입니다. 데이터 유형: 문자열
필드	요청된 필드의 값(있는 경우)입니다. 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
필드.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "label": "String", "name": "String", "type": "String", "value": "String" }`
필드.<field_name>.display_value	요청된 필드의 표시 값입니다. 데이터 유형: 문자열
fields.<field_name>.label	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
fields.<field_name>.name	요청된 필드의 이름입니다. 일치 <field_name>. 데이터 유형: 문자열
fields.<field_name>.type	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
fields.<field_name>.value	요청된 필드의 값입니다. 데이터 유형: 문자열
언어	현재 문서에 대한 두 글자 ISO 639-1 언어 코드입니다(번역이 가능한 경우). 데이터 유형: 문자열
언어	지식 문서의 각 번역된 버전(번역된 경우)의 경우: `"languages": [ { "label": "String", "language": "String", "sys_id": "String" } ]` 데이터 유형: 배열
languages.label	언어에 대한 문자열 표현입니다. 데이터 유형: 문자열
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

주:

사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

지원되는 요청 매개변수

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

표 26. 쿼리 매개변수
이름	설명
필드	결과에 상세 정보를 표시하기 위해 지식 [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
킬로바이트	결과를 제한할 지식베이스 [kb_knowledge_base] 테이블에서 쉼표로 구분된 지식베이스 sys_ids 목록입니다. 데이터 유형: 문자열
언어	결과를 제한할 두 글자 ISO 639-1 언어 코드 형식의 쉼표로 구분된 언어 목록입니다. 또는 '모두'를 입력하여 인스턴스에 설치된 모든 유효한 언어로 검색합니다. 데이터 유형: 문자열 기본값: 사용자의 세션 언어 또는 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	요청된 필드의 표시 값입니다. 데이터 유형: 문자열
articles.fields.<field_name>.label	요청된 필드를 나타내는 레이블입니다. 예: `지식`. 데이터 유형: 문자열
articles.fields.<field_name>.name	요청된 필드의 이름입니다. <field_name>와 일치합니다. 데이터 유형: 문자열
articles.fields.<field_name>.type	요청된 필드의 데이터 유형입니다. 데이터 유형: 문자열
articles.fields.<field_name>.value	요청된 필드의 값입니다. 데이터 유형: 문자열
articles.id	지식 [kb_knowledge] 테이블의 지식 문서 sys_id. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
문서.번호	지식 문서 번호입니다. 데이터 유형: 문자열
문서.순위	이 검색과 관련된 문서의 검색 순위입니다. 데이터 유형: 부동
문서.점수	관련성 점수, 점수에 따라 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
문서.snippet	지식 문서의 일부를 보여주는 텍스트입니다. 데이터 유형: 문자열
문서.제목	지식 문서에 대한 간단한 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수에 대한 메타 정보입니다. 데이터 유형: 객체 `"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 문서의 수입니다. 데이터 유형: 숫자
meta.end	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
meta.fields	문서의 필드입니다. 데이터 유형: 문자열
meta.filter	데이터를 획득하는 데 사용되는 필터입니다. 데이터 유형: 문자열
메타.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"
      }
    ]
  }
}