mcpField
R
rest-integration

rest-integration

github.com/serac-labs开发7764 次安装9 周前更新
代码仓库

关于 rest-integration

面向 ServiceNow 开发者的 REST 集成模式指南，涵盖对外请求、认证、响应处理与错误恢复，并介绍相关 MCP 工具。

主要功能

  1. 01发送 GET 和 POST 请求
  2. 02配置多种认证方式
  3. 03处理响应正文与标头
  4. 04设置超时并实现重试

适用场景

  1. 01调用外部 API
  2. 02解析 JSON 响应
  3. 03排查请求失败与限流

MCP 相关

介绍用于创建 REST Message 的 MCP 工具示例。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/serac-labs/serac --skill rest-integration

安装后在 Claude Code 中输入/rest-integration确认已加载。

详细介绍

ServiceNow 的 REST 集成模式

ServiceNow 提供 RESTMessageV2，用于发起出站 REST API 调用；同时提供 REST API，用于接收入站请求。

出站 REST（调用外部 API）

基本 GET 请求
var request = new sn_ws.RESTMessageV2()
request.setEndpoint("https://api.example.com/users")
request.setHttpMethod("GET")
request.setRequestHeader("Accept", "application/json")

var response = request.execute()
var httpStatus = response.getStatusCode()
var body = response.getBody()

if (httpStatus == 200) {
  var data = JSON.parse(body)
  gs.info("Found " + data.length + " users")
}
带 JSON 请求体的 POST 请求
var request = new sn_ws.RESTMessageV2()
request.setEndpoint("https://api.example.com/incidents")
request.setHttpMethod("POST")
request.setRequestHeader("Content-Type", "application/json")
request.setRequestHeader("Accept", "application/json")

var payload = {
  title: "New Incident",
  description: "Created from ServiceNow",
  priority: "high",
}
request.setRequestBody(JSON.stringify(payload))

var response = request.execute()
使用 REST Message 记录

创建 REST Message 记录，以便重复使用集成配置：

// Using predefined REST Message from sys_rest_message
var request = new sn_ws.RESTMessageV2("External API", "Create User")

// Set variable substitutions defined in the REST Message
request.setStringParameter("user_name", userName)
request.setStringParameter("email", email)

var response = request.execute()

身份验证方式

基本身份验证
var request = new sn_ws.RESTMessageV2()
request.setEndpoint("https://api.example.com/data")
request.setHttpMethod("GET")
request.setBasicAuth("username", "password")
Bearer 令牌
var request = new sn_ws.RESTMessageV2()
request.setEndpoint("https://api.example.com/data")
request.setHttpMethod("GET")
request.setRequestHeader("Authorization", "Bearer " + token)
OAuth 2.0（使用 OAuth 配置文件）
var request = new sn_ws.RESTMessageV2()
request.setEndpoint("https://api.example.com/data")
request.setHttpMethod("GET")
request.setAuthenticationProfile("oauth2", "My OAuth Profile")
API 密钥
var request = new sn_ws.RESTMessageV2()
request.setEndpoint("https://api.example.com/data")
request.setHttpMethod("GET")
request.setRequestHeader("X-API-Key", apiKey)
// Or as query parameter
request.setQueryParameter("api_key", apiKey)

错误处理

try {
  var request = new sn_ws.RESTMessageV2()
  request.setEndpoint("https://api.example.com/data")
  request.setHttpMethod("GET")
  request.setHttpTimeout(10000) // 10 second timeout

  var response = request.execute()
  var httpStatus = response.getStatusCode()

  if (httpStatus == 200) {
    var body = response.getBody()
    var data = JSON.parse(body)
    // Process successful response
  } else if (httpStatus == 401) {
    gs.error("Authentication failed")
  } else if (httpStatus == 404) {
    gs.error("Resource not found")
  } else if (httpStatus >= 500) {
    gs.error("Server error: " + httpStatus)
  } else {
    gs.error("Unexpected status: " + httpStatus)
  }
} catch (ex) {
  gs.error("REST Exception: " + ex.message)
}

响应处理

解析 JSON 响应
var body = response.getBody()
var data = JSON.parse(body)

// Access nested data
var userName = data.user.name
var items = data.items || []
处理数组
var body = response.getBody()
var users = JSON.parse(body)

for (var i = 0; i < users.length; i++) {
  var user = users[i]
  gs.info("User: " + user.name + " (" + user.email + ")")
}
响应标头
var contentType = response.getHeader("Content-Type")
var rateLimitRemaining = response.getHeader("X-RateLimit-Remaining")

用于 REST 的 MCP 工具

// Create REST Message record
snow_create_rest_message({
  name: "External API",
  endpoint: "https://api.example.com",
  authentication: "basic", // or "oauth2", "api_key"
  methods: [
    {
      name: "Get Users",
      http_method: "GET",
      endpoint: "/users",
    },
    {
      name: "Create User",
      http_method: "POST",
      endpoint: "/users",
      content_type: "application/json",
    },
  ],
})

// Test REST connection
snow_test_rest_connection({
  endpoint: "https://api.example.com/health",
})

最佳实践

  1. 使用 REST Message 记录 - 集中配置，便于维护
  2. 设置超时 - 使用 setHttpTimeout() 防止脚本挂起
  3. 处理所有状态码 - 不要只处理 200
  4. 记录失败信息 - 使用 gs.error() 进行调试
  5. 对响应缓慢的 API 使用异步调用 - 不要阻塞业务规则
  6. 安全存储凭据 - 使用 Connection & Credential Aliases
  7. 实现重试逻辑 - 应对暂时性故障
  8. 注意速率限制 - 检查响应标头，并实现退避机制

重试模式

function callApiWithRetry(endpoint, maxRetries) {
  var retries = 0
  var delay = 1000 // Start with 1 second

  while (retries < maxRetries) {
    try {
      var request = new sn_ws.RESTMessageV2()
      request.setEndpoint(endpoint)
      request.setHttpMethod("GET")

      var response = request.execute()

      if (response.getStatusCode() == 200) {
        return JSON.parse(response.getBody())
      }

      if (response.getStatusCode() >= 500) {
        // Server error - retry
        retries++
        gs.sleep(delay)
        delay = delay * 2 // Exponential backoff
        continue
      }

      // Client error - don't retry
      throw new Error("Client error: " + response.getStatusCode())
    } catch (ex) {
      retries++
      if (retries >= maxRetries) {
        throw ex
      }
      gs.sleep(delay)
      delay = delay * 2
    }
  }
}

评论

支持 Markdown