学习基础知识

使用集成构建器构建公共或私有应用程序。私有应用可以在任何时候更新为公共应用。

概述

成功加入Envoy的开发人员计划后，您将被授予访问Integration Builder的权限。它将出现在integration页面的“构建自己的”部分。在Envoy仪表板中可用之后，安装它并单击连接帐户打开构建器。

建造者被分成四个部分:

• 细节
• 事件
• 设置步骤
• API凭证

细节

这包含了你的应用程序的基本细节。如果你将你的应用程序公开列出，这些信息将出现在集成目录的应用程序清单中。

提示

您将希望在保存后收到API凭据之前，以未选中“live”复选框的方式完成构建器。一旦你把API凭证放到应用环境中，你就可以上线了。

事件

这些是你想让你的插件监听和响应的事件。订阅事件很简单，只需放入插件工作者的端点URL即可。当相关事件发生时，我们将向该URL发送一个POST请求。您可以了解到更多关于在这些请求中预期的内容在这里．

设置步骤

您创建的每个步骤都代表了您希望插件安装程序显示的一个屏幕。这些步骤是你如何从安装程序中收集必要的信息，以使你的插件正常工作。

例如，安装程序可能会被要求提供他们首选的配置，或者他们可能会被要求使用你的插件与之对话的一些外部服务进行身份验证。

步骤可以是以下任何一个

• 一个用来进行身份验证的对话框
• 弹出式-一个自定义内容的模态窗口
• 表单——用户填写的内容

每种步骤类型都有不同的配置设置

OAuth2一步

当安装完成时OAuth2步骤，Envoy自动处理OAuth2流。在流的最后，您可以通过提供一个“Validation URL”来保存生成的访问令牌和任何其他生成的数据。注意，不同于形式步骤类型，使用验证URL是保存这些值的唯一方法。

对于这种步骤类型，倾向于将数据存储在存储中，而不是将任何对象发送回存储在安装配置中，因为存储是敏感数据的最佳位置(它从不向前端公开)。

另外，一定要将在构建器中找到的“回调URL”注册为有效的redirect_uri在外部系统中，你什么都不反对。

弹出的步骤

当您希望完全控制某些外部认证时，应该使用此步骤类型。您甚至可以使用它重建OAuth2流。

要创建一个弹出窗口，提供一个“Content URL”。当安装程序到达这一步时，我们将显示一个重定向到此URL的弹出窗口。另外，我们将追加一个状态查询参数设置为URL。

当你完成了你的流程，重定向用户回到“回调URL”在构建器中发现，与相同的状态查询参数附加到该回调URL。此重定向将关闭弹出窗口并完成该步骤。如果您希望为该步骤保存任何值，请将它们作为额外的查询参数传递。

对于复杂的数据，比如嵌套对象，或者您希望保存在存储中的敏感数据，您可以像其他步骤类型一样使用“Validation URL”。

表单的步骤

当安装程序完成时形式步骤，它们的值会自动保存到安装配置中，使用你指定的“Key”作为键来访问请求元的值配置财产。

如果您希望控制保存哪些值(如果有的话)，可以提供一个“Validation URL”，Envoy将以路径的形式访问该URL。

对该请求的响应应该是一个对象，该对象将用作键和值，并将保存在安装配置中。为了防止该步骤完成，返回一个400响应。如果您的响应是一个JSON对象，其中包含消息属性，我们将使用它作为显示给安装程序的错误消息。

下面是可用字段类型的列表形式步骤有:

• 文本-典型文本输入
• 复选框——典型的复选框
• 链接-一个按钮，打开一个链接，在一个新的标签或弹出
• 信息——静态文本
• 选择-一个下拉菜单，它的选项由插件中的一个端点填充
• 资源选择-预先设置的下拉框选择特使资源(位置，流程，员工等)
• 映射-映射一个选项列表到一些其他数据类型

大多数字段类型都是不言自明的，所以下面我们将探索更复杂的字段类型。

选择表单类型

选择框显示选项列表。要创建一个选择框，您必须提供一个“Options URL”，Envoy将点击这个URL来加载选择选项。你必须用一个JSON对象数组来响应它，其中每个对象必须有一个标签和价值．

选择框具有可搜索和分页的选项。一个可搜索的选择将有一个搜索栏在下拉菜单中。一个分页选择将不断加载更多的选项，当你向下滚动下拉列表。选择项可以同时进行搜索和分页。

当一个下拉菜单是可搜索的，对选项URL的调用将包括一个搜索参数。分页后，对该URL的调用将包括页面参数。插件负责用适当的选项对象数组(带有标签和价值)，根据这些参数。

当启用分页时，Integration Builder将为“所选值”请求一个额外的URL。这对于那些表单字段已经从先前的保存中获得了与之关联的值，但该值没有出现在选项的第一页的情况很有用。Envoy将向该URL发出请求价值参数为该值加载适当的选项对象，并将其作为选项插入。

使用游标的高级分页

作为替代分页分页，特使也支持光标分页，其中分页是通过标记完成的，而不是页码。它的工作原理如下:

Envoy检索第一页数据的初始调用将不包含参数。插件应该用一个对象而不是一个选项数组来响应。这个对象应该包括数据属性和选项数组光标财产。不管它的价值是什么光标然后，当Envoy请求下一页数据时，属性将被传递回插件光标参数。

使用游标分页对于包装使用游标的api很有用，或者对于动态变化的数据显示一致的下拉框很有用。

阅读更多关于游标在这里。

形式映射类型

的映射类型比选择，但解决了一个非常常见的用例。它生成一组数据到另一组数据的映射。例如，您可以将Envoy访问者类型映射到外部系统的用户类型。

在大多数情况下映射类型函数，例如选择类型，其中必须提供一组选项以呈现下拉列表。这个下拉菜单将出现在屏幕的左侧。您将被要求选择一个辅助字段类型，该类型将显示在屏幕的右侧。然后安装程序将能够从左侧下拉菜单中选择一个选项来映射到右侧的值。安装程序可以添加任意数量的映射。

API凭证

API凭证是一个客户端ID和客户端机密分配给你的插件。它们只在你的插件第一次保存之后生成，并且被你的插件用来生成插件范围内的访问令牌。

这些访问令牌的特殊之处在于，它们专门用于执行插件操作，比如将条目保存到存储中，或更新作业。它们还用于验证Envoy随每个请求一起发送到插件的签名。Node.js SDK会自动使用这些值，一旦它们出现在ENVOY_CLIENT_ID和ENVOY_CLIENT_SECRET环境变量。在本地，您可以创建.env文件来定义这些变量。