使用自定义连接器调用第三方接口

操作场景

通过使用AstroZero的自定义连接器、服务编排或事件功能，带您快速对接一个外部服务的接口。例如，对接一个已有的Rest服务，通过Rest服务获取数据并加工，并在AstroZero中使用。

{
“request”: “value”
}

{
“response”: “value”
}

操作流程

通过自定义连接器，调用第三方接口的基本操作流程，如图1所示。

图1 操作流程图

步骤1：创建自定义连接器

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

   表2 自定义连接器参数说明

   参数	说明
   标签	自定义连接器的标签，创建后可修改。 取值范围：1~64个字符。
   名称	自定义连接器的名称，名称是连接器在系统中的唯一标识，创建后不可修改。命名要求如下： 长度不能超过64个字符，包括前缀命名空间的长度。 说明： 名称前的内容为命名空间，在AstroZero中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。
   图标	为自定义连接器添加图标。支持从本地上传图片，作为连接器的图标。
   描述	根据实际需求，输入自定义连接器的描述信息。 取值范围：1~255个字符。

6. 在“动作”页签中，新建自定义连接器动作，设置动作的基本信息，单击“下一步”。
   图3 设置基本信息
   

   表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个字符。

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

   如果此接口没有消息头输入参数，则不需要配置参数，请单击删除第一行参数。若有消息头输入参数，且有多个，请单击进行复制。

   图4 消息头入参配置页面
   

   表4 消息头入参说明

   参数	说明
   标签	消息头输入参数的标签名，用于在页面显示。
   名称	新建消息头输入参数的名称，名称是消息头入参在系统中的唯一标识。
   数据类型	消息头输入参数的数据类型。 数字 字符串 布尔值 敏感文本
   默认值	设置消息头入参的默认取值，勾选“默认”后，才可以自定义。
   描述	根据实际需求，在输入框中入参的描述信息。
   默认	消息头输入参数是否有默认值。勾选后，可在“默认值”中进行自定义。“数据类型”为“敏感文本”时，不允许设置默认值。
   必填	消息头输入参数是否为必填。
   操作	单击或，可复制或删除消息头输入参数。

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

   该步骤配置的是请求的路径或消息体对应的内容，由参数的“参数位置”决定是路径参数还是消息体参数。

   本示例中，请配置一个URL查询参数为key，请求体参数request的入参，参数解释请参见表5。

   图5 输入参数配置页面
   

   表5 输入参数说明

   参数	说明
   标签	输入参数的标签名，用于在页面显示。
   名称	新建输入参数的名称，名称是输入参数在系统中的唯一标识。
   参数位置	设置输入参数的位置，取值如下： 消息体 URL查询参数 URL路径参数
   数据类型	设置输入参数的数据类型，取值如下： 日期：日期类型，精度到天。 日期/时间：时间类型，精度到秒。 数字：数字类型。 字符串：字符串类型。 布尔值：布尔类型，取值为“true”和“false”。 全局结构体 键值对(Map)：Map集合类型。 对象：对象标识类型。 敏感文本，如姓名、手机号等。
   命名空间	“数据类型”设置为“全局结构体”时，需要设置输入参数所属的命名空间。
   元数据名称	“数据类型”设置为“对象”时，需要选择元数据的名称，即应用中创建的自定义对象。
   默认值	设置输入参数的默认取值。
   描述	根据实际需求，在输入框中输入参数的描述信息。 取值范围：1~255个字符。
   默认	输入参数是否有默认值。勾选后，可在“默认值”中进行自定义。“数据类型”为“敏感文本”时，不允许设置默认值。
   必填	输入参数是否设置为必填。
   集合	输入参数是否设置为数组类型。
   操作	单击或，可复制或删除输入参数。

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

   配置输出的参数，取决于“参数位置”，该参数可能来自于响应消息头或者请求消息头。此案例中，响应体有一个response的参数。

   图6 输出参数配置页面
   

   表6 输出参数说明

   参数	说明
   标签	输出参数的标签名，用于在页面显示。
   名称	新建输出参数的名称，名称是输出参数在系统中的唯一标识。
   参数位置	设置输出参数的位置，取值如下： 消息头 消息体
   数据类型	设置输出参数的数据类型，取值如下： 日期：日期类型，精度到天。 日期/时间：时间类型，精度到秒。 数字：数字类型。 字符串：字符串类型。 布尔值：布尔类型，取值为“true”和“false”。 全局结构体 键值对(Map)：Map集合类型。 对象：对象标识类型。
   命名空间	“数据类型”设置为“全局结构体”时，需要设置输入参数所属的命名空间。
   元数据名称	“数据类型”设置为“对象”时，需要选择元数据的名称，即应用中创建的自定义对象。
   描述	根据实际需求，输入参数的描述信息。
   集合	输出参数是否设置为数组类型。
   操作	单击或，可复制或删除输出参数。

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

