文档首页/ Astro轻应用 AstroZero/ 用户指南（低代码）/ 使用AstroZero进行应用集成开发/ 使用连接器调用第三方接口/ 使用Rest服务调用Rest协议接口
更新时间：2024-12-12 GMT+08:00
查看PDF
分享

使用Rest服务调用Rest协议接口

当系统需要调用第三方提供的Rest协议接口时，可以通过配置Rest服务来实现。Rest服务是第三方系统提供的，是一组模块化的Rest接口，通过配置第三方提供的Rest服务的URL进行调用。对接Rest服务后，可以为服务添加动作，动作用于将第三方接口转换成AstroZero可识别的，方便AstroZero进行调用。

创建自定义连接器对接Rest服务

通过自定义链接对接Rest服务，并为Rest服务添加动作，使得系统可以调用第三方提供的Rest协议的接口，实现第三方提供的业务功能。

  1. 参考登录AstroZero新版应用设计器中操作，登录应用设计器。
  2. 在左侧导航栏中，选择“集成”。
  3. 在“连接器 ”中，单击“连接器实例”，进入连接器实例页面。
  4. 在类型中，选择“自定义连接器”，进入自定义连接器页面。
  5. 单击“+”，配置连接器信息，单击“保存”。

    图1 创建自定义连接器
    表1 自定义连接器参数说明

    参数

    说明

    标签

    自定义连接器的标签，创建后可修改。

    取值范围：1~64个字符。

    名称

    自定义连接器的名称，名称是连接器在系统中的唯一标识，创建后不可修改。命名要求如下：

    • 长度不能超过64个字符，包括前缀命名空间的长度。
      须知：

      名称前的内容为命名空间，在AstroZero中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。

    • 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。

    图标

    为自定义连接器，添加图标。支持从本地上传图片，作为连接器的图标。

    描述

    根据实际需求，输入自定义连接器的描述信息。

    取值范围：1~255个字符。

  6. 在“认证信息”页签，单击“新建”，进入添加认证信息页面。
  7. 设置认证信息，单击“保存”。

    可以新建多个认证，不同的动作可以有不同的认证方式。

    图2 设置认证基本信息
    图3 设置鉴权信息
    表2 认证信息参数说明

    参数

    说明

    标签

    新建认证的标签名，用于在页面显示。

    取值范围：1~64个字符。

    名称

    新建认证的名称，名称是认证在系统中的唯一标识。命名要求如下：

    • 长度不能超过64个字符，包括前缀命名空间的长度。
      须知：

      名称前的内容为命名空间，在AstroZero中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。

    • 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。

    目录

    认证所属的目录分类名称，直接在下拉框中选择。

    描述

    根据实际需求，输入认证的描述信息。

    取值范围：1~255个字符。

    使用证书

    服务端是否需要客户端证书，是否需要进行双向认证。勾选“使用证书”时，需要配置证书类型、证书和密钥。

    使用根证书

    客户端是否需要服务端证书，是否需要进行双向认证。

    勾选“使用根证书”时，需要提前在管理中心开启根证书校验并上传根证书，具体操作请参见开启AstroZero根证书认证对方服务端身份。上传后，在根证书下拉框中选择对应的证书即可。

    API主机地址

    配置此地址后，可以限定REST操作的请求前缀，防止敏感信息泄露。每次更改此地址，都需要重新配置鉴权信息。

    打包当前配置

    选中该选项后，应用打包时会将当前配置的连接器信息一并打出。例如，如果应用包发布到运行环境，当前配置默认为被同步到运行环境中。默认为选中，对信息敏感的场景，建议不勾选。

    鉴权设置
    • 鉴权协议：设置鉴权协议，支持OAuth、简单消息头和JWT（JSON Web Tokens）三种。
    • 鉴权模式：设置为“client credentials”，此处只支持OAuth2的client credentials鉴权模式。
    • 鉴权地址：第三方系统OAuth2协议，获取的token地址。例如，AstroZero获取token的地址为“https://{host}:{port}/baas/auth/v1.0/oauth2/token”，这里需要填入第三方系统的。
    • Client ID：OAuth2协议中的client id。如果该REST Service是AstroZero提供的，可通过如下方法查看：
      1. 进入AstroZero环境配置页面。
      2. 在左侧导航栏中，选择“集成连接 > OAuth”，进入OAuth管理页面。
      3. 在OAuth认证列表中，查看对应鉴权的“客户端Id”。
    • Client Secret：OAuth2协议中的client secret。如果该REST Service是AstroZero提供的，可通过如下方法查看：
      1. 进入AstroZero环境配置页面。
      2. 在左侧导航栏中，选择“集成连接 > OAuth”，进入OAuth管理页面。
      3. 在OAuth认证列表中，查看对应鉴权后。
      4. 在弹出的页面，单击“确定”，将密钥文件下载到本地。

        密钥文件中的client_secret，即为Client Secret的值。

    • 消息体属性：从鉴权接口返回的，消息字段的映射规则。

      根据OAuth2标准协议，返回体一般如图4所示。由于不同的第三方实现的情况可能不一样，返回的不一定是标准的键值。例如，有些第三方接口返回的是“accessToken”，而不是“access_token”，所以平台需要对这些不标准的键值映射成标准的。

      图3中配置的消息体属性是第三方返回的“accessToken”，AstroZero使用“access_token”这个键值来存储。最终存储的结果如下：

      {
“access_token”: ${accessToken}
}
    • 消息头属性：定义调用业务接口时，所用的消息头的映射规则。

      当使用获取的token，去返回具体rest action时，按照OAuth2的标准一般是将token放到请求头上。例如，Authorization: Bearer ${access_token}。

      但是由于各个第三方接口实现的差异性，不一定叫Authorization，也不一定会在token前面加Bearer，例如访问平台的接口，token直接放在请求头Access-Token上，且不需要Bearer前缀，所以需要配置消息头属性。

      图3中配置的消息头属性，意思是将从消息体属性获取到的“access_token”放到请求头“Access-Token”上。
    图4 返回体

