核心参考

Zapier 平台核心参考

大多数函数都以 (z, bundle) 的形式被调用。本文档是对这些对象的参考，解释如何使用它们。

如果您使用 TypeScript，可以从 zapier-platform-core 导入 ZObject、Bundle 和 PerformFunction。

z 对象

我们为 z 对象提供了多个方法，该对象作为集成中所有函数调用的第一个参数提供。

z 对象作为第一个参数传递给您的函数，例如：perform: (z) => 。

z.request([url], options)

z.request([url], options) 是一个基于 Promise 的 HTTP 客户端，包含一些 Zapier 特定的功能。请参阅 Making HTTP Requests。z.request() 会对非 ASCII 字符以及这些保留字符进行 percent-encode：:$/?#[]@$&+,;=^@。您可以使用 skipEncodingChars 来修改此行为。

z.console

z.console.log(message) 是一个日志控制台，类似于 Node.js 的 console，但它会远程记录日志，并在测试中输出到 stdout。请参阅 Log Statements。

z.dehydrate(func, inputData)

z.dehydrate(func, inputData) 用于延迟评估函数，非常适合避免在轮询期间进行 API 调用或实现复用。请参阅 Dehydration。

z.dehydrateFile(func, inputData)

z.dehydrateFile 用于延迟下载文件，非常适合避免在轮询期间进行 API 调用或实现复用。请参阅 File Dehydration。

z.stashFile(bufferStringStream, [knownLength], [filename], [contentType])

z.stashFile(bufferStringStream, [knownLength], [filename], [contentType]) 是一个基于 Promise 的文件存储器，返回一个 URL 文件指针。请参阅 Stashing Files。

z.JSON

z.JSON 类似于内置的 JSON 对象，例如 z.JSON.parse('...')，但它会捕获错误并生成更友好的错误跟踪信息。

z.hash()

z.hash() 是一个加密工具，用于执行操作，如 z.hash('sha256', 'my password')。

z.errors

z.errors 是一组错误类，您可以在代码中抛出这些错误，例如 throw new z.errors.HaltedError('...')。

可用的错误包括：

Error（在 v9.3.0 中添加） - 停止当前操作，并允许（自动）重试。请参阅 General Errors。
HaltedError - 停止当前操作，但不会关闭 Zap。请参阅 Halting Execution。
ExpiredAuthError - 停止当前操作，并向用户发送电子邮件以手动重新连接。请参阅 Stale Authentication Credentials。
RefreshAuthError - （适用于 OAuth2 或 Session Auth）告诉 Zapier 刷新凭证并重试操作。请参阅 Stale Authentication Credentials。
ThrottledError（在 v11.2.0 中新增） - 告诉 Zapier 在指定的秒数延迟后重试当前操作。请参阅 Handling Throttled Requests。

有关错误处理的更多细节，请参阅这里。

z.cursor

z.cursor 对象公开了两个方法：

z.cursor.get(): Promise
z.cursor.set(string): Promise

您设置的任何数据都将在大约一小时内（或直到被覆盖）对该 Zap 可用。有关更多信息，请参阅：paging。

z.generateCallbackUrl()

z.generateCallbackUrl() 会返回一个回调 URL，您的应用可以稍后向其发送 POST 请求，以处理长时间运行的任务（如转录或编码作业）。在此期间，Zap 和任务会等待您的响应，用户会看到任务标记为等待中。

例如，在您的 perform 中，您可能这样做：

const perform = async (z, bundle) => {
  // 例如这个 URL：
  // https://zapier.com/hooks/callback/123/abcdef01-2345-6789-abcd-ef0123456789/abcdef0123456789abcdef0123456789abcdef01/
  // 请考虑检查 bundle.meta.isLoadingSample 以确定这是测试运行还是真实运行！
  const callbackUrl = z.generateCallbackUrl();
  await z.request({
    url: "https://example.com/api/slow-job",
    method: "POST",
    body: {
      // ... 您的集成所需的内容
      url: callbackUrl,
    },
  });
  return { hello: "world" };  // 稍后可在 bundle.outputData 中使用
};

在您自己的 /api/slow-job 视图（或更可能是异步作业）中，当长时间运行的作业完成时，您应该向 Zapier 发送此请求，以填充 bundle.cleanedRequest：

POST /hooks/callback/123/abcdef01-2345-6789-abcd-ef0123456789/abcdef0123456789abcdef0123456789abcdef01/ HTTP/1.1
Host: zapier.com
Content-Type: application/json
{"foo": "bar"}

我们建议使用 bundle.meta.isLoadingSample 来确定执行是否发生在前端（例如：在 Zap 设置期间），因为使用 z.generateCallbackUrl() 可能不合适。在这种情况下，不要生成回调，或者如果必须，返回存根数据。

