如何使用 OpenAPI

如何调用控制台 OpenAPI

  1. 在调用控制台 OpenAPI 前，需要用户在平台右上角，点击个人中心-访问令牌-新增，创建访问令牌用于授权
  2. 在调用控制台 OpenAPI 前，确保已获取 API 所需的访问令牌，并加入到请求 Header 中
  3. OpenAPI 文档中只展示相对路径，如 /openapi/v1/administrators，不展示实际请求路径。需要将你的控制台访问地址作为与路径拼凑起来，形成完整地址。如 http://192.168.2.225:7070/openapi/v1/administrators

OpenAPI 文档约定格式

控制台 OpenAPI 文档格式主要如下：

  1. 请求：
  2.     基本信息: 介绍 API 是干什么的
  3.     请求方法: 介绍 API 所需要的请求方法（POST、PUT、DELETE、GET等）
  4.     请求参数: API 所使用的路径参数和查询参数的简要说明
  5.     请求体: 这部分参数需要放在 HTTP 请求的 Body 中，一般为 JSON 格式
  6.     请求体示例: 对应 API 的成功请求参数的样例
  7. 响应：
  8.     响应体: 一次 API 调用后，HTTP 响应中 Body 部分的内容
  9.     响应体示例: API 成功请求结果的样例

OpenAPI 通用参数说明

以下参数是在调用平台时，经常会使用到的路径参数的说明。

名称位置类型中文名说明
team_idpathstring团队ID标识某一个团队的ID，32位字符串
app_idpathint应用ID标识某个应用，整型
service_idpathstring组件ID标识某一个组件的ID，32位字符串
region_namepathstring集群唯一标识标识某个集群的名称，在企业下唯一，用户自定义值
user_idpathint用户ID标识某一个用户的ID，整型

参数的获取以及接口示例

Rainbond主要分四个视图：企业视图、团队视图、应用视图、组件视图，因此 Openapi 文档也按照此逻辑进行组织。

下面介绍具体请求样例：

获取企业下团队列表

  1. curl -X GET 'http://192.168.2.225:7070/openapi/v1/teams' -H 'Authorization: <此处请填写从控制台获取的访问令牌>'

响应结果示例

此处的 tenant_id 即对应 team_id 的值

  1. {
  2.     "tenants":[
  3.         {
  4.             "ID":1,
  5.             "tenant_id":"8e5a07dd37e34dd7a2a74b0a2ab29d95",
  6.             "tenant_name":"o19p6wen",
  7.             "tenant_alias":"admin的团队",
  8.             "is_active":true,
  9.             "enterprise_id":"f246bce23170eeaac90d6f7b150793f0",
  10.             "create_time":"2022-06-01T13:52:13.321196",
  11.             "creater":"admin",
  12.             "role_infos":[
  13.                 {
  14.                     "role_id":"1",
  15.                     "role_name":"管理员"
  16.                 }
  17.             ]
  18.         }
  19.     ],
  20.     "total":1,
  21.     "page":1,
  22.     "page_size":10
  23. }

获取集群列表

  1. curl -X GET 'http://192.168.2.225:7070/openapi/v1/regions' -H 'Authorization: <此处请填写从控制台获取的访问令牌>'

响应结果示例

此处的 region_name 即对应集群唯一标识

  1. [
  2.     {
  3.         "region_id":"febc993cefe84d158b3ac245d7aa0943",
  4.         "region_name":"test",
  5.         "region_alias":"自建集群",
  6.         "url":"https://192.168.2.225:8443",
  7.         "status":"1",
  8.         "desc":"提供主机安装 Kubernetes 集群并对接",
  9.         "scope":"private",
  10.         "ssl_ca_cert":null,
  11.         "cert_file":null,
  12.         "key_file":null
  13.     }
  14. ]

获取应用列表

team_id 与 region_name 请填写上述两个接口获取到的响应值

  1. curl -X GET 'http://192.168.2.225:7070/openapi/v1/teams/{team_id}/regions/{region_name}/apps' -H 'Authorization: <此处请填写从控制台获取的访问令牌>'

响应结果示例

此处的 ID 即对应 app_id

  1. [
  2.     {
  3.         "ID":1,
  4.         "tenant_id":"8e5a07dd37e34dd7a2a74b0a2ab29d95",
  5.         "group_name":"测试应用",
  6.         "region_name":"test",
  7.         "is_default":true,
  8.         "order_index":0,
  9.         "note":"",
  10.         "username":"",
  11.         "governance_mode":"BUILD_IN_SERVICE_MESH",
  12.         "create_time":"2022-06-01T13:52:13.407637",
  13.         "update_time":"2022-06-15T15:37:51.020167",
  14.         "app_type":"rainbond",
  15.         "app_store_name":null,
  16.         "app_store_url":null,
  17.         "app_template_name":null,
  18.         "version":null,
  19.         "logo":"",
  20.         "k8s_app":"app-38b4d14a"
  21.     }
  22. ]

构建组件

根据以上接口请求示例，我们可以继续寻找到对应的 service_id ，从而对组件进行操作。此处以构建组件为例

  1. curl -X POST 'http://192.168.2.225:7070/openapi/v1/teams/{team_id}/regions/{region_name}/apps/{app_id}/services/{service_id}/build' -H 'Authorization: <此处请填写从控制台获取的访问令牌>'

响应结果示例

  1. {
  2.     "event_id": "5821167607ec460b89b326084fb3d1e0"
  3. }