创建并启用Rest动作

对接Rest服务后，通过添加动作，使得系统可以调用第三方提供的Rest协议的接口，实现第三方提供的业务功能。

  1. 单击创建自定义连接器对接Rest服务中已创建的Rest服务，在“动作”页签，单击“新建”。
  2. 设置动作的基本信息，单击“下一步”。

    图5 新建动作设置基本信息
    表3 动作基本信息参数说明

    参数

    说明

    标签

    新建动作的标签名，用于在页面显示。

    取值范围：1~64个字符。

    名称

    新建动作的名称，名称是动作在系统中的唯一标识。命名要求如下：

    • 长度不能超过64个字符，包括前缀命名空间的长度。
      须知：

      名称前的内容为命名空间，在AstroZero中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。

    • 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。

    URL

    第三方提供的，协议服务的URL地址。例如，/path/test （认证信息需要配置主机地址）、http://www.域名.com或者http://系统参数。

    方法
    在下拉框中，选择请求的方法。
    • GET：获取资源。
    • POST：创建资源。
    • PUT：更新资源。
    • PATCH：用于更新资源的部分内容。
    • DELETE：删除资源。
    • OPTIONS：用于获取当前URL所支持的方法。

    方法选择“PUT”或“POST”时，可自定义输入消息体参数。当第三方入参为数组或非JSON类型时，需要在定义输入参数设置为“键-值”形式。勾选后系统会引入一个通用的入参变量“$in”，将数组或非JSON类型的变量存到“$in”中，变成“键-值”格式传入到Rest Action中。

    内容类型

    输入内容的类型，该值取决于第三方支持哪种类型，是在HTTP标准协议中定义的。

    • application/json
    • application/x-www-form-urlencoded
    • application/xml
    • multipart/form-data
    • text/html
    • text/plain

    返回类型

    取值为“application/json”时，表示会忽略第三方实际返回的“content-type”，使用第三方配置的“content-type”来解析第三方返回的内容。

    如果该参数取值为空，表示使用http返回中的“content-type”，来解析第三方返回的内容。

    超时时间

    当超出该参数设定的时间，第三方没有返回结果时系统报错。

    单位：秒。

    日期 格式

    如果该Rest服务输入参数包括Date类型且有固定的要求格式，则必须进行配置。

    请确保AstroZero提供的输入参数，符合第三方要求。例如，该Rest服务存在Date类型输入参数，且要求格式为“YYYY-MM-DD”，则此处必须配置为“YYYY-MM-DD”。

    日期/时间 格式

    如果该Rest服务输入参数包括DateTime类型且有固定的要求格式，则必须进行配置。

    请确保AstroZero提供的输入参数，符合第三方要求。例如，该Rest服务存在DateTime类型输入参数，且要求格式为“YYYY-MM-DD hh:mm:ss”，则此处必须配置为“YYYY-MM-DD hh:mm:ss”。

    禁用请求头规范化

    是否禁用请求头规范化。如果勾选，不会将 “'accept-language' ”规范化成 “'Access-Language'”。

    默认为不勾选。

    禁用HTML字符转义

    是否禁用Json格式请求体中的HTML字符转义，如 &、<> 等字符。 如果勾选，“'&' ”不会转义为 “'\u0026' ”。

    默认为不勾选。

    描述

    根据实际需求，输入动作的描述信息。

    取值范围：1~255个字符。

  3. 设置消息头入参，单击“下一步”。

    如果此接口没有消息头输入参数，则不需要配置参数，请删除第一行参数。如果有消息头输入参数，且有多个，请单击。如果之前创建Rest Service时，有定义消息头参数，可选择“从模板中插入”，并定义输入参数的基本信息。
    图6 消息头入参配置页面
    表4 消息头入参说明

    参数

    说明

    标签

    消息头输入参数的标签名，用于在页面显示。

    名称

    新建消息头输入参数的名称，名称是消息头入参在系统中的唯一标识。

    数据类型
    消息头输入参数的数据类型。
    • 数字
    • 字符串
    • 布尔值
    • 敏感文本

    默认值

    设置消息头入参的默认取值，勾选“默认”后，才可以自定义。

    描述

    根据实际需求，在输入框中入参的描述信息。

    默认

    消息头输入参数是否有默认值。勾选后，可在“默认值”中进行自定义。“数据类型”为“敏感文本”时，不允许设置默认值。

    必填

    消息头输入参数是否为必填。

    操作

    单击或，可复制或删除消息头输入参数。

  4. 设置输入参数，单击“下一步”。

    如果此接口没有输入参数，则不需要配置参数，删除第一行参数。如果有输入参数，且有多个，请单击，并定义输入参数的基本信息。

    页面上方“消息体格式”参数使用说明：当方法为“PUT”或“POST”时，该参数才会显示。当第三方入参为数组类型或者非JSON类型时，需要将“输入消息体方式”设置为“值”形式。

    例如，如果设置“消息体格式”为“键-值”，假设定义了输入参数A、B、C，调用时消息体中传递了参数 {A:1,B:2, C:3} ，此时被调用方收到的参数信息是 {A:1,B:2, C:3}。如果设置“输入消息体方式”为“值”，此时默认使用$in输入参数定义，调用时消息体中传递了参数{$in: [1,2,3] }，此时被调用方收到的参数信息为[1,2,3]。

    图7 输入参数配置页面
    表5 输入参数说明

    参数

    说明

    标签

    输入参数的标签名，用于在页面显示。

    名称

    新建输入参数的名称，名称是输入参数在系统中的唯一标识。

    参数位置

    设置输入参数的位置，取值如下：

    • 消息体
    • URL查询参数
    • URL路径参数

    数据类型
    设置输入参数的数据类型，取值如下：
    • 日期：日期类型，精度到天。
    • 日期/时间：时间类型，精度到秒。
    • 数字：数字类型。
    • 字符串：字符串类型。
    • 布尔值：布尔类型，取值为“true”和“false”。
    • 全局结构体
    • 键值对(Map)：Map集合类型。
    • 对象：对象标识类型。
    • 敏感文本，如姓名、手机号等。

    命名空间

    “数据类型”设置为“全局结构体”时，需要设置输入参数所属的命名空间。

    元数据名称

    “数据类型”设置为“对象”时，需要选择元数据的名称，即应用中创建的自定义对象。

    默认值

    设置输入参数的默认取值。

    描述

    根据实际需求，在输入框中输入参数的描述信息。

    取值范围：1~255个字符。

    默认

    输入参数是否有默认值。勾选后，可在“默认值”中进行自定义。“数据类型”为“敏感文本”时，不允许设置默认值。

    必填

    输入参数是否设置为必填。

    集合

    输入参数是否设置为数组类型。

    操作

    单击或，可复制或删除输入参数。

  5. 设置输出参数，单击“保存”。

    如果此接口没有输出参数，则不需要配置参数，请删除第一行参数。如果有输出参数，且有多个参数，请单击，并定义输出参数的基本信息。

    页面上方“消息体格式”参数使用说明：设置“输出消息体方式”为“值”后，系统会引入一个通用的出参变量“$out”，将body的内容存到“$out”中，作为出参。

    例如，若设置“消息体格式”为“键-值”，假设定义了输出参数A、B、C，调用后返回消息体中传递了参数 {A:1,B:2, C:3} ，此时调用方收到的参数信息是 {A:1,B:2, C:3}；若设置“输出消息体方式”为“值”，此时默认使用$out输出参数定义，调用业务接口返回消息体中传递了参数[1,2,3]，此时调用方收到的参数信息为{$out:[1,2,3]}。

    图8 输出参数配置页面
    表6 输出参数说明

    参数

    说明

    标签

    输出参数的标签名，用于在页面显示。

    名称

    新建输出参数的名称，名称是输出参数在系统中的唯一标识。

    参数位置

    设置输出参数的位置，取值如下：

    • 消息头
    • 消息体

    数据类型
    设置输出参数的数据类型，取值如下：
    • 日期：日期类型，精度到天。
    • 日期/时间：时间类型，精度到秒。
    • 数字：数字类型。
    • 字符串：字符串类型。
    • 布尔值：布尔类型，取值为“true”和“false”。
    • 全局结构体
    • 键值对(Map)：Map集合类型。
    • 对象：对象标识类型。

    命名空间

    “数据类型”设置为“全局结构体”时，需要设置输入参数所属的命名空间。

    元数据名称

    “数据类型”设置为“对象”时，需要选择元数据的名称，即应用中创建的自定义对象。

    描述

    根据实际需求，输入参数的描述信息。

    集合

    输出参数是否设置为数组类型。

    操作

    单击或，可复制或删除输出参数。

  6. 在动作页签，单击该Rest Action所在行的，启用Rest Action。

    单击“导出”，可导出zip包，zip包中包括该服务的所有Rest接口。单击“导入”，可通过导入yaml文件，导入Rest Action。

