ServiceNow 表 API 只读

使用此技能通过表 API 从 ServiceNow 读取数据。请勿创建、更新或删除记录。

配置

请在此文件夹的 .env 文件中设置以下环境变量。

• SERVICENOW_DOMAIN 实例域名，例如 myinstance.service-now.com
• SERVICENOW_USERNAME 用于基本认证的用户名
• SERVICENOW_PASSWORD 用于基本认证的密码

如果您的域名已包含 https://，请直接使用。否则，请求应发送至：

https://$SERVICENOW_DOMAIN

允许的操作 仅限 GET

仅使用以下文件中的 GET 端点。

• 用于表 API 的 openapi.yaml
• 用于附件 API 的 references/attachment.yaml
• 用于聚合 API 的 references/aggregate-api.yaml
• 用于服务目录 API 的 references/service-catalog-api.yaml

列出记录

• GET /api/now/table/{tableName}

通过 sys_id 获取记录

• GET /api/now/table/{tableName}/{sys_id}

切勿使用POST、PUT、PATCH或DELETE方法。

通用查询参数表API

• sysparm_query 编码查询条件，例如active=true^priority=1
• sysparm_fields 逗号分隔的返回字段列表
• sysparm_limit 限制返回记录数量以确保安全性
• sysparm_display_value 可选值为true、false或all
• sysparm_exclude_reference_link 设为true可减少冗余信息

完整参数列表请参见openapi.yaml文件

命令行界面

所有读取操作请使用内置CLI工具。默认从.env文件获取认证信息，可通过命令行参数覆盖

命令概览

• list table 从指定数据表列出记录
• get table sys_id 根据sys_id获取单条记录
• batch file.json 单次调用执行多个读取请求
• attach 读取附件及文件内容
• stats table 聚合统计信息
• schema table 列出有效字段名和类型
• history table sys_id 读取完整的评论与工作记录时间线
• sc endpoint Service Catalog GET 端点

认证标志

• --domain 域实例
• --username 用户
• --password 密码

查询标志

可将以下任何一项用作 --sysparm_* 标志。

• --sysparm_query
• --sysparm_fields
• --sysparm_limit
• --sysparm_display_value
• --sysparm_exclude_reference_link
• --sysparm_suppress_pagination_header
• --sysparm_view
• --sysparm_query_category
• --sysparm_query_no_domain
• --sysparm_no_count

附件 API 参数

• --sysparm_query
• --sysparm_suppress_pagination_header
• --sysparm_limit
• --sysparm_query_category

聚合 API 参数

• --sysparm_query
• --sysparm_avg_fields
• --sysparm_count
• --sysparm_min_fields
• --sysparm_max_fields
• --sysparm_sum_fields
• --sysparm_group_by
• --sysparm_order_by
• --sysparm_having
• --sysparm_display_value
• --sysparm_query_category

服务目录参数

• --sysparm_view
• --sysparm_limit
• --sysparm_text
• --sysparm_offset
• --sysparm_category
• --sysparm_type
• --sysparm_catalog
• --sysparm_top_level_only
• --record_id
• --template_id
• --mode

输出

• --pretty pretty print JSON输出
• --out path 将二进制附件内容保存到文件

示例

列出最近的事件。

node cli.mjs list incident --sysparm_limit 5 --sysparm_fields number,short_description,priority,sys_id

使用过滤器查询。

node cli.mjs list cmdb_ci --sysparm_query "operational_status=1^install_status=1" --sysparm_limit 10

获取单条记录。

node cli.mjs get incident <sys_id> --sysparm_fields number,short_description,opened_at

动态覆盖认证。

node cli.mjs list incident --domain myinstance.service-now.com --username admin --password "***" --sysparm_limit 3

附件元数据与文件下载。

node cli.mjs attach list --sysparm_query "table_name=incident" --sysparm_limit 5
node cli.mjs attach file <sys_id> --out /tmp/attachment.bin

聚合统计。

node cli.mjs stats incident --sysparm_query "active=true^priority=1" --sysparm_count true

服务目录只读GET请求。

node cli.mjs sc catalogs --sysparm_text "laptop" --sysparm_limit 5
node cli.mjs sc items --sysparm_text "mac" --sysparm_limit 5
node cli.mjs sc item <sys_id>
node cli.mjs sc item-variables <sys_id>

服务目录端点仅限GET

