更新时间:2025-08-28 GMT+08:00

对接ROMA Connect调用服务的API

应用与数据集成平台(ROMA Connect)是一个全栈式的服务平台,聚焦应用和数据连接,提供数据、API、消息和设备集成能力,帮助企业快速联接云上云下,消除数字鸿沟,实现数字化转型。在华为云Astro轻应用中,通过连接器和ROMA Connect对接后,可调用ROMA Connect的API集成服务。

前提条件

华为云Astro轻应用提供了默认对接的ROMA Connect服务器,也支持对接自有ROMA Connect实例。本章节以华为云Astro轻应用对接自有ROMA Connect为例进行说明,默认对接的ROMA Connect服务器配置类似。

  • 已在ROMA Connect平台上完成应用创建(创建时,应用的“Key”字符长度必须小于60,否则后续向华为云Astro轻应用同步时会失败)、函数API创建、API分组创建、API创建、调试、发布和授权操作。关于ROMA Connect的具体操作,请参见使用ROMA Connect集成服务配置API授权
  • 已在ROMA Connect上,设置“app_secret”和“app_route”值为“on”。

    修改方法:在ROMA Connect实例控制台的“实例信息”页面,选择“配置参数”,修改“app_secret”和“app_route”的“参数运行值”为“on”。

  • 对接自有ROMA Connect实例时,请确保已参考设置应用中对接的ROMA Connect信息中操作,在华为云Astro轻应用中设置ROMA Connect实例信息。

费用说明

应用对接ROMA Connect连接器后,ROMA Connect服务需要单独付费,具体收费标准请参见华为云定价应用停用后,ROMA Connect服务仍将按照既定的计费规则继续计费。

在华为云Astro轻应用上调用ROMA Connect的API

在ROMA Connect上创建的应用和发布的API,可以直接同步到华为云Astro轻应用。通过华为云Astro轻应用的ROMA Connect类型连接器,可在服务编排或事件中调用ROMA Connect的API。

  1. 查看ROMA Connect侧创建的应用Key值是否带有前缀,如果带有前缀,则需要在华为云Astro轻应用新建系统参数。

    1. 在ROMA Connect实例控制台的左侧导航栏中,选择“集成应用”。单击应用名,进入概览页面查看Key值。
      • 如果Key值带有前缀,例如为“test__com.appcube.user”,带有前缀“test__”,则需要执行1.b
      • 如果Key值不带前缀,例如为“com.appcube.user”,则执行2
    2. 新建系统参数。
      1. 在华为云Astro轻应用服务控制台的主页中,单击“进入首页”,进入应用开发页面。
      2. 单击页面左上角的,选择环境管理 > 环境配置,进入环境配置页面。
      3. 在左侧导航栏中,选择“系统设置 > 系统参数”。
      4. 单击“新建”,创建系统参数“roma_app_prefix”,配置参数值为此前缀取值“test__”,华为云Astro轻应用在后续同步API和调用API时会主动拼上此前缀。
        图1 创建系统参数

  2. 在连接器中同步ROMA Connect应用和API,并查看具体API。

    1. 参考登录华为云Astro轻应用应用设计器中操作,进入应用设计器。
    2. 在左侧导航栏中,选择“集成”
    3. 单击“连接器”中的“ 连接器实例”,进入连接器实例页面。
    4. 在左侧导航栏中,选择“HTTP > ROMA连接器”。
    5. 单击“同步应用”,将ROMA Connect上注册的应用直接同步到平台。
      图2 单击“同步应用”

      同步后,可在ROMA Connect连接器列表中,可查看到对应的应用。

      ROMA Connect连接器中的应用,可以由ROMA Connect同步而来,也可以通过安装包导入。通过安装包导入的ROMA Connect连接器中的应用,在ROMA Connect平台并不存在。需要将ROMA Connect资产导入到ROMA Connect平台,用户才可正常使用ROMA Connect连接器。

    6. 单击对应的连接器名称,在右侧“API接口”页签单击“同步API”,将ROMA Connect上发布并授权的API直接同步到华为云Astro轻应用。

      同步后,在“API接口”页签中,可查看到“获取人员信息”API。

    7. 单击API名称,可查看API具体信息,包括基本信息、消息头入参、输入和输出参数。

      如果ROMA Connect上该API有更新,请在ROMA Connect平台重新发布并授权API,然后在华为云Astro轻应用重新同步应用和API。

      API参数说明,如表1所示。

      表1 API参数说明

      参数类别

      参数名称

      说明

      消息头入参

      X-HW-APPKEY

      X-HW-APPKEY:ROMA应用的请求密钥,用于私钥认证。

      1. 在ROMA Connect实例控制台的左侧导航栏中,选择“集成应用”。
      2. 单击应用名,进入概览页面。
      3. 单击Secret右侧的,即可查看Secret信息。

      X-HW-ID

      ROMA应用的Key值。

      1. 在ROMA Connect实例控制台的左侧导航栏中,选择“集成应用”。
      2. 单击应用名,进入概览页面。
      3. 在概览页,查看Key值。

      Accept

      接收类型,默认值“application/json”。

      输入参数

      userID

      用户ID,为自定义输入参数。

      输出参数

      retCode

      结果码。

      retJSON

      接收JSON格式化的ROMA Connect返回数据。

      $out

      接收非格式化的ROMA Connect返回数据。

      对于POST请求类型,输入参数会有“$body”,通过此入参传递body结构体。可使用出参“$out”接版权信息设置后收非格式化的ROMA Connect返回数据,$out为结构体类型。

      如果业务需要在API中,增加其他消息头入参或输入参数,需要在ROMA Connect的API管理侧重新编辑API,定义好入参,重新发布并授权API,然后在华为云Astro轻应用重新同步该API。

