@zapier / zapier-sdk

目录表

• 文档
• 稳定
• 快速入门
• 安装
• 预排
• 工厂
• 可用功能
• 账户
  • getProfile
• 行动
  • createActionRun
  • getAction
  • getActionInputFieldsSchema
  • getActionRun
  • listActionInputFieldChoices
  • listActionInputFields
  • listActions
  • runAction
• 应用程序
  • apps.{appKey}
  • apps.{appKey}.{actionType}.{actionKey}
  • getApp
  • listApps
• 客户端凭证
  • createClientCredentials
  • deleteClientCredentials
  • listClientCredentials
• 连接
  • createConnection
  • findFirstConnection
  • findUniqueConnection
  • getConnection
  • getConnectionStartUrl
  • listConnections
  • waitForNewConnection
• HTTP请求
  • fetch
• 人为输入（实验）
  • createForm
• Next Gen Zaps （Beta版）
  • cancelDurableRun
  • createWorkflow
  • createWorkflowDraft
  • deleteWorkflow
  • disableWorkflow
  • discardWorkflowDraft
  • enableWorkflow
  • getDurableRun
  • getTriggerRun
  • getWorkflow
  • getWorkflowDraft
  • getWorkflowRun
  • getWorkflowVersion
  • importWorkflow
  • listDurableRuns
  • listWorkflowDrafts
  • listWorkflowRuns
  • listWorkflowVersions
  • listWorkflows
  • publishWorkflowDraft
  • publishWorkflowVersion
  • runDurable
  • runWorkflow
  • runWorkflowDraft
  • triggerWorkflow
  • updateWorkflow
  • updateWorkflowDraft
  • validateWorkflow
• Next Gen Zaps（实验）
  • disableAgenticManagement
  • enableAgenticManagement
  • getAgenticManagementConfig
  • getAgenticManagementIntent
  • updateAgenticManagementConfig
  • updateAgenticManagementIntent
• 表
  • createTable
  • createTableFields
  • createTableRecords
  • deleteTable
  • deleteTableFields
  • deleteTableRecords
  • getTable
  • getTableRecord
  • listTableFields
  • listTableRecords
  • listTables
  • updateTableRecords
• 触发器
  • ackTriggerInboxMessages
  • createTriggerInbox
  • deleteTriggerInbox
  • drainTriggerInbox
  • ensureTriggerInbox
  • getTriggerInbox
  • getTriggerInputFieldsSchema
  • leaseTriggerInboxMessages
  • listTriggerInboxMessages
  • listTriggerInboxes
  • listTriggerInputFieldChoices
  • listTriggerInputFields
  • listTriggers
  • pauseTriggerInbox
  • releaseTriggerInboxMessages
  • resumeTriggerInbox
  • updateTriggerInbox
  • watchTriggerInbox
• 虚拟文件系统（实验）
  • appendVfsFile
  • copyVfsFile
  • createVfsDirectory
  • deleteVfsPath
  • listVfsDirectory
  • moveVfsPath
  • readVfsFile
  • statVfsPath
  • writeVfsFile

文档

官方文件可于以下网址查阅：

https://docs.zapier.com/sdk

代理有时会被阻止查看npm上的文档，因此您可能需要为它们提供到官方文档的链接，或者将这里的文档复制到提示符中。

稳定

每个SDK方法都属于三个稳定性层之一，由导入路径选择。层是这个SDK做出的承诺：导入路径告诉您需要知道的关于什么可能会中断的一切。

SDK目前处于公测阶段。每个包的版本都是0。小版本可以包含重大更改。等级描述的是你在着陆前得到多少警告，而不是是否可以着陆。

• 稳定的 - - - - - - import { createZapierSdk } from "@zapier/zapier-sdk"
• β - - - - - - import { createZapierSdk } from "@zapier/zapier-sdk/beta"
• 实验 - - - - - - import { createZapierSdk } from "@zapier/zapier-sdk/experimental"

每个子路径都是它上面的子路径的超集 /beta 包括所有稳定的东西， /experimental 包括所有测试版——所以选择更宽的层永远不会带走方法。非稳定方法宣布自己：对每个方法的第一次调用都会记录一个每进程一次的警告，并且下面引用的每个非稳定部分都以其层的契约开头。

