{"id":21810136,"url":"https://github.com/yunionio/mcclient_java","last_synced_at":"2025-04-13T22:01:47.450Z","repository":{"id":34377795,"uuid":"154431814","full_name":"yunionio/mcclient_java","owner":"yunionio","description":"Java SDK for Cloudpods API","archived":false,"fork":false,"pushed_at":"2025-04-07T02:30:11.000Z","size":547,"stargazers_count":3,"open_issues_count":0,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T19:09:40.446Z","etag":null,"topics":["api","cloudpods","hybridcloud","java","multicloud","sdk"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yunionio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-10-24T03:15:39.000Z","updated_at":"2025-04-07T02:28:13.000Z","dependencies_parsed_at":"2023-01-15T06:41:00.685Z","dependency_job_id":"6c5648ad-0373-407e-8037-137c1e99d1d1","html_url":"https://github.com/yunionio/mcclient_java","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunionio%2Fmcclient_java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunionio%2Fmcclient_java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunionio%2Fmcclient_java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunionio%2Fmcclient_java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yunionio","download_url":"https://codeload.github.com/yunionio/mcclient_java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248788873,"owners_count":21161726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cloudpods","hybridcloud","java","multicloud","sdk"],"created_at":"2024-11-27T13:32:46.138Z","updated_at":"2025-04-13T22:01:47.409Z","avatar_url":"https://github.com/yunionio.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cloudpods Java SDK\n\nCloudpods Java SDK为访问多云平台API的Java SDK。实现了账号认证，获取认证token，并携带token，构造HTTP REST API访问各类资源接口的功能。\n\n- SDK 源码地址为: https://github.com/yunionio/mcclient_java\n- 做为 maven 模块使用请参考: https://central.sonatype.com/artifact/com.yunionyun.mcp/mcclient/overview\n\n## 1. 主要的类\n\n主要的类如下：\n\n* Client：API客户端\n* TokenCredential: 认证获得的token\n* Session：一个session\n* AuthAgent：一个长期运行的客户端Agent\n* 资源类，如ServerManager\n\n\n### 1.1 Client: 客户端实例\n\nClient类的主要方法如下：\n\n#### 1) Client构造函数\n\n```java\npublic Client(String authUrl, int timeout, boolean debug, boolean insecure)\n```\n\n参数说明如下：\n\n* authUrl(String): keystone服务的认证URL，通常为 https://\u003cmaster_ip\u003e:30500/v3，其中master_ip为Cloudpods部署实例的服务IP\n* timeout(int):  访问APIde的超时时间，一般设置为60（单位秒）\n* debug(boolean): 是否开启debug模式，开启后，会输出debug日志。初期方便排查问题，一般设置为true\n* insecure(boolean): 是否接受自签名的https证书，一般设置为true\n\n返回值：Client实例\n\n#### 2) Client.Authenticate\n\n认证接口，初始化Client之后，调用该接口认证，认证成功获得token（TokenCredential）。\n\n```java\npublic TokenCredential Authenticate(String user, String passwd, String domain, String project, String projectDomain)\n```\n\n参数说明如下：\n\n* user(String): 用户名，该参数必填\n* passwd(String): 用户密码，该参数必填\n* domain(String): 用户归属域，该参数可选，不指定，则为默认域（Default域）\n* project(String): 用户归属项目，该参数必填。用户加入项目需要指定角色。用户认证后，将具备该用户在该项目的角色具有的权限。\n* projectDomain(String): 该参数可选，如果不指定，则为默认域（Default域）\n\n\n#### 3) Client.newSession\n\n初始化Client并认证成功后，通过 client.newSession 获得访问API的session实例，用于后续访问服务接口的凭证。\n\n```java\npublic Session newSession(\n\t\t\tString region,\n\t\t\tString zone,\n\t\t\tEndpointType endpointType,\n\t\t\tTokenCredential token)\n```\n\n参数说明如下：\n\n* region(String): 访问的Cloudpods实例的region，一般为\"region0\"\n* zone(String): 访问的可用区，该参数可选。一般为null\n* endpointType(String): 访问服务端点的类型，可选值为：internal和public。一般要选择public。只有客户端在部署Cloudpods的Kubernetes集群里运行时，才可以使用internal。\n* token(TokenCredential): 调用client.Authenticate认证获得的token，该值必填\n\n返回值：返回一个session，该session包含了token以及环境变量，用于访问各类资源的接口。\n\n### 1.2 AuthAgent: 一个验证token的服务Agent实例\n\nAuthAgent提供了一个长期运行的具有管理员权限的Agent实例，用于验证token，并且也能提供具有admin权限的session，访问资源的API。AuthAgent的主要方法有：\n\n#### 1) AuthAgent构造函数\n\n```java\npublic AuthAgent(\n\t\t\tString authUrl,\n\t\t\tString domain,\n\t\t\tString user,\n\t\t\tString passwd,\n\t\t\tString project,\n\t\t\tString projectDomain,\n\t\t\tint cacheSize,\n\t\t\tint timeout,\n\t\t\tboolean debug,\n\t\t\tboolean insecure)\n```\n\n输入参数：\n\n* authUrl(String): keystone服务的认证URL，通常为 https://\u003cmaster_ip\u003e:30500/v3，其中master_ip为Cloudpods部署实例的服务IP\n* user(String): 用户名，该参数必填\n* passwd(String): 用户密码，该参数必填\n* domain(String): 用户归属域，该参数可选，不指定，则为默认域（Default域）\n* project(String): 用户归属项目，该参数必填。用户加入项目需要指定角色。用户认证后，将具备该用户在该项目的角色具有的权限。\n* projectDomain(String): 该参数可选，如果不指定，则为默认域（Default域）\n* cacheSize(int): 认证token的缓存大小（token的个数），一般1024。AuthAgent将用于验证用户的token，认证后将被缓存。\n* timeout(int):  访问APIde的超时时间，一般设置为60（单位秒）\n* debug(boolean): 是否开启debug模式，开启后，会输出debug日志。初期方便排查问题，一般设置为true\n* insecure(boolean): 是否接受自签名的https证书，一般设置为true\n\n#### 2) AuthAgent.start\n\n```java\npublic void start()\npublic void start_sync_ready()\n```\n\n初始化AuthAgent之后，启动AuthAgent。启动后，调用start()方法，AuthAgent将会自动向keystone认证，获得一个adminToken，之后周期性地向keystone认证，刷新adminToken。 start()方法是异步启动认证流程，而start_sync_read()方法是同步启动认证流程。\n\n#### 3) AuthAgent.getAdminSession\n\n该方法返回AuthAgent保存的adminToken生成的session，用于访问API。\n\n```java\npublic Session getAdminSession(String region, String zone, EndpointType endpointType)\n```\n\n参数说明如下：\n\n* region(String): 访问的Cloudpods实例的region，一般为\"region0\"\n* zone(String): 访问的可用区，该参数可选。一般为null\n* endpointType(EndpointType): 访问服务端点的类型，可选值为：EndpointType.InternalURL和EndpointType.PublicURL。一般需要选择public。只有客户端在部署Cloudpods的Kubernetes集群里运行时，才可以使用internal。\n\n#### 4) AuthAgent.verify\n\n该方法校验token字符串，并返回一个TokenCredential对象\n\n```java\npublic TokenCredential verify(String token)\n```\n\n### 1.3 资源类\n\n每种云资源都有对应的类，通过这些类的方法实现对该资源的API的访问，这些类基本都实现了如下的方法：\n\n#### 1) List\n\n列出资源，对应`GET /\u003cresources\u003e`的REST API。\n\n```java\npublic ListResult List(Session s, JSONObject query, ManagerContext[] ctx)\npublic ListResult List(Session s, JSONObject query, ManagerContext ctx)\npublic ListResult List(Session s, JSONObject query)\n```\n\n输入参数说明如下：\n* s(Session): Session实例\n* query(JSONObject): 请求URL的query String对应的key: value\n* ctx: 请求上下文，每一个ctx对应URL路径的一个`/\u003cresources\u003e/\u003cres_id\u003e`\n\n输出参数为：ListResult，用于存储列表结果\n\n#### 2) Get\n\n获取单个资源的详情，对应`GET /\u003cresources\u003e/\u003cres_id\u003e`的REST API。\n\n```java\npublic JSONObject Get(Session s, String id, JSONObject query, ManagerContext[] ctx)\npublic JSONObject Get(Session s, String id, JSONObject query, ManagerContext ctx)\npublic JSONObject Get(Session s, String id, JSONObject query)\npublic JSONObject GetById(Session s, String id, JSONObject query, ManagerContext[] ctx)\npublic JSONObject GetById(Session s, String id, JSONObject query, ManagerContext ctx)\npublic JSONObject GetById(Session s, String id, JSONObject query)\npublic JSONObject GetByName(Session s, String name, JSONObject query, ManagerContext[] ctx)\npublic JSONObject GetByName(Session s, String name, JSONObject query, ManagerContext ctx)\npublic JSONObject GetByName(Session s, String name, JSONObject query)\n```\n\n输入参数说明如下：\n* s(Session): Session实例\n* id(String): 资源的ID\n* query(JSONObject)：请求的REST API URL的query string\n* ctx: 请求上下文，每一个ctx对应URL路径的一个`/\u003cresources\u003e/\u003cres_id\u003e`\n\n输出参数为：JSONObject，存储了一个资源的信息\n\n#### 3) Get Specific Attribute\n\n获取某个资源的特性属性的值，对应`GET /\u003cresources\u003e/\u003cres_id\u003e/\u003cattribute\u003e`的REST API。\n\n```java\npublic JSONObject GetSpecific(Session s, String id, String spec, JSONObject query, ManagerContext[] ctx)\npublic JSONObject GetSpecific(Session s, String id, String spec, JSONObject query, ManagerContext ctx)\npublic JSONObject GetSpecific(Session s, String id, String spec, JSONObject query)\n```\n输入参数说明如下：\n* s(Session): Session实例\n* id(String): 资源的ID\n* spec(String): 属性的名称\n* query(JSONObject)：请求的REST API URL的query string\n* ctx: 请求上下文，每一个ctx对应URL路径的一个`/\u003cresources\u003e/\u003cres_id\u003e`\n\n输出参数为：JSONObject，存储了一个该资源对应属性的信息\n\n#### 4) Create\n\n新建一个资源，对应`POST /\u003cresources\u003e`的REST API。\n\n```java\npublic JSONObject Create(Session s, JSONObject params, ManagerContext[] ctx)\npublic JSONObject Create(Session s, JSONObject params, ManagerContext ctx)\npublic JSONObject Create(Session s, JSONObject params)\n```\n\n输入参数说明如下：\n* s(Session): Session实例\n* params(JSONObject)：请求的REST API URL的body存储的JSONObject\n* ctx: 请求上下文，每一个ctx对应URL路径的一个`/\u003cresources\u003e/\u003cres_id\u003e`\n\n输出参数为：JSONObject，存储了一个新建资源的信息\n\n#### 5) PerformAction\n\n对某个资源执行特定的操作，对应`POST /\u003cresources\u003e/\u003cres_id\u003e/\u003caction\u003e`的REST API。\n\n```java\npublic JSONObject PerformAction(Session s, String id, String action, JSONObject params, ManagerContext[] ctx)\npublic JSONObject PerformAction(Session s, String id, String action, JSONObject params, ManagerContext ctx)\npublic JSONObject PerformAction(Session s, String id, String action, JSONObject params)\n```\n\n输入参数说明如下：\n* s(Session): Session实例\n* id(String): 资源的ID\n* action(String): 属性的名称\n* params(JSONObject)：请求的REST API的body存储的JSONObject\n* ctx: 请求上下文，每一个ctx对应URL路径的一个`/\u003cresources\u003e/\u003cres_id\u003e`\n\n输出参数为：JSONObject，存储了执行操作结果的信息\n\n\n#### 6) Update\n\n更新指定资源的信息，对应`PUT /\u003cresources\u003e/\u003cres_id\u003e`的REST API。\n\n```java\npublic JSONObject Update(Session s, String id, JSONObject params, ManagerContext[] ctx)\npublic JSONObject Update(Session s, String id, JSONObject params, ManagerContext ctx)\npublic JSONObject Update(Session s, String id, JSONObject params)\n```\n\n输入参数说明如下：\n* s(Session): Session实例\n* id(String): 资源的ID\n* params(JSONObject)：请求的REST API的body存储的JSONObject\n* ctx: 请求上下文，每一个ctx对应URL路径的一个`/\u003cresources\u003e/\u003cres_id\u003e`\n\n输出参数为：JSONObject，存储了更新操作结果的信息\n\n#### 7) Delete\n\n删除指定资源，对应`DELETE /\u003cresources\u003e/\u003cres_id\u003e`的REST API。\n\n```java\npublic JSONObject Delete(Session s, String id, ManagerContext[] ctx)\npublic JSONObject Delete(Session s, String id, ManagerContext[] ctx, JSONObject query)\npublic JSONObject Delete(Session s, String id, ManagerContext ctx)\npublic JSONObject Delete(Session s, String id)\n```\n\n输入参数说明如下：\n* s(Session): Session实例\n* id(String): 资源的ID\n* ctx: 请求上下文，每一个ctx对应URL路径的一个`/\u003cresources\u003e/\u003cres_id\u003e`\n* query(JSONObject)：请求的REST API URL的query string\n\n输出参数为：JSONObject，存储了删除操作结果的信息\n\n## 2. SDK使用流程\n\n### 2.1 仅作为客户端使用\n\n这时候只需要初始化Client\n\n```java\n    client = new Client(...) // 具体参数参见代码\n    s = client.newSession(...)\n    ServerManager mgr = new ServerManager()\n    ListResult result = mgr.List(s, null)\n\n    .... // use other manager\n```\n\n\n### 2.2 作为服务的验证token的一个服务\n\n这时候需要初始化Agent。注意Agent会启动一个定时任务，定时更新adminToken。验证用户token需要使用adminToken。\n\n```java\n    agent = new AuthAgent(...) // 具体参数参见代码\n    agent.start()\n    ...\n    // token is hidden in http \"X-Auth-Token\" header\n    user_cred = agent.verify(token)\n    if (user_cred != null) {\n        // pass verification, user user_cred to obtain user's information\n    } else {\n        // verify failed\n    }\n```\n\n\n## 测试\n\n测试环境变量存储在 /opt/test_conf.properties\n\n在测试代码中，通过 Env.get(key) 获得\n\n```\n# sample test_conf.properties\nauthUrl=https://192.168.2.11:30500/v3\nusername=test\npassword=passwd0\ndomain=Default\nproject=system\nprojectDomain=Default\nregion=region0\n```\n\n启动测试：\n\n```\nmvn test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyunionio%2Fmcclient_java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyunionio%2Fmcclient_java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyunionio%2Fmcclient_java/lists"}