步骤2：配置连接器认证信息

自定义连接器在服务编排或事件中调用时，需要先配置认证信息。

1. 参考步骤1：创建自定义连接器中操作，进入自定义连接器页面。
2. 在“认证信息”页签，单击“新建”，进入添加认证信息页面。
3. 设置认证信息，单击“保存”。
   AstroZero提供了丰富的认证类型供用户选择，请按照自身业务需求，配置对应的认证信息。

   图7 添加认证信息-基本信息
   
   图8 添加认证信息-鉴权设置
   

   表7 添加认证信息参数说明

   参数	说明
   标签	认证的标签名，用于在页面显示。 取值范围：1~64个字符。
   名称	认证的名称，名称是认证在系统中的唯一标识。命名要求如下： 长度不能超过64个字符，包括前缀命名空间的长度。 说明： 名称前的内容为命名空间，在AstroZero中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。
   目录	认证所属的目录分类名称。
   描述	根据实际需求，输入认证的描述信息。 取值范围：1~255个字符。
   使用证书	服务端是否需要客户端证书，是否需要进行双向认证。勾选“使用证书”时，需要配置证书类型，证书和密钥。 默认为选中。
   证书类型	勾选“使用证书”时，才会显示该参数。 证书所属的类型，支持“CRT”和“P12”两种。
   证书	勾选“使用证书”时，才会显示该参数。 从本地上传“CRT”和“P12”类型的证书。
   密钥	勾选“使用证书”时，才会显示该参数。 输入已上传证书的访问密钥。
   使用根证书	客户端是否需要服务端证书，是否需要进行双向认证。 勾选“使用根证书”时，需要提前开启根证书校验并上传根证书，具体操作请参见开启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提供的，请参考客户端模式接入认证中操作获取。 Client Secret：OAuth2协议中的client secret。如果该REST Service是AstroZero提供的，请参考客户端模式接入认证中操作获取。
   消息体属性	从鉴权接口返回的，消息字段的映射规则。 根据OAuth2标准协议，返回体一般如图9所示。由于不同的第三方实现的情况可能不一样，返回的不一定是标准的键值。例如，有些第三方接口返回的是“accessToken”，而不是“access_token”，所以平台需要对这些不标准的键值映射成标准的。 图8中配置的消息体属性是第三方返回的“accessToken”，AstroZero使用“access_token”这个键值来存储。最终存储的结果如下： { “access_token”: ${accessToken} }
   消息头属性	定义调用业务接口时，所用的消息头的映射规则。 当使用获取的token，去返回具体rest action时，按照OAuth2的标准一般是将token放到请求头上。例如，Authorization: Bearer ${access_token}。 但是由于各个第三方接口实现的差异性，不一定叫Authorization，也不一定会在token前面加Bearer，例如访问平台的接口，token直接放在请求头Access-Token上，且不需要Bearer前缀，所以需要配置消息头属性。 图8中配置的消息头属性，意思是将从消息体属性获取到的“access_token”放到请求头“Access-Token”上。

   图9 返回体
   

步骤3：在服务编排中调用自定义连接器

创建一个服务编排，在服务编排中调用已创建的自定义连接器，将经过Rest服务加工的数据在AstroZero中使用。

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

4. 在服务编排设计器页面左侧，“连接器 > 自定义 > 服务名”，拖拽步骤1：创建自定义连接器中的Rest服务图标至画布中。
   

   请确保自定义连接器中已添加认证信息（如步骤2：配置连接器认证信息），否则此处无法拖动。

5. 配置要调用的动作。
   图11 配置要调用的动作
   

6. 单击服务编排设计器页面上方的，保存服务编排。
7. 保存成功后，单击，运行服务编排。

   如果Rest服务无法调通，可以通过工具栏上的“跟踪”按钮查看运行日志，例如最常见的网关不可达。

   图12 网关不可达
   

   服务编排调试成功后，即可把服务编排应用于您的业务逻辑中。