如何使用 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 所需要的请求方法(POSTPUTDELETEGET等)
  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_idregion_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. }