更新时间:2022-04-26 GMT+08:00
分享

如何开放API接口

什么是API接口

API接口是用户将在应用中开发的脚本、服务编排等包装成自定义REST接口的形式发布出去使用,使得URL地址的表达形式更规范,方便让第三方系统进行调用。

如何定义API接口

  1. 在AppCube开发环境首页,单击某个应用,进入应用开发页面。
  2. 单击左下角的“服务”,进入服务管理页面。

    图1 服务
    图2 服务管理界面
    • 私有接口:使用私有接口,您可以将服务编排的URL映射到内部网关,提供给内部脚本、服务编排等流程调用。对于BO可以定义私有接口。
    • 公共接口:使用公共接口,您可以将服务编排、脚本或对象的URL映射到外部网关,第三方可以通过OAuth2.0调用。
    • 内部网关:仅当前租户能够访问映射到内部网关中的自定义接口,即只有同一租户下的脚本、服务编排等才能调用发布的私有接口。
    • 外部网关:其他租户或第三方系统均可访问映射到外部网关中的自定义接口。

  3. 单击“新建”,填写表1中参数,单击“保存”。

    表1 API信息

    参数名

    参数说明

    操作名称

    API接口名称。

    版本

    API接口版本,格式为“x.y.z”。

    URL

    API接口路径, 固定以 /service/{命名空间}__{应用名}/{版本} 开头, 后面接API的具体路径。

    内容类型

    请求中的body类型。

    • application/json
    • multipart/form-data
    • binary-data

    “multipart/form-data”和“binary-data”用于文件上传接口,选择该内容类型,只能调用post类型的脚本。

    分类

    该接口所属的分类。

    选填项,直接输入。

    描述

    关于该自定义API的描述信息。

    类型

    选择资源类型,只有服务编排类型的接口能够在服务编排中被调用,其他类型接口只能通过API的形式进行调用。

    • 服务编排:表示该定义URL调用的接口类型是服务编排。
    • 脚本:表示该定义URL调用的接口类型是脚本。
    • 对象:表示该定义URL是操作对象数据,包括对象数据的增删改查。

    自定义响应

    是否需要格式化调用该URL后返回的响应消息。如果勾选,表示对响应消息进行格式化,删除resCode、resMsg、result外层信息,只透传返回的消息。

    例如,不勾选“自定义响应”,返回如下响应消息:

    {
        "resCode": "0",
        "resMsg": "成功",
        "result": [
            {
                "equipments": [
                    {
                        "createdBy": "aaa",
                        "createdBy.__objectType": "User"
                    },
                    {
                        "createdBy": "aaa",
                        "createdBy.__objectType": "User"
                    }
                ],
                "total": "2"
            }
        ]
    }

    则勾选“自定义响应”后,只返回如下响应消息:

    {
        "equipments": [
            {
                "createdBy": "aaa",
                "createdBy.__objectType": "User"
            },
            {
                "createdBy": "aaa",
                "createdBy.__objectType": "User"
            }
        ],
        "total": "2"
    }

    资源

    根据类型选定需要绑定的资源,如脚本,服务编排或者操作的对象名称。

    注意:

    如果您找不到想绑定的服务编排或脚本,请检查服务编排或脚本是否启用,如果没有启用请单击按钮启用。

    对象操作

    当“类型”选择为“对象”时,该参数才会显示。

    • Insert Record:新增对象数据。
    • Update or Insert Record:更新或者新增对象数据。
    • Update By ID:按记录ID更新对象数据
    • Delete By ID:按记录ID删除对象数据
    • Query By ID:按记录ID查询对象数据
    • Update By Condition:按条件更新对象数据。
    • Delete By Condition:按条件删除对象数据。
    • Query By Condition:按条件查询对象数据

    方法

    API接口的HTTP方法。

    • GET:请求服务器返回指定资源。
    • PUT:请求服务器更新指定资源。
    • POST:请求服务器新增资源或执行特殊操作。
    • DELETE:请求服务器删除指定资源。
    • PATCH:请求服务器更新资源的部分内容。当资源不存在的时候,PATCH可能会去创建一个新的资源。

  4. 单击API接口列表操作栏按钮,查看定义的API信息。单击“测试一下”可模拟API接口调用。

    图3 API接口请求参数信息
    图4 API接口返回参数信息

    API接口的请求参数和返回消息体,为绑定的资源(如脚本,服务编排等)所配置的入参和出参。

