Skip to main content

字段和字段集

在处理 Zapier API 时，需要考虑两种主要类型的字段：输入字段和输出字段：

输入字段

这些字段是为一个操作提供的，以便其能够运行。它们类似于函数的参数。

输出字段

这些字段是由一个操作返回的。这些字段随后可以被_映射_到 Zap 中的后续操作的输入字段中。

输入字段​

要获取一个操作的输入字段，请向 /actions/{action_id}/inputs 端点发送请求：

请求

// POST /actions/core:853266/inputs
{
  "data": {
    "authentication": "762331",
    "inputs": {}
  }
}

无效化​

invalidates_input_fields 字段表示当给定字段的值发生变化时，是否需要从 /inputs 端点_重新获取_输入字段。一个现实世界的例子是电子表格应用：在向工作表添加新行时，第一个输入字段允许用户选择相关的工作表，一旦选择后，就会出现更多输入字段（每个对应选定工作表中的一列）。如果用户更改了工作表，则必须重新获取输入字段。

在重新获取输入字段时，请确保包含所有已填充的字段：

请求

// POST /actions/core:5381/inputs
{
  "data": {
    "authentication": "928117",
    "inputs": {
      "spreadsheet": "my_sheet"
    }
  }
}

在这个例子中，如果用户更改了 spreadsheet 的值，我们应该重新获取 /inputs 并传递这个新值，以重新加载所有字段。如果 worksheet 被修改，我们同样会重新获取 /inputs 并重新加载非依赖字段。这是因为 spreadsheet 和 worksheet 都将 invalidates_input_fields 字段设置为 true。

依赖关系​

有时，一个输入字段_依赖_于一个或多个其他字段，这意味着如果任何依赖字段发生变化，就需要重新获取 /inputs。这通过 depends_on 数组字段来表示，该数组包含字段 ID 的字符串。继续使用电子表格的例子，worksheet 字段依赖于 spreadsheet 字段。也就是说，如果用户更改了工作表，worksheet 字段的值必须被清除（并重新获取 /inputs），因为操作可用的输入集现在已经不同。

无效化与依赖关系流程​

Platform UI vs CLI comparison

某些操作的输入序列可能很复杂，这个流程演示了如何向用户呈现这些输入。

输入字段类型​

输入字段模式

value_type 键表示给定字段接受的用户数据类型。根据该模式，value_type 的选项包括：STRING、NUMBER、INTEGER、BOOLEAN、ARRAY 和 OBJECT。以下变体需要额外注意：

数组字段​

数组字段接受底层值类型的 JSON 数组。items 键会为数组定义，并包含一个键 type，其值为数组项的值类型。

这个输入字段：

"column_names": {
  "value_type": "ARRAY",
  "items": {
    "type": "STRING"
  }
}

会接受这个值：

"column_names": ["Word", "Definition"]

对象字段​

对象字段接受带有任意键和_字符串_值的 JSON 对象。

这个输入字段：

"dictionary": {
  "value_type": "OBJECT"
}

会接受这个值：

"dictionary": {
  "apple": "A fruit!",
  "salmon": "A fish!"
}

布尔字段​

虽然布尔字段逻辑上是 true 或 false，但它们的实际值取决于特定操作。因此，布尔值与 format 为 SELECT 配对，并且选项应从 /choices 获取。有关更多信息，请参阅选项。这个输入字段：

{
  "type": "input_field",
  "id": "replace_all_rows",
  "format": "SELECT",
  "value_type": "BOOLEAN"
  ...
}

需要向 /choices 发送请求；

// response from POST https://api.zapier.com/v2/actions/core:gq7MXdsdsaaqqDBj/inputs/replace_all_rows/choices
{
  "id": "False",
  "type": "choice",
  "label": "No",
  "value": "False"
},
{
  "id": "True",
  "type": "choice",
  "label": "Yes",
  "value": "True"
}

最终会接受这个值：

"False"

其中这是所选选项的 id。有关更多信息，请参阅选项。

输入格式​

format 键表示如何向用户呈现给定输入字段，详见该模式。其选项包括：DATETIME、MULTILINE、PASSWORD、CODE、READONLY、FILE、SELECT。有关这些字段如何由 Zapier 处理的更多信息，请参阅我们的帮助文档。

以下变体需要额外注意：

只读字段​

这些字段仅作为文本呈现，不需要输入。description 字段包含要呈现的文本。

"format": "READONLY"

文件字段​

这些字段应包含一个文件 URL，该 URL 会在 Zap 执行期间由 Zapier 平台获取。

"format": "FILE"

选择字段​

这些字段需要向 /choices 发送额外请求，以获取该输入可用的选项。有关更多信息，请参阅选项。

"format": "SELECT"

选项​

选项模式

当 format 键等于 SELECT 时，/choices 端点返回用户应从中选择的选项列表。

继续使用电子表格的例子，第一个输入字段是 (spreadsheet)，其类型为 string。其 format 为 SELECT，这意味着该字段有一组_选项_供用户选择（在 UI 中通常会渲染为下拉菜单）。

要获取这些选项，请使用 /actions/{action_id}/inputs/{input_id}/choices 端点：

请求

// POST /actions/core:853266/inputs/spreadsheet/choices
{
  "data": {
    "authentication": "762331",
    "inputs": {}
  }
}

因此，这个输入字段只有两个可用选项。在创建 Zap 时，请为所需的输入传递所选选项的 id。

字段集​

字段集模式

输入字段可以_分组_到字段集中（就像 HTML 中的一样）。这为 UI 中的字段渲染提供提示。

仅支持一层嵌套（字段集不能包含在另一个字段集中）。

信息字段​

信息字段模式

信息字段没有输入，但包含一些 Markdown 格式的文本，这些文本应在表单的相应位置渲染。这通常用于向用户提供有帮助的提示。

输出字段​

输出字段模式

一旦用户填充了所有输入字段，我们可以使用 /actions/{action_id}/outputs 端点来确定给定操作可用的输出字段：

请求

// POST /actions/core:853266/outputs
{
  "data": {
    "authentication": "762331",
    "inputs": {
      "worksheet": "ABC123",
      "spreadsheet": "EFGH456"
    }
  }
}

在实际中，可能会有更多输出字段可用。有关这些字段如何映射到 Zap 中后续步骤的输入字段的详细信息，请参阅构建 Zap。