UIP 是连接器构建器活动挂钩

用于创建、读取和管理连接器活动上的 JavaScript 请求前/请求后挂钩的语法和选项。

uip is connectors builder activity hook 管理 JavaScript 转换挂钩 — 连接器的转义阴影线，用于声明性字段或参数无法表达的请求/响应逻辑。它是activity下的嵌套子组，由于钩子作者需要大量运行时上下文文档，因此该子组需要单独的页面。请参阅连接器构建器，以了解也适用的共享概念（连接器目录解析、典型的创作流程）。

挂钩文件位于连接器目录中的 app/element/hooks/ 下。挂钩可以附加到特定的资源和方法（资源挂钩），也可以针对每个请求运行（全局挂钩--global ）。

大纲

uip is connectors builder activity hook list [--connector-dir <path>]
uip is connectors builder activity hook get <filename> [--connector-dir <path>]
uip is connectors builder activity hook create --hook-type <preRequest|postRequest> [options...] [--connector-dir <path>]
uip is connectors builder activity hook delete <filename> [--connector-dir <path>]

uip 是连接器构建器活动挂钩列表

列出 app/element/hooks/ 下的 JavaScript 挂钩文件，以及每个文件是否在 element.json 中被引用。

选项

长	值	描述
--connector-dir <path>	路径	连接器目录。

示例

uip is connectors builder activity hook list

数据形状（--输出 json）

{
  "Code": "HookList",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Hooks": [
      { "filename": "resource-account-GET-postRequest.js", "registered": true }
    ]
  }
}

磁盘上存在但具有 registered: false 的挂钩文件为孤立文件 — 在重新注册（对其重新运行 hook create，或手动将其连接到 element.json）之前，其代码会免费运行。

UIP 是连接器构建器活动“获取”挂钩

读取单个挂钩文件的来源和注册状态。

参数

名称	必填	用途
<filename>	是	Hook 文件名，例如resource-account-GET-postRequest.js 或 global-preRequest.js。

选项

长	值	描述
--connector-dir <path>	路径	连接器目录。

示例

uip is connectors builder activity hook get resource-account-GET-postRequest.js

数据形状（--输出 json）

{
  "Code": "Hook",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Filename": "resource-account-GET-postRequest.js",
    "Registered": true,
    "Code": "done({ response_body });"
  }
}

UIP 是连接器构建器活动挂钩“创建”

创建一个 JavaScript 挂钩文件（除非 --no-auto-register），然后在 element.json 中注册其引用。

选项

长	值	必填	描述
--resource-name <name>	字符串	有条件地*	挂钩附加到的资源。如果使用 --global，则不需要。
--method <method>	字符串	有条件地*	资源的 HTTP 方法。如果使用 --global，则不需要。
--path <internalPath>	字符串	否	资源内部路径（唯一的 element.json 资源路径），用于在列表资源和 ID 值资源共享方法（例如/contacts/{id}）— 供应商路径不是唯一的，重要的是内部路径。
--hook-type <type>	preRequest|postRequest	是	挂钩阶段。
--custom-code <js>	字符串	否**	挂钩正文，内联。与 --custom-code-file 互斥。
--custom-code-file <path>	路径	否**	内容将成为挂钩正文的 .js 文件的路径。优先于 --custom-code。
--description <text>	字符串	否	放置在文件顶部的注释。
--context-params <list>	字符串	否	覆盖挂钩引用上的 contextParams 字符串。
--no-auto-register	标记	否	写入文件，但不在 element.json 中注册。
--global	标记	否	在顶层 hooks[] 数组中注册连接器范围内的挂钩，而不是附加到一个资源和方法。
--connector-dir <path>	路径	否	连接器目录。

* Commander 无法在表达式中表达“除非 --global 这是必需的”以声明方式 — 两个选项都是明文选项（非 requiredOption），基础服务在运行时强制执行资源挂钩案例，如果非全局挂钩中缺少 --resource-name/--method，则会失败。

** 同时传递 --custom-code 和 --custom-code-file 表示错误。自行编写挂钩正文（或让智能体编写）——CLI 仅放置和注册文件；它不会生成挂钩逻辑。

挂钩正文上下文

挂钩通过 done({...}) 返回，绝不是返回纯 return，并且必须在每个代码路径上调用 done()。CLI 会完全自动绑定您的正文引用的变量；使用 --context-params 覆盖该集合（如果使用，则明确列出 multipart_hook_context_items）。

preRequest — 只读：

