全局脚本

Configure Global Scripts in Connector Builder to run JavaScript before or after every API request for consistent request and response processing.

使用连接器生成器中的“全局脚本”选项卡，您可以编写在连接器发出每个 API 请求之前或之后运行的 JavaScript。使用前请求脚本修改传出请求，使用后请求脚本修改传出请求。

何时使用全局脚本

当您需要对连接器中的所有请求应用一致的逻辑时，全局脚本非常有用，例如：

• 发送前注入或覆盖请求标头、参数或正文
• 根据配置值动态构建供应商 URL
• 在供应商响应正文返回到工作流之前转换正文
• 在不调用供应商 API 的情况下，根据自定义条件停止请求

Scripts for a single resource

Each resource also has its own Scripts tab, alongside Parameters, Request fields, Response fields, and Activity designer. It provides the same Pre-request script and Post-request script editors, the same snippets, and the same variables and done() contract as the connector-level Global Scripts tab.

The difference is scope:

• A script on the Global Scripts tab runs for every request the connector makes.
• A script on a resource's Scripts tab runs only for that resource.

Use a resource script when the logic applies to one endpoint, and a global script when it applies to the whole connector.

编写脚本

要打开“全局脚本” 选项卡，请执行以下操作：

1. 在 Integration Service 中，打开“连接器生成器”并选择自定义连接器。
2. 从顶部导航栏中选择“全局脚本” 。
3. 展开“请求前脚本”或“请求后脚本” ，然后输入 JavaScript。

Scripts run in a sandboxed JavaScript environment, with no network access and no way to import packages.

Standard JavaScript built-ins are available: JSON, Date, Array, Object, URL, encodeURIComponent, URLSearchParams, TextEncoder, TextDecoder, btoa, atob, crypto, Blob, FormData, Headers, Intl, and BigInt.

重要提示：

Buffer is not available. Use btoa and atob for base64 encoding instead.

The following are not available in the sandbox:

类别	不可用
Evaluation and imports	eval, any require() call, a top-level import or export statement, a dynamic import(...) expression
网络	fetch, XMLHttpRequest, WebSocket
Timers and workers	setTimeout、setInterval、setImmediate、Worker、importScripts、postMessage
Runtime and globals	Deno、process、globalThis、self、window、WebAssembly、Buffer

done()函数

每个脚本都必须调用done()以表示已完成。done()用于立即终止执行 — 无法访问在done()之后写入的任何代码。

// Pass through unchanged
done();

// Override one or more output values
done({
  request_vendor_headers: updatedHeaders
});

// Return multiple overrides
done({
  request_vendor_body: newBody,
  request_vendor_headers: newHeaders
});

// Stop the request — do not call the vendor API
done({ continue: false });

// Stop the request and return an error
done({
  continue: false,
  response_status_code: 400,
  response_error_message: "Invalid action"
});

使用代码片段

Select Snippets in the script panel to insert code templates into the active script editor.

The Pre-request script panel offers the following templates, grouped under Prerequest scripts:

• Update provider URL — Sets request_vendor_path to a full URL, replacing the provider URL for that request.
• Use a configuration — Reads a value from configuration (the connector's base URL, in the sample) and sends it to the provider as a request header.
• Skip a provider request — Sets continue to false so the request is never sent to the provider.

The Post-request script panel offers the following templates, grouped under Postrequest scripts:

• Update the response body — Copies response_body into a local variable, adds a field to it, and returns the modified body.
• SR metadata generation from vendor metadata — Builds standard resource field metadata from a vendor metadata response, deriving each custom field's type, format, display name, description, supported methods, and enum values.

前请求脚本

在将每个 API 调用发送到提供程序之前，预请求脚本会运行。可以通过done()设置具有写入或读写访问权限的变量。

变量	访问	描述
request_method	读取	API 调用的 HTTP 方法（ GET 、 POST等）。
request_vendor_method	读取和写入	将传递给提供程序的 HTTP 方法。
request_headers	读取	作为 API 调用的一部分传递的请求标头。
request_vendor_headers	读取和写入	将发送给提供程序的标头。
request_path	读取	API 调用的请求路径。
request_vendor_path	读取和写入	将发送给提供程序的请求路径。如果路径以http开头，则将其用作完整的请求 URL。
request_path_variables	读取	从 URL 模板中提取的路径变量。
request_parameters	读取	作为 API 调用的一部分传递的查询参数。
request_vendor_parameters	读取和写入	将发送给提供程序的查询参数。
request_body	读取	作为 API 调用的一部分作为字符串传递的请求正文。
request_body_raw	读取	请求正文作为 API 调用的一部分作为未处理的字符串传递。
request_vendor_body	读取和写入	将发送给提供程序的请求正文。接受写入字符串、列表或映射。
request_body_map	读取	作为 API 调用的一部分作为映射传递的请求正文。
request_vendor_body_map	读取	系统会将作为映射发送给提供程序的请求正文。
request_vendor_url	读取	将用于供应商调用的完全格式端点 URL。
request_expression	读取	已转换为{attribute, value, operator}映射列表的 CEQL where参数。
request_previous_response	读取	上一个链接资源的响应正文。如果不属于链， null 。
request_previous_response_headers	读取	上一个链接资源的响应标头。如果不属于链， null 。
request_root_key	读取和写入	用于在请求 JSON 有效负载中构建子对象的点路径路径（例如data.record ）。
object_name	读取	请求的规范对象名称。
vendor_object_name	读取	供应商对象名称。与object_name相同，除非在资源上进行覆盖。
configuration	读取	连接器配置属性。
response_status_code	写入	当continue为false时要返回的 HTTP 状态代码。
response_error_message	写入	在将请求发送给供应商之前返回的错误消息。
response_body	写入	当continue为false时要返回的响应正文。
response_body_raw	写入	当continue为false时，要以字符串形式返回的响应正文。
response_root_key	读取和写入	用于将响应限制为子对象的点格式路径（例如data.records ）。
multipart_hook_context_items	读取和写入	用于文件上传请求的多部分表单项。
continue	写入	设置为false可跳过供应商调用。默认为true 。

示例：通过配置注入动态标头

var headers = request_vendor_headers || {};
var config = configuration || {};

headers['Authorization'] = 'Bearer ' + config['oauth_token'];

done({ request_vendor_headers: headers });

示例：覆盖供应商 URL 路径

var baseUrl = configuration['base_url'];
if (!baseUrl) {
  done({ continue: false, response_error_message: "Missing configuration: 'base_url'" });
  return;
}

var apiVersion = configuration['api_version'] || 'v1';
var modelId = request_path_variables.modelId;
var vendorUrl = baseUrl.startsWith('http') ? baseUrl : 'https://' + baseUrl;

done({
  request_vendor_path: vendorUrl + '/' + apiVersion + '/models/' + modelId + '/completions'
});

示例：修改请求正文

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

后请求脚本

请求后脚本在收到供应商的响应后运行。所有前请求变量仍可用作“读取”。将添加以下特定于响应的变量，并且configuration变为“读取和写入”。可以通过done()设置具有写入或读写访问权限的变量。

变量	访问	描述
response_iserror	读取	true 供应商响应指示存在错误（200–207 以外的状态代码）。
response_status_code	读取和写入	来自供应商的 HTTP 状态代码。
response_body	读取和写入	来自供应商的响应正文。
response_body_raw	读取和写入	来自供应商的原始响应正文，为字符串形式。
response_body_raw_map	读取	来自供应商的原始响应正文，作为映射。
response_body_map	读取	供应商的响应正文，作为映射。
response_headers	读取和写入	来自供应商的响应标头。
response_error_message	写入	要返回的错误消息。将响应转换为错误。
response_root_key	读取和写入	用于将响应限制为子对象的点格式路径（例如data.records ）。
configuration	读取和写入	连接器配置属性。更改会保留到连接器实例。
multipart_hook_context_items	读取和写入	用于文件上传请求的多部分表单项。
metadata_merge	写入	设置为true可将供应商元数据与模型元数据相结合。

提示：

在每个请求后脚本中添加错误防护。如果响应是错误，则不加参数调用done() ，以使其保持不变。

示例：转换响应正文

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

body.processed = true;
body.timestamp = new Date().toISOString();

done({ response_body: body });

实用功能

以下实用程序函数在两种脚本类型中都可用：

函数	描述
console.log()	输出调试消息。

自带 LLM 连接器用例

如果要为 LLM 提供程序（例如自托管模型或第三方推理端点）构建连接器，全局脚本可让您调整请求和响应以匹配预期合同，而无需单独修改每个资源。

提示：

对于常见的 LLM 提供程序（AWS Bedrock、Azure OpenAI、Google Vertex AI、OpenAI V1），您可以从预填充身份验证设置和脚本的连接器模板开始。有关详细信息，请参阅使用连接器模板。

以下脚本显示了此场景的完整请求前设置和请求后设置。

前置请求：设置身份验证标头

从连接器配置中注入提供程序的 API 密钥，并强制执行预期的Content-Type ：

var headers = {
  'Content-Type': 'application/json',
  'x-api-key': configuration['api_key']
};

done({
  request_vendor_headers: headers,
  request_vendor_body: request_body_map
});

预请求:插入系统消息

设置默认模型参数，并确保发送给模型的每个对话中均包含系统消息：

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

var hasSystemMessage = body.messages.some(function(msg) {
  return msg.role === 'system';
});

if (!hasSystemMessage) {
  body.messages.unshift({
    role: 'system',
    content: 'You are a helpful assistant.'
  });
}

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

请求后：处理选项数组

迭代供应商响应中的choices数组，并添加自定义元数据，然后返回到工作流：

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

if (body.choices && body.choices.length > 0) {
  body.choices.forEach(function(choice) {
    choice.processed_by = 'connector-post-script';
  });
}

body.custom_metadata = {
  processed: true,
  timestamp: new Date().toISOString()
};

done({ response_body: body });

最佳实践

• 始终调用done() — 未调用done()的脚本会挂起请求。
• 在变更前复制变量— 运行时使用严格模式 。先赋值给局部变量var headers = request_vendor_headers; ，然后修改headers 。
• 不要在done()之后写入代码，此代码无法访问。
• 检查null或undefined — 对于 GET 和 DELETE 请求， request_body和request_vendor_body是否为undefined 。
• 使用continue: false进行短接— 直接返回响应，而不调用供应商。