快速入门

对于新项目。

下面将从头开始创建一个新项目，设置SDK和SDK CLI，并为您提供一个工作启动器示例：

# Create a new Zapier SDK project (scaffolds files, installs deps, and logs you in).
npx @zapier/zapier-sdk-cli init my-zapier-app

# Or skip the interactive prompts and accept all defaults.
npx @zapier/zapier-sdk-cli init my-zapier-app --non-interactive

安装

对于现有的项目。

运行向导式设置来添加未声明的Zapier SDK依赖项，验证和检查连接的应用：

npx @zapier/zapier-sdk-cli setup

如果你已经有了一个项目，想要开始通过Zapier使用SDK集成应用程序：

npm install @zapier/zapier-sdk
npm install -D @zapier/zapier-sdk-cli @types/node typescript

预排

假设您已经将CLI包安装到您的项目中（请参阅上面的说明），您（或代理）可以立即开始使用它。这对于内省你想在代码中使用的动作、连接等非常有用，但你也可以直接使用它来使用集成。

# See all available commands
npx zapier-sdk --help

# Login to Zapier.
npx zapier-sdk login

# Search from thousands of supported apps.
npx zapier-sdk list-apps --search "gmail"
# The output will show you the valid keys next to the app title like this:
# 1. Gmail (GoogleMailV2CLIAPI, gmail)

# Run any action for the app, using one of the app keys.
npx zapier-sdk run-action gmail
# This will ask you for the type of action you want to run.
# `search` or `write` are typically great for testing.
# Note that you usually need a connection to the app to run
# the action. If you don't already have one, you can create a new one at:
# https://zapier.com/app/assets/connections

# List connections for an app.
npx zapier-sdk list-connections gmail
# Or only list the ones you own.
npx zapier-sdk list-connections gmail --owner me
# Or just grab the first one.
npx zapier-sdk find-first-connection gmail --owner me

# Make any API request to an app using your connection.
npx zapier-sdk curl "https://gmail.googleapis.com/gmail/v1/users/me/labels" --connection 123

下面是可选的，但如果你想从代码中调用我们的动作，为这些动作安装TypeScript类型会很有帮助。你也可以直接用 fetch 发出任意的API请求。在这种情况下，您实际上并不需要这个，相反，您可能需要查找第三方API文档的类型或良好的代理。

# Search for apps that you want to use.
npx zapier-sdk list-apps --search "slack"
npx zapier-sdk list-apps --search "google sheets"
# The output will show you the valid keys next to the app title like this:
# 1. Slack (SlackCLIAPI, slack)
# 1. Google Sheets (GoogleSheetsV2CLIAPI, google-sheets, google_sheets)

# Generate TypeScript types for actions and fields of any apps you want to use.
npx zapier-sdk add slack google-sheets

# By default, types will be generated inside your `src` or `lib` folder if you
# have one or otherwise the root folder. Make sure your `tsconfig.json` file
# includes the generated type files.

# Alternatively, you can specify a custom output directory.
npx zapier-sdk add slack google-sheets --types-output ./types

现在让我们编写一些代码！

import { createZapierSdk } from "@zapier/zapier-sdk";

// ######## Initialize Zapier SDK ########
// Option 1: Running `zapier-sdk login` authenticates through your browser and
// stores a token on your local machine. As long as you have the CLI package
// installed as a development dependency, the SDK will automatically use it.
const zapier = createZapierSdk();

// Option 2: Provide a client ID and client secret.
// You can get these by running `zapier-sdk create-client-credentials`.
// This allows you to run the SDK in a server/serverless environment.
// const zapier = createZapierSdk({
//   credentials: {
//     clientId: "your_client_id_here", // or use ZAPIER_CREDENTIALS_CLIENT_ID env var
//     clientSecret: "your_client_secret_here", // or use ZAPIER_CREDENTIALS_CLIENT_SECRET env var
//   },
// });

// Option 3: Provide a valid Zapier token.
// This is for partner OAuth or internal Zapier use.
// const zapier = createZapierSdk({
//   credentials: "your_zapier_token_here", // or use ZAPIER_CREDENTIALS env var
// });

