インポートセット API

  • リリースバージョン: Washingtondc
  • 更新日 2024年02月01日
  • 読む17読むのに数分

    • インポートセット API は、インポートセットテーブルの操作を可能にするエンドポイントを提供します。

    この API は、関連する変換マップに基づいて受信データを変換します。インポートセット API は、同期変換に対応しています。インポートセット API は、既存の SOAP インターフェイスを反映します。

    セキュリティ

    REST API 経由によるテーブルへのアクセスは BasicAuth によって制限されています。認証や認可なしでテーブルにアクセスできるようにするには、テーブル名を sys_public.list に追加します。テーブルに定義された ACL は引き続き適用されます。ACL を無効にするのは管理者の責任です。

    インポートセット - GET /now/import/{stagingTableName}/{sys_id}

    指定されたインポートステージングレコードと結果の変換結果を取得します。

    URL 形式

    バージョニングされた URL：/api/now/{api_version}/import/{stagingTableName}/{sys_id}

    デフォルトの URL：/api/now/import/{stagingTableName}/{sys_id}

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

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

    データタイプ：文字列
    stagingTableName インポートデータの取得元のテーブルの名前。

    データタイプ：文字列
    sys_id データを含むレコードの sys_id。

    データタイプ：文字列
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 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 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    404 指定されたリソースが利用できなかったことを示します。インポートセットテーブルはスケジュールに基づいて頻繁に削除されるため、変換結果が存在しなくなった場合、GET 要求は 404 Not Found 応答を返すことがあります。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

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

    名前 説明
    import_set インポートセットの名前。

    データタイプ：文字列
    result インポートされたデータセットに関する情報を含むオブジェクトのリスト。
    データタイプ：アレイ
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name インポートセットの表示名。

    データタイプ：文字列
    result.display_value インポートセットの値。

    データタイプ：文字列
    result.record_link インポートされたレコードのテーブル API GET 要求。

    データタイプ：文字列
    result.status インポートのステータス。

    データタイプ：文字列
    result.sys_id インポートレコードの sys_id。

    データタイプ：文字列
    result.table データがインポートされたテーブルの名前。

    データタイプ：文字列
    result.transform_map 変換マップの名前。

    データタイプ：文字列
    staging_table インポートステージングテーブルの名前。

    データタイプ：文字列

    サンプル cURL 要求

    curl "https://instance.servicenow.com/api/now/import/imp_user/e2928be64f411200adf9f8e18110c777" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.service-now.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    インポートセット - POST /now/import/{stagingTableName}

    指定されたステージングテーブルに受信データを挿入し、インポートセットテーブルの事前定義された変換マップに基づいて変換をトリガーします。

    変換は同期的に行われます。定義する変換マップごとに、応答にはターゲットレコードに関する情報などの変換結果が含まれます。
    注:
    変換スクリプトの status_message フィールドと error_message フィールドが処理され、カスタム応答フィールドとともに応答で返されます。

    URL 形式

    バージョニングされた URL：/api/now/{api_version}/import/{stagingTableName}

    デフォルトの URL：/api/now/import/{stagingTableName}

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

    注:
    インポートセット POST メソッドは、要求本文パラメーターで文字列データタイプの名前と値のペアのみを受け入れます。他のデータタイプが指定されている場合、インポートセットテーブルに保存される結果の値が、意図した形式に準拠しない可能性があります。たとえば、ネストされた JSON オブジェクトの「:」表記が「=」に変更されます。
    表 : 7. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    stagingTableName データのインポート元のテーブルの名前。

    データタイプ：文字列
    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    呼び出し固有 インポートフィールドに挿入する名前と値のペア。

    データタイプ：文字列

    ヘッダー

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

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

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

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

    ステータスコード

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

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

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

    名前 説明
    import_set インポートセットの名前。

    データタイプ：文字列
    result インポートされたデータセットに関する情報を含むオブジェクトのリスト。
    データタイプ：アレイ
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name インポートセットの表示名。

    データタイプ：文字列
    result.display_value インポートセットの値。

    データタイプ：文字列
    result.record_link インポートされたレコードのテーブル API GET 要求。

    データタイプ：文字列
    result.status インポートのステータス。

    データタイプ：文字列
    result.sys_id インポートレコードの sys_id。

    データタイプ：文字列
    result.table データがインポートされたテーブルの名前。

    データタイプ：文字列
    result.transform_map 変換マップの名前。

    データタイプ：文字列
    staging_table インポートステージングテーブルの名前。

    データタイプ：文字列

    サンプル cURL 要求

    curl "https://instance.servicenow.com/api/now/import/imp_user" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{'first_name':'John','last_name':'Public','user_id':'john.public','email':'john.public@company.com'}" \
--user "username":"password"
    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.servicenow.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    インポートセット - POST /now/import/{stagingTableName}/insertMultiple

    指定されたステージングテーブルに複数のレコードを挿入し、単一の要求で事前定義された変換マップまたは強力な変換エンジン (RTE) 構成に基づいて変換をトリガーします。

    デフォルトでは、変換は非同期です。同期変換を設定するには、REST での複数挿入 [sys_rest_insert_multiple] テーブルに新しいレコードを作成し、ソーステーブルを選択して、変換を同期に設定します。

    このエンドポイントは、2 つの可能な形式で要求本文を送信できます。
    データソースファイル形式
    JSON データソースからステージングテーブルを生成した場合、ソースファイルの JSON 形式と一致します。
    ステージングテーブル列形式
    デフォルトです。キーと値のペアのステージングテーブル列の要求本文の形式と一致します。

    URL 形式

    バージョニングされた URL：/api/now/{api_version}/import/{stagingTableName}/insertMultiple

    デフォルトの URL：/api/now/import/{stagingTableName}/insertMultiple

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

    注:
    インポートセット POST メソッドは、要求本文パラメーターで文字列データタイプの名前と値のペアのみを受け入れます。他のデータタイプが指定されている場合、インポートセットテーブルに保存される結果の値が、意図した形式に準拠しない可能性があります。たとえば、ネストされた JSON オブジェクトの「:」表記が「=」に変更されます。
    表 : 13. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    stagingTableName データのインポート元のインポートセットテーブルの名前。「 Import Sets の主要な概念」を参照してください。

    データタイプ：文字列
    表 : 14. クエリパラメーター
    名前 説明
    multi_import_set_id マルチインポートセット [sys_multi_import_set] テーブル内のエントリの sys_id。指定すると、現在のインポートが新しい複数インポートセットに追加されるのではなく、この複数インポートセットに追加されます。

    データタイプ：文字列
    run_after インポートセット [sys_import_set] テーブル内のエントリの sys_id。指定されたインポートセットが完了した後、現在のインポートセットを実行できるようにします。このパラメーターを使用して、インポートの順序を強制できます。

    このパラメーターは、非同期変換でのみ有効です。

    データタイプ：文字列
    表 : 15. 要求本文 (JSON)
    フォーマット 説明
    データソースファイル この要求本文の形式は、データソースの作成に使用された JSON ファイル形式と一致します。データソースの JSON と同じ形式で要求本文を提供します。JSON 入力は、データソースのプロパティによって異なります。ファイルタイプデータソースのJSON情報を参照してください。
    • このオプションは、ステージングテーブルが JSON データソースを使用して作成された場合にのみ使用できます。ファイルタイプのデータソースの作成を参照してください。
    • データソース [sys_data_source] テーブルの [各行のパス] フィールドでデータソースのパスを定義する必要があります。
    • REST での複数挿入ユーザーのデフォルトの動作を変更するには、REST での複数挿入 [sys_rest_insert_multiple] テーブルにエントリを作成します。
    • REST での複数挿入エントリで [データソース形式を使用] を有効にします。

    データタイプ：オブジェクト
    ステージングテーブル列 (デフォルト) この要求本文の形式は、ステージングテーブルの列と一致します。ステージングテーブル列に一致するキーと値のペアの records アレイを使用して、インポートフィールドに挿入します。各 JSON キーは、挿入される値を表す JSON 値にテーブル列をマップします。JSON 入力は、ステージングテーブルのフィールドによって異なります。

    列マッピングのデフォルトのキー値は列テーブルです。

    {
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}
    マッピング設定を変更するには、REST での複数挿入 [sys_rest_insert_multiple] テーブルにエントリを追加し、[列マッピング] を [ラベル] から [列名] に変更します。
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    データディクショナリは、システム内のテーブルフィールドの詳細を提供します。

    データタイプ：アレイ

    ヘッダー

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

    表 : 16. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    Content-Type 要求本文のデータ形式。application/json のみをサポートします。
    表 : 17. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

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

    応答本文 (JSON)

    名前 説明
    import_set_id インポートセット [sys_import_set] テーブルに追加されたレコードの sys_id。非同期要求の場合は、このインポートセットプロセスが完了した後に、この値を使用して別のインポートセットを実行できます。

    データタイプ：文字列
    multi_import_set_id マルチインポートセット [sys_multi_import_set] テーブルに追加されたレコードの sys_id。この値を使用して、複数のインポートセットを 1 つのセットにグループ化できます。

    データタイプ：文字列

    サンプル cURL 要求

    次の例は、ステージングテーブル列の形式を使用して、u_employee_import_set_table という名前のインポートテーブルで変換を実行する方法を示しています。

    curl "https://instance.servicenow.com/api/now/import/u_employee_import_set_table/insertMultiple" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"records\": [
  {
   \"Address\": \"Hollywood\",
   \"Name\": \"Tom\",
   \"ID\": \"123\"
  },
  {
   \"Address\": \"Vine\",
   \"Name\": \"Irene\",
   \"ID\": \"456\"
  }
  ]
}" \
--user 'username':'password'

    結果には、インポートセット [sys_import_set] テーブルとマルチインポートセット [sys_multi_import_set] テーブルの新しいレコードの sys_id が含まれます。

    {
  "import_set_id": "<import_set_sys_id>",
  "multi_import_set_id": "<multi_import_set_sys_id>"
}