跳到主要内容

集成中心-API集成介绍

功能概述​

在集成中心的API集成模块，可以统一管理第三方API的鉴权认证配置和API接口的请求配置，经过授权的应用都可以直接调用配置好的API来获取数据或推送数据。

除了自定义配置接口外，在API库中，平台还预置了200多个常用的API模板，组织管理员也可以将自定义的连接添加到组织下的API库。

以下几处可直接调用配置好的连接认证或API接口:

  • 工作表的[API查询]字段和[文本识别]字段
  • 控件事件中[调用已集成]动作
  • 工作流的[调用已集成API]节点，可以直接使用集成中心里的配置好的API
  • 工作流的[API认证与连接] 节点，可以直接使用集成中心里的「连接与认证」

入口​

在平台主页，点击左侧导航栏“集成”-"API集成"进入管理页面。

API集成中有"我的连接"和"API库"两部分

  • 我的连接

    在这里可以创建第三方API的连接并保存鉴权认证、配置接口请求信息和授权给相关应用。

  • API库

    • 公共库： 由平台预设的API连接模板，可以直接安装使用，但是API连接配置不能更改，只能填充参数。

    • 组织库： 组织管理员可以将组织内创建的API连接添加到组织库，其他成员可以申请使用。

安装预置API快速体验功能​

在API库中，内置了200多种常用API服务，安装后，连接认证以及API接口等相关信息都自动配置好，您只需填写和配置必要的参数值即可。

我们以[天眼查]为例，介绍下安装和使用过程。

1、安装目标API​

进入集成中心后，找到[天眼查]，点击查看接口介绍，然后点击安装。

2、配置连接信息​

界面中出现了需要token的信息，需要我们前往提供服务的网站注册账户，申请接口并获取到这个token，然后填写进来保存即可。

3、启用需要的API​

一个服务商可以有多个接口服务，找到需要的接口开启即可。

4、授权给需要的应用​

只有添加了授权的应用，才能使用此连接服务和API功能。

5、工作表中使用集成API​

进入CRM应用，添加API查询字段和工商信息相关的字段。

功能效果

第一步、连接与认证​

上一章我们通过安装预置API模板，了解了使用过程。本章我们详细介绍从0开始配置自定义连接的操作过程。

添加自定义连接​

进入集成中心后，切换到[我的连接]，点击[+自定义连接]-[创建自定义连接]

选择鉴权方式​

根据所需API服务的鉴权要求，选择对应的鉴权方式，如果不需要或者在请求URL中进行API Key鉴权，则直接点击[API Key或无需鉴权]，选择后点击保存并继续。

连接参数​

连接参数是配置鉴权时依赖的一些身份参数，比如企业微信中要获取Token时需要corpid和corpsecret，这些参数服务商都会分配给我们，我们只需粘贴到此处即可，如果API接口不需要，连接参数可以不配置。

在API服务商系统内获取到相关信息后，填充到对应的参数值然后保存即可（安装的API服务，只能填写参数值，不能改参数名等信息）

  • 参数值可以选择隐藏显示，勾选隐藏后，参数值加密显示，不允许取消隐藏

  • 参数值隐藏后，只能修改，不能再显示

连接参数 除了获取Token时可能需要，在调用API时请求参数也可能需要，因此，服务商的基础应用信息都可以填写在这里供鉴权认证使用或API请求时使用。

Basic Auth 认证​

此方式表示每次请求API时都需要提供用户的username和password。

用户名和密码可以在这里直接写固定值，也可以从配置好的连接参数中选择。

OAuth 2.0 鉴权认证(客户端凭证)​

通过此方式可以获取到的Access Token，供API请求时使用。

  • 默认生成 app_id 和 app_secret 两个param参数；可以更改或删除
  • 参数值可以从连接参数中选择
  • 配置完毕后点击[获取Access Token]按钮，测试
  • 根据API服务要求，可以配置过期时长，到时自动获取新Token。

OAuth 2.0 认证（授权码）​

  • 授权回调地址：HAP侧生成的回调地址，用于接受授权完成后的回调信息。通常需要拿到这个地址配置在集成侧的应用里

  • 授权认证地址：OAuth 2.0协议中用于接收用户认证请求的URL

  • 获取/刷新Access Token节点:根据集成侧的接口文档完成对应鉴权配置

对于授权码鉴权类型的API都是基于个人身份进行认证的，在「账户」模块，可以查看自己完成授权的账户列表。还可以操作「编辑账户名称」、「删除账户」、「重新授权」、「手动刷新 token」。

配置连接的基本信息​

可以设置连接的名称、Logo、和描述

第二步、API接口请求配置​

连接认证配置完成后，就可以开始配置相关的API请求了。 切换到[API管理]，点击创建API按钮开始配置。

主要配置基本信息、输入参数、API请求参数和输出参数，以及使用代码块来个性化处理输入和输出参数。

API基本信息​

点击相关位置，可以设置API的名、描述说明、图标和颜色

输入参数​

输入参数用于在工作表或工作流中使用 API 查询时，可以传入动态值。传进来后，可以将此参数值再传给API请求参数。

参数默认值​

  • 如果参数为非必填，且传进来的为空值，则使用默认值（如果有）。

  • 必填参数一定会有值传进来，不需要设置默认值，但也支持设置（取消必填时可用）

