如何调用后台接口

在应用开发过程中，经常需要在高级页面组件中调用后台接口来完成整个业务场景（例如获取购物车中用户的ID，订单编号，商品信息等）。为方便用户调用可配置的API，平台提供了桥接器功能。桥接器封装了平台的一些逻辑，如csrftoken验证、数据共享、数据周期调用功能等。

低代码平台预置了18个桥接器，其中的API数据桥接器、FLOW数据桥接器、SCRIPT数据桥接器和OBJECT数据桥接器为通用桥接器。在开发自定义组件时，可以根据API的类型引入使用。剩余的14个，为平台预置组件的桥接器，如地图、散点图等。如果预置的桥接器不能满足开发需求，还可以自定义开发桥接器进行上传使用。

在经典版应用设计器的“资产 > 高级页面 > 桥接器 ”页面中，可查看系统预置的桥接器或自定义桥接器，如下图所示：

图1 桥接器列表

初识桥接器（组件预置桥接器）

低代码平台预置的桥接器，在相应预置组件包中也有配置。例如，在预置的柱状图“基本折线图”组件包中，已配置好了预置的“柱状图和折线图数据桥接器”。

在高级页面开发过程中，选中折线图组件后，在右侧的“组件属性设置 > 数据”页签中，选用预置的桥接器，即可进行配置。

图2 组件预置桥接器配置示例

“组件属性设置 > 数据”页签中，主要参数说明如下：

• 桥接器实例：调用的桥接器名称，可从下拉框中选择该组件已配置的桥接器。如何在组件中配置桥接器，请参见如何在组件中使用通用桥接器。
• 数据类型 > 静态数据：获取桥接器中定义的静态数据作为该组件的数据来源，也可以在静态数据编辑器中修改或重置静态数据。当静态数据编辑器失去鼠标焦点后，组件会依据该静态数据重新渲染。
  图3 重新渲染
  
• 数据类型 > 动态数据：通过动态调用后台的服务编排或脚本，获取数据作为该组件的数据来源。
  

  • 当系统预置的事件和动作无法满足用户需求时，用户可自定义桥接器，在页面中进行使用，更多介绍请参见如何自定义桥接器。
  • 若数据类型为动态数据，您需要参考服务编排或脚本开发和API接口中相关内容，开发好后台逻辑，并将获取的URL配置到数据面板的URL输入框，并且后台逻辑返回数据的结构需跟静态数据编辑器中显示的数据结构相同。
  • URL：桥接器通过动态调用后台的服务编排或脚本，来获取数据作为该组件的数据来源，需配置服务编排或脚本的自定义接口URL。
    

    接口输出数据的结构要和静态数据编辑器中，显示的数据保持一致。

  • 共享数据：若该高级页面中多个组件通过桥接器调用一个公共的请求来访问同一个接口的数据（请求参数也一致），通过勾选该项可避免重复调用接口。
• 调用周期：用于配置周期调用后台接口或获取静态数据的时间间隔（单位为秒）。默认配置为“0”，表示只调用一次后台接口或者只获取一次静态数据。

以在组件中，调用AstroZero中的脚本实现加减法计算器为例，向您介绍如何在组件中使用通用桥接器。在组件中使用通用桥接器的相关组件开发规范及方法，请参见开发高级组件。

图4 桥接器示例组件

1. 开发脚本。

   若想要在组件中调用后台服务，首先需要在应用中开发一个后台服务（脚本或服务编排）。

   1. 参考脚本开发实例中操作，新建一个脚本，假设脚本名称为“CalScript”，模板采用“示例服务脚本”，并启用该脚本。
      更多关于脚本的介绍，请参见脚本开发。

      图5 新建脚本示例
      
   2. 脚本调试。
      单击工具栏中的运行按钮，打开调试台，输入参数后单击运行脚本按钮，即可进行脚本调试。

      图6 调试脚本示例
      
      脚本输入参数示例：

      {
          "op": "+",
          "value1": 1,
          "value2": 1
      }

      脚本输出参数示例：

      {
          "result": 2
      }

   3. 单击脚本编辑器上方的，启用脚本。

2. 新建服务。

   在1中，已通过脚本模板新建并启用脚本，通过桥接器调用该脚本前，需要新建服务。

   1. 单击经典版应用设计器左下角的“服务”，进入服务页面。
   2. 在公共接口中，单击“新建”，进入新建公共接口页面。
   3. 配置服务的参数，单击“保存”。
      图7 新建服务示例
      
      • 操作名称：设置为“calculate”。
      • 版本：设置为“1.0.0”。
      • URL：补充为“/calculate”。
      • 类型：选择“脚本”。
      • 资源：选择1中创建的脚本（需要在已启用状态）。
      • 方法：选择“POST”。

      服务保存成功后，请在公共接口列表中获取URL，用于配置桥接器。

      图8 服务列表示例
      
      

      本例中新建的服务URL为“/service/CNAME1__customName23/1.0.0/calculate”，在组件属性设置时，只需设置为“/CNAME1__customName23/1.0.0/calculate”即可。

