ナレッジ管理 API は、最も閲覧された注目のナレッジ記事のリストを検索、表示、およびフェッチするためのエンドポイントを提供します。

この API は、ナレッジ API (sn_km_api) プラグインが有効になっている場合にのみ使用できます。ナレッジ管理 REST API は当初、ServiceNow Store で利用可能なナレッジ API アプリを使用して Orlando 年にリリースされました。

注: Knowledge Management REST API は公的にアクセス可能であり、公的にアクセス可能なナレッジベースを、非認証ユーザーを含むすべてのユーザーが利用できるようにします。バージョン 1.0.1 以降では API が編集可能になっており、管理者は API に関連付けられた [スクリプト化済み REST サービスセキュリティ (Scripted REST Service Security)] タブで [認証が必要] フラグを選択することで、非認証アクセスを禁止するように各エンドポイントを構成できます。

他のドメインで Knowledge Management REST API エンドポイントを使用できるようにするには、クロスオリジンリソース共有 (CORS) ルールを定義します。詳細については、「 CORS ルールの定義」を参照してください。

この REST API を使用してスコープ付きナレッジベースから記事を表示するには、制限付きの申請者アクセス特権 [sys_restricted_caller_access] テーブルで要求スコープからの sn_km_api スコープ読み取りアクセスを許可します。詳細については、「 アプリケーション リソースへのクロススコープ アクセスを定義する」を参照してください。

デフォルトでは、非認証ユーザーおよび snc_external ユーザーに対して、この API には 1 時間当たり 500 のレート制限があります。レート制限の詳細については、「 受信 REST API のレート制限」を参照してください。

Knowledge Management - 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 オプションアクセスするエンドポイントのバージョン。たとえば、v1v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

データタイプ:文字列

表 : 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)

例: 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"
          }
        }
      }
    ]
  }
}

Knowledge Management - 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 オプションアクセスするエンドポイントのバージョン。たとえば、v1v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

データタイプ:文字列

article_sys_id 取得しようとしている添付ファイルを含むナレッジ記事の sys_id。

データタイプ:文字列

テーブル:ナレッジベース [kb_knowledge]

attachment_sys_id 添付ファイルが属しているレコードの sys_id。

データタイプ:文字列

表 : 8. クエリパラメーター
名前 説明
なし
表 : 9. 要求本文パラメーター (XML または JSON)
名前 説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

表 : 10. 要求ヘッダー
ヘッダー 説明
承認 応答本文のデータフォーマット。サポートされるタイプ:application/json または application/xml

デフォルト: application/json

表 : 11. 応答ヘッダー
ヘッダー 説明
Content-Type 応答のコンテンツタイプ (例:image/gif または */*)。

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

応答本文のパラメーター

名前 説明
ファイルは応答として返されます。

例: サンプル 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).

Knowledge Management - 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 オプションアクセスするエンドポイントのバージョン。たとえば、v1v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

データタイプ:文字列

ID ナレッジ記事のSys_idまたはナレッジベース (KB) 番号。

データタイプ:文字列

テーブル:ナレッジ [kb_knowledge]

表 : 21. 要求本文パラメーター (XML または JSON)
名前 説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

表 : 22. 要求ヘッダー
ヘッダー 説明
承認 応答本文のデータフォーマット。サポートされるタイプ:application/json または application/xml

デフォルト: application/json

表 : 23. 応答ヘッダー
ヘッダー 説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 24. ステータスコード
ステータスコード 説明
200 成功。要求が正常に処理されました。
401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。

応答本文のパラメーター (JSON または XML)

例: 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 - GET knowledge/articles/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 オプションアクセスするエンドポイントのバージョン。たとえば、v1v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

データタイプ:文字列

表 : 27. 要求本文パラメーター (XML または JSON)
名前 説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

表 : 28. 要求ヘッダー
ヘッダー 説明
承認 応答本文のデータフォーマット。サポートされるタイプ:application/json または application/xml

デフォルト: application/json

表 : 29. 応答ヘッダー
ヘッダー 説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 30. ステータスコード
ステータスコード 説明
200 成功。要求が正常に処理されました。
401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。

応答本文のパラメーター (JSON または XML)

例: 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"
      }
    ]
  }
}