创建动作

动作定义

现在让我们创建第一个动作——获取随机冰淇淋口味。

npm run cli actions create

系统会询问三个问题来定义你的新动作：

  1. Piece 文件夹名称：与动作所在文件夹关联的名称。有助于在 Piece 内组织和分类动作。
  2. 动作显示名称：用户在界面中看到的名称，清晰传达动作的用途。
  3. 动作描述：在 UI 中显示的简短说明信息，指导用户了解动作的功能和目的。

接下来，让我们创建动作文件：

示例：

npm run cli actions create

? 请输入 piece 文件夹名称：gelato
? 请输入动作显示名称：get icecream flavor
? 请输入动作描述：获取随机冰淇淋口味。

这将在 packages/pieces/community/gelato/src/lib/actions 目录下创建一个名为 get-icecream-flavor.ts 的新 TypeScript 文件。

在该文件中粘贴以下代码：

import {
  createAction,
  Property,
  PieceAuth,
} from '@activepieces/pieces-framework';
import { httpClient, HttpMethod } from '@activepieces/pieces-common';
import { gelatoAuth } from '../..';

export const getIcecreamFlavor = createAction({
  name: 'get_icecream_flavor', // 必须在整个 Piece 中唯一，此值不应更改。
  auth: gelatoAuth,
  displayName: '获取冰淇淋口味',
  description: '获取随机冰淇淋口味',
  props: {},
  async run(context) {
    const res = await httpClient.sendRequest<string[]>({
      method: HttpMethod.GET,
      url: 'https://cloud.activepieces.com/api/v1/webhooks/RGjv57ex3RAHOgs0YK6Ja/sync',
      headers: {
        Authorization: context.auth, // 在请求头中传递 API 密钥
      },
    });
    return res.body;
  },
});

createAction 函数接受一个包含多个属性的对象，包括动作的 name、displayName、description、props 和 run 函数。

name 属性是动作的唯一标识符。displayName 和 description 属性用于提供人类可读的名称和描述。

props 属性是一个对象，定义了动作需要用户提供的属性。本例中，动作不需要任何属性。

run 函数是在执行动作时被调用的函数。它接受一个参数 context，其中包含动作属性的值。

run 函数使用 httpClient.sendRequest 方法发起 GET 请求，获取随机冰淇淋口味。它在请求头中加入了 API 密钥认证。最后，它返回响应体。

你可以通过声明 [输出 Schema](/docs/activepieces/build-pieces/piece-reference/output-schema) 来描述动作输出在构建器中的呈现方式——包括为不透明 ID 或数组形式返回的输出添加可读标签。

暴露定义

要使动作能被 Activepieces 识别，请将其添加到 Piece 定义的 actions 数组中。

import { createPiece } from '@activepieces/pieces-framework';
// 不要忘记添加以下导入。
import { getIcecreamFlavor } from './lib/actions/get-icecream-flavor';

export const gelato = createPiece({
  displayName: 'Gelato',
  logoUrl: 'https://cdn.activepieces.com/pieces/gelato.png',
  authors: [],
  auth: gelatoAuth,
  // 在此处添加动作。
  actions: [getIcecreamFlavor], // <--------
  triggers: [],
});

测试

默认情况下，开发环境只构建特定的组件。打开 .env.dev 文件，在 AP_DEV_PIECES 中添加 “gelato”。

更多详情请查看 Piece 开发 部分。

编辑环境变量后，重新启动后端。Piece 将被重新构建。之后，你需要刷新前端才能看到更改。

如果构建失败，尝试运行 `npx turbo run build --filter=@activepieces/piece-gelato` 进行调试。 它将显示代码中的任何错误。

要测试该动作，请使用 Activepieces 中的工作流构建器。其运行效果应如截图所示。

Gelato 动作