# 将应用程序连接到自动化

当系统中发生事件时发送应用程序事件，例如创建订单或收到付款。事件可以启动一次运行、继续一次正在等待该事件的运行，或取消与取消规则匹配的运行。每个自动化有一个事件 URL，适用于这三种用途。

> Automations is in Early access. Your workspace permissions determine which actions you can perform.

如果你无法打开 Automations 或创建草稿，请参阅[工作区访问和编辑权限](/docs/guides/automations/troubleshooting#automations-is-missing-from-the-dashboard)。

## 配置启动运行的事件

1. 创建一个自动化，将 **Event from your application** 设为触发器。
2. 设置 **Event name**，例如 `order.created`。名称区分大小写，可包含字母、数字、点、下划线或连字符。
3. 为应用程序发送的数据定义 **Event fields**。以订单为例，添加一个名为 `order_id` 的字符串字段。后续步骤可以使用这些字段。
4. 发布自动化。成功页面会显示 **How to start a run**，包括事件 URL 和请求示例。

如需再次查找连接详情，选择触发器并在快速编辑中点击 **How to connect your application**。展开的编辑器会显示连接控件。

## 模拟草稿或执行已发布版本

使用 **Preview workflow** 配合示例数据来模拟草稿，不会发送消息或更改数据。运行 cURL 命令、点击 **Send event…** 或使用 **Start run** 会执行已发布的自动化，可能产生实际操作。已保存和未保存的草稿更改不会应用于这些运行。

在发送事件之前先发布自动化。如果没有已发布版本，请求会被立即拒绝；事件不会排队或保存以备后用。编辑器中的示例可能反映草稿更改，因此在发送依赖这些更改的数据之前，请先发布。

## 复制 URL 并发送事件

使用 **Copy request** 获取包含 URL、请求头和示例正文的 cURL 命令。将示例值替换为你的应用程序数据。

URL 中包含工作区和自动化 ID：

```text
POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>
```

使用从仪表板复制的完整 URL。你不需要 `X-Workspace-Id` 请求头。当前的身份验证选项是 **No authentication**：任何拥有此 URL 的人都可以发送事件。请将其保存在服务器配置中。

对于配置了 `order.created` 的自动化，将 `AUTOMATION_EVENT_URL` 设为复制的 URL 并发送：

```bash
curl --request POST "$AUTOMATION_EVENT_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "order.created",
    "data": { "order_id": "order_123" }
  }'
```

将 `type` 设为已配置的事件名称，将 `data` 设为与事件字段匹配的对象。你还可以提供 `occurred_at` 作为 RFC 3339 时间戳；默认值为事件到达的时间。

带有 `status: "queued"` 的 `202 Accepted` 响应确认事件已排队。Bird 会生成事件标识符并以 `event_id` 返回。打开自动化的 **Runs** 标签页检查执行情况。排队成功并不意味着事件已匹配触发器或运行已启动。

你也可以在仪表板中使用 **Send event…** 提交示例，无需终端。这会发送一个真实事件。

## 继续一个正在等待事件的运行

等待步骤使用与触发器相同的自动化 URL。它的事件名称和 `subject_key` 标识发生了什么以及哪个运行应接收该事件。

1. 在 **Automation settings** 中，启用 **Skip overlapping runs** 和 **Use a business key**。将 **Business key** 设为能标识订单、发票或其他对象的值。以订单为例，使用表达式 `trigger.data.data.order_id`。
2. 添加 **Wait for application event** 并配置其事件名称、事件字段和超时时间。例如，等待 `order.paid`，包含一个字符串 `payment_id` 字段。
3. 发布后发送启动事件，等待其运行出现在 **Runs** 中。
4. 向同一 URL 发送后续事件，`subject_key` 等于该运行的业务键：

```json
{
  "type": "order.paid",
  "subject_key": "order_123",
  "data": { "payment_id": "payment_456" }
}
```

`subject_key` 是业务键的值，例如 `order_123`；它不是事件 ID 或运行 ID。等待步骤的展开连接视图会显示针对您所配置键的指引。

匹配事件可以在运行启动后、到达等待步骤之前被捕获。在匹配的运行存在之前处理的事件不会为将来的运行保存。带过滤器的等待仅在事件字段和过滤器都匹配时才继续。如果在截止时间之前没有处理到符合条件的事件，运行将走超时路径。

**Automation settings** 中的取消规则也使用此 URL。规则可以针对自动化的所有活跃运行，或匹配 `subject_key` 的运行。配置过滤器来缩小取消范围。取消无法撤销已执行的操作。

## 已发布版本与暂停的自动化

新运行使用事件被处理时的活跃版本。现有运行保留其原始版本，包括事件字段和等待条件。发布更改后的事件格式不会更新已启动的运行。

暂停已发布的自动化会停止新运行。暂停期间，事件仍然可以继续或取消现有运行。

## 处理投递和重试

事件异步处理，可能被重试或乱序处理。在发送后续事件之前，请等待启动运行已存在。事件的 `occurred_at` 不控制处理顺序、不延长等待时间、也不阻止超时。

重试保护是有限的。如果重试记录过期或丢失，事件可能被再次处理，可能针对较新的版本或不同的活跃运行。请将应用程序设计为能容忍重复事件。

要启用重试保护，请在首次尝试时提供 `Idempotency-Key`，然后在重试时使用相同的 URL 和未更改的请求体重新发送该键。每个新请求使用一个新键。重放请求会返回相同的 `event_id`。[幂等性指南](/docs/guides/idempotency)介绍了有限的重放窗口和冲突响应。

## 排查事件问题

- **请求返回 4xx：** 检查响应的错误详情、URL 以及必需的 `type` 和对象 `data` 字段。发送 `Content-Type: application/json`。整个请求体必须在 25 KB（25,000 字节）以内；超出限制的请求体会返回 `413`。
- **自动化尚未发布：** 在发送事件之前先发布。被拒绝的事件不会保留；发布后请重新发送请求。
- **The request returns 202 but no run starts:** 检查自动化是否处于活跃状态、事件名称是否与触发器匹配，以及数据是否与已发布的事件字段一致。重叠保护可能会在另一个运行仍处于活跃状态时跳过新运行。还需检查[每月运行配额](/docs/guides/automations/runs#early-access-run-allowance)；达到限额后被跳过的启动不会排入下个月的队列。
- **运行停留在等待步骤：** 检查事件名称、精确的业务键、数据字段、过滤器和超时时间。使用运行原始已发布版本中的事件格式。
- **重试返回冲突：** 使用原始键和未更改的请求进行重试。如果你打算发送不同的事件，请使用新的键。

请求的信封在排队之前进行检查。事件数据在处理过程中根据触发器、等待和取消规则进行检查，因此已排队的事件可能无法匹配其中任何规则。

## 后续步骤

- [打开 **Automations**](https://bird.com/dashboard/w/automations) 来配置和发布你的工作流。
- 在你的应用程序中[处理幂等重试](/docs/guides/idempotency)。
- 在运行中的工作流中[等待事件](/docs/guides/automations/waits)。
- [浏览 Automations 指南](/docs/guides/automations)。

## Related resources

- [Preview your first automation](/docs/get-started/automations) (docs)