3. 在自定义组件中，开发桥接器逻辑，并参考6中操作，将组件上传到组件库中。

   在自定义组件中配置所需桥接器实例，并通过AstroZero提供的API发起请求和处理返回结果信息。该组件详细说明如下：

   1. 在BridgeTestWidget.editor.js文件中，配置桥接器实例。

      config: [{
          "type": "connectorV2",
          "name": "APIConnector",
          "model": "ViewModel",
          "label": "AstroZero通用桥接器示例",
          "value": ""
      }]

      桥接器配置项说明如下：

      • type：配置项的类型，桥接器的配置项类型为固定值“connectorV2”。
      • name：桥接器的变量名称，可通过该值获取桥接器实例。

        例如getConnectorInstanceByName('APIConnector')，其中getConnectorInstanceByName为低代码平台提供的API。

      • model：桥接器实例的模型，通用桥接器实例模型均为“ViewModel”，只有属于该模型的桥接器实例，才可在数据配置栏中配置。
        图9 选择桥接器
        
      • label：配置项的标题。
        图10 配置桥接器标题
        
      • value：配置项的默认值。
   2. 在BridgeTestWidget.js文件中，定义桥接器处理逻辑。

      组件中，常用桥接器的相关API，如表1所示。

      表1 桥接器API列表

      API名称	详细说明
      getConnectorInstanceByName('APIConnector')	通过桥接器的变量名称获取桥接器实例，其中“APIConnector”类型为String，表示桥接器的变量名称。
      ConnectorIns.process(renderCbk, errCbk)	通过桥接器实例调用process函数，主要作用为发起调用服务的请求和处理返回结果信息。 在通过process函数发起请求前，需设置桥接器实例的requestParams属性为请求的参数，如下所示。 ConnectorIns.requestParams = param; renderCbk 类型为Function，当返回结果信息后调用该函数，处理返回信息。 errCbk 类型为Function，如果未设置URL属性，调用该函数处理错误。
      ConnectorIns.query(param)	通过桥接器实例调用process函数，用于发起调用服务的请求和处理返回结果信息。 param：请求参数。 其返回结果为Promise对象。

      示例代码如下所示：

      1. 获取桥接器实例。

         ConnectorIns: thisObj.getConnectorInstanceByName('APIConnector')// Line 70，

      2. 构造请求参数和renderCbk函数。

         calculate: function () {
             let _this = this;
             // 构造请求参数
             let connectorParam = {
                 "op": _this.option,
                 "value1": _this.number1,
                 "value2": _this.number2
             };
             let connector = _this.ConnectorIns;
             // 本例中通过定义的callFlowConn函数统一处理桥接器相关操作
             thisObj.callFlowConn(connector, connectorParam, _this.setResult);
         },
         // 构造renderCbk函数，该例中为设置返回值
         setResult: function (resData) {
             let _this = this;
             if (resData.data && resData.data.result != undefined) {
                 _this.result = resData.data.result;
             }
         }

      3. 发起请求。

         callFlowConn: function (connector, param, callbackFunc) {
         
             var thisView = this;
             if (connector) {
             // 通过桥接器实例的process方法处理请求示例：
                 // connector.requestParams = param;
                 // connector.process(function (response) {
                 //     if (response) {
                 //         callbackFunc.call(thisView, response);
                 //     }
                 // });
             // 通过桥接器实例的query方法处理请求示例：
                 connector.query(param).then(res => callbackFunc(res));
             } else {
                 console.log("没有设置Connector或数据类型");
             }
         }

4. 配置桥接器属性。
   在页面中，拖入本例中的示例组件BridgeTestWidget，并配置该组件的桥接器属性，操作示例如下图所示。

   图11 配置桥接器属性示例
   

   配置参数说明：

   • 桥接器实例：桥接器类型，本示例选择“通用AppCube API数据桥接器”。
   • 数据类型：本示例选择“动态数据”。
   • 请求方法：数据为动态数据类型时需配置，这里选择的方法对应的是组件开发调用接口所用的方法。如果需要使用多个方法调用接口时，需要在界面配置多个方法。本示例选择“post”。
   • 前缀：配置请求URL的部分内容，本例中为“/CNAME__customName23/1.0.0/calculate”，平台会自动为您拼接完整的URL。
   • 共享数据：是否共享数据。若“数据类型”为“动态数据”，该参数才会显示，勾选表示某项目里多个组件调用一个公共的请求而访问同一个接口的数据，避免多次调接口。
   • 调用周期：每隔多少秒调用一次后台接口或者获取静态数据，默认配置为“0”，表示只调用一次或者只获取一次静态数据。

5. 预览效果。

   组件的桥接器属性配置完成后，保存页面并依次发布、预览，查看效果是否符合预期。

   图12 预览示例
   

   如上图所示，调用服务返回的结果结构如下，其中resCode和resMsg为固定结构，result属性对应的值为脚本或服务编排返回的结果。

   {
       "resCode":"0",
       "resMsg":"成功",
       "result":{"result":112}
   }

如何自定义桥接器

