# 使用自定义连接器调用第三方接口 #### 操作场景 通过使用华为云Astro轻应用的自定义连接器、服务编排或事件功能，带您快速对接一个外部服务的接口。例如，对接一个已有的Rest服务，通过Rest服务获取数据并加工，并在华为云Astro轻应用中使用。 表1Rest服务接口 | 参数 | 值 | |:---|:---| | 路径 | https://example.com/path/to/data?key=value | | 请求方法 | POST | | 请求头 | X-Header | | 请求体类型 | application/json | | 请求体参数 | ``` { “request”: “value” } ``` | | 响应体类型 | application/json | | 响应体参数 | ``` { “response”: “value” } ``` | #### 操作流程 通过自定义连接器，调用第三方接口的基本操作流程，如[图1]所示。 图1操作流程图 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001980671901.png) #### 步骤1：创建自定义连接器 1. 参考[登录华为云Astro轻应用应用设计器](https://support.huaweicloud.com/usermanual-astrozero/astrozero_05_9004.html)中操作，登录应用设计器。 2. 在左侧导航栏中，选择"集成"。 3. 单击"连接器"中的" 连接器实例"，进入连接器实例页面。 4. 在类型中，选择"自定义连接器"，进入自定义连接器页面。 5. 单击"+"，配置连接器信息，单击"保存"。 图2创建自定义连接器 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001970970720.png "点击放大") 表2自定义连接器参数说明 | 参数 | 说明 | |:---|:---| | 标签 | 自定义连接器的标签，创建后可修改。 取值范围：1\~64个字符。 | | 名称 | 自定义连接器的名称，名称是连接器在系统中的唯一标识，创建后不可修改。命名要求如下： - 长度不能超过64个字符，包括前缀命名空间的长度。 名称前的内容为命名空间，在华为云Astro轻应用中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。 - 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。 | | 图标 | 为自定义连接器添加图标。支持从本地上传图片，作为连接器的图标。 | | 描述 | 根据实际需求，输入自定义连接器的描述信息。 取值范围：1\~255个字符。 | 6. 在"动作"页签中，新建自定义连接器动作，设置动作的基本信息，单击"下一步"。 图3设置基本信息 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000002306231860.png "点击放大") 表3动作基本信息参数说明 | 参数 | 说明 | |:---|:---| | 标签 | 新建动作的标签名，用于在页面显示。 取值范围：1\~64个字符。 | | 名称 | 新建动作的名称，名称是动作在系统中的唯一标识。命名要求如下： - 长度不能超过64个字符，包括前缀命名空间的长度。 名称前的内容为命名空间，在华为云Astro轻应用中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。 - 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。 | | 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"和"text/event-stream"两种类型。如果**不配置** 即**为空**，则表示使用HTTP响应中的"Content-Type"来解析第三方返回的内容。 - application/json：选择该类型时，系统将忽略第三方实际返回的"Content-Type"，采用第三方配置的"Content-Type"来解析返回内容。 - text/event-stream：选择该类型时，将以处理流式报文的方式处理接口返回值，需要确保第三方接口的返回值为**流式报文** ，**且** **响应体中的"Content-Type"为"text/event-stream"**。 | | 超时时间 | 当超出该参数设定的时间，第三方没有返回结果时系统报错。 单位：秒。 | | 日期 格式 | 如果该Rest服务输入参数包括Date类型且有固定的要求格式，则必须进行配置。 请确保华为云Astro轻应用提供的输入参数，符合第三方要求。例如，该Rest服务存在Date类型输入参数，且要求格式为"YYYY-MM-DD"，则此处必须配置为"YYYY-MM-DD"。 | | 日期/时间 格式 | 如果该Rest服务输入参数包括DateTime类型且有固定的要求格式，则必须进行配置。 请确保华为云Astro轻应用提供的输入参数，符合第三方要求。例如，该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. 设置消息头入参，单击"下一步"。 如果此接口没有消息头输入参数，则不需要配置参数，请单击![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001936101789.png)删除第一行参数。若有消息头输入参数，且有多个，请单击![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001936101785.png)进行复制。 图4消息头入参配置页面 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001936601802.png "点击放大") 表4消息头入参说明 | 参数 | 说明 | |:---|:---| | 标签 | 消息头输入参数的标签名，用于在页面显示。 | | 名称 | 新建消息头输入参数的名称，名称是消息头入参在系统中的唯一标识。 | | 数据类型 | 消息头输入参数的数据类型。 - 数字 - 字符串 - 布尔值 - 敏感文本 | | 默认值 | 设置消息头入参的默认取值，勾选"默认"后，才可以自定义。 | | 描述 | 根据实际需求，在输入框中入参的描述信息。 | | 默认 | 消息头输入参数是否有默认值。勾选后，可在"默认值"中进行自定义。"数据类型"为"敏感文本"时，不允许设置默认值。 | | 必填 | 消息头输入参数是否为必填。 | | 操作 | 单击![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001914542088.png)或![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001946261169.png "点击放大")，可复制或删除消息头输入参数。 | 8. 设置输入参数，单击"下一步"。 该步骤配置的是请求的路径或消息体对应的内容，由参数的"参数位置"决定是路径参数还是消息体参数。 本示例中，请配置一个URL查询参数为key，请求体参数request的入参，参数解释请参见[表5]。 图5输入参数配置页面 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001894302196.png "点击放大") 表5输入参数说明 | 参数 | 说明 | |:---|:---| | 标签 | 输入参数的标签名，用于在页面显示。 | | 名称 | 新建输入参数的名称，名称是输入参数在系统中的唯一标识。 | | 参数位置 | 设置输入参数的位置，取值如下： - 消息体 - URL查询参数 - URL路径参数 | | 数据类型 | 设置输入参数的数据类型，取值如下： - 日期：日期类型，精度到天。 - 日期/时间：时间类型，精度到秒。 - 数字：数字类型。 - 字符串：字符串类型。 - 布尔值：布尔类型，取值为"true"和"false"。 - 全局结构体 - 键值对(Map)：Map集合类型。 - 对象：对象标识类型。 - 敏感文本，如姓名、手机号等。 | | 命名空间 | "数据类型"设置为"全局结构体"时，需要设置输入参数所属的命名空间。 | | 元数据名称 | "数据类型"设置为"对象"时，需要选择元数据的名称，即应用中创建的自定义对象。 | | 默认值 | 设置输入参数的默认取值。 | | 描述 | 根据实际需求，在输入框中输入参数的描述信息。 取值范围：1\~255个字符。 | | 默认 | 输入参数是否有默认值。勾选后，可在"默认值"中进行自定义。"数据类型"为"敏感文本"时，不允许设置默认值。 | | 必填 | 输入参数是否设置为必填。 | | 集合 | 输入参数是否设置为数组类型。 | | 操作 | 单击![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001946275669.png)或![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001914716508.png "点击放大")，可复制或删除输入参数。 | 9. 设置输出参数，单击"保存"。 配置输出的参数，取决于"参数位置"，该参数可能来自于响应消息头或者请求消息头。此案例中，响应体有一个response的参数。 图6输出参数配置页面 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001894302152.png "点击放大") 表6输出参数说明 | 参数 | 说明 | |:---|:---| | 标签 | 输出参数的标签名，用于在页面显示。 | | 名称 | 新建输出参数的名称，名称是输出参数在系统中的唯一标识。 | | 参数位置 | 设置输出参数的位置，取值如下： - 消息头 - 消息体 | | 数据类型 | 设置输出参数的数据类型，取值如下： - 日期：日期类型，精度到天。 - 日期/时间：时间类型，精度到秒。 - 数字：数字类型。 - 字符串：字符串类型。 - 布尔值：布尔类型，取值为"true"和"false"。 - 全局结构体 - 键值对(Map)：Map集合类型。 - 对象：对象标识类型。 | | 命名空间 | "数据类型"设置为"全局结构体"时，需要设置输入参数所属的命名空间。 | | 元数据名称 | "数据类型"设置为"对象"时，需要选择元数据的名称，即应用中创建的自定义对象。 | | 描述 | 根据实际需求，输入参数的描述信息。 | | 集合 | 输出参数是否设置为数组类型。 | | 操作 | 单击![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001914557120.png)或![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001946276197.png "点击放大")，可复制或删除输出参数。 | 10. 在动作页签，单击该动作所在行的![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001894302148.png)，启用该动作。 #### 步骤2：配置连接器认证信息 自定义连接器在服务编排或事件中调用时，需要先配置认证信息。 1. 参考[步骤1：创建自定义连接器]中操作，进入自定义连接器页面。 2. 在"认证信息"页签，单击"新建"，进入添加认证信息页面。 3. 设置认证信息，单击"保存"。 华为云Astro轻应用提供了丰富的认证类型供用户选择，请按照自身业务需求，配置对应的认证信息。 图7添加认证信息-基本信息 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000002134402829.png "点击放大") 图8添加认证信息-鉴权设置 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000002098763638.png "点击放大") 表7添加认证信息参数说明 | 参数 | 说明 | |:---|:---| | 标签 | 认证的标签名，用于在页面显示。 取值范围：1\~64个字符。 | | 名称 | 认证的名称，名称是认证在系统中的唯一标识。命名要求如下： - 长度不能超过64个字符，包括前缀命名空间的长度。 名称前的内容为命名空间，在华为云Astro轻应用中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。 - 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不能以下划线结尾。 | | 目录 | 认证所属的目录分类名称。 | | 描述 | 根据实际需求，输入认证的描述信息。 取值范围：1\~255个字符。 | | 使用证书 | 服务端是否需要客户端证书，是否需要进行双向认证。勾选"使用证书"时，需要配置证书类型，证书和密钥。 默认为选中。 | | 证书类型 | 勾选"使用证书"时，才会显示该参数。 证书所属的类型，支持"CRT"和"P12"两种。 | | 证书 | 勾选"使用证书"时，才会显示该参数。 从本地上传"CRT"和"P12"类型的证书。 | | 密钥 | 勾选"使用证书"时，才会显示该参数。 输入已上传证书的访问密钥。 | | 使用根证书 | 客户端是否需要服务端证书，是否需要进行双向认证。 勾选"使用根证书"时，需要提前开启根证书校验并上传根证书，具体操作请参见[开启华为云Astro轻应用根证书认证对方服务端身份](https://support.huaweicloud.com/usermanual-astrozero/astrozero_06_2009.html)。上传后，在根证书下拉框中选择对应的证书即可。 | | API主机地址 | 配置此地址后，可以限定REST操作的请求前缀，防止敏感信息泄露。每次更改此地址，都需要重新配置鉴权信息。 | | 打包当前配置 | 选中该选项后，应用打包时会将当前配置的连接器信息一并打出。例如，如果应用包发布到运行环境，当前配置默认为被同步到运行环境中。默认为选中，对信息敏感的场景，建议不勾选。 | | 鉴权设置 | - 鉴权协议：设置鉴权协议，支持OAuth、简单消息头和JWT（JSON Web Tokens）三种。 - 鉴权模式：设置为"client credentials"，此处只支持OAuth2的client credentials鉴权模式。 - 鉴权地址：第三方系统OAuth2协议，获取的token地址。例如，华为云Astro轻应用获取token的地址为"https://{host}:{port}/baas/auth/v1.0/oauth2/token"，这里需要填入第三方系统的。 - Client ID：OAuth2协议中的client id。如果该REST Service是华为云Astro轻应用提供的，请参考[客户端模式接入认证](https://support.huaweicloud.com/usermanual-astrozero/astrozero_05_0890.html#astrozero_05_0890__section153744140251)中操作获取。 - Client Secret：OAuth2协议中的client secret。如果该REST Service是华为云Astro轻应用提供的，请参考[客户端模式接入认证](https://support.huaweicloud.com/usermanual-astrozero/astrozero_05_0890.html#astrozero_05_0890__section153744140251)中操作获取。 | | 消息体属性 | 从鉴权接口返回的，消息字段的映射规则。 根据OAuth2标准协议，返回体一般如[图9]所示。由于不同的第三方实现的情况可能不一样，返回的不一定是标准的键值。例如，有些第三方接口返回的是"accessToken"，而不是"access_token"，所以平台需要对这些不标准的键值映射成标准的。 [图8]中配置的消息体属性是第三方返回的"accessToken"，华为云Astro轻应用使用"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返回体 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001914771746.png) #### 步骤3：在服务编排中调用自定义连接器 创建一个服务编排，在服务编排中调用已创建的自定义连接器，将经过Rest服务加工的数据在华为云Astro轻应用中使用。 1. 参考[登录华为云Astro轻应用应用设计器](https://support.huaweicloud.com/usermanual-astrozero/astrozero_05_9004.html)中操作，登录应用设计器。 2. 在左侧导航栏中，选择"逻辑"。 3. 单击编排后![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001894302200.png)，设置服务编排的标签和名称，单击"添加"。 图10添加一个服务编排 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000002013579985.png "点击放大") 4. 在服务编排设计器页面左侧，"连接器 \> 自定义 \> *服务名* "，拖拽[步骤1：创建自定义连接器]中的Rest服务图标至画布中。 **请确保自定义连接器中已添加认证信息（如[步骤2：配置连接器认证信息]），否则此处无法拖动。** 5. 配置要调用的动作。 图11配置要调用的动作 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000002134522521.png "点击放大") 6. 单击服务编排设计器页面上方的![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001894302124.png)，保存服务编排。 7. 保存成功后，单击![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001936101837.png)，运行服务编排。 如果Rest服务无法调通，可以通过工具栏上的"跟踪"按钮查看运行日志，例如最常见的网关不可达。 图12网关不可达 ![](https://support.huaweicloud.com/usermanual-astrozero/zh-cn_image_0000001894302192.png "点击放大") 服务编排调试成功后，即可把服务编排应用于您的业务逻辑中。 #### 相关文档 通过自定义连接器将第三方数据库集成到华为云Astro轻应用中，具体操作请参见[通过华为云Astro轻应用连接器对接第三方数据库](https://support.huaweicloud.com/bestpractice-astrozero/astrozero_bestpractice_0020.html)。