参数格式规则和要求​

  • 参数类型：文本、数值、日期时间、人员、部门、附件、数组、对象数组；

  • 附件字段中无论有多少个文件，传入的的数组，格式如下。

    ["URL1","URL2","URL3"...]， 如果需要URL字符串，则使用代码块处理后再传入API请求参数。

  • 必填的参数在工作表和工作流中使用此API时传入的参数不能为空；

  • 对象数组的必填验证规则：

    • 对象数组必填，则在使用时必须传入该数组；对象数组不必填，则在使用时该数组可以不传入；
    • 对象数组必填且子元素没有设置必填项，则在使用时允许传入的数组为空数组；
    • 对象数组必填且子元素有必填项，则在使用时会验证传入的子元素是否有值；
    • 对象数组不必填但子元素有必填项，则未传入对象数组时不验证子元素是否有值，该数组传了值之后，则需要验证必填的子元素项是否有值；

  • 别名规则：仅支持字母、数字、下划线、短横线（减号）

  • 在发送API请求时，数组对象子元素将以别名作为key

  • 参数支持默认值

插入代码​

当传入的参数格式或数据不符合API参数要求时，可以通过代码处理后再传递给API参数。也可以将API返回的结果经常代码处理后再输出。

支持 Javascript和Python语言。

常见场景有：

  • 结合时间戳、密钥等加密后获取Token

  • 传递手机号时去掉 +86

  • 传递附件图片时传递URL字符串

  • 将API返回的数据封装为JSON数组并输出返回

  • 从API返回的JSON数据中进行处理后输出返回

代码块节点的使用方法

API请求配置​

在这里配置发送 API 请求时需要的URL、 Query Param、Header、Body 等请求参数。

请求中的参数值可以选择[连接参数]和[输入参数]、[鉴权认证]3个地方的动态值。

配置完毕后，点击[测试API]，输入测试参数，即可返回请求的数据。

相关配置信息介绍，可参考发送API请求介绍

输出参数​

在API执行请求后，将获取到的数据格式化输出，以便被工作表字段或被工作流节点引用。

其依据的示例数据是上一步测试时返回的响应Body中的数据。

输出配置方法： 使用JSON解析后将需要的内容添加到参数中。JSON解析

发布API​

输出参数配置完毕后，就可以发布API了。发布后才能被应用的工作表或工作流调用。

添加更多API接口​

一个连接认证内，可以添加多个API接口请求，这些API接口共用用同一个连接。

第三步、授权给应用​

集成中心配置好的API，需要配置连接的拥有者，错误提醒机制和授权应用，获得授权才能直接调用。

切换到[授权到应用]栏位下，可以进行操作操作。

拥有者​

连接的拥有者可以修改和查看连接的配置，可以接收错误消息。

发送错误消息​

如果调用时出现错误，是否向拥有者发送消息，如果发送，可以配置发送消息类型，如果是相同类型消息则多久才通知一次，不需要次次提醒，造成干扰。

授权应用​

只有本组织的应用才能添加授权，授权后，应用下的工作表和工作流可以调用API。

第四步、如何调用集成API​

具体请参考相关介绍

连接和API管理​

连接的导出导入和升级​

可以直接将API进行导出、导入创建、导入升级，实现API的快速迁移。

进入连接详情页，点击右上角更多按钮，可以进行导出和导入升级的操作。升级更新时，不会更改目标连接中的连接参数的显隐配置。

也可以导出API库中的连接：

在创建新的自定义连接时，可以导入创建。

连接中的API管理​

在连接的API管理栏目下，可以管理此连接下的所有API，可以开启停用API。

点击某个API，可以进一步查看和管理此API的信息。

查看引用​

可以看到此接口被哪些工作表和工作流引用。点击工作表/工作流名称可以直接打开对应的编辑页面。

请求日志​

可以查看所有引用此 API 发送的请求日志。 无权限人员不能查看日志。

请求参数示例：

返回结果示例

如何申请上架到API库​

在集成中心中您可申请上架自己集成的产品到API库中，以提供给其他用户使用。在申请上架后，我们工作人员会在1～3个工作日内完成审核。

上架标准​

在申请前需要注意以下事项避免审核不通过。

  • 完善“自定义连接”Logo、基础信息、连接说明、接口名称、接口说明等信息。
  • 不出现无意义字符如test、123等名称或标识。
  • 必须包含产品介绍、产品官网、对接流程（接口文档链接不强制）。
  • 若您有特殊需求如加急审核可通过联系与您对应的明道云HAP销售或实施进行咨询。

补充：建议在产品介绍中加上您的联系方式，以免后续用户想要使用您提供的API时出现接口报错等其他问题时可通过该联系方式联系您。

可参考以下“自定义连接”模板（也可通过查看API库中的官方已对接产品）

上架步骤​

  1. 在"集成中心" > "我的连接"中找到需要上架的连接（产品）

  2. 补充连接的“使用说明”

    必须包含产品介绍、产品官网、对接流程（接口文档不强制）。建议留下您的联系方式方便后续用户安装使用您的连接时出现疑问或其它接口相关问题可联系您进行解决。

  3. 点击右上角"⋮"按钮 ，然后选择“申请上架到API库”

  4. 根据提示信息完善连接上架信息，最后点击“申请上架新版本”即申请成功。等待后台工作人员进行审核，审核时间约1～3个工作日。

如何更新已上架API​

  1. 进入需要更新上架的“自定义连接”

  2. 点击右上角"⋮"按钮，并点击“申请上架新版本”

  3. 默认情况下更新接口不需要改动原有产品信息，若需要更改调整可按照下面提示更改所需要的产品连接信息即可，最后点击“申请上架新版本”即申请成功。等待后台工作人员进行审核，审核时间约1～3个工作日。

添加或安装最新API​

在用户使用集成中心API库的接口过程中，作者需要对所拥有的API更新上架。需要将更新的接口进行复制并且关闭原有接口重新申请上架，否则需要维护更新的API则不会出现在已安装的用户连接中。

用户若需要更新从API库中安装的连接中的API可分为以下两种情况。

  • SaaS环境：

    点击“添加API”,在列表中会显示新的API接口。

  • 私有环境：需要重新安装API库中的连接。