如何进行鉴权

AppCube采用OAuth 2.0协议进行接入认证。第三方系统在调用AppCube业务接口前,需要在AppCube上进行鉴权注册,获取接入客户端ID、密钥等鉴权信息,才能实现调用AppCube业务接口。

AppCube平台提供了两种授权模式进行Oauth鉴权,分别是“客户端模式”和“授权码模式”,两种授权模式适用的鉴权范围有所不同。

  • 通过“客户端模式”获取的access-token可用于调用API接口时进行鉴权,使用时在请求消息头上设置“access-token”。
  • 通过“授权码模式”获取的access-token只用于获取用户信息时进行鉴权,使用时在请求消息头上设置“Authorization”。

每个OAuth都有特定的用途,建议为不同的第三方系统单独新建一个OAuth。

客户端模式接入认证

  1. 在AppCube开发环境首页,单击“管理”,进入管理控制台。
  2. 在左侧导航栏中,选择“系统管理 > OAuth”,单击“新建”。
  3. 输入名称,设置授权类型为“客户端模式”,选择用户,并单击“保存”。

    系统会自动生成客户端鉴权ID和密钥。

    图5 新建客户端模式Oauth管理
    • 第三方通过OAuth认证接入系统后,将以选择的用户身份操作数据,所以需要确保选择的用户具有调用API的相关权限。
    • 选择的用户的权限不能为匿名用户权限“Anonymous_User_Profile”,因为Guest用户没有访问API的权限,无法配置OAuth。

  4. 在OAuth管理列表页单击该鉴权所在行,下载密钥文件到本地,从中获取鉴权的客户端ID和鉴权密钥取值。

    密钥可以只创建一次,不需要重复新建。

    密钥文件中包含如下参数:
    • username:当“授权类型”配置为“客户端模式”时,密钥文件会包含该参数,为3中设置的用户名。
    • client_id:鉴权的客户端ID。
    • client_secret:鉴权密钥。

  5. 根据鉴权ID和鉴权密钥调用接口“/baas/auth/v1.0/oauth2/token”获取access_token。后续第三方需要通过access_token访问业务接口。

    表2 接口基本信息

    接口名称

    接口路径

    接口协议

    接口方法

    token

    /baas/auth/v1.0/oauth2/token

    HTTPS

    POST

    表3 请求参数说明

    参数名

    类型

    必选(M)/可选(O)

    参数位置

    参数含义

    grant_type

    String

    M

    Body

    授权模式,OAuth2.0中的grant_type字段的取值。

    client_credentials(即客户端模式)

    client_id

    String

    M

    Body

    鉴权的客户端ID,可在OAuth查看。

    4获取。

    client_secret

    String

    M

    Body

    鉴权密钥,可在OAuth查看。

    4获取。

    redirect_url

    String

    O

    Body

    重定向URL。

    http://www.***.com

    locale

    String

    O

    Body

    语言。

    en_US

    响应样例:

    通过Curl请求模拟接口调用:curl -i -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=client_credentials&client_id=鉴权ID值&client_secret=鉴权密钥值' https://AppCube域名/baas/auth/v1.0/oauth2/token

    响应如下:

    {
        "access_token": "ACCESS_TOKEN",
        "expires_in": 7200,
        "token_type": "Bearer"
    }

    其中,access_token为证后可信任的Token凭证;expires_in为当前access_token的有效期;token_type为access_token类型。

  6. 第三方调用AppCube的业务接口,这里以调用AppCube的自定义接口“queryEquipments”为例进行举例说明。

    1. 通过下面的REST接口调用“queryEquipments”。
      https://AppCube域名/service/CNAME__Elevator/1.0.1/queryEquipments

      其中“AppCube域名”替换为AppCube对外提供的开发态域名“appcube.cn-north-4.huaweicloud.com”,“service/CNAME__Elevator/1.0.1/queryEquipments”替换为自定义接口“queryEquipments”的URL。

    2. (可选)调用接口https://AppCube域名/u-route/baas/sys/v1.0/csrf/get(调用该接口时,需要在请求消息头上设置“access-token”)获取“csrf-token”值。
      调用接口后,返回的result取值即为“csrf-token”值。

      调用公共接口时,当需要做CSRF校验时,才需执行该步骤。

    3. 请求消息头Request Header中增加如下内容。
      • access-token:“ACCESS_TOKEN
      • Content-Type”:“application/json
      • “csrf-token”:“上一步result取值

      其中,“access-token”配置为执行5后获取的值。

    4. 请求消息体中写入该接口的输入参数。

      样例如下:

      {
          "equipmentSn": "001" 
      }
    5. 调用成功,输出如下信息。
      {
        "interviewId": "002N000000MJ77KcFGwC",
        "outputs": {
          "Equipments": [
            {
              "HW__equipmentBrand__CST": null,
              "HW__equipmentModel__CST": null,
              "HW__equipmentSN__CST": "9996660001",
              "HW__fullAddress__CST": "",
              "HW__installationDetailAddress__CST": null,
              "HW__installationSiteArea__CST": "",
              "HW__installationSiteCity__CST": "",
              "HW__installationSiteProvince__CST": "",
              "HW__latitude__CST": "",
              "HW__longitude__CST": "",
              "createdBy": "10gd000000MEGPaz7P16",
              "createdBy.__objectType": "User",
              "createdBy.name": "test",
              "createdDate": "2018-12-19 06:39:29",
              "currencyIsoCode": "",
              "custom": true,
              "equipmentSn__CST": "9996660001",
              "fullAddress__CST": "",
              "id": "c000000000MFhgYMQtmq",
              "installedPackage": null,
              "isLocked": false,
              "lastModifiedBy": "10gd000000MEGPaz7P16",
              "lastModifiedBy.__objectType": "User",
              "lastModifiedBy.name": "test",
              "lastModifiedDate": "2018-12-19 06:39:29",
              "latitude__CST": "",
              "longitude__CST": "",
              "name": "荔枝苑10栋1单元1号",
              "owner": "10gd000000MEGPaz7P16",
              "owner.__objectType": "User",
              "owner.name": "test"
            },
            {
              "HW__equipmentBrand__CST": "",
              "HW__equipmentModel__CST": null,
              "HW__equipmentSN__CST": "3217890001",
              "HW__fullAddress__CST": "ssss",
              "HW__installationDetailAddress__CST": null,
              "HW__installationSiteArea__CST": null,
              "HW__installationSiteCity__CST": null,
              "HW__installationSiteProvince__CST": null,
              "HW__latitude__CST": null,
              "HW__longitude__CST": null,
              "createdBy": "10gd000000MEGPaz7P16",
              "createdBy.__objectType": "User",
              "createdBy.name": "test",
              "createdDate": "2018-12-18 12:49:46",
              "currencyIsoCode": "",
              "custom": true,
              "equipmentSN__CST": "3217890001",
              "fullAddress__CST": "ssss",
              "id": "c000000000METF70NiZk",
              "installedPackage": null,
              "isLocked": false,
              "lastModifiedBy": "10gd000000MEGPaz7P16",
              "lastModifiedBy.__objectType": "User",
              "lastModifiedBy.name": "test",
              "lastModifiedDate": "2018-12-21 07:34:06",
              "latitude__CST": "",
              "longitude__CST": "",
              "name": "A栋1单元1号",
              "owner": "10gd000000MEGPaz7P16",
              "owner.__objectType": "User",
              "owner.name": "test"
            }
          ],
          "total": "2"
        }
      }

