> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 自动化发送 HTTP 请求

> AI 表格自动化 HTTP 请求：支持 GET/POST/PUT/PATCH/DELETE 方法向指定 URL 发送请求，将字段数据或流程中间结果传递给第三方系统，响应结果可继续作为后续步骤的输入。

# 1 功能概述

发送 HTTP 请求是AI表格自动化流程中的核心操作，支持通过预配置的网络请求向指定 URL 发送数据，从而触发外部系统的接口调用或数据交互。该功能可无缝衔接AI表格的字段数据或自动化流程的中间结果，实现与第三方平台的深度集成。生成的响应结果还可作为后续自动化步骤的输入，形成完整的自动化工作流。

发起HTTP请求，通过向指定的 URL 发出网络请求，实现和三方系统的打通，比如：

* 同步数据到内部系统：将数据同步到ERP、CRM等内部系统，免去人工手动同步。
* 数据抓取和爬虫：构建网络爬虫，获取网页内容并提取所需的数据。
* 集成第三方服务：集成各种第三方服务，如支付、发送短信或获取地理位置信息。

# 2 说明

## 2.1 请求方法

选择请求类型（必填）。请求类型决定了你希望对服务器执行什么样的操作

|         |                                                                                      |
| ------- | ------------------------------------------------------------------------------------ |
| 请求方法    | 说明                                                                                   |
| GET     | **获取服务器数据**  请求指定的页面或数据接口，并返回响应主体。常用来检索或获取信息。                                        |
| POST    | **向服务器提交数据（例如提交表单或者上传文件）**  用于将数据提交到指定资源（如表单提交、文件上传），提交的数据被包含在请求文本中。常用来创建新资源、修改现有资源。 |
| PUT     | **修改服务器的数据**  用于替换整个资源，需提供完整数据，通常用于更新操作。                                             |
| PATCH   | 部分修改服务器的数据                                                                           |
| OPTIONS | 获取服务器支持的请求类型                                                                         |
| DELETE  | 删除服务器的数据                                                                             |

## 2.2 参数说明

### 2.2.1 GET 请求

| 参数类型 | 参数名称   | 说明                                                          |
| ---- | ------ | ----------------------------------------------------------- |
| 入参   | 请求 URL | 包含路径和查询参数（如`<https://api.example.com/data?param1=value1`）。> |
| 入参   | 查询参数   | 附加在URL中的键值对（如`?page=1&limit=10`）。                           |
| 入参   | 请求头    | 可选，用于传递认证信息（如`Authorization: Bearer token`）。                |
| 出参   | 响应体    | 返回的数据内容（如JSON、XML或文本）。                                      |

### 2.2.2 POST/PUT/PATCH/DELETE 请求

| 参数类型 | 参数名称                  | 说明                                                           |
| ---- | --------------------- | ------------------------------------------------------------ |
| 入参   | 请求 URL                | 包含路径和查询参数（如`<https://api.example.com/resource/123`）。>        |
| 入参   | 查询参数                  | 可选，附加在URL中的键值对（如`?action=update`）。                           |
| 入参   | 请求头                   | 用于指定内容类型（如`Content-Type: application/json`）和认证信息。            |
| 入参   | 请求体                   | 要以请求头中Content-Type 设定的类型保持一致                                 |
| 出参   | 响应体                   | 返回的数据内容（如JSON、XML或文本）。                                       |
| 出参   | 返回值（仅当响应体为 JSON 时需配置） | 若响应体为JSON，可提取字段供后续流程使用（如`{"id": 123, "status": "success"}`）。 |

📌关于APISecret的说明

如果你请求的系统需要对请求进行验签，那么当你填写了apiSecret时，你的系统收到的HTTP请求Header中将包含签名相关Header：

* x-ddpaas-signature-timestamp：\<签名时时间戳>
* x-ddpaas-signature：\<签名串>

其中 \<签名串> = calcSignature(apiSecret, \<签名时时间戳>)，apiSecret是注册时指定的签名密钥。

你请求的系统应使用如下方法计算签名并验证签名串是否正确，以防未授权的调用：

```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
public static String calcSignature(String apiSecret, long ts) {
    try {
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec key = new SecretKeySpec(apiSecret.getBytes(), "HmacSHA256");
        mac.init(key);
        return Base64.getEncoder()
            .encodeToString(mac.doFinal(Long.toString(ts).getBytes()));
    } catch (NoSuchAlgorithmException | InvalidKeyException e) {
        log.error("sign api secret failed", e);
    }
}
```

### 2.2.3 定义出参，选择响应体

* HTTP请求的返回值（出参）会向下传给后续的步骤。响应体决定了在后续步骤中，流程将如何解析和引用这些参数。

<img src="https://mintcdn.com/dingtalk-8c0f98e2/ibah_7iYMOhNKsx4/zh/aitable/automation/http-request/images/image_eX3xpHE1HA.png?fit=max&auto=format&n=ibah_7iYMOhNKsx4&q=85&s=989746164ccfcd712a9e5e10e6971ca6" alt="" width="2432" height="1558" data-path="zh/aitable/automation/http-request/images/image_eX3xpHE1HA.png" />

