文档中心

大数据研发治理套件

Activity （任务节点）类型

Web

Web Activity 用于在 Pipeline 中发送同步 HTTP 请求，并将响应提供给下游 Activity。您可以配置请求地址、方法、参数、认证、成功状态码和重试策略，无需为一次 API 调用单独编写脚本。

概述

Web Activity 适合调用业务接口、发送处理完成通知、查询外部服务状态，或向外部系统提交任务。

调用方式
目前支持 GET、POST、PUT 三种方法。Web Activity 为同步调用：节点仅等待本次 HTTP 请求的响应，不等待外部任务最终完成。例如接口返回 202 Accepted 且该状态码在成功范围内时，仅表示请求已被接受；外部任务的真实状态需要通过后续步骤查询。
能力范围与网络要求
- 不支持异步 Webhook 回调等待、WebSocket、SSE、二进制响应和大文件传输。
- 仅支持访问公网可达的 https:// 地址；不提供私有域名解析、VPC 网络配置或计算资源组选择。
- 需要访问私网 HTTP 接口时，请改用 HTTP 数据源配合 Lookup Activity。

配置步骤

在 Pipeline 编排页面添加 Web Activity，并设置节点名称和上下游依赖。
选择 HTTP 方法，填写 URL、Query 参数、Headers 和 Body。
按目标接口要求选择并配置认证方式。
设置成功状态码、响应超时和重试策略。
使用开发环境参数发送测试请求，检查状态码和响应内容。

注意
测试请求会调用真实接口。POST、PUT 测试前需要确认操作可能产生的业务影响。测试请求不会创建正式 Pipeline 实例。
保存并调试 Pipeline，确认后发布。发布后可在实例详情中查看运行结果。

请求配置

配置项	必填	说明
节点名称	是	在当前 Pipeline 中唯一，例如 `notify_order_api`；命名规则沿用通用 Activity 配置。
HTTP 方法	是	GET、POST 或 PUT。
URL	是	仅支持公网可达的 https:// 地址，其他协议会在发布或运行前被阻断。URL 支持参数引用替换。
Query 参数	否	以键值对追加到 URL，同名参数不能重复。
Headers	否	请求 Header 键值对；不能覆盖认证配置生成的 Header 或平台管理的 Header。
Body	否	支持 JSON、Text、无 Body 或 application/x-www-form-urlencoded。JSON 内容在保存及运行时解析后都需合法；当前不支持 multipart/form-data。
认证方式	是	支持 no auth、basic auth 和 token auth 三种认证方式，默认为 no auth。请根据目标接口要求配置。

说明

请求及认证中的文本字段支持参数引用替换。不同环境可以为同名参数赋不同值，以切换接口地址和凭证；Web Activity 无需选择 HTTP Connection 或 Profile。建议使用界面选择器插入引用，避免混用不同材料中的参数命名写法。

认证配置

认证方式	配置内容	使用场景
no auth	无附加认证字段	无需认证的接口。
basic auth	用户名、密码	使用 HTTP Basic 认证的接口。
token auth	Token	使用已有 Token 的接口。

说明

密码、Token 等敏感值应使用平台支持的敏感参数引用，避免在配置和代码中保存明文凭证。敏感参数的解析值不会作为普通业务 Output 输出。

响应判定与运行策略

Web Activity 根据成功状态码判断本次 HTTP 请求是否成功，根据重试策略决定失败后是否继续尝试，并通过总超时时间控制节点的最长执行时长。相关配置项介绍如下表所示：

配置项	默认值或限制	说明
成功状态码	`200–299`	可配置单值或范围。超出成功集合时节点失败。
响应超时	默认 60 秒，最大 600 秒。	限制本次同步请求等待响应的时间。
响应体上限	4 MiB	超限失败，不返回截断的成功结果。
响应 Header 上限	64 KiB	超限失败。
跟随重定向	默认开启，最多 5 次。	系统会对初始 URL 及每一次重定向目标逐跳执行 SSRF 安全检查，拒绝访问内网地址和元数据地址。
最大重试次数	默认 0	主动配置后才开启业务请求重试。
总超时时间		从节点发起第一次请求起算，到判定节点失败为止的总上限，请求本身耗时与重试等待时长都计入其中。
重试策略
重试状态码	默认 408、429、500–599	可按业务需要修改，仅命中填写的状态码才会触发重试。
连接失败时重试	默认开启	开启后，TCP 连接失败、DNS 解析失败等网络层错误也会触发重试。
重试间隔	默认 0 秒	首次等待时长。实际等待时长由该值和退避策略共同决定。
退避策略	默认固定间隔	决定每次重试之间等待时长的增长方式，提供两种模式：固定间隔：每次重试前等待相同时间；适用于希望重试节奏稳定、可预测的场景。指数退避：重试等待时间随次数递增；适用于 429、5xx 等需要延后重试的场景，可减少短时间内的连续请求。