授权码模式接入认证

  1. 在AppCube开发环境首页,单击“管理”,进入管理控制台。
  2. 在左侧导航栏中,选择“系统管理 > OAuth”,单击“新建”。
  3. 授权类型选择“授权码模式”,输入名称进行配置,并单击“保存”。系统会自动生成客户端ID和客户端密钥。

    每个OAuth都有特定的用途,因此建议为不同的第三方系统单独新建一个OAuth。

    图6 新建授权码模式OAuth管理

    重定向地址将作为第三方系统同意授权后的跳转页面,并在页面地址上携带授权码信息。

  4. 在OAuth管理列表页单击该鉴权所在行,下载密钥文件到本地,从中获取客户端鉴权ID和鉴权密钥取值。

    密钥可以只创建一次,不需要重复新建。

    密钥文件中包含如下参数:
    • redirect_uri:当“授权类型”配置为“授权码模式”时,密钥文件会包含该参数,为上一步设置的重定向地址。
    • client_id:鉴权的客户端ID。
    • client_secret:鉴权密钥。

  5. 第三方系统访问AppCube获取授权码code的接口“https://AppCube域名/baas/auth/v1.0/oauth2/authorize?response_type=code&client_id=鉴权ID值&redirect_uri=重定向地址”。如果第三方系统选择同意接受授权,认证服务器将浏览器重定向到之前第三方系统注册时指定的重定向地址,同时附带上授权码,即重定向地址/?code=授权码

    若引导第三方系统打开页面时提示“该链接无法访问”,请检查如下参数是否填写错误:

    • 鉴权ID值:为上一步获取的鉴权客户端ID。
    • 重定向地址:为3配置的重定向地址。

  6. 客户端收到授权码code,根据鉴权ID、鉴权密钥、授权码code在自己后端调用接口“ https://AppCube域名/baas/auth/v1.0/oauth2/token”获取access_token。后续第三方需要通过access_token获取授权用户信息。这一步是服务器上完成的,用户无感知。

    表4 接口基本信息

    接口名称

    接口路径

    接口协议

    接口方法

    token

    https://AppCube域名/baas/auth/v1.0/oauth2/token

    HTTPS

    POST

    表5 请求参数说明

    参数名

    类型

    必选(M)/可选(O)

    参数位置

    参数含义

    grant_type

    String

    M

    Body

    授权模式,OAuth2.0中的grant_type字段的取值。

    authorization_code(即授权码模式)

    client_id

    String

    M

    Body

    客户端鉴权ID,可在OAuth查看。

    4中获取。

    client_secret

    String

    M

    Body

    客户端鉴权密钥,可在OAuth查看。

    4中获取。

    redirect_url

    String

    M

    Body

    重定向地址。

    4中获取。

    code

    String

    M

    Body

    授权码。

    5中获取。

    locale

    String

    O

    Body

    语言。

    en_US

    响应样例:

    通过Curl请求模拟接口调用:curl -i -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=authorization_code&client_id=鉴权ID值&client_secret=鉴权密钥值&redirect_uri=重定向地址&code=授权码' https://AppCube域名/baas/auth/v1.0/oauth2/token

    响应如下:

    {
        "access_token": "ACCESS_TOKEN",
        "expires_in": 7200,
        "refresh_token":"REFRESH_TOKEN",
        "token_type": "Bearer"
    }
    表6 返回参数说明

    参数

    参数说明

    access_token

    认证后可信任的Token凭证。

    expires_in

    当前access_token的有效期。

    refresh_token

    用于刷新access_token。

    token_type

    access_token类型。

    使用授权码获取access-token后即失效,重新获取access-token需要重新生成授权码。

  7. (可选)刷新access_token。

    由于access_token拥有较短的有效期,例如6中获取的access_token,有效期是7200秒(即2小时),当access_token超时后,可以使用refresh_token进行刷新,refresh_token有效期为30天,当refresh_token失效之后,需要用户重新授权。

    获取6的refresh_token后,请求以下链接获取access_token:

    https://AppCube域名/baas/auth/v1.0/oauth2/token?grant_type=refresh_token&client_id=鉴权ID值&client_secret=客户端鉴权密钥&refresh_token=REFRESH_TOKEN

  8. 将获取的token_type与access_token进行拼接,以{token_type} {access_token}的形式设置为Headers中的Authorization参数,通过Get请求调用接口“https://AppCube域名/u-route/baas/oauth/v1.0/userinfo”获取用户信息。

    {
      "resCode": "0",
      "resMsg": "成功",
      "result": {
        "usrname": "test",
        "alias": "",
        "email": "test@***.com",
        "aboutme": "",
        "company_name": "name01",
        "photo": "",
        "address": "",
        "phone": "18888888888",
        "country": "",
        "post_code": "",
        "province": "",
        "city": ""
      }
    }