默认情况下，POST 到回调 URL 的有效负载会增强从初始 perform 返回的数据，以组成最终值。

如果您需要自定义最终值，可以定义一个 performResume 方法，该方法接收三个 bundle 属性：

bundle.outputData 是 {"hello": "world"}，这是从初始 perform 返回的数据。
bundle.cleanedRequest 是 {"foo": "bar"}，这是来自回调 URL 的有效负载。
bundle.rawRequest 是对应于 bundle.cleanedRequest 的完整请求对象。

const performResume = async (z, bundle) => {
  // 这会生成最终值为: {"hello": "world", "foo": "bar"}
  // 这是当未定义自定义 `performResume` 时默认行为。
  return {
    ...bundle.outputData,
    ...bundle.cleanedRequest,
  };
};

应用有最多 30 天的时间来 POST 到回调 URL。如果在此期间用户删除或修改了 Zap 或任务，我们将不会恢复任务。

performResume 只会在 Zap 实时运行时执行，无法在 Zap 编辑器中配置 Zap 时测试它。您可以使用 bundle.meta.isLoadingSample 来加载固定样本，以允许用户测试包含 performResume 的步骤。

一些注意事项：

performResume 当前不受 Platform UI 支持。它只能用于使用 CLI 构建的集成。
在搜索或写入步骤中，如果搜索部分失败并继续到写入部分，则为写入部分生成的回调 URL 可能无法识别或等待。这可能导致 performResume 操作未执行，从而影响任务流程。
在迁移使用 performResume 的操作时，必须确保新 API 的 performResume 代码向后兼容。这样，如果迁移发生在等待回调的运行中，它仍能成功。

bundle 对象

此对象包含用户的身份验证详细信息以及 API 请求的数据。

bundle 对象作为第二个参数传递给您的函数，例如：perform: (z, bundle) => 。

bundle.authData

bundle.authData 是用户提供的身份验证数据，如 api_key 或 access_token。请参阅身份验证。

bundle.inputData

bundle.inputData 是用户为触发器/搜索/创建的特定运行提供的数据，由 inputFields 定义。例如：

{createdBy: 'his name is Bobby Flay', style: 'he cooks mediterranean', scheduledAt: "2021-09-09T09:00:00-07:00"}

bundle.inputDataRaw

您通常应该使用 bundle.inputData 而不是这个。 bundle.inputDataRaw 类似于 bundle.inputData，但是在处理（如解释友好日期时间和渲染 { {curlies} }）之前：

{createdBy: 'his name is { {123__chef_name} }', style: 'he cooks { {456__style} }', scheduledAt: "today"}

“curlies” 表示从先前步骤映射的数据。形式为 {{NODE_ID__key_name}}。

您通常应该使用 bundle.inputData 而不是这个。

bundle.meta

bundle.meta 包含额外信息，用于根据用户操作执行高级行为。它具有以下选项：

键	默认值	描述
isLoadingSample	false	如果为 true，则此运行是通过 Zap 编辑器手动启动的
isFillingDynamicDropdown	false	如果为 true，则此轮询用于填充动态下拉菜单。您只需返回指定的字段（如 id 和 name），不过返回所有内容也没问题
isPopulatingDedupe	false	如果为 true，则此轮询的结果将用于初始化去重列表，而不是触发 Zap。您应该获取尽可能多的项目。请参阅：deduplication
limit	-1	您应该获取的项目数。-1 表示没有限制。请尽可能地将此集成到您的调用中
page	0	用于分页，以唯一标识应返回的结果页
timezone	null	用户为其帐户或特定自动化配置的时区。以 TZ 标识符形式接收，例如 “America/New_York”
isTestingAuth	false	（遗留属性）如果为 true，则轮询是由用户测试其帐户触发的（通过点击 “test” 或在设置期间）。我们使用这些数据填充身份验证标签，但它主要用于验证我们进行了成功的身份验证请求
withSearch	undefined	当在搜索或创建步骤中调用创建时，withSearch 将是搜索的键
inputFields		如果一个或多个输入字段通过各自的 meta 属性定义了此数据，则包含额外的输入字段上下文。此对象的键是各自输入字段的 key 值，每个 key 的值是对应输入字段的 meta 对象值。请参阅 FieldSchema 参考，了解如何定义输入字段 meta

在 v8.0.0 之前，bundle.meta 中的信息不同。请参阅旧文档以获取以前的值，以及 wiki 以获取旧值到新值的映射。

这是一个轮询触发器示例，同时用于为动态下拉菜单提供数据：

const perform = async (z, bundle) => {
  const params = { per_page: 100 };
  // 轮询最近的 100 个团队
  if (bundle.meta.isFillingDynamicDropdown) {
    // 动态下拉菜单支持分页
    params.per_page = 30;
    params.offset = params.per_page * bundle.meta.page;
  }
  const response = await z.request({
    url: `${API_BASE_URL}/teams`,
    params,
  });
  return response.json;
};
// ...

