介绍
# ServiceNow Table API Read Only
使用此技能通过 Table API 从 ServiceNow 读取数据。请勿创建、更新或删除记录。
## 配置
在此文件夹的 .env 文件中设置以下环境变量。
- SERVICENOW_DOMAIN 实例域名，例如 myinstance.service-now.com - SERVICENOW_USERNAME 基本身份验证的用户名 - SERVICENOW_PASSWORD 基本身份验证的密码
如果您的域名已经包含 https://，则请原样使用。否则，应向以下地址发出请求：
``` https://$SERVICENOW_DOMAIN ```
## 允许的操作 仅限 GET
仅使用这些文件中的 GET 端点。
- openapi.yaml 用于 Table API - references/attachment.yaml 用于 Attachment API - references/aggregate-api.yaml 用于 Aggregate API - references/service-catalog-api.yaml 用于 Service Catalog API
### 列出记录 - GET /api/now/table/{tableName}
### 通过 sys_id 获取记录 - GET /api/now/table/{tableName}/{sys_id}
切勿使用 POST、PUT、PATCH 或 DELETE。
## Table 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
使用捆绑的 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
### Attachment API 参数
- --sysparm_query - --sysparm_suppress_pagination_header - --sysparm_limit - --sysparm_query_category
### Aggregate 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
### Service Catalog 参数
- --sysparm_view - --sysparm_limit - --sysparm_text - --sysparm_offset - --sysparm_category - --sysparm_type - --sysparm_catalog - --sysparm_top_level_only - --record_id - --template_id - --mode
### 输出
- --pretty 美化打印 JSON 输出 - --out path 将二进制附件内容保存到文件
### 示例
列出最近的事件。
```bash node cli.mjs list incident --sysparm_limit 5 --sysparm_fields number,short_description,priority,sys_id ```
使用过滤器进行查询。
```bash node cli.mjs list cmdb_ci --sysparm_query "operational_status=1^install_status=1" --sysparm_limit 10 ```
获取单条记录。
```bash node cli.mjs get incident <sys_id> --sysparm_fields number,short_description,opened_at ```
即时覆盖身份验证。
```bash node cli.mjs list incident --domain myinstance.service-now.com --username admin --password "***" --sysparm_limit 3 ```
附件元数据和文件下载。
```bash node cli.mjs attach list --sysparm_query "table_name=incident" --sysparm_limit 5 node cli.mjs attach file <sys_id> --out /tmp/attachment.bin ```
聚合统计。
```bash node cli.mjs stats incident --sysparm_query "active=true^priority=1" --sysparm_count true ```
Service Catalog 只读 GET。
```bash 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> ```
### Service Catalog 端点 仅限 GET
- cart - delivery-address user_id - validate-categories - on-change-choices entity_id - catalogs - catalog sys_id - catalog-categories sys_id - category sys_id - items - item sys_id - item-variables sys_id - item-delegation item_sys_id user_sys_id - producer-record producer_id record_id - record-wizard record_id wizard_id - generate-stage-pool quantity - step-configs - wishlist - wishlist-item cart_item_id - wizard sys_id
### Schema 检查
如果您不确定字段名称，请使用此功能。
```bash node cli.mjs schema incident ```
### 读取工单历史记录
使用此功能读取完整的对话，而不仅仅是当前状态。
```bash node cli.mjs history incident <sys_id> ```
### 专家预设
在 specialists/ 下创建 JSON 批处理文件以一次运行多个读取。
- specialists/incidents.json
每个条目支持 sysparm_* 字段以及以下项目。
- name 批处理输出中的标签 - table 目标表 - sys_id 可选的单条记录获取
运行批处理预设。
```bash node cli.mjs batch specialists/incidents.json --pretty ```
## 输出
Table API 默认返回 JSON。结果出现在 result 下。
## 注意事项
- 使用 sysparm_limit 保持结果较小。 - 使用 sysparm_fields 避免较大的负载。 - 出于设计考虑，此技能为只读。
## 代理工具包摘要
- list 和 get 显示记录的当前状态。 - attach 显示文件和屏幕截图。 - stats 显示分析和聚合。 - sc 显示请求的项目变量。 - schema 显示数据库映射以纠正错误。 - history 显示人类对话的时间线。
## 观察与笔记（重要）
- Service Catalog 端点可能会根据目录内容和搜索文本返回空数组——请尝试更具体的 `--sysparm_text` 条目或增加 `--sysparm_limit`。 - 默认情况下，表读取启用了 `sysparm_display_value`，以返回人类友好的值（例如，用户名而不是 sys_ids）。如果您需要原始系统 ID，请传递 `--sysparm_display_value false`。 - 对于代理发起的查询，请保持 `--sysparm_limit` 较小，以避免大型负载和超时。对于计数或聚合，请优先使用 `stats`，而不是下载许多行。 - 附件：元数据可通过 `attach list`/`attach get` 获取；使用 `attach file <sys_id> --out <path>` 下载二进制内容以进行本地分析。 - Schema 检查（`schema`）避免猜测字段名称，是在读取未知表之前建议的第一步。 - 历史记录（`history`）从 `sys_journal_field` 获取日记条目（评论/work_notes），对于读取工单的完整对话线程非常有用。 - 使用 `--pretty` 使 JSON 输出易于人工阅读，并帮助代理总结较长的结果。
## 推荐的批处理预设
我建议使用 `specialists/` 下的这些专家 JSON 预设来加速常见的读取工作流程。它们是安全的（只读），并演示了如何组合相关的读取。
1) `specialists/inspect_incident_schema.json` — `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）：
```json [ { "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` — 事件表的最近附件：
```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 } ] ```
如何使用这些： - 对于 schema：`node cli.mjs batch specialists/inspect_incident_schema.json --pretty` - 对于 history：替换 `<SYS_ID>`，然后运行 `node cli.mjs batch specialists/incident_history_template.json --pretty`（或运行 `node cli.mjs history incident <SYS_ID> --pretty`） - 对于 attachments：`node cli.mjs batch specialists/attachments_incident.json --pretty`，然后运行 `node cli.mjs attach file <sys_id> --out /tmp/file` 下载文件。
这些预设是有意的只读和保守的（限制设置得很小）。随时可以请求额外的预设（P1 仪表板、最近的更改、升级）。