说明

成功状态码仅代表 HTTP 请求结果，不代表业务一定成功，业务结果请由后续节点基于响应体判断。
Web Activity 不允许跳过 TLS 证书校验。
重试会导致目标接口在短时间内收到多次相同请求，POST、PUT 等副作用接口请由目标服务自身保证幂等。
请求已经发送但响应丢失时，外部系统可能已经处理请求。重新测试或重跑前，请先核对外部系统状态。
取消等待不能撤销对方已经接受的业务操作。
Retry-After 是目标服务器在响应头中返回的“下一次重试建议时长”，不属于节点配置项。平台是否遵循 Retry-After、以及与“重试间隔 / 退避策略”如何协调，以实际产品实现为准。如需查看，可在节点 Output 的 headers 中读取该响应头。

配置示例

以下为无认证 JSON 请求的配置示例。api.example.com 为说明用地址，请替换为您有权调用的测试接口，并通过界面生成实际配置。

activities:
  - name: notify_order_api
    type: web
    request:
      method: POST
      url: https://api.example.com/v1/jobs/callback
      authentication:
        type: no_auth
      headers:
        Content-Type: application/json
      bodyMode: json
      body:
        businessDate: "20261013"
        result: success
    response:
      successStatusCodes: ["200-299"]
      timeoutSeconds: 60
      maxBytes: 4194304
    retryPolicy:
      maxRetries: 0
    position:
      x: "600"
      y: "100"

注意

生产接口通常需要配置认证。若接口支持幂等键，应按其协议设置 Header 名称和值；同一次业务操作的重试应使用同一键值。不能仅增加一个 Header 就假设接口具备幂等能力。
bodyMode 的枚举值必须与实际实现一致；如果实际值不是 json，应替换为线上接口或页面生成的真实值。

Output

Web Activity 的业务 Output 固定包含四个一级字段：

字段	类型	说明
`status_code`	integer	最终业务 HTTP 响应状态码。
`header`	object	响应 Header 对象。目标服务器返回的所有响应头（如 `Content-Type`、`Retry-After` 等）均包含在该字段中。字段名称以实际返回结果为准，不保证统一转换为小写。
`response`	JSON 值、string 或 null	有效 JSON 返回解析值；其他文本响应返回 UTF-8 字符串；空响应返回 null。
`duration_ms`	integer	业务 HTTP 请求的实际耗时，单位为毫秒。

例如：

{
  "status_code": 202,
  "header": {
    "content-type": "application/json"
  },
  "response": {
    "accepted": true,
    "job_id": "job_001"
  },
  "duration_ms": 684
}

在下游配置项中单击插入动态内容，选择目标上游节点。引用语法由当前版本的选择器生成；使用前应核对实际输出结构并完成运行验证。
请使用当前页面生成的引用，并根据目标节点的实际响应结构取值；不要手工拼接未验证的字段路径。
response 可能是 JSON 对象、数组、文本或 null。只有实际返回对象包含 job_id 时，才可进一步取该字段。请勿直接套用其他节点或其他版本的引用表达式。
非成功状态码的响应仍可在当前执行尝试的详情中用于排障，但不能按成功节点的 Output 供普通下游引用。连接失败时可能没有 HTTP 响应，应查看错误详情和日志。

常见问题

问题	排查方法
401	检查认证方式、当前环境参数和 Token 有效期。Token 失效后应更新相应凭证或引用。
403	检查目标 API 授权与访问策略；重新获取 Token 不一定能解决权限问题。
域名解析或连接失败	确认 URL 使用 `https://`，且目标地址可以从公网访问。Web Activity 不提供私有域名解析、VPC 网络配置或计算资源组选择；私网 HTTP 场景请使用 HTTP 数据源配合 Lookup Activity。
JSON Body 无效	检查参数替换后的引号、数字、布尔值和 JSON 语法。
响应不是对象	检查接口实际返回类型；`response` 也可能是文本、数组或 null。
响应过大	精简返回字段或改用适合数据传输的能力；Web Activity 不用于大文件传输。
超时后重复产生业务操作	先核查目标系统状态，再决定是否重试，并使用目标接口支持的幂等机制。

使用建议

先使用测试接口验证认证、网络和响应结构，再接入正式环境。
成功状态码只反映 HTTP 调用结果；业务是否成功还需根据响应内容判断。
为跨环境配置使用同名参数，使用敏感参数承载凭证。
对会写入或删除数据的请求谨慎开启重试，并避免让接口返回不必要的敏感数据。

最近更新时间：2026.11.06 14:18:37

这个页面对您有帮助吗？

有用

无用

大数据研发治理套件

概述 #

配置步骤 #

请求配置 #

认证配置 #

响应判定与运行策略 #

配置示例 #

Output #

常见问题 #

使用建议 #

概述