自定义OAuth2授权码模式接入鉴权

前面介绍的是第三方系统访问AppCube时,如何配置接入鉴权,通过鉴权认证的第三方系统才可访问AppCube。

在AppCube开发的应用也可自定义OAuth2授权码模式接入鉴权,当应用配置鉴权后,只有通过鉴权的第三方系统才可访问应用。

  1. 参考1~4获取鉴权ID“client_id”和鉴权密钥“client_secret”。
  2. 在应用开发界面,开发者通过自定义接口,给第三方接入调用,用于第三方系统获取授权码code。
  3. 平台应用调用脚本API,判断第三方客户端的鉴权ID“client_id”和重定向地址“redirect_url是否和注册接入鉴权时匹配。如果匹配,则由平台应用自定义接口,实现登入跳转和授权跳转。在授权完成后,再调用脚本API获取授权码code,并将需要展示给第三方的授权用户信息通过该API传给AppCube,AppCube会返回一个code然后应用重定向到“redirect_url”,并携带code。

    • 判断第三方客户端的鉴权ID“client_id”和重定向地址“redirect_url是否和注册接入鉴权时匹配的API样例如下:
      // Here's your code.
      import * as oauth from 'oauth'
      let handle = oauth.getAuthorizeHandle()
      let clientDatas: oauth.clientDataFromApp = {
          redirect_uri: "http://10.26.30.68:14000/appauth/code",
          client_id: "bff4398905ee4a918722debec98b594c",
      }
      let pass = handle.checkURL(clientDatas)
      console.log(pass) //true
      if (pass){
      //判断是否登入,做登入跳转
      //判断是否授权,做授权跳转
      }
    • 获取授权码code的脚本API样例如下:
      // Here's your code.
      import * as oauth from 'oauth'
      let handle = oauth.getAuthorizeHandle()
       
       
      //前面步骤已经走完
      let clientDatas: oauth.clientDataFromApp = {
            redirect_uri: "http://10.26.30.68:14000/appauth/code",
          client_id: "bff4398905ee4a918722debec98b594c",
      }
       
      let userInfo = {
          "name": "jack",
          "phone": "1256287222",
          "email": "dsfsdf.com"
      } 
      let code = handle.getAuthCode(clientDatas, userInfo)
      console.log(code) //WEUcqXbeQDKUHxcn8til3Q

  1. 第三方系统接收到该请求,并解析出code后,在自己的后端访问AppCube接口获取access_token,其步骤和6一致。
  2. 第三方系统在获取到access_token后,用该凭证访问平台“https://AppCube域名/u-route/baas/oauth/v1.0/third/userinfo”接口(注意,该接口和8中的接口不同),来获取授权用户的信息。

    响应如下:

    {
        "resCode": "0",
        "resMsg": "成功",
        "result": {
            "email": "dsfsdf.com",
            "name": "jack",
            "phone": "1256287222"
        }
    }