// ######## Access Apps ########
// List methods return a promise for a page with {data, nextCursor}.
const { data: firstPageApps, nextCursor } = await zapier.listApps();
// Use the cursor to get the next page:
const { data: secondPageApps } = await zapier.listApps({ cursor: nextCursor });

console.log({
  firstPageApps,
  secondPageApps,
});

// Use `.pages()` to iterate over all pages.
// Be careful with lots of pages, note the `search` to filter.
for await (const page of zapier.listApps({ search: "slack" }).pages()) {
  const { data: apps } = page;
  console.log({
    apps,
  });
}

// Use `.items()` to iterate over all items of all pages:
// Again, be careful with lots of items. Note the `maxItems` to limit the total items.
for await (const app of zapier.listApps({ maxItems: 100 }).items()) {
  console.log({
    app,
  });
}

// You can collect all results, but this could take a while for long lists!
const allApps = await Array.fromAsync(
  zapier.listApps({ maxItems: 100 }).items(),
);

console.log({
  allApps,
});

// The item methods return a promise for a single item, wrapped with {data}.
// This is just to give us room to add metadata in the future.
const { data: app } = await zapier.getApp({ app: "slack" });

console.log({
  app,
});

// ######## Connection Usage ########
const { data: myConnections } = await zapier.listConnections({
  app: "slack",
  owner: "me",
});

console.log({
  myConnections,
});

// ######## Find Actions ########
// Option 1: List actions
// Remember, this is just the first page which may not include them all!
// See `.items()` usage above, which can be used to make sure you get all actions.
const { data: actions } = await zapier.listActions({ app: "slack" });

console.log({
  actions,
});

const singleAction = await zapier.getAction({
  app: "slack",
  actionType: actions[0].action_type,
  action: actions[0].key,
});

console.log({
  singleAction,
});

// Option 2: Access actions via the `apps` proxy
// If you've generated TS types for an app using `zapier-sdk add`, you can
// access the app's actions like this:

// await zapier.apps.slack.read.channles({});
// await zapier.apps.slack.write.send_message({})

// ######## Run Actions ########
// Option 1:
const { data: channels } = await zapier.runAction({
  app: "slack",
  actionType: "read",
  action: "channels",
  connection: myConnections[0].id,
});

console.log({
  channels,
});

const { data: profile } = await zapier.getProfile();

// Option 2:
// Create an app binding to your connection.
const mySlack = zapier.apps.slack({
  connection: myConnections[0].id,
});

// Use your app binding to run the action.
const { data: users } = await mySlack.search.user_by_email({
  inputs: {
    email: profile.email,
  },
});

console.log({
  users,
});

// You can also skip the app binding and pass the connection into the action.
const { data: sameUsers } = await zapier.apps.slack.search.user_by_email({
  inputs: {
    email: profile.email,
  },
  connection: myConnections[0].id,
});

console.log({
  sameUsers,
});

// If the slug for an app has dashes, you can also use a snake_cased app key.
// For example, either of the following are valid:
// zapier.apps["google-sheets"]
// zapier.apps.google_sheets

// We have tens of thousands of actions across thousands of apps, but you're
// still not limited to those. You can make any arbitrary API request to an app
// using the same connections with `.fetch`! This returns a response just
// like a normal `fetch` call in JavaScript.
const emojiResponse = await zapier.fetch("https://slack.com/api/emoji.list", {
  connection: myConnections[0].id,
});

const emojiData = await emojiResponse.json();

console.log(emojiData.emoji);

工厂

这个 createZapierSdk(...) factory函数是SDK的主要入口点。它提供了管理连接、列出应用程序、运行操作等方法。

命名连接

命名连接允许您将工作流代码与特定连接id分离。不是硬编码ID，而是通过名称引用连接，SDK从映射中解析它。

当执行引擎或部署系统管理工作流应该使用哪些连接时，这很有用。

提供映射

连接配置在 .zapierrc 旁边的应用程序版本pin，或内联通过 manifest 选择:

const zapier = createZapierSdk({
  manifest: {
    apps: { slack: { implementationName: "SlackCLIAPI", version: "1.21.1" } },
    connections: {
      slack_work: { connectionId: "01234567-89ab-cdef-0123-456789abcdef" },
      google_sheets: { connectionId: 67890 },
    },
  },
});

