generic-crud-operations

汎用 CRUD 操作

概要

ServiceNow MCP は、プラットフォーム内のあらゆるテーブルで動作する汎用ツールを提供します。このスキルでは、テーブルごとに専用ツールを用意することなく、160 以上の ServiceNow テーブルで作成、読み取り、更新、削除（CRUD）操作を行う方法を説明します。

• どのような問題を解決しますか？ テーブル操作のための、単一で一貫性のある方法を提供します
• このスキルは誰が使うべきですか？ ServiceNow のデータを扱う開発者、管理者、インテグレーター
• 期待される成果は何ですか？ あらゆるテーブルのレコードをクエリ、作成、更新、取得できるようになります

前提条件

• MCP ServiceNow サーバーが設定され、実行中であること
• 対象テーブルに適切な ServiceNow ロールがあること（テーブルによって異なります）
• ServiceNow のテーブル構造（sys_id、表示値）の基本的な理解

手順

ステップ 1：テーブルスキーマを確認する

テーブルを操作する前に、スキーマの確認を使って構造を把握します。

基本スキーマを取得：

Tool: SN-Get-Table-Schema
Parameters:
  table_name: incident

応答に含まれる情報：

• フィールド名と型
• フィールドの長さと必須フラグ
• 参照テーブルの関係
• 選択肢フィールドの選択肢の値

拡張スキーマを取得：

Tool: SN-Discover-Table-Schema
Parameters:
  table_name: incident
  include_relationships: true

応答に含まれる情報：

• すべての基本スキーマ情報
• 親テーブルと子テーブルの関係
• 参照先テーブルと外部キー

ステップ 2：レコードをクエリする（読み取り）

フィルター、フィールド選択、ページネーションを使って、あらゆるテーブルをクエリします。

基本的なクエリ：

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: active=true
  limit: 10

フィールドを選択してクエリ：

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: active=true^priority=1
  fields: sys_id,number,short_description,state,assigned_to
  limit: 20

ページネーションを使ってクエリ：

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: active=true
  fields: number,short_description
  limit: 50
  offset: 100

並べ替えてクエリ：

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: active=true^ORDERBYDESCpriority
  fields: number,short_description,priority
  limit: 25

ステップ 3：単一のレコードを取得する（読み取り）

sys_id を指定して、特定のレコードを取得します。

レコードを取得：

Tool: SN-Get-Record
Parameters:
  table_name: incident
  sys_id: abc123def456...

フィールドを選択してレコードを取得：

Tool: SN-Get-Record
Parameters:
  table_name: incident
  sys_id: abc123def456...
  fields: number,short_description,state,priority,assigned_to

ステップ 4：レコードを作成する（作成）

適切なフィールド値を指定して、あらゆるテーブルに新しいレコードを作成します。

レコードを作成：

Tool: SN-Create-Record
Parameters:
  table_name: incident
  data:
    short_description: Network connectivity issue in Building A
    description: Users in Building A floor 3 unable to access network resources
    category: network
    subcategory: connectivity
    impact: 2
    urgency: 2
    caller_id: <user_sys_id>
    assignment_group: <group_sys_id>

応答で返される内容：

• 作成されたレコードの sys_id
• number（自動生成される場合）
• 作成されたすべてのフィールド値

参照フィールドを含むレコードを作成：

Tool: SN-Create-Record
Parameters:
  table_name: task
  data:
    short_description: Follow up with customer
    parent: <parent_task_sys_id>
    assigned_to: <user_sys_id>
    assignment_group: <group_sys_id>
    due_date: 2024-12-31

ステップ 5：レコードを更新する（更新）

sys_id を指定して、既存のレコードを更新します。

単一のフィールドを更新：

Tool: SN-Update-Record
Parameters:
  table_name: incident
  sys_id: abc123def456...
  data:
    state: 2

複数のフィールドを更新：

Tool: SN-Update-Record
Parameters:
  table_name: incident
  sys_id: abc123def456...
  data:
    state: 2
    assigned_to: <user_sys_id>
    work_notes: Investigation in progress
    priority: 2

参照フィールドを更新：