在服务编排中调用ROMA Connect的API

  1. 参考创建空白华为云Astro轻应用服务编排中操作,创建一个服务编排。
  2. 在服务编排设计页面左侧,选择“连接器 > ROMA”,拖拽“人员管理”(连接器名称为ROMA应用名称)图元至画布中。
  3. 参考表1,设置变量和服务编排的输入输出参数。

    1. 选中开始图元,在服务编排设计页面右侧,选择
    2. 在私有结构体页面,单击“新增”。
      创建输出参数结构体类型变量前,首先需要创建私有结构体类型。
      图3 添加私有结构体类型
    3. 新增一个空的私有结构体“retJson”,不用设置结构体成员。
      图4 新建私有结构体
    4. 在服务编排设计页面右侧,选择
    5. 在全局上下文页面,单击“对象变量”后的加号。
      图5 添加对象变量
    6. 选择“私有结构体”,设置页面参数,名称为“retJson”,结构体选择已创建的私有结构体“retJson”。
      图6 配置私有结构体变量

    7. 参照上述操作,新增“out”私有结构体变量,结构体选择创建的私有结构体“out”。
      图7 对象out对象变量
    8. 在服务编排设计页面右侧,选择
    9. 在全局上下文页面,单击“变量”后的加号,新增图9中两个变量。
      图8 创建变量
      图9 添加两个变量
    10. 单击工作区域开始图元或空白区域,在服务编排设计页面右侧,选择,设置该服务编排的入参和出参。
      图10 设置服务编排的入参和出参
    11. 参考设置华为云Astro轻应用系统参数中操作,新建系统参数“appkey”,值填写为ROMA应用的请求密钥。

      由于“X-HW-APPKEY”为ROMA应用的请求密钥,可能发生变化,您可以新建系统参数,加密存储此入参,并通过公式引用。当请求密钥变化时,修改系统参数即可。

      图11 新建系统参数appkey
    12. 在服务编排设计页面右侧,选择
    13. 在全局上下文页面,单击“公式”后的加号,新建公式变量“appkey”,表达式为“SYSPARAMETER("appkey")”。
      图12 新建公式变量

  4. 在“连接器”页面进行配置,“动作”选择具体调用的API,例如“获取人员信息”,根据表1配置入参和出参,并连接图元。

    • 动作:具体调用的API,API选项由2.f同步而来。
    • 输入参数:调用API的输入参数。
    • 输出参数:调用API的输出参数。

  5. 单击服务编排页面上方的,保存服务编排。
  6. 保存成功后,单击编辑器页面上方的,执行服务编排。
  7. 设置如下输入参数,单击“运行”

    输入参数样例如下:

    {
        "userid": "001"
    }

    若显示如下信息,表示成功调用ROMA Connect的API。

    {
      "interviewId": "002N000000cOeh5XCDrc",
      "outputs": {
        "out": {
          "retCode": "0",
          "retJSON": {
            "result": {
              "employ_name": "zhangsan",
              "employ_no": "00xxxxxx"
            }
          }
        },
        "retCode": "0",
        "retJson": {
          "result": {
            "employ_name": "zhangsan",
            "employ_no": "00xxxxxx"
          }
        }
      }
    }

在脚本中调用ROMA Connect的API

  1. 参考创建空白华为云Astro轻应用脚本中操作,创建一个脚本。
  2. 在脚本编辑器中,输入如下代码。

    // Here's your code.
    import * as roma from "roma";
    import * as sys from "sys";
    // 通过ROMA应用名创建client,第二个参数可以不填写, roma.newClient("人员管理");
    let client1 = roma.newClient("人员管理", roma.NameType.AppName)
    
    // 通过ROMA应用的APPID创建client
    let client2 = roma.newClient("com.appcube.user", roma.NameType.AppId)
    
    //通过API名称调用,第一个参数是API名称,入参在第二个参数中传入,$body可以传入body参数
    let resp1 = client1.sendRest("获取人员信息", {
        "X-HW-APPKEY": sys.getParameter("appkey"),
        "X-HW-ID": "com.appcube.user",
        userID: "1110000",
        $body: {}
    });
    console.log(resp1.$out)
    
    //通过API的URL调用,第一个参数是请求方法,第二个参数为接口URL,入参在第三个参数中传入,$body可以传入body参数
    let resp2 = client1.sendRestByURL("GET", "/getUserInfo", {
        "X-HW-APPKEY": sys.getParameter("appkey"),
        "X-HW-ID": "com.appcube.user",
        userID: "1110000",
        $body: {}
    });
    console.log(resp2.$out)

  3. 单击脚本编辑器页面上方的,保存脚本。
  4. 保存成功后,单击编辑器页面上方的,执行脚本。
  5. 脚本中已设置输入参数,请直接单击测试窗口右上角的,执行脚本。

    日志页签显示如下信息,表示成功调用ROMA Connect的API。
    0813 16:33:31.504|debug|vm[2]>>> app cube 1.2.12 8fce52d0 2020-07-17 10:14:41 +0800 debug
    0813 16:33:31.504|debug|vm[2]>>> node: 1
    0813 16:33:31.504|debug|vm[2]>>> script: test10__roma 1.0.1 
    0813 16:33:31.504|debug|vm[2]>>> locale: zh_CN
    0813 16:33:31.504|debug|vm[2]>>> timezone: Local
    0813 16:33:31.723|debug|vm[2]>>> { retCode: '0', retJSON: { result: { employ_name: 'zhangsan', employ_no: '00xxxxxx' } } } (test10__roma.ts:17)
    0813 16:33:31.773|debug|vm[2]>>> { retCode: '0', retJSON: { result: { employ_name: 'zhangsan', employ_no: '00xxxxxx' } } } (test10__roma.ts:26)