• 购物车
• 配送地址 用户ID
• 验证类别
• 变更选项 实体ID
• 目录
• 目录 系统ID
• 目录类别 系统ID
• 类别 系统ID
• 项目
• 项目 系统ID
• 项目变量 系统ID
• 项目委托 项目系统ID 用户系统ID
• 生产者-记录 生产者编号 记录编号
• 记录-向导 记录编号 向导编号
• 生成-阶段-池 数量
• 步骤配置
• 愿望清单
• 愿望清单-条目 购物车条目编号
• 向导 系统编号

架构检查

如果不确定字段名称，请使用此功能。

node cli.mjs schema incident

读取工单历史

使用此功能读取完整对话，而不仅仅是当前状态。

node cli.mjs history incident <sys_id>

专家预设

在 specialists/ 目录下创建 JSON 批处理文件，以便一次性运行多次读取。

• specialists/incidents.json

每个条目都支持 sysparm_* 字段以及这些项目。

• 批量输出中的名称标签
• 表 目标表
• 系统编号 可选单条记录获取

运行批处理预设。

node cli.mjs batch specialists/incidents.json --pretty

输出

Table API 默认返回 JSON。结果出现在 result 下。

备注

• 使用 sysparm_limit 保持返回结果集较小。
• 使用 sysparm_fields 以避免载荷过大。
• 此技能按设计为只读。

代理工具包概要

• list 和 get 显示记录的当前状态。
• attach 显示文件和截图。
• stats 显示分析和聚合数据。
• sc 显示请求的项目变量。
• schema 显示数据库映射以纠正错误。
• history 显示人工对话的时间线。

观察与备注（重要）

• 服务目录端点可能返回空数组，具体取决于目录内容和搜索文本——请尝试使用更具体的--sysparm_text搜索词或增加--sysparm_limit的值。
• sysparm_display_value在读取表时默认启用，以返回人类友好的值（例如，用户名而非系统ID）。如需原始系统ID，请传递--sysparm_display_value false.
• 保持--sysparm_limit对于代理发起的查询，保持较小的数值以避免大量负载和超时。建议使用统计来获取计数或聚合数据，而不是下载大量行。
• 附件：元数据可通过附件列表/附件获取获取；使用附件文件 <sys_id> --out <路径>下载二进制内容进行本地分析。
• 架构检查（架构）可避免猜测字段名称，是在读取未知表之前建议的第一步。
• 历史记录（历史）从sys_journal_field获取日志条目（评论/工作备注），对于读取工单的完整对话线程非常有用。
• 使用--pretty参数使JSON输出便于人工审阅，并帮助代理总结冗长的结果。

推荐的批处理预设

我推荐使用specialists/目录下的这些专业JSON预设，以加速常见的读取工作流。它们是安全的（只读）并展示了如何组合相关的读取操作。

1. specialists/inspect_incident_schema.json— 用于事件的模式检查：

[
  {
    "name": "schema-incident",
    "table": "sys_dictionary",
    "sysparm_query": "name=incident^elementISNOTEMPTY",
    "sysparm_fields": "element,column_label,internal_type,reference",
    "sysparm_limit": 500
  }
]

2. specialists/incident_history_template.json— 历史记录模板（运行前请将<SYS_ID>替换为目标sys_id）：

[
  {
    "name": "incident-history",
    "table": "sys_journal_field",
    "sysparm_query": "name=incident^element_id=<SYS_ID>",
    "sysparm_fields": "value,element,sys_created_on,sys_created_by",
    "sysparm_order_by": "sys_created_on",
    "sysparm_limit": 500
  }
]

3. specialists/attachments_incident.json— 事件表的最近附件：

[
  {
    "name": "recent-incident-attachments",
    "table": "attachment",
    "sysparm_query": "table_name=incident",
    "sysparm_fields": "sys_id,file_name,content_type,table_sys_id,sys_created_on",
    "sysparm_limit": 20
  }
]

如何使用这些预设：

• 对于模式检查：node cli.mjs batch specialists/inspect_incident_schema.json --pretty
• 对于历史记录：请替换<SYS_ID>然后运行 node cli.mjs batch specialists/incident_history_template.json --pretty（或运行node cli.mjs history incident <SYS_ID> --pretty）
• 对于附件：运行 node cli.mjs batch specialists/attachments_incident.json --pretty，然后运行 node cli.mjs attach file <sys_id> --out /tmp/file以下载文件。

这些预设配置是故意设置为只读和保守的（限制设置得较小）。欢迎随时请求额外的预设配置（如P1仪表板、近期变更、升级记录等）。