request_method、request_headers、request_path、request_path_variables、request_parameters、request_body、request_body_map（将请求正文策划为映射 — 直接读取字段）、request_body_raw、request_vendor_body_map、request_vendor_url、request_expression（在 CEQL 中表示为 [{attribute,value,operator}]）、request_previous_response、request_previous_response_headers、object_name、vendor_object_name、configuration（在此阶段只读）。

preRequest — 读取/写入（编辑，然后仅返回您更改的密钥；纯done()将不加修改地通过所有内容）：

request_vendor_method、request_vendor_headers、request_vendor_path、request_vendor_parameters、request_vendor_body（读取时为字符串；写入时为字符串、列表或映射）、request_root_key、multipart_hook_context_items。

preRequest — done()仅限密钥： continue （ false会跳过供应商调用，但仍运行postRequest ）、 response_status_code / response_body / response_body_raw / response_error_message （将无需调用供应商）。

postRequest — 只读：

response_iserror（true，除非 HTTP 状态为 200–207），response_body_map，response_body_raw_map，实际发送给供应商的每个 request_* 变量，request_previous_response，request_previous_response_headers。

postRequest — 读取/写入（编辑并返回更改后的键）：

response_body（映射）、response_body_raw（字符串）、response_headers、response_status_code、response_root_key、configuration（在此阶段可写入 — 见下文）、multipart_hook_context_items。

postRequest — done()仅限键： response_error_message （将调用转换为错误；状态来自response_status_code ，否则为 400）、 connection_identity （设置连接的显示名称）、 metadata_merge / merge_objects （ 对象发现资源）。

关键规则：

• configuration 在 preRequest 中为只读，在 postRequest 中为可读/可写。要保留每个连接的派生值（例如，从令牌计算得出的基本 URL），请将其写入 postRequest 挂钩：done({ configuration: { 'base.url': url } })。在 configuration 中写入 preRequest 无效。
• 以 request_vendor_path 开头的 http 将成为完整的请求 URL，会绕过连接器已配置的基本 URL。
• 严格来说，成功指的是 HTTP 200–207。response_iserror 是派生变量，并且是只读的 — 为其返回不同的值不会执行任何操作。

引擎：挂钩运行时 (Denal) 支持新式 JavaScript（ ?. 、 ?? 、 async / await ）和require() ，适用于固定模块集： axios （用于从挂钩内部进行辅助 HTTP 调用）、 crypto 、 url 、 querystring 、 util 、 buffer 、 zlib 、 lodash 、 jmespath 、 moment 。

有关何时（和何时不）访问挂钩而不是声明性字段/参数的指导，CLI 指向uipath-connector-builder技能的references/hooks.md — 请参阅uip skills 。

示例

# Post-request hook for a resource, from an agent-written JS file
uip is connectors builder activity hook create \
  --resource-name Account --method GET --hook-type postRequest \
  --custom-code-file ./account-postRequest.js

# Global pre-request hook
uip is connectors builder activity hook create \
  --hook-type preRequest --global --custom-code-file ./my-hook.js

数据形状（--输出 json）

{
  "Code": "HookCreated",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Filename": "resource-Account-GET-postRequest.js",
    "HookType": "postRequest",
    "Method": "GET",
    "ResourceName": "Account",
    "FilePath": "app/element/hooks/resource-Account-GET-postRequest.js",
    "HookReference": {},
    "RegisteredInElement": true
  }
}

对于全局挂钩，Filename 遵循 global-<hookType>.js 模式（例如global-preRequest.js）和 ResourceName/Method。

UIP 是连接器构建器活动挂钩“删除”

删除挂钩文件，并从 element.json 中去除对其的所有引用。

参数

名称	必填	用途
<filename>	是	挂钩要删除的文件名。

选项

长	值	描述
--connector-dir <path>	路径	连接器目录。

没有专用的“编辑挂钩”按钮动词 — 删除并重新创建，或直接编辑磁盘上的文件（挂钩文件是纯 JavaScript，而不是生成的工件）。

示例

uip is connectors builder activity hook delete resource-account-GET-postRequest.js

数据形状（--输出 json）

{
  "Code": "HookRemoved",
  "Data": {
    "ConnectorRoot": "/work/periodic-design-acme",
    "Filename": "resource-account-GET-postRequest.js",
    "FileDeleted": true,
    "ReferenceRemoved": true
  }
}

相关内容

• 活动— 挂钩附加到的资源/字段/方法/参数命令。
• 连接器构建器— 概念和四个租户生命周期动词。
• 身份验证— 配置连接器的身份验证方案。
• 触发器和状态— 事件触发器和低级别元素文件编辑。

另请参阅

• Integration Service 工具概述
• 全局选项
• 退出代码