* 选择响应体为JSON时，在后续步骤中会按照 JSON 规则对返回值进行结构化解析。因此，你需要手动填写一段返回值示例，以便在后续的步骤中，引用这些结构化的数据。

  <img src="https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/QvjnAAbRLb5ynXo5/img/6504e7f8-4085-45b9-9df5-315b38466d17.png" referrerPolicy="no-referrer" alt="" />
* 选择响应体为Text时，在后续的步骤中你能以text的格式引用整段返回值。

<img src="https://mintcdn.com/dingtalk-8c0f98e2/ibah_7iYMOhNKsx4/zh/aitable/automation/http-request/images/image_qs1WwX4nna.png?fit=max&auto=format&n=ibah_7iYMOhNKsx4&q=85&s=eb4685580c7cd46d9d921157d712fce8" alt="" width="2432" height="3074" data-path="zh/aitable/automation/http-request/images/image_qs1WwX4nna.png" />

* 选择响应体为None时，在后续步骤中将无法引用返回值的参数。

  <img src="https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/QvjnAAbRLb5ynXo5/img/92b43d17-cb77-4387-908a-f9c085443af0.png" referrerPolicy="no-referrer" alt="" />

# 3 常见问题

## 3.1 常见问题

* 问：默认HTTP失败规则包括以下情况
  * 状态码≠200
  * 系统异常失败，例如请求超时。

![](https://docs.dingtalk.io/core/api/resources/img/5eecdaf48460cde504de3b9e47e52bd8d1d5101b618320c219d28d1dd67f039915575e05a9d9575b39e8703ac5556d0ddeef526ad995f180e3467893156b9e1545d9a70219869bd29fc1567e33b287ea724220056927e30a38d07168ac0cfd52?docKey=eLbnj86494oNOaNY)

* 问：HTTP 请求超时错误可能由哪些原因引起？

  答：原因：网络延迟、服务器响应慢、防火墙/代理限制、DNS解析异常、服务器负载高。
* 问：AI表格自动化流程发送的 HTTP 请求是否支持配置固定 IP 地址（IP 白名单）以增强安全性？

  答：支持，多数平台允许通过配置出站IP白名单或绑定固定IP地址，需在平台后台或API网关中设置。 203.119.128.0/17, 59.82.0.0/16, 140.205.0.0/16, 106.11.0.0/16
* 问：是否支持在请求 URL 中直接附加查询参数以传递附加数据？

  答：支持，通过`?key1=value1&key2=value2`格式附加参数，适用于GET请求，部分POST请求也可使用（需服务器兼容）。
* 问：HTTP 请求未被正确解析的常见原因有哪些？如何验证请求的有效性？

  答：原因：

  * 请求格式错误（如JSON语法错误）。
  * 编码问题（如未正确设置`Content-Type`）。
  * 服务器端接口变更或版本不匹配。
  * 缺少必要请求头（如认证Token）。
    验证方法：
  * 使用工具（如Postman、curl）手动发送相同请求。
  * 检查响应状态码（如400表示客户端错误，5xx表示服务器错误）。
  * 启用调试日志或抓包分析（如Wireshark）。
* 问：符合 JSON 格式规范的 HTTP 响应体应包含哪些必要结构或约束条件？

  答：

  * 结构约束：
    * 必须为合法JSON对象（`{}`）或数组（`[]`）。
    * 字段名需用双引号包裹（`"key"`）。
    * 支持的数据类型：字符串、数字、布尔值、对象、数组、`null`。
  * 常见约定：包含状态码（`"code"`）、消息（`"message"`）、数据（`"data"`）等字段。
* 问：HTTP 请求中可配置的 Key-Value 参数对的最大数量限制是多少？

  答：

  * 无硬性限制，但受以下因素影响：
    * URL长度限制（通常建议不超过2048字符）。
    * 服务器端解析能力（如部分服务限制参数数量）。
    * 性能优化（避免过度冗余参数）。
* 问：能否在后续自动化步骤中引用 HTTP 响应中返回的数组类型数据进行处理？

  答：可以通过循环遍历，或在发送消息时通过组合字段输出
* 问：使用群组自定义机器人发送消息时，若直接复制开放平台的示例代码仍无法成功，可能涉及哪些配置或代码适配问题？

  答：

  * 常见问题：
    1. Webhook地址错误：未替换实际生成的URL或Token。
    2. 权限不足：机器人未加入目标群组或未授权操作。
    3. 格式不匹配：请求体格式与API要求不符（如未正确设置`Content-Type`）。
    4. 签名验证失败：缺少或错误的签名（如未计算时间戳或密钥）。
    5. 网络限制：防火墙或代理阻止请求。
  * 解决方法：
    * 仔细核对示例代码中的占位符（如`{token}`）。
    * 使用调试工具检查请求头、请求体和响应内容。
    * 查阅开放平台的开发者文档或联系技术支持。