每个连接项将一个名称映射到 connectionId。Zapier连接API返回uuid格式的id id 条目的字段 listConnections）; 来自旧连接的正整数也被接受。应用程序版本解析通过 apps 的部分 .zapierrc.

使用命名连接

的引用连接 connection 参数。传递要从连接映射中解析的连接名称，或要直接使用的连接ID。

// Per-call with alias
await zapier.apps.slack.read.channels({ connection: "slack_work" });

// Factory binding
const slack = zapier.apps.slack({ connection: "slack_work" });
await slack.read.channels({});

// Lower-level runAction
await zapier.runAction({
  app: "slack",
  actionType: "read",
  action: "channels",
  connection: "slack_work",
});

// Authenticated fetch
await zapier.fetch("https://slack.com/api/auth.test", {
  connection: "slack_work",
});

// Direct connection ID also works (UUID or legacy positive integer)
await zapier.apps.slack.read.channels({
  connection: "01234567-89ab-cdef-0123-456789abcdef",
});

可用功能

账户

您的Zapier用户帐户，即SDK登录时使用的帐户。用这个来确认是谁。

getProfile

获取当前用户的配置文件信息

参数:

返回: Promise<ProfileItem>

例子:

const { data: profile } = await zapier.getProfile();

行动

动作是应用程序可以做的事情，比如发送电子邮件或创建联系人。使用这些工具来查找应用程序的操作，查看它们需要什么输入，并直接在Zap之外运行它们。

createActionRun

启动操作运行并返回其ID，而无需等待结果。操作的运行是异步的：这将立即返回一个运行ID，并且 getActionRun 获取结果。当您想要开始工作并稍后收集它时，请使用这一对（多次运行，将ID交给另一个进程，在重新启动时幸存下来）。 runAction 是启动运行并等待其结果的单调用形式。

参数:

返回: Promise<StartedActionRunItem>

例子:

const { data: startedActionRun } = await zapier.createActionRun({
  app: "example-app",
  actionType: "read",
  action: "example-action",
});

getAction

获取有关特定操作的详细信息

参数:

返回: Promise<ActionItem>

例子:

const { data: action } = await zapier.getAction({
  app: "example-app",
  actionType: "read",
  action: "example-action",
});

getActionInputFieldsSchema

获取操作输入字段的JSON Schema表示形式。返回一个JSON Schema对象，该对象描述操作输入参数的结构、类型和验证规则。

参数:

返回: Promise<InputSchemaItem>

例子:

const { data: inputSchema } = await zapier.getActionInputFieldsSchema({
  app: "example-app",
  actionType: "read",
  action: "example-action",
});

getActionRun

开始运行的操作的当前状态 createActionRun。这是一个立即返回的时间点读取：Zapier尚未完成执行的运行返回状态 waiting，因此再次调用以检查结果。 runAction 开始运行并在一次调用中等待其结果。结果将在创建运行后存储7天。

参数:

返回: Promise<ActionRunItem>

例子:

const { data: actionRun } = await zapier.getActionRun({
  run: "example-run",
});

listActionInputFieldChoices

获取动态下拉输入字段的可用选项

参数:

返回: Promise<PaginatedResult<InputFieldChoiceItem>>

例子:

// Get first page and a cursor for the second page
const { data: inputFieldChoices, nextCursor } =
  await zapier.listActionInputFieldChoices({
    app: "example-app",
    actionType: "read",
    action: "example-action",
    inputField: "example-input-field",
  });

// Or iterate over all pages
for await (const page of zapier
  .listActionInputFieldChoices({
    app: "example-app",
    actionType: "read",
    action: "example-action",
    inputField: "example-input-field",
  })
  .pages()) {
  // Do something with each page
}

// Or iterate over individual items across all pages
for await (const inputFieldChoice of zapier
  .listActionInputFieldChoices({
    app: "example-app",
    actionType: "read",
    action: "example-action",
    inputField: "example-input-field",
  })
  .items()) {
  // Do something with each inputFieldChoice
}

listActionInputFields

获取特定操作所需的输入字段

参数:

返回: Promise<PaginatedResult<RootFieldItem>>

|名字| Ty