CMDB データ取り込み API

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：8分

    • CMDB データ取り込み API は、インポートセットテーブルへのオブジェクトのアレイのバッチ取り込みを可能にするエンドポイントを提供します。

    警告:
    この API は推奨されなくなりました。拡張性と安定性が向上した同じ機能の場合は、 インポートセット:POST /now/import/{stagingTableName}/insertMultiple エンドポイントを使用します。Quebec リリース以降、CMDB データ取り込み API の使用は、代わりにインポートセット - insertMultiple エンドポイントを使用するように移行する必要があります。

    また、この API は、デフォルトでは zboot インスタンスでは機能しません。

    この API は 構成管理データベース (CMDB) (com.snc.cmdb) プラグインを介してアクティブ化され、cmdb_import_api_admin ロールが必要です。

    CMDB データの取り込み:POST /cmdb/ingest/{data_source_sys_id}

    渡されたsys_idによって識別されるデータソースレコードに関連付けられたインポートセットテーブルにレコードを挿入します。

    警告:
    この API は推奨されなくなりました。拡張性と安定性が向上した同じ機能の場合は、 インポートセット:POST /now/import/{stagingTableName}/insertMultiple エンドポイントを使用します。Quebec リリース以降、CMDB データ取り込み API の使用は、代わりにインポートセット - insertMultiple エンドポイントを使用するように移行する必要があります。

    また、この API は、デフォルトでは zboot インスタンスでは機能しません。

    要求本文には、インポートセットテーブルに挿入するオブジェクト (ペイロード) の JSON アレイが含まれている必要があります。各オブジェクトはテーブルの行に相当し、各名前と値のペアは列に相当します。JSON ペイロードは、「u_」プリフィックスなしでインポートセットのフィールド名を利用する必要があります。たとえば、フィールド名「u_matching_record」は、要求本文ペイロードで「matching_record」にする必要があります。インポートセットテーブルが存在する場合、エンドポイントは既存のインポートセットテーブルに行 (オブジェクト) を追加します。重複のチェックや既存レコードの更新は行われません。

    最初にアプリケーションをビルドする場合は、このエンドポイントを呼び出す前に、まず関連するデータソースレコードをインスタンスに作成する必要があります。このエンドポイントを使用して既存のインポートセットテーブルにレコードを追加するだけの場合は、データソースレコードを作成する必要はありませんが、そのsys_idを知っている必要があります。データソースレコードは、指定されたペイロードを挿入するインポートセットテーブルを記述しています。このテーブルは、インポートセット行 [sys_import_set_row] テーブルを拡張する必要があります。また、データソースを 添付ファイル に設定し、形式を JSON に設定する必要があります。データソースの詳細については、「 データソース」を参照してください。

    データソースレコードで定義されたインポートセットテーブルが存在しない場合、エンドポイントは渡されたペイロードをデータソースレコードに添付します。最初のインポートセットテーブルを作成するには、データをインポートセットテーブルに手動でインポートする必要があります。データをインポートするには、関連する [データソース] フォームで、[関連リンク] セクションの [ 20 件のレコードのテストロード ] または [ すべてのレコードをロード ] リンクをクリックします。インポートセットテーブルが作成されると、このエンドポイントを使用してテーブルに列を追加することはできません。インポートセットテーブルに存在しない名前と値のペアが後で渡された場合は、警告なしに無視されます。インポートセットテーブル内の列を変更する必要がある場合は、手動でテーブルに追加できます。インポートセットテーブルを削除したり名前を変更したり、新しいペイロードを使用してエンドポイントを再度呼び出すこともできます。

    このエンドポイントにアクセスするには、cmdb_import_api_admin ロールが必要です。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/cmdb/ingest/{data_source_sys_id}

    デフォルト URL: /api/now/cmdb/ingest/{data_source_sys_id}

    注:
    使用可能なバージョン は、REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    api_version オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    data_source_sys_id データソースレコードのSys_id。

    データタイプ：文字列
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    アレイ 関連するインポートセットテーブルに追加するデータを説明するオブジェクトの自由形式のアレイ。アレイ内の各オブジェクトは、インポートセットテーブルの行を定義します。各名前と値は列をペアにします。
    注:
    このアレイには名前を付ける必要があります 。例:"{\"records\":[{\"hostname\": \"Hostname1\", \"serialnumber\": \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\", \"model\": \"Model Id"},{\"vendor\": \"ABC Co\"}]}"。

    データタイプ：オブジェクトのアレイ

    ヘッダー

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

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

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 6. ステータスコード
    ステータスコード 説明
    201 作成されました。添付ファイルがデータソースに追加されました。
    202 承認済み。インポートセットテーブルに行が追加されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    404 見つかりません。要求されたアイテムが見つかりませんでした。
    409 競合。添付ファイルは既にデータソースに存在します。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。
    501 実装されていません。要求形式はサポートされていません。

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

    名前 説明
    エラー 発生したエラーについて説明します。

    データタイプ: オブジェクト

    "error": {
  "details": "String",
  "message": "String"
}
    error.details エラーに関する追加情報。

    データタイプ：文字列
    error.message エラーを説明するメッセージ。

    データタイプ：文字列
    import_set ペイロードが追加されたインポートセットテーブルの名前。

    データタイプ：文字列
    staged_row_count インポートセットテーブルに追加された行の数。

    データタイプ：数値
    staging_table ペイロードをステージングするために使用されるデータソースレコードの名前。

    データタイプ：文字列
    status エラーステータス。

    データタイプ：文字列

    cURL 要求のサンプル

    curl "instance.service-now.com/api/now/cmdb/ingest/4dd9686d1b9800103d374087bc4bcb3d" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type:application/json" \
--data "{\"records\":[{\"hostname\": \"Hostname1\", \"serialnumber\": \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\", \"model\": \"Model 5100"},{\"vendor\": \"ABC Co\"},
{\"hostname\": \"Hostname2\", \"serialnumber\": \"3adb3873-7fc5-564d-8844-e7769e4d6ded\", \"model\": \"Model 5200"},{\"vendor\": \"ACME Co\"}]}"
--user "username":"password"

    成功した応答:

    {
  "result": {
    "staged_row_count": 2,
    "import_set": "ISET0010010",
    "staging_table": "sn_my_demo_integra_demo_data_source_01"
  }
}