请求脚本中 Auth 认证使用指南

适用范围

Auth 只在请求脚本中可用。

请求脚本用于在平台真正发起第三方 HTTP 请求前，修改当前请求配置 reqConf。它适用于网关服务、网关环境等带有 requestScript / requestScriptMethod 的 HTTP 请求链路。

内置对象

请求脚本运行时会自动注入两个对象：

reqConf
Auth

reqConf 是即将发送的 HTTP 请求配置，结构如下：

{
  "method": "POST",
  "url": "https://example.com/api",
  "params": {},
  "headers": {},
  "body": {},
  "contentType": 1
}

字段说明：

请求脚本不需要 return，直接修改 reqConf 即可。脚本执行结束后，平台会把修改后的 reqConf 回写并用于实际 HTTP 请求。

Auth 方法

Bearer Token

JS：

Auth.bearer(reqConf, "your-token");

Python：

Auth.bearer(reqConf, "your-token")

最终效果：

Authorization: Bearer your-token

Basic Auth

JS：

Auth.basic(reqConf, "username", "password");

Python：

Auth.basic(reqConf, "username", "password")

最终效果：

Authorization: Basic base64(username:password)

API Key 请求头

JS：

Auth.apiKeyHeader(reqConf, "X-API-Key", "your-api-key");

Python：

Auth.apiKeyHeader(reqConf, "X-API-Key", "your-api-key")

最终效果：

X-API-Key: your-api-key

API Key Query 参数

JS：

Auth.apiKeyQuery(reqConf, "access_token", "your-token");

Python：

Auth.apiKeyQuery(reqConf, "access_token", "your-token")

最终请求 URL 会追加：

?access_token=your-token

Digest Auth

JS：

Auth.digest(reqConf, "username", "password");

Python：

Auth.digest(reqConf, "username", "password")

Digest 会先基于当前 reqConf 发起一次未认证请求，用响应头中的 WWW-Authenticate 计算摘要，再写入：

Authorization: Digest ...

注意：

• reqConf.method 和 reqConf.url 必须有效。
• 目标服务必须返回 Digest challenge，也就是 WWW-Authenticate: Digest ...。
• auth-int 模式不支持 multipart/form-data 请求体。

无认证

JS：

Auth.none(reqConf);

Python：

Auth.none(reqConf)

Auth.none 不会主动删除已有认证信息，只会保持请求配置结构可用。

常见脚本示例

JS：Bearer Token 并追加租户头

Auth.bearer(reqConf, "your-token");

reqConf.headers["X-Tenant-Id"] = "tenant001";
reqConf.params["page"] = 1;
reqConf.body["deviceId"] = "demo-device";

JS：接口要求 API Key 放 Query

Auth.apiKeyQuery(reqConf, "api_key", "your-api-key");

reqConf.params["timestamp"] = Date.now();

JS：完全手写 Authorization

不使用 Auth 也可以直接操作请求头：

reqConf.headers["Authorization"] = "Bearer " + "your-token";
reqConf.headers["X-Trace-Id"] = "trace-001";

Python：Basic Auth 并修改 JSON 请求体

Auth.basic(reqConf, "username", "password")

reqConf["headers"]["X-Tenant-Id"] = "tenant001"
reqConf["body"]["deviceId"] = "demo-device"

Python：无请求体 GET

Auth.bearer(reqConf, "your-token")

reqConf["method"] = "GET"
reqConf["contentType"] = 3
reqConf["body"] = None
reqConf["params"]["deviceId"] = "demo-device"

生效链路

请求脚本的处理顺序：

1. 平台先根据接口配置构造 RequestConfig。
2. 如果配置了 requestScript，调用 executeRequestContent。
3. 脚本修改 reqConf，可通过 Auth 写入认证信息。
4. 平台将脚本结果回写到 RequestConfig。
5. HTTP 执行器读取 url、params、headers、body、contentType 发起请求。

因此 Auth 的本质是修改 reqConf.headers 或 reqConf.params，不是独立的认证通道。

常见问题

1. 脚本里提示 Auth is not defined

常见原因：

• 当前脚本不是请求脚本，而是数据解析函数脚本。
• 当前链路没有走 executeRequestContent。
• 环境配置 script.bridge.allow-list 限制了桥接对象，未允许 Auth。

2. Auth.bearer 执行了但第三方仍返回 401

建议检查：

• token 是否带了多余的 Bearer 前缀；Auth.bearer 会自动拼接。
• 第三方是否要求其他 header，例如租户、应用编号、时间戳、签名。
• 当前接口是否实际走 HTTP 请求链路，而不是 Redis、WebSocket、MCP 等其他链路。
• 请求脚本后续代码是否覆盖了 reqConf.headers["Authorization"]。

3. Digest 认证失败

建议检查：

• 目标服务第一次响应是否包含 WWW-Authenticate: Digest ...。
• reqConf.url 是否为完整可访问地址。
• reqConf.method 是否正确。
• 目标服务是否使用当前实现支持的算法：MD5、MD5-sess、SHA-256、SHA-256-sess。

4. 应该用 Auth 还是手写 header

常见认证建议优先使用 Auth：

• Basic
• Bearer
• API Key Header
• API Key Query
• Digest

特殊签名算法、动态 HMAC、时间戳签名等场景，可以在请求脚本中自行计算并写入：

reqConf.headers["Authorization"] = "Custom " + signature;
reqConf.headers["X-Timestamp"] = String(Date.now());

快速选择