在服务编排中，调用动作

创建一个服务编排，通过在服务编排中调用Rest服务中添加的动作，将第三方提供的业务功能集成到AstroZero中使用。

  1. 参考登录AstroZero新版应用设计器中操作，登录应用设计器。
  2. 在左侧导航栏中，选择“逻辑”。
  3. 单击编排后，设置服务编排的标签和名称，单击“添加”。

    图9 添加一个服务编排

  4. 在服务编排设计器页面左侧，选择“连接器 > 自定义 > 服务名”，拖拽2中的Rest服务图标至画布中。
  5. 设置调用动作参数。

    图10 配置动作
    表7 调用动作参数说明

    参数

    说明

    动作

    选择创建并启用Rest动作中创建的动作。

    输入参数

    设置输入参数，单击“新增行”，可进行添加。

    在“目标”中，选择4中设置的输入参数，在“源”中设置对应的值。

    输出参数

    设置输出参数，单击“新增行”，可进行添加。

    在“目标”中，选择5中设置的输出参数，在“源”中设置对应的值。

  6. 单击服务编排设计器页面上方的，保存服务编排。
  7. 保存成功后，单击，运行服务编排。
  8. 在输入参数中，输入请求参数，单击“运行”，查看输出结果。

在脚本中，调用动作

创建一个脚本，通过在脚本中调用Rest服务中添加的动作，将第三方提供的业务功能集成到AstroZero中使用。

  1. 参考登录AstroZero新版应用设计器中操作，登录应用设计器。
  2. 在左侧导航栏中，选择“逻辑”。
  3. 单击脚本后的，设置脚本名称，单击“添加”。

    图11 新增一个空脚本

  4. 在脚本编辑器中，输入如下代码。 

    // Here's your code.
import * as connector from "connector";
let client = connector.newClient("命名空间__test", "test1");
let result = client.invoke("命名空间_flapRefund", {});
console.log(result)

    其中，“命名空间__test”表示连接器的名称，“test1”为创建自定义连接器对接Rest服务配置的认证信息名称，“命名空间__flapRefund”为创建并启用Rest动作中配置的动作名称。

  5. 单击脚本编辑器页面上方的，保存脚本。
  6. 脚本保存成功后，单击，运行脚本。
  7. 在页面底部“输入参数”页签中，输入请求参数，单击测试窗口右上角的。
  8. 在“日志”页签，查看打印的日志。

相关文档