bundle.rawRequest

bundle.rawRequest 只在 webhook 的 perform、OAuth 身份验证方法的 getAccessToken 以及回调操作的 performResume 中可用。

bundle.rawRequest 包含触发 perform 方法的 HTTP 请求的原始信息，或代表触发 getAccessToken 调用的用户浏览器请求：

{method: 'POST', querystring: 'foo=bar&baz=qux', headers: {'Content-Type': 'application/json'}, content: '{"hello": "world"}'}

在 bundle.rawRequest 中，除 Content-Length 和 Content-Type 之外的标头会以 Http- 为前缀，所有标头都将采用 Camel-Case 命名。例如，标头 X-Time-GMT 会变为 Http-X-Time-Gmt。

bundle.cleanedRequest

bundle.cleanedRequest 只在 webhook 的 perform、OAuth 身份验证方法的 getAccessToken 以及回调操作的 performResume 中可用。

bundle.cleanedRequest 会返回请求的格式化和解析版本。以下部分中的某些或全部可用：

{method: 'POST', querystring: {foo: 'bar', baz: 'qux'}, headers: {'Content-Type': 'application/json'}, content: {hello: 'world'}}

bundle.outputData

bundle.outputData 只在回调操作的 performResume 中可用。

bundle.outputData 会返回您在 perform 中原始返回的数据，允许您将其与 bundle.rawRequest 或 bundle.cleanedRequest 混合。

bundle.targetUrl

bundle.targetUrl 只在 webhook 的 performSubscribe 和 performUnsubscribe 方法中可用。

这是您应该向其发送钩子数据的 URL。它看起来像 https://hooks.zapier.com/1234/abcd。我们提供它，以便您可以向您的服务器发送 POST 请求。您的服务器应该存储此 URL，并在有新数据报告时将其用作目的地。

例如：

const subscribeHook = async (z, bundle) => {
  const options = {
    url: "https://57b20fb546b57d1100a3c405.mockapi.io/api/hooks",
    method: "POST",
    body: {
      url: bundle.targetUrl,  // bundle.targetUrl 包含钩子 URL，此应用应该调用
    },
  };
  const response = await z.request(options);
  return response.data;  // 或 response.json，如果您使用的是 core v9 或更早版本
};
module.exports = {
  // ...
  performSubscribe: subscribeHook,
  // ...
};

请参阅 REST hook example 以获取更多信息。

bundle.subscribeData

bundle.subscribeData 在 webhook 的 perform 和 performUnsubscribe 方法中可用。

这是一个对象，包含您从 performSubscribe 函数返回的数据。它应该包含您需要向服务器发送 DELETE 请求以停止向 Zapier 发送 webhook 的信息。

bufferedBundle 对象

在 v15.15.0 中添加。

此对象包含用户的身份验证详细信息（bufferedBundle.authData）以及 API 请求的缓冲数据（bufferedBundle.buffer）。它仅用于 create 操作的 performBuffer 函数。

bufferedBundle 对象作为第二个参数传递给 performBuffer 函数，例如：performBuffer: async (z, bufferedBundle) => 。

bufferedBundle.authData

这是用户提供的身份验证数据，如 api_key 或 access_token。请参阅身份验证。

bufferedBundle.groupedBy

这是用户为选定的 inputFields 提供的数据，用于按组处理 create 操作的多个运行。

bufferedBundle.buffer

这是一个数组，包含用户提供的数据和一些元数据，用于允许 create 操作的多个运行在单个 API 请求中处理。

bufferedBundle.buffer[].inputData

这是缓冲区中 create 操作的特定运行的用户提供的数据，由 inputFields 定义。

bufferedBundle.buffer[].meta

它包含一个幂等性 ID，用于在缓冲数据中标识每个运行的数据。

z 对象​

z.request([url], options)​

z.console​

z.dehydrate(func, inputData)​

z.dehydrateFile(func, inputData)​

z.stashFile(bufferStringStream, [knownLength], [filename], [contentType])​

z.JSON​

z.hash()​

z.errors​

z.cursor​

z.generateCallbackUrl()​

bundle 对象​

bundle.authData​

bundle.inputData​

bundle.inputDataRaw​

bundle.meta​

bundle.rawRequest​

bundle.cleanedRequest​

bundle.outputData​

bundle.targetUrl​

bundle.subscribeData​

bufferedBundle 对象​

bufferedBundle.authData​

bufferedBundle.groupedBy​

bufferedBundle.buffer​

bufferedBundle.buffer[].inputData​

bufferedBundle.buffer[].meta​