概述
本技能提供在 ServiceNow 中开发自定义 Scripted REST API 的完整指南。Scripted REST API 允许你：暴露自定义端点——创建超出标准 Table API 的专用 API；控制数据转换——按集成需求塑造请求与响应格式；实现业务逻辑——在一次 API 调用中执行复杂操作；保护集成安全——应用细粒度的认证与授权；支持外部系统——为第三方系统集成提供接口。
适用场景：标准 Table API 无法满足需求时；需要在 API 层中加入自定义业务逻辑时；需要特定的请求/响应格式时；外部系统需要专用端点时；需要聚合多张表的数据时。
目标使用者：构建自定义 ServiceNow 集成的开发者、集成专家和管理员。
前置条件
角色：admin、web_service_admin 或 scoped app developer。 权限：创建/修改 sys_ws_definition、sys_ws_operation。 知识：JavaScript、REST 原则、HTTP 方法、JSON。 环境：开发实例（切勿直接在生产环境开发 API）。
相关技能：admin/update-set-management（捕获 API 定义）、admin/application-scope（作用域应用 API 开发）、security/acl-management（API 安全控制）。
表架构
理解底层表对于以编程方式创建 API 至关重要。核心表结构：sys_ws_definition（API 定义）下含 sys_ws_operation（资源/端点），端点内配置请求头、查询参数、路径参数（在 relative_path 中定义）与处理请求/响应的脚本。
关键关系：sys_ws_definition 为 API 容器，关键字段为 name、namespace、base_path、active；sys_ws_operation 为单个端点，关键字段为 name、http_method、relative_path、script；sys_script_include 为可复用逻辑，关键字段为 name、script、api_name；sys_ws_api_header 为自定义请求头，关键字段为 name、api_id、direction。
API URL 结构
https://<instance>.service-now.com/api/<namespace>/<api_name>/<version>/<resource>/<path_param>
示例：https://dev12345.service-now.com/api/x_company/customer_api/v1/customers/12345，依次对应实例、命名空间、API 名称、版本、资源与路径参数。
操作流程
第一阶段：API 设计。创建 API 前需仔细规划结构。定义 API 需求并记录规范，例如 API 名称、命名空间（作用域应用用 x_company，全局用 now）、版本、基础路径，以及各资源端点的 HTTP 方法。规划认证方式，可选类型包括：Basic Auth（服务账号，默认启用）、OAuth 2.0（第三方应用，需配置 OAuth 提供方）、API Key（简单集成，通过自定义请求头校验）、Session（基于浏览器，Cookie 认证）、Mutual TLS（高安全场景，证书校验）。
第二阶段：创建 API 定义。若在作用域应用中创建，先设置当前应用与更新集。随后通过 MCP 工具 SN-Create-Record 在 sys_ws_definition 表创建记录，关键字段说明：namespace 为 URL 段，建议使用应用作用域；enforce_acl 用于检查底层表 ACL，建议设为 true；is_versioned 启用版本控制，建议始终为 true；baseline_version 为未指定版本时的默认版本，建议从 v1 开始；published 控制 API 可发现性，开发阶段建议设为 false。保存返回的 sys_id。之后可用 SN-Query-Table 查询验证，service_address 字段显示完整 API URL。
第三阶段：创建资源（操作）。通过 MCP 工具 SN-Create-Record 在 sys_ws_operation 表创建各端点，示例包括：GET 集合资源（列表，支持分页、过滤与搜索，返回 result 与 meta 信息）；GET 单个资源（按 ID 查询，支持 sys_id 与 account_number 两种查找，含 404/400/403 处理与关联联系人聚合）；POST 资源（创建，含必填字段与邮箱格式校验、重复邮箱检测、201 状态与 Location 请求头设置）；PUT 资源（更新，含权限检查、邮箱变更校验与重复检测）。每个操作脚本使用标准的 (function process(request, response) {...})(request, response) 结构，并配置 requires_acl_authorization、requires_authentication 等安全选项。
适用场景与限制。本技能适用于 ServiceNow 平台上的自定义集成开发，需要开发实例环境、相应角色权限与 JavaScript/REST 知识。资料中的付费、价格、平台限制等细节暂未提供。