지식 관리 REST API

릴리스 버전: Washingtondc

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

읽기44분

Knowledge Management REST API를 사용하면 가장 많이 살펴본 지식 문서 목록 및 추천 지식 문서 목록을 검색하고, 보고, 가져올 수 있습니다.

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

주:

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

다른 도메인에서 Knowledge Management 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 속도 제한을 참조하세요.

Knowledge Management - /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>`: 테이블 열의 이름입니다. `<연산자>`: 유효한 값은 다음과 같습니다. =: 정확히 <value>와 일치합니다. !=: <value>와 일치하지 않습니다. ^: 둘 이상의 조건을 지정하고 논리적으로 AND를 지정할 수 있습니다. ^OR: 둘 이상의 조건을 지정하고 논리적으로 OR할 수 있습니다. LIKE : <attr> 지정된 문자열을 포함합니다. 데이터 유형이 문자열인 <attr> 필드에서만 작동합니다. STARTSWITH: <attr>은 지정된 문자열로 시작합니다. 데이터 유형이 문자열인 <attr> 필드에서만 작동합니다. ENDSWITH: <attr>은 지정된 문자열로 끝납니다. 데이터 유형이 문자열인 <attr> 필드에서만 작동합니다. `<value>`: 일치시킬 값입니다. 모든 매개변수는 대/소문자를 구분합니다. 쿼리에는 다음과 같은 항목이 두 개 이상 포함될 수 있습니다. `filter=<attr><operator><value>[<operator><attr><operator><value>]`입니다. 데이터 유형: 문자열 기본값 : 비어 있음
필드	결과에 세부 정보를 표시하기 위해 Knowledge [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
Kb	결과를 제한할 지식베이스 [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" } ]`
articles.fields	요청된 필드의 값입니다(있는 경우). 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
articles.fields.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "label": "String", "name": "String", "type": "String", "value": "String" }`
articles.fields.<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	Knowledge [kb_knowledge] 테이블에서 sys_id Knowledge 문서입니다. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
articles.number	지식 문서 번호입니다. 데이터 유형: 문자열
articles.rank	이 검색과 관련된 문서의 검색 순위입니다. 데이터 유형: 숫자(부동)
articles.snippet	지식 문서의 작은 부분을 보여 주는 텍스트입니다. 데이터 유형: 문자열
articles.score	관련성 점수, 점수별로 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
articles.title	지식 문서에 대한 간단한 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수의 메타 정보입니다. 데이터 유형: 객체 `"meta": { "count": Number, "end": Number, "fields": "String", "filter": "String", "kb": "String", "language": "String", "query": "String", "start": Number, "status": {Object}, "ts_query_id": "String" }`
메타 카운트	사용 가능한 KB 문서 수입니다. 데이터 유형: 숫자
메타.끝	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
메타 필드	문서의 필드입니다. 데이터 유형: 문자열
메타.필터	데이터를 획득하는 데 사용되는 필터입니다. 데이터 유형: 문자열
메타.kb	sys_ids 지식베이스 문서 목록입니다. 데이터 유형: 문자열
메타 언어	요청된 KB 문서의 쉼표로 구분된 언어 목록입니다. 데이터 유형: 문자열
meta.query	지정된 요청 쿼리입니다. 데이터 유형: 문자열
메타.시작	결과 집합의 시작 인덱스입니다. 데이터 유형: 숫자
메타 상태	호출의 상태입니다. 데이터 유형: 문자열
meta.ts_쿼리_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. 쿼리 매개변수
이름	설명
필드	결과에 세부 정보를 표시하기 위해 Knowledge [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
Kb	결과를 제한할 지식베이스 [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" } ]`
articles.fields	요청된 필드의 값입니다(있는 경우). 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
articles.fields.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "name": "String", "label": "String", "type": "String", "value": "String" }`
articles.fields.<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	Knowledge [kb_knowledge] 테이블에서 sys_id Knowledge 문서입니다. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
articles.number	지식 문서 번호입니다. 데이터 유형: 문자열
articles.rank	이 검색과 관련된 문서의 검색 순위입니다. 데이터 유형: 숫자(부동)
articles.score	관련성 점수, 점수별로 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
articles.snippet	지식 문서의 작은 부분을 보여 주는 텍스트입니다. 데이터 유형: 문자열
articles.title	지식 문서에 대한 간단한 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수의 메타 정보입니다. 데이터 유형: 객체 `"meta": { "count": Number, "end": Number, "fields": "String", "filter": "String", "kb": "String", "language": "String", "query": "String", "start": Number, "status": {Object}, "ts_query_id": "String" }`
메타 카운트	사용 가능한 KB 문서 수입니다. 데이터 유형: 숫자
메타.끝	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
메타 필드	문서의 필드입니다. 데이터 유형: 문자열
메타.필터	데이터를 획득하는 데 사용되는 필터입니다. 데이터 유형: 문자열
메타.kb	sys_ids 지식베이스 문서 목록입니다. 데이터 유형: 문자열
메타 언어	요청된 KB 문서의 쉼표로 구분된 언어 목록입니다. 데이터 유형: 문자열
meta.query	지정된 요청 쿼리입니다. 데이터 유형: 문자열
메타.시작	결과 집합의 시작 인덱스입니다. 데이터 유형: 숫자
메타 상태	호출의 HTTP 상태입니다. 데이터 유형: 문자열
meta.ts_쿼리_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	Knowledge [kb_knowledge] 테이블에 있는 지식 문서의 Sys_id 또는 KB(지식베이스) 번호입니다. 데이터 유형: 문자열

표 20. 쿼리 매개변수
이름	설명
필드	결과에 세부 정보를 표시하기 위해 Knowledge [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
언어	두 글자 ISO 639-1 언어 코드; 예를 들어 프랑스어의 경우 "fr"입니다. 검색에서 지식 문서 KB 번호를 id 다음으로 사용하고 문서의 번역된 버전이 지정된 언어로 제공되는 경우에만 결과가 표시됩니다. 주: 매개변수를 KB 번호(sys_id 아님)로 설정할 id 때만 유효합니다. 데이터 유형: 문자열
search_id	를 사용하지 search_rank않는 한 선택 사항입니다. 이 문서를 반환한 검색의 고유 식별자입니다. 요소를 반환하는 articles.id 다음 API 중 하나를 사용하여 검색할 search_id 수 있습니다. Knowledge Management - /knowledge/articles 가져오기 지식 관리 - GET /knowledge/articles/featured Knowledge Management - 지식/문서/most_viewed 가져오기 and search_rank 매개변수를 전달 search_id 하면 문서 조회수가 증가하고 Knowledge 사용 [kb_use] 테이블에 문서에 대한 항목이 기록됩니다. 지식베이스 [kb_view2] 페이지에서도 증가된 조회수를 확인할 수 있습니다. 데이터 유형: 문자열
search_rank	를 사용하지 search_id않는 한 선택 사항입니다. 요소를 반환하는 다음 API 중 하나를 사용하여 검색할 수 있는 클릭률별 articles.rank 문서 검색 순위입니다. Knowledge Management - /knowledge/articles 가져오기 지식 관리 - GET /knowledge/articles/featured Knowledge Management - 지식/문서/most_viewed 가져오기 데이터 유형: 숫자
update_view	조회수를 업데이트하고 Knowledge 사용 [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	파일 크기. 데이터 유형: 문자열 단위: 바이트
attachments.state	상태 가능한 값: 사용 가능 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} }`
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	요청된 필드를 나타내는 레이블입니다. 예를 들면 `지식입니다`. 데이터 유형: 문자열
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	Knowledge [kb_knowledge] 테이블에서 sys_id Knowledge 문서입니다. 데이터 유형: 문자열
템플릿	반환된 문서가 템플릿인지 여부를 나타내는 플래그입니다. 가능한 값: 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": []
  }
}