Tool: SN-Update-Record
Parameters:
  table_name: incident
  sys_id: abc123def456...
  data:
    assignment_group: <new_group_sys_id>
    assigned_to: <new_user_sys_id>

ステップ 6：バッチ操作

複数の操作を効率よく実行します。

バッチ作成：

Tool: SN-Batch-Create
Parameters:
  records:
    - table: sys_user_group
      data:
        name: Network Support L1
        description: Level 1 network support
    - table: sys_user_group
      data:
        name: Network Support L2
        description: Level 2 network support
    - table: sys_user_group
      data:
        name: Network Support L3
        description: Level 3 network support

バッチ更新：

Tool: SN-Batch-Update
Parameters:
  updates:
    - table: incident
      sys_id: abc123...
      data:
        state: 6
        resolution_code: Solved
    - table: incident
      sys_id: def456...
      data:
        state: 6
        resolution_code: Solved
    - table: incident
      sys_id: ghi789...
      data:
        state: 6
        resolution_code: Solved

よく使われるフィールドパターン

システムフィールド（すべてのテーブル）

フィールド	説明	備考
sys_id	一意の識別子	32 文字の GUID、読み取り専用
sys_created_on	作成日時	読み取り専用
sys_created_by	作成者のユーザー名	読み取り専用
sys_updated_on	最終更新日時	読み取り専用
sys_updated_by	最終更新者のユーザー名	読み取り専用
sys_mod_count	更新回数	読み取り専用
sys_class_name	テーブル名	拡張テーブル用

参照フィールド

参照フィールドは、他のテーブルにあるレコードへのリンクです。

参照を設定：

{
  "assigned_to": "5137153cc611227c000bbd1bd8cd2007"
}

表示値を取得：

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: active=true
  fields: number,assigned_to,assigned_to.name,assigned_to.email
  limit: 10

応答に含まれる情報：

{
  "assigned_to": {
    "value": "5137153cc611227c000bbd1bd8cd2007",
    "display_value": "John Smith"
  },
  "assigned_to.name": "John Smith",
  "assigned_to.email": "[email protected]"
}

選択肢フィールド

選択肢フィールドには、あらかじめ定義された値があります。

利用可能な選択肢を取得：

Tool: SN-Query-Table
Parameters:
  table_name: sys_choice
  query: name=incident^element=state
  fields: value,label

一般的なインシデントの状態：

値	ラベル
1	新規
2	進行中
3	保留中
6	解決済み
7	クローズ

日付／時刻フィールド

日付形式： YYYY-MM-DD 日時形式： YYYY-MM-DD HH:MM:SS

例：

{
  "due_date": "2024-12-31",
  "work_start": "2024-12-01 09:00:00"
}

ツールの使用方法

MCP ツール（Claude Code／Desktop）

ツール	用途
SN-Query-Table	フィルターを使ってレコードをクエリする
SN-Get-Record	sys_id を指定して単一のレコードを取得する
SN-Create-Record	新しいレコードを作成する
SN-Update-Record	既存のレコードを更新する
SN-Get-Table-Schema	テーブル構造を確認する
SN-Discover-Table-Schema	関係を含む拡張スキーマを確認する
SN-Batch-Create	複数のレコードを作成する
SN-Batch-Update	複数のレコードを更新する

REST API（ChatGPT/Other）

エンドポイント	メソッド	目的
/api/now/table/{table}	GET	レコードを検索
/api/now/table/{table}/{sys_id}	GET	単一のレコードを取得
/api/now/table/{table}	POST	レコードを作成
/api/now/table/{table}/{sys_id}	PATCH	レコードを更新
/api/now/table/{table}/{sys_id}	PUT	レコードを置換
/api/now/table/{table}/{sys_id}	DELETE	レコードを削除

REST クエリパラメーター：

パラメーター	説明
sysparm_query	エンコードされたクエリ文字列
sysparm_fields	カンマ区切りのフィールド一覧
sysparm_limit	返すレコードの最大数
sysparm_offset	スキップするレコード数（ページネーション）
sysparm_display_value	表示値を返す（all、true、false）

ネイティブツール（Claude Code）