如何使用错误码

系统支持对错误码信息进行多语言国际化配置。您可以通过配置错误码,实现根据用户使用的语言不同将错误码信息进行不同的展示。

  1. 自定义错误码。

    1. 在App视图下左侧菜单栏下方选择“配置”,在打开的页签选择“自定义错误码”
    2. 配置“显示名称”,该名称将会显示在运营配置页签。
    3. 单击“新建”。

      您也可单击“导入”,选择系统中已创建的错误码进行导入。

    4. 参照表7配置错误码参数,单击“保存”。
      图7 新建错误码
      表7 错误码参数说明

      参数

      参数说明

      名称

      客户自定义的错误码。建议以字母打头。

      包括命名空间,长度不超过64个字节。

      系统根据“名称”和“语言”匹配错误码进行展示。请保证“名称”+“语言”唯一。

      类别

      该错误码所属的分类。

      Http状态码

      Http协议状态码。

      语言

      请根据实际情况从下拉列表中选择语言类型。目前支持中文、英文、西班牙语、法语和缅甸语。

      单击“新增”支持创建多语言错误码。

      单击语言后的“?”显示:请在翻译工作台中添加支持的语言。单击“翻译工作台”可跳转至翻译工作台配置页面。

      格式

      错误码信息描述。在描述中,可以用{Number}表示变量名。例如 {0} 表示第一个输出变量,{1} 表示第二个输出变量,以此类推。

      长度不超过255个字节。

  2. 创建脚本。

    在脚本中调用抛出错误信息的context函数setI18nError('ErrorCodeName','变量1','变量2')。该函数中输入参数为错误码名称"t__testErrorCode"和错误码信息中所携带的变量("val1"和"val2")。
    // test custom error func , get diff language content by user lang
    import * as context from 'context';
    export class TestDemo {
        @action.method({ label: 'test', description: 'error code', input: 'No input', output: 'No output' })
        public test() {
            //使用setI18nError函数设定错误码和错误码信息携带变量
            context.setI18nError('t__testErrorCode', 'val1', 'val2');
        }
    }

  3. 按照如何定义API接口中的步骤绑定上述开发的脚本,进行测试,最终根据用户使用的语言返回相应语言的错误信息。

    图8 自定义错误信息测试

分享:

    相关文档

    相关产品

close