Knowledge Management - 지식/문서/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. 쿼리 매개변수
이름	설명
필드	결과에 세부 정보를 표시하기 위해 Knowledge [kb_knowledge] 테이블의 쉼표로 구분된 필드 목록입니다. 데이터 유형: 문자열 기본값: 없음
Kb	결과를 제한할 지식베이스 [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" } ]`
articles.fields	요청된 필드의 값(있는 경우) 데이터 유형: 객체 `"fields": { "<field_name>": {Object} }`
articles.fields.<field_name>	fields 매개변수를 사용하여 요청된 각 필드를 나열합니다(있는 경우). 데이터 유형: 객체 `"<field_name>": { "display_value": "String", "label": "String", "name": "String", "type": "String", "value": "String" }`
articles.fields.<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	Knowledge [kb_knowledge] 테이블에서 sys_id Knowledge 문서입니다. 데이터 유형: 문자열
articles.link	문서에 대한 링크입니다. 데이터 유형: 문자열
articles.number	지식 문서 번호입니다. 데이터 유형: 문자열
articles.rank	이 검색과 관련된 문서의 검색 순위입니다. 데이터 유형: 부동
articles.score	관련성 점수, 점수별로 내림차순으로 정렬된 결과입니다. 데이터 유형: 문자열
articles.snippet	지식 문서의 작은 부분을 보여 주는 텍스트입니다. 데이터 유형: 문자열
articles.title	지식 문서에 대한 간단한 설명 또는 제목입니다. 데이터 유형: 문자열
메타	결과 및 요청 매개변수의 메타 정보입니다. 데이터 유형: 객체 `"meta": { "count": Number, "end": Number, "fields": "String", "filter": "String", "kb": "String", "language": "String", "query": "String", "start": Number, "status": {Object}, "ts_query_id": "String" }`
메타 카운트	사용 가능한 KB 문서 수입니다. 데이터 유형: 숫자
메타.끝	결과 집합의 끝 인덱스입니다. 데이터 유형: 숫자
메타 필드	문서의 필드입니다. 데이터 유형: 문자열
메타.필터	데이터를 획득하는 데 사용되는 필터입니다. 데이터 유형: 문자열
메타.kb	sys_ids 지식베이스 문서 목록입니다. 데이터 유형: 문자열
메타 언어	요청된 KB 문서의 쉼표로 구분된 언어 목록입니다. 데이터 유형: 문자열
meta.query	지정된 요청 쿼리입니다. 데이터 유형: 문자열
메타.시작	결과 집합의 시작 인덱스입니다. 데이터 유형: 숫자
메타 상태	호출의 HTTP 상태입니다. 데이터 유형: 문자열
meta.ts_쿼리_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"
      }
    ]
  }
}