上記の MCP ツールを主な手段として使用してください。未加工の REST は、MCP では実行できない操作がある場合に限り、最後の手段として使用してください。その場合は、会話の外ですでに設定されている、組織が承認したローカルの認証情報ヘルパーを利用してください。認証情報をユーザーに貼り付けるよう求めたり、コマンドに埋め込んだり、認証ヘッダーを含むリクエストを生成したりしないでください。MCP ワークフローで使用するものと同じスキーマチェック、フィールド選択、ページネーション、ACL、明示的なインスタンス指定を維持してください。

ベストプラクティス

• 最初に必ずスキーマを確認する： 不慣れなテーブルを扱う前に SN-Get-Table-Schema を使用します
• フィールドを指定する： 必要なフィールドだけを含めて、レスポンスのペイロードを減らし、パフォーマンスを向上させます
• ページネーションを使用する： 大規模なデータセットでは、limit と offset を使用して結果をページ単位で取得します
• sys_id を検証する： 参照フィールドには、参照先のテーブルに存在する有効な sys_id が必要です
• エラーを処理する： 特に作成・更新操作では、レスポンスにエラーメッセージがないか確認します
• 操作をバッチ処理する： 複数のレコード（5～10 件以上）には、効率化のためバッチツールを使用します

トラブルシューティング

レコードが見つからない

症状： クエリ結果が空になる、または取得時に 404 が返される
原因： 無効な sys_id、レコードの削除、または権限不足
解決策： sys_id が存在すること、およびユーザーにテーブルの読み取り権限があることを確認します

権限が拒否される（403）

症状： 作成・更新時に 403 Forbidden エラーが発生する
原因： ユーザーにテーブルまたは特定フィールドへの書き込み権限がない
解決策： テーブル操作に必要な ACL とロールを確認します

無効なフィールド値

症状： フィールドの検証エラーにより作成・更新に失敗する
原因： 値がフィールドの型または選択肢リストと一致しない
解決策： 特に選択肢フィールドと参照フィールドについて、フィールドスキーマで有効な値を確認します

参照フィールドが拒否される

症状： 参照フィールドの値が保存されない
原因： sys_id が無効、または参照先のレコードが存在しない
解決策： 参照先のテーブルを検索して、有効な sys_id を取得します

必須フィールドが不足している

症状： 必須フィールドのエラーにより作成に失敗する
原因： データに必須フィールドが指定されていない
解決策： スキーマで必須フィールドを確認し、必要な値をすべて含めます

例

例 1：アクティブなユーザーを検索

Tool: SN-Query-Table
Parameters:
  table_name: sys_user
  query: active=true
  fields: sys_id,user_name,name,email,department
  limit: 50

例 2：構成アイテムを作成

Tool: SN-Create-Record
Parameters:
  table_name: cmdb_ci_server
  data:
    name: web-server-01
    ip_address: 192.168.1.100
    os: Linux Red Hat
    cpu_count: 4
    ram: 16384
    classification: Production
    environment: Production

例 3：複数のインシデントを更新

Tool: SN-Batch-Update
Parameters:
  updates:
    - table: incident
      sys_id: inc001...
      data:
        assignment_group: <network_team_id>
        work_notes: Routing to network team per triage
    - table: incident
      sys_id: inc002...
      data:
        assignment_group: <network_team_id>
        work_notes: Routing to network team per triage

例 4：ドットウォーキングでレコードを取得

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: number=INC0010001
  fields: number,short_description,caller_id.name,caller_id.email,caller_id.department.name

例 5：ページネーション付きクエリ

# Page 1
Tool: SN-Query-Table
Parameters:
  table_name: change_request
  query: state=-1
  fields: number,short_description,start_date,end_date
  limit: 100
  offset: 0

# Page 2
Tool: SN-Query-Table
Parameters:
  table_name: change_request
  query: state=-1
  fields: number,short_description,start_date,end_date
  limit: 100
  offset: 100

関連スキル

• itsm/natural-language-queries - 自然言語検索を使いこなす
• itsm/quick-reference - ITSM クイックリファレンスカード
• admin/batch-operations - 高度なバッチ操作

参考資料

• ServiceNow Table API
• エンコードされたクエリ文字列
• REST API のベストプラクティス