当通用桥接器不能满足您的场景需求，支持用户自定义桥接器，并上传到平台中，供高级页面使用。在桥接器中，平台对外开放的自定义部分主要执行流程如下所示：

图13 桥接器执行流程图

如上图所示，桥接器中主要的自定义函数为constructUrl和transform，您可以按需求封装上述函数，以此实现不同功能的桥接器。自定义桥接器中常用的API说明，请参考高级页面桥接器中预置的API。在应用开发界面左侧列表单击，选择“高级页面 > 桥接器模板”，下载模板解压后可查看API调用示例。

1. 在本地开发桥接器相关文件，并打成Zip包。
   1. 参考登录经典应用设计器中操作，登录经典版应用设计器。
   2. 在左侧列表中，单击，选择“高级页面 > 桥接器模板”。
   3. 单击模板，在模板详情页单击“下载”。
   4. 在“下载桥接器模板”弹出框中，设置桥接器名称和桥接器模型名称，单击“保存”。

      例如，设置“桥接器名称”为“bridgeTest”，“桥接器模型名称”为“bridgeModel”。若选择“下载原始模板”，下载到本地的包中桥接器名称和桥接器模型名称不会被修改。

   5. 将下载到本地的包进行解压，使用您熟悉的开发工具进行开发。

      以原始模板包为例，说明Zip包中的文件及文件的功能。

      表2 桥接器目录结构说明

      文件名	详细说明
      mock\data.json	定义该桥接器静态数据，当在“组件属性设置”面板中数据栏配置该桥接器并选择静态数据类型时，AstroZero将读取该文件内容，作为静态数据来源。
      bridgeTest.js	实现该桥接器的业务逻辑，其中主要函数及API描述如下： var bridgeTest = ConnectorWrapper.extend()：表示该自定义桥接器继承于AstroZero平台定义的ConnectorWrapper类，此为开发规范。 init函数实现。 transform函数实现。 constructUrl函数实现。 Studio.registerConnector("bridgeTest", "bridgeTest", "", bridgeTest, bridgeModel)：注册该桥接器，参数分别为桥接器的命名空间、桥接器名称、桥接说明、桥接器实例和桥接器模型。
      bridgeModel.js	定义桥接器的对象模型。
      packageinfo.json	桥接器的元数据描述文件，用于描述该桥接器。 connectorApi.name：桥接器名称。 connectorApi.namespace：桥接器的命名空间。 connectorApi.model：桥接器模型。 connectorDescription：定义该桥接器的说明。 authorName：定义该桥接器的开发人员。

      “bridgeTest.js”代码如下，加粗为预置的桥接器API，API说明请参见高级页面桥接器中预置的API。

      var bridgeTest = ConnectorWrapper.extend({
          init: function () {
              this.setInputParams([{
                  label: "URL",
                  type: "text",
                  name: "url",
                  value: "/service/v1.0/getBasicInfo",
                  validation: {
                      rules: {
                          required: true,
                      },
                      messages: {
                          required: "Please enter the URL."
                      }
                  }
              }]);
          },
          transform: function (resultData, cbk) {
              if (resultData.resCode == "0") {
                  var modelObj = new bridgeModel();
                  modelObj.setName(resultData.result[0].name);
                  cbk(modelObj);
              }
          },
          constructUrl: function (inputParamsObj) {
              var options = {
                  data: JSON.stringify(inputParamsObj.input),
                  contentType: "text/html;charset=utf-8",
                  beforeSend: function (xhr) {
                      xhr.setRequestHeader("bass-method", "post");
                      xhr.setRequestHeader("Content-Type", "application/json");
                  }
              };
              this.setLoadMethod("post", "json", "", "", options);
              this.setUrl(inputParamsObj.url);
          }
      });
      
      Studio.registerConnector("bridgeTest", "bridgeTest", "", bridgeTest, bridgeModel);

   6. 根据需求修改js文件内容。

2. 在左侧列表中，单击，选择“高级页面 > 桥接器”。
3. 单击“提交新桥接器”，新建桥接器。

   AstroZero支持批量上传桥接器，单击“批量操作桥接器”，可进行批量操作。

4. 输入桥接器基本信息，选择zip包，单击“提交”，上传桥接器。

   上传完成后，在“租户”下，可查看到该桥接器。

   图14 图5 上传完成
   
   

   “全局”中为平台预置的桥接器，不可编辑和禁用预置桥接器。

5. （可选）您可单击某一自定义桥接器，进入该桥接器详情页面，可进行编辑基本信息、编辑桥接器配置信息、下载或者禁用操作。

   若禁用桥接器后，可在“高级页面> 禁用资产”中看到已禁用的桥接器。禁用后您可在桥接器详细页面单击“删除”，弹出确认框，您可填入该桥接器名称后单击“确定”，删除该桥接器。

   在“概况”页签下看查看该桥接器的描述信息；在“更改历史”可查看该桥接器的历史版本（按照版本依次排序显示，最近版本号在最上面），可下载、在线预览代码和发布上传不同版本的桥接器。

   图15 图6 该桥接器详情页面
   

6. 在组件中，配置该桥接器，详细操作请参见4。