开发机器人 action流程详情

原文：飞书文档-如何快速上架机器人aciton

官方已经支持了 3 个 action：

  1. WebHook 发送网络请求

  2. 钉钉消息通知

  3. 企业微信消息通知 不管是后续开发新的 action，还是用户自定义自己的 aciton，整个流程是通用的。本文介绍如何上架一个自定义的 Action(service)

基础流程


基础概念


  • action 是机器人执行过程中的节点，最简单的理解就是他是一个函数。最简单的实现也是云函数。

    • 一个函数只专注于干一件事情。

    • action 可以组合起来，编排流程，完成一系列的工作。

  • service 服务，action 是归属于一个服务的。想要提供 action 必须先注册一个服务。

    • 例如：服务「 维格表」提供了「创建记录」、「查询记录」的 action 实现一个 action 的过程实际上就是在实现一个函数，和 ts 定义函数一样。需要定义函数的传入参数和函数的返回类型。

  • 入参类型告诉用户你这个 action 怎么使用，需要传入哪些信息才能正常工作。

  • 返回类型可以告诉下一个 action，当前 action 能提供什么，next action 可以用 current action 的 output 作为 input

实现

需求场景

这里有一个完整的场景流程。

我有张书单的表，我需要通过条形码录入其书籍信息。包涵其标题、作者、封面。

你可能想到了之前的图书扫码录入，它需要用户获取捷径、使用指定模版、提供 API Token、提供表格地址。 当我们将这个功能做成 aciton 时，用户可以自助地建立一条 robot 来完成这项工作。用户路径变短、这个服务也更加通用。

我们把他概括为一条 automation 的需求，当表格内的某个字段（条形码）更新时，自动获取图书信息，填充到指定字段。

  • 用户在任意表格新建一个 robot

    • trigger 选取「当记录更新时」

      • 仅监听「条形码」字段的变化

    • 用户新建「获取图书信息」的 action

      • 选取「条形码」字段作为输入。

    • 用户新建「更新维格表记录」的 action

      • 选取书单表

      • 将「获取图书信息」action 返回的 标题、封面、作者绑定「书单」表中的字段。

获取图书信息，涉及到 API 调用。云平台有很多付费的 API 接口提供 isbn 查询的服务，你可以把API 封装成一个 action 上架到 automation 中，这样同空间的用户可以直接使用这项服务，当你把服务公开，全部空间站的人都可以使用，造福整个维格星球。

你可以为有类似需求的用户提供服务，设置有偿使用，让您的服务更健康的运行下去。

接口设计

通过上面的需求，我们已经知道 「获取图书信息」这个 action 的 input 就是条形码，输出值就是标题、封面、作者。

选取任意云函数平台，新建云函数，实现此功能。

interface IBookInfo {
        title: string;
        author: string;
        cover: string;
}
function getBookInfo(barCode: string): IBookInfo {
  // 
        return 
}

云函数实现

下面是 cloudflare worker 实现 「webhook 发送请求」 这个 action 的代码，我们可以继续扩展这个云函数，丰富我们的service 的能力。接下来在这个代码上继续添加 pathname 为 getBookInfo 时的处理逻辑。

addEventListener("fetch", (event) => {
  event.respondWith(
    handleRequest(event.request).catch(
      (err) => new Response(err.stack, { status: 500 })
    )
  );
});

async function handleRequest(request) {
  const { pathname } = new URL(request.url);
  if (pathname.startsWith("/sendRequest")) {
    return sendReq(request)
  }
        if (pathname.startsWith("/getBookInfo")) {
                // 获取图书信息
                                        
        }
  // 其他 pathname 的处理逻辑
}

async function sendReq(request){
  const {method, headers,url,body} = await request.json();
  return fetch(url,{
      body,
      method,
      headers: {
        'content-type': 'application/json'
      },
  })
}

云函数会有一个唯一访问的地址，上面这个 worker 分配的地址是 https://actions.gine.workers.dev

记下这个 URL。

对于开发者来说，云函数是最简单的做法。私有化部署，或者我们自己控制，可以直接在 room 里面实现 action 。具体可以参考百度如流添加自己 action 的做法，详情咨询冯鹏龙

上架

我们的 action 是依附于 service 的。云函数也可以根据传入的 pathname 做不同的处理逻辑。这就相当于一个云函数有一个唯一 URL，即 service 的 baseURL 以在 test 环境注册 service 为例，访问。

  1. 先调用接口登录 https://test.vika.ltd/api/v1/doc.html#/default/授权相关接口/signInUsingPOST

  2. 再调用接口注册 automation service https://test.vika.ltd/api/v1/doc.html#/%20/Automation%20API/edit_4


    创建服务需要提供

    1. name

    2. logo

    3. baseUrl

      这个 service 的调用基础地址，就是上面那个 worker 的地址。

    注册完之后会返回新建服务的 serviceId。记下这个 id。下面新建 action 会用到

  1. 调用接口注册 automation actionType https://test.vika.ltd/api/v1/doc.html#/%20/Automation%20Action%20Type%20API/create_10


    注册 action 原型需要提供：

    1. name

    2. inputJSONSchema

      1. action 的输入类型，也就上面我们定义函数的 input interface，但是要以 JSONSchema 的形式提供。

    3. outputJSONSchema

      1. action 的输出类型，也就上面我们定义函数的 output interface，但是要以 JSONSchema 的形式提供。

    4. serviceId

      1. 上面注册的服务 id，我们的 acitonType 要归属与某个 service 下

    5. endpoint

      1. 以 https://actions.gine.workers.dev/webhook 为例其中 webhook 就是 action 的 endpoint。

      2. baseUrl 是 service 定义的，endpoint 是 action 定义的。二者结合可以得到 action 的唯一调用地址。当 action 被触发时，就会调用这个云函数执行并且返回结果。

如何做到

https://www.figma.com/file/4YrYKFdMdggFYK8Cdd7NpO?embed_host=share&kind=&node-id=0%3A1&viewer=1

扩展思路

基于上面的思路，可以提供很多 API 的查询服务，其中一条思路就是花钱买 API，然后用云函数封装成 aciton 上架。实际上有很多数据集都是公开的，你可以免费下载他们，然后存储在可以与云函数互通的服务中，通过函数调用获取。

网上也有很多公开的 API，你可以利用他们。比如随机返回猫咪图片的 API。可以做这样一条 workflow，当用户新建记录时候，往附件列写入随机的猫咪图片。听起来有点意思但是没啥用，这不重要，继续扩展。

比如用户用表格管理自己的文章，新建记录，输入标题。当标题/标签/其他要素改变后，用这些关键词去 「unsplash」 获取一张免费的封面图上传到附件中（这个更适合用小组件实现）