CloudStack常用API

最新推荐文章于 2024-09-01 15:24:59 发布

dandanfengyun

最新推荐文章于 2024-09-01 15:24:59 发布

阅读量783

点赞数

分类专栏：云计算 CloudStack CentOS 文章标签：云计算

本文链接：https://blog.youkuaiyun.com/dandanfengyun/article/details/107506781

版权

云计算同时被 3 个专栏收录

37 篇文章

订阅专栏

CentOS

23 篇文章

订阅专栏

CloudStack

22 篇文章

订阅专栏

本文详细介绍了CloudStack的API使用，包括URL解析、常用API命令如查看虚拟实例、查询公共IP、异步命令状态查看等，并提供了命令字符串示例及返回结果解析。同时，讨论了API调用失败时的错误响应。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

API URL解析

所有CloudStack API请求都以HTTPGET/POST的形式提交，并带有相关的命令和任何参数。CloudStack API 可以看做是一个HTTP请求

http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

1. http://localhost:8080/client/api
2. ?command=deployVirtualMachine
3. &serviceOfferingId=1
4. &diskOfferingId=1
5. &templateId=2
6. &zoneId=4
7. &apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
8. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

1		CloudStack API URL。希望与之交互的云实例
2		待执行的命令 与API URL 之间 使用 ？ 隔开分离
3-6 	待执行命令的参数 不同段值对（field=value）前面有一个符号字符&
7		唯一标识帐户的用户API KEY
8		为验证执行API命令的用户帐户而创建的签名散列。

分解该 URL

基础URL： CloudStack管理服务器基本URL 加上处理传入请求的APIservlet的路径

http://localhost:8080/client/api?

命令字符串：查询字符串由命令、命令参数和标识帐户的API KEY组成

command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ

&field=value
段值对（field=value） field 不区分大小写，但是value区分大小写

签名：使用用户 Secret Key 和HMAC SHA-1散列算法组合生成的命令字符串的签名

&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

## Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D散列签名
## 注，改签名生成后是要经过URL编码。
## 大致是将+=/等转换为%2B %3D %2F等

CloudStack API经分解后，可知最重要的是命令字符串，以及经命令字符串生成的用户认证签名散列

命令字符串由段值对（field=value）构成，不同段值对之间使用&分隔

命令字符串中包含了三类数据命令、命令参数和标识帐户的API KEY组成

一		command=???					# 命令
二		参数名=参数值				# 命令所需参数与参数传入值
三		apiKey=标识账户的API KEY		# 用户API KEY

常用API命令与参数和返回值

一、查看虚拟实例信息 listVirtualMachines

命令字符串

field	value值描述	是否必需
command	命令(listVirtualMachines)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
id	虚拟实例ID ID是唯一的	false
name	虚拟实例名称，名称也是惟一的但是可以输入模糊值	false
state	虚拟实例状态（Running, Stopped, Present, Destroyed, Expunged）	false
serviceofferingid	服务方案ID（计算方案）	false
hostid	宿主机id	false

命令字符串示例

command=listVirtualMachines&response=json&apiKey=9Ssb1m64hHRc9A4XQFsghUBuB1fsz_PJ2wHeHEjQARWtFA_pMu_Trhd7Vyy023OONVYLv0UrZY9EfihDwx-b4A

较重要返回结果

虚拟实例相关

Response Name	Description
id	虚拟实例ID
name	虚拟实例名称
account	与虚拟实例关联的用户
created	创建时间
state	运行状态
hostname	宿主机名称
templateid	使用模板ID
templatename	使用模板名
serviceofferingid	服务方案ID
serviceofferingname	服务方案名
serviceofferingname	服务方案名
securitygroup	安全组
nic	虚拟实例网络相关

虚拟实例nic网络相关

Response Name	Description
id	nicID
gateway	网关
netmask	子网掩码
ipaddress	IPV4地址
ip6address	IPV6地址

数据示例如下

{
    "listvirtualmachinesresponse": {
        "count": 1,	
        "virtualmachine": [
            {
                "id": "1a9a8606-921e-489b-9d27-6e22d4400b0b",
                "name": "CentOS7Test",
                "displayname": "CentOS7Test",
                "account": "admin",
                "userid": "d86f1bf0-ca2b-11ea-abc8-000c29972b82",
                "username": "admin",
                "domainid": "ab8efe85-ca2b-11ea-abc8-000c29972b82",
                "domain": "ROOT",
                "created": "2020-07-23T10:12:21+0800",
                "state": "Running",
                "haenable": false,
                "groupid": "dcf670db-5001-459f-bf9a-6b8f1b7628fd",
                "group": "test",
                "zoneid": "2d372d51-fca5-409a-a98c-d09edb943138",
                "zonename": "Zone1",
                "hostid": "b9c1e868-81bf-4f2c-a28d-8876dafef3d1",
                "hostname": "agent",
                "templateid": "e3d7f9f9-6209-4f28-a16b-f48d544c44e6",
                "templatename": "CentOS6MiniModel",
                "templatedisplaytext": "CentOS6MinimalModel",
                "passwordenabled": false,
                "serviceofferingid": "bebcf7d6-b8e3-454c-b600-d2b2b3c50b4f",
                "serviceofferingname": "Medium Instance",
                "cpunumber": 1,
                "cpuspeed": 1000,
                "memory": 1024,
                "cpuused": "6.12%",
                "networkkbsread": 13,
                "networkkbswrite": 0,
                "diskkbsread": 45553,
                "diskkbswrite": 1365,
                "memorykbs": 1048576,
                "memoryintfreekbs": 524288,
                "memorytargetkbs": 524288,
                "diskioread": 1931,
                "diskiowrite": 258,
                "guestosid": "c583de96-ca2b-11ea-abc8-000c29972b82",
                "rootdeviceid": 0,
                "rootdevicetype": "ROOT",
                "securitygroup": [
                    {
                        "id": "d86f5621-ca2b-11ea-abc8-000c29972b82",
                        "name": "default",
                        "description": "Default Security Group",
                        "account": "admin",
                        "ingressrule": [],
                        "egressrule": [],
                        "tags": [],
                        "virtualmachineids": []
                    }
                ],
                "nic": [
                    {
                        "id": "945db421-96c5-4d40-9037-6064bebcf145",
                        "networkid": "7f9883ab-d15d-45b1-a9c1-0aa9c1f7f230",
                        "networkname": "defaultGuestNetwork",
                        "netmask": "255.255.255.0",
                        "gateway": "192.168.199.1",
                        "ipaddress": "192.168.199.47",
                        "broadcasturi": "vlan://untagged",
                        "traffictype": "Guest",
                        "type": "Shared",
                        "isdefault": true,
                        "macaddress": "1e:00:b7:00:00:1c",
                        "secondaryip": [],
                        "extradhcpoption": []
                    }
                ],
                "hypervisor": "KVM",
                "instancename": "i-2-8-VM",
                "details": {
                    "keyboard": "us",
                    "memoryOvercommitRatio": "2.0",
                    "Message.ReservedCapacityFreed.Flag": "false",
                    "cpuOvercommitRatio": "2.0"
                },
                "affinitygroup": [],
                "displayvm": true,
                "isdynamicallyscalable": false,
                "ostypeid": "c583de96-ca2b-11ea-abc8-000c29972b82",
                "tags": []
            }
        ]
    }
}

二、查询可用公共IP地址

命令字符串

field	value值描述	是否必需
command	命令(listPublicIpAddresses)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
allocatedonly	只返回已经分配的IP	false
forvirtualnetwork	展示虚拟网络IP（高级网络部署时虚拟network）,基础网路设置时参数值设置为false	false
ipaddress	指定ipaddress的信息	false
state	返回指定状态的IP，Free或者Allocated	false
id	IP地址的ID	false

命令字符串示例

command=listPublicIpAddresses&response=json&forvirtualnetwork=false&allocatedonly=false&stats=Free&apiKey=9Ssb1m64hHRc9A4XQFsghUBuB1fsz_PJ2wHeHEjQARWtFA_pMu_Trhd7Vyy023OONVYLv0UrZY9EfihDwx-b4A

较重要返回结果

Response Name	Description
ipaddress	IP地址
id	公共IP的id
allocated	IP被分配时间，只有IP已被分配才有该字段
state	IP状态可能是Allocated或Free
issystem	是否是系统IP（基本不可能是true），被系统VM绑定和是system IP是两回事
networkid	网络Id

数据示例

{
    "listpublicipaddressesresponse": {
        "count": 40,
        "publicipaddress": [
            {
                "id": "4ce8e8d7-800d-404b-a3fa-755201c8477e",
                "ipaddress": "192.168.199.79",
                "zoneid": "2d372d51-fca5-409a-a98c-d09edb943138",
                "zonename": "Zone1",
                "issourcenat": false,
                "forvirtualnetwork": false,
                "vlanid": "c856f28a-2609-456b-b749-fdd15b1cff9a",
                "vlanname": "vlan://untagged",
                "isstaticnat": false,
                "issystem": false,
                "networkid": "7f9883ab-d15d-45b1-a9c1-0aa9c1f7f230",
                "state": "Free",
                "physicalnetworkid": "70d9da42-f6d4-4e0c-a259-b3c76d9ddb1b",
                "tags": [],
                "isportable": false,
                "fordisplay": true
            },
            {
                "id": "f1d72c88-52d8-4ed9-ae1a-94cc732f503f",
                "ipaddress": "192.168.199.78",
                "zoneid": "2d372d51-fca5-409a-a98c-d09edb943138",
                "zonename": "Zone1",
                "issourcenat": false,
                "forvirtualnetwork": false,
                "vlanid": "c856f28a-2609-456b-b749-fdd15b1cff9a",
                "vlanname": "vlan://untagged",
                "isstaticnat": false,
                "issystem": false,
                "networkid": "7f9883ab-d15d-45b1-a9c1-0aa9c1f7f230",
                "state": "Free",
                "physicalnetworkid": "70d9da42-f6d4-4e0c-a259-b3c76d9ddb1b",
                "tags": [],
                "isportable": false,
                "fordisplay": true
            },
            ......
          ]
    }
}

三、异步命令状态查看 queryAsyncJobResult

CloudStack API调用返回除查询命令结果是同步返回结果的，其他的API基本都是耗时操作异步命令，会返回异步任务的jobid 根据该jobid查询异步任务完成状态。

命令字符串

field	value值描述	是否必需
command	命令(queryAsyncJobResult)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
jobid	异步任务的ID	true

命令字符串示例

command=queryAsyncJobResult&response=json&jobid=1&apiKey=9Ssb1m64hHRc9A4XQFsghUBuB1fsz_PJ2wHeHEjQARWtFA_pMu_Trhd7Vyy023OONVYLv0UrZY9EfihDwx-b4A

较重要返回结果

Response Name	Description
jobid	任务id
jobstatus	任务状态 0表示仍在进行 1表示任务执行成功 2表示任务执行失败
jobresult	任务成功或任务失败后返回的结果信息
accountid	执行任务的账户
cmd	异步任务命令
created	任务创建时间
completed	任务结束时间
jobresultcode	任务结果的状态码

有三种可能的返回结果数据示例

任务仍在进行示例停止实例进行中

{
    "queryasyncjobresultresponse": {
        "accountid": "d86f10de-ca2b-11ea-abc8-000c29972b82",
        "userid": "d86f1bf0-ca2b-11ea-abc8-000c29972b82",
        "cmd": "org.apache.cloudstack.api.command.admin.vm.StopVMCmdByAdmin",
        "jobstatus": 0,
        "jobprocstatus": 0,
        "jobresultcode": 0,
        "jobinstancetype": "VirtualMachine",
        "jobinstanceid": "1a9a8606-921e-489b-9d27-6e22d4400b0b",
        "created": "2020-07-23T13:06:02+0800",
        "jobid": "7b57691c-0998-41d6-bfb1-9ba0fd20fcb8"
    }
}

任务执行成功示例启动实例成功

{
    "queryasyncjobresultresponse": {
        "accountid": "d86f10de-ca2b-11ea-abc8-000c29972b82",
        "userid": "d86f1bf0-ca2b-11ea-abc8-000c29972b82",
        "cmd": "org.apache.cloudstack.api.command.admin.vm.StartVMCmdByAdmin",
        "jobstatus": 1,
        "jobprocstatus": 0,
        "jobresultcode": 0,
        "jobresulttype": "object",
        "jobresult": {
            "virtualmachine": {
                "id": "1a9a8606-921e-489b-9d27-6e22d4400b0b",
                "name": "CentOS7Test",
                "displayname": "CentOS7Test",
                "account": "admin",
                "userid": "d86f1bf0-ca2b-11ea-abc8-000c29972b82",
                "username": "admin",
                "domainid": "ab8efe85-ca2b-11ea-abc8-000c29972b82",
                "domain": "ROOT",
                "created": "2020-07-23T10:12:21+0800",
                "state": "Running",
                "haenable": false,
                "groupid": "dcf670db-5001-459f-bf9a-6b8f1b7628fd",
                "group": "test",
                "zoneid": "2d372d51-fca5-409a-a98c-d09edb943138",
                "zonename": "Zone1",
                "hostid": "b9c1e868-81bf-4f2c-a28d-8876dafef3d1",
                "hostname": "agent",
                "templateid": "e3d7f9f9-6209-4f28-a16b-f48d544c44e6",
                "templatename": "CentOS6MiniModel",
                "templatedisplaytext": "CentOS6MinimalModel",
                "passwordenabled": false,
                "serviceofferingid": "bebcf7d6-b8e3-454c-b600-d2b2b3c50b4f",
                "serviceofferingname": "Medium Instance",
                "cpunumber": 1,
                "cpuspeed": 1000,
                "memory": 1024,
                "cpuused": "6.23%",
                "networkkbsread": 13,
                "networkkbswrite": 0,
                "diskkbsread": 46177,
                "diskkbswrite": 4081,
                "memorykbs": 1048576,
                "memoryintfreekbs": 524288,
                "memorytargetkbs": 524288,
                "diskioread": 1987,
                "diskiowrite": 852,
                "guestosid": "c583de96-ca2b-11ea-abc8-000c29972b82",
                "rootdeviceid": 0,
                "rootdevicetype": "ROOT",
                "securitygroup": [
                    {
                        "id": "d86f5621-ca2b-11ea-abc8-000c29972b82",
                        "name": "default",
                        "description": "Default Security Group",
                        "account": "admin",
                        "ingressrule": [],
                        "egressrule": [],
                        "tags": [],
                        "virtualmachineids": []
                    }
                ],
                "nic": [
                    {
                        "id": "945db421-96c5-4d40-9037-6064bebcf145",
                        "networkid": "7f9883ab-d15d-45b1-a9c1-0aa9c1f7f230",
                        "networkname": "defaultGuestNetwork",
                        "netmask": "255.255.255.0",
                        "gateway": "192.168.199.1",
                        "ipaddress": "192.168.199.47",
                        "broadcasturi": "vlan://untagged",
                        "traffictype": "Guest",
                        "type": "Shared",
                        "isdefault": true,
                        "macaddress": "1e:00:b7:00:00:1c",
                        "secondaryip": [],
                        "extradhcpoption": []
                    }
                ],
                "hypervisor": "KVM",
                "instancename": "i-2-8-VM",
                "details": {
                    "keyboard": "us",
                    "memoryOvercommitRatio": "2.0",
                    "Message.ReservedCapacityFreed.Flag": "false",
                    "cpuOvercommitRatio": "2.0"
                },
                "affinitygroup": [],
                "displayvm": true,
                "isdynamicallyscalable": false,
                "ostypeid": "c583de96-ca2b-11ea-abc8-000c29972b82",
                "tags": [],
                "jobid": "b1e37efd-ce82-4869-8c94-7e9d21f555ce",
                "jobstatus": 0
            }
        },
        "jobinstancetype": "VirtualMachine",
        "jobinstanceid": "1a9a8606-921e-489b-9d27-6e22d4400b0b",
        "created": "2020-07-23T13:23:20+0800",
        "completed": "2020-07-23T13:26:20+0800",
        "jobid": "b1e37efd-ce82-4869-8c94-7e9d21f555ce"
    }
}

任务执行失败示例创建新实例失败

{
    "queryasyncjobresultresponse": {
        "accountid": "d86f10de-ca2b-11ea-abc8-000c29972b82",
        "userid": "d86f1bf0-ca2b-11ea-abc8-000c29972b82",
        "cmd": "org.apache.cloudstack.api.command.admin.vm.DeployVMCmdByAdmin",
        "jobstatus": 2,
        "jobprocstatus": 0,
        "jobresultcode": 530,
        "jobresulttype": "object",
        "jobresult": {
            "errorcode": 533,
            "errortext": "Unable to create a deployment for VM[User|i-2-10-VM]"
        },
        "jobinstancetype": "VirtualMachine",
        "jobinstanceid": "ac9d1b0c-f2a1-49fb-9fb8-d87b371018b6",
        "created": "2020-07-23T13:19:27+0800",
        "completed": "2020-07-23T13:19:28+0800",
        "jobid": "ffbccf6f-2fba-42e3-899a-491d0c131423"
    }
}

四、创建虚拟实例 deployVirtualMachine

异步命令
命令字符串

field	value值描述	是否必需
command	命令(deployVirtualMachine)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
serviceofferingid	服务方案id（计算方案）	true
templateid	模板id	true
zoneid	资源域id	true
name	虚拟实例名称	false
ipaddress	IPv4 公共IP	false
hostid	宿主机id	false

命令字符串示例

command=deployVirtualMachine&response=json&serviceofferingid=8dc2f63f-eab1-4fb8-b070-c73ca4aa93f8&templateid=9f3741df-8bd5-4b4b-8f24-36fcbc0f72b7&zoneid=16c8ac5d-84a7-4070-adec-5a0aaa17a686&name=CentOS7Test1&ipaddress=192.168.199.51&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果

Response Name	Description
id	创建的资源ID（如实例，模板，NIC等资源时会返回资源id）
jobid	异步任务id

数据示例

{
    "deployvirtualmachineresponse": {
        "id": "f3269f7d-ea10-494d-bc1d-a460baf89ca7",
        "jobid": "993f113e-231d-40ea-ad04-a5af01b4611c"
    }
}

具体异步任务执行结果使用queryAsyncJobResult根据jobid查询

五、启动虚拟实例 startVirtualMachine

异步命令

命令字符串

field	value值描述	是否必需
command	命令(startVirtualMachine)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
id	虚拟实例的id	true
hostid	宿主机id	false
clusterid	集群id	false
podid	提供点id	false

命令字符串示例

command=startVirtualMachine&response=json&id=f3269f7d-ea10-494d-bc1d-a460baf89ca7&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果

Response Name	Description
jobid	异步任务id

数据示例

{
    "startvirtualmachineresponse": {
        "jobid": "979f5288-7237-4bda-a9f6-24e9325ce89c"
    }
}

具体异步任务执行结果使用queryAsyncJobResult根据jobid查询

六、停止虚拟实例 stopVirtualMachine

异步命令

命令字符串

field	value值描述	是否必需
command	命令(stopVirtualMachine)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
id	虚拟实例的id	true
forced	为true表示强制停止虚拟实例（即使命令执行失败也会标记虚拟实例已停止，否则就强制虚拟实例关机），默认是false	false

命令字符串示例

command=stopVirtualMachine&response=json&id=f3269f7d-ea10-494d-bc1d-a460baf89ca7&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果

Response Name	Description
jobid	异步任务id

数据示例

{
    "stopvirtualmachineresponse": {
        "jobid": "81034134-3421-4e91-838e-45105d6b9a3b"
    }
}

具体异步任务执行结果使用queryAsyncJobResult根据jobid查询

七、重启虚拟实例 rebootVirtualMachine

异步命令需要虚拟实例状态为 Running才可执行成功。

命令字符串

field	value值描述	是否必需
command	命令(rebootVirtualMachine)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
id	虚拟实例的id	true

命令字符串示例

command=rebootVirtualMachine&response=json&id=f3269f7d-ea10-494d-bc1d-a460baf89ca7&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果

Response Name	Description
jobid	异步任务id

数据示例

{
    "rebootvirtualmachineresponse": {
        "jobid": "9e87a356-024c-4f14-8b91-d1e9f38271da"
    }
}

具体异步任务执行结果使用queryAsyncJobResult根据jobid查询

八、销毁虚拟实例 destroyVirtualMachine

异步命令

命令字符串

field	value值描述	是否必需
command	命令(destroyVirtualMachine)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
id	虚拟实例的id	true
expunge	如果设置为true，销毁实例同时会删除该实例。默认为false	false

命令字符串示例

command=destroyVirtualMachine&response=json&id=f3269f7d-ea10-494d-bc1d-a460baf89ca7&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果

Response Name	Description
jobid	异步任务id

数据示例

{
    "destroyvirtualmachineresponse": {
        "jobid": "8edc6b9d-ab3e-40c8-a643-9f0ea36ca723"
    }
}

具体异步任务执行结果使用queryAsyncJobResult根据jobid查询

九、恢复虚拟示例 recoverVirtualMachine

同步命令只有虚拟实例状态为Destroyed才可执行。竟然是同步命令。

命令字符串

field	value值描述	是否必需
command	命令(recoverVirtualMachine)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
id	虚拟实例的id	true

命令字符串示例

command=recoverVirtualMachine&response=json&id=f3269f7d-ea10-494d-bc1d-a460baf89ca7&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果虚拟实例信息

虚拟实例相关

Response Name	Description
id	虚拟实例ID
name	虚拟实例名称
account	与虚拟实例关联的用户
created	创建时间
state	运行状态
hostname	宿主机名称
templateid	使用模板ID
templatename	使用模板名
serviceofferingid	服务方案ID
serviceofferingname	服务方案名
serviceofferingname	服务方案名
securitygroup	安全组
nic	虚拟实例网络相关

虚拟实例nic网络相关

Response Name	Description
id	nicID
gateway	网关
netmask	子网掩码
ipaddress	IPV4地址
ip6address	IPV6地址

数据示例

{
    "recovervirtualmachineresponse": {
        "virtualmachine": {
            "id": "f3269f7d-ea10-494d-bc1d-a460baf89ca7",
            "name": "CentOS7Test1",
            "displayname": "CentOS7Test1",
            "account": "admin",
            "userid": "4ba56941-ca2c-11ea-abc8-000c29972b82",
            "username": "admin",
            "domainid": "cd4d1b50-ca2b-11ea-abc8-000c29972b82",
            "domain": "ROOT",
            "created": "2020-07-20T12:09:24+0800",
            "state": "Stopped",
            "haenable": false,
            "zoneid": "16c8ac5d-84a7-4070-adec-5a0aaa17a686",
            "zonename": "Zone1",
            "templateid": "9f3741df-8bd5-4b4b-8f24-36fcbc0f72b7",
            "templatename": "CentOS7MiniModel",
            "templatedisplaytext": "CentOS7 Minimal Model",
            "passwordenabled": false,
            "serviceofferingid": "8dc2f63f-eab1-4fb8-b070-c73ca4aa93f8",
            "serviceofferingname": "Medium Instance",
            "cpunumber": 1,
            "cpuspeed": 1000,
            "memory": 1024,
            "cpuused": "0.36%",
            "networkkbsread": 44,
            "networkkbswrite": 18,
            "diskkbsread": 155059,
            "diskkbswrite": 10883,
            "memorykbs": 1048576,
            "memoryintfreekbs": 1048576,
            "memorytargetkbs": 1048576,
            "diskioread": 7328,
            "diskiowrite": 2229,
            "guestosid": "39ed4a30-ca2c-11ea-abc8-000c29972b82",
            "rootdeviceid": 0,
            "rootdevicetype": "ROOT",
            "securitygroup": [
                {
                    "id": "4ba59dcc-ca2c-11ea-abc8-000c29972b82",
                    "name": "default",
                    "description": "Default Security Group",
                    "account": "admin",
                    "ingressrule": [],
                    "egressrule": [],
                    "tags": [],
                    "virtualmachineids": []
                }
            ],
            "nic": [
                {
                    "id": "eb4daa0f-54f2-4470-b398-4d228f8ae898",
                    "networkid": "fdc3685e-e6f6-4e21-bd92-3e888cf0cf3e",
                    "networkname": "defaultGuestNetwork",
                    "netmask": "255.255.255.0",
                    "gateway": "192.168.199.1",
                    "ipaddress": "192.168.199.51",
                    "broadcasturi": "vlan://untagged",
                    "traffictype": "Guest",
                    "type": "Shared",
                    "isdefault": true,
                    "macaddress": "02:00:4f:f0:00:01",
                    "secondaryip": [],
                    "extradhcpoption": []
                }
            ],
            "hypervisor": "KVM",
            "instancename": "i-2-11-VM",
            "details": {
                "keyboard": "us",
                "memoryOvercommitRatio": "2.0",
                "Message.ReservedCapacityFreed.Flag": "false",
                "cpuOvercommitRatio": "2.0"
            },
            "affinitygroup": [],
            "displayvm": true,
            "isdynamicallyscalable": false,
            "ostypeid": "39ed4a30-ca2c-11ea-abc8-000c29972b82",
            "tags": []
        }
    }
}

十、删除虚拟实例 expungeVirtualMachine

异步命令只有虚拟实例状态为Destroyed才可执行

命令字符串

field	value值描述	是否必需
command	命令(expungeVirtualMachine)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
id	虚拟实例的id	true

命令字符串示例

command=expungeVirtualMachine&response=json&id=f3269f7d-ea10-494d-bc1d-a460baf89ca7&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果

Response Name	Description
jobid	异步任务id

数据示例

{
    "expungevirtualmachineresponse": {
        "jobid": "da2f1706-4a5d-49d6-96fa-d9c7ebbf0d4d"
    }
}

具体异步任务执行结果使用queryAsyncJobResult根据jobid查询
不过该异步任务的返回json较为特殊

{
    "queryasyncjobresultresponse": {
        "accountid": "4ba55ceb-ca2c-11ea-abc8-000c29972b82",
        "userid": "4ba56941-ca2c-11ea-abc8-000c29972b82",
        "cmd": "org.apache.cloudstack.api.command.admin.vm.ExpungeVMCmd",
        "jobstatus": 1,
        "jobprocstatus": 0,
        "jobresultcode": 0,
        "jobresulttype": "object",
        "jobresult": {
            "success": true
        },
        "jobinstancetype": "VirtualMachine",
        "jobinstanceid": "f3269f7d-ea10-494d-bc1d-a460baf89ca7",
        "created": "2020-07-24T09:57:38+0800",
        "completed": "2020-07-24T09:57:48+0800",
        "jobid": "da2f1706-4a5d-49d6-96fa-d9c7ebbf0d4d"
    }
}

十一、更改虚拟实例IP updateVmNicIp

异步命令需要虚拟实例状态为Stopped 注，每一个NIC都是依附于虚拟实例的。

命令字符串

field	value值描述	是否必需
command	命令(updateVmNicIp)	true
response	返回值类型，可选xml或者json，默认是xml，一般希望返回json数据	false
apiKey	标识用户的API KEY	true
nicid	虚拟实例的NIC的id	true
ipaddress	要更改的虚拟实例ip地址，尽管可以不设置，但不设置新的IP执行该命令就毫无意义	false

命令字符串示例

command=updateVmNicIp&response=json&nicid=a3e5ed04-9f60-48e1-a4e9-c24dbe80d127&ipaddress=192.168.199.71&apiKey=zsElxq-OfzPyJ8LJcrv7V5vKO74GP6UM-3TuniJoGflIHMWDAfby2rGYypFnL7XROnzxuLBHNFKk4uQCvP1AMA

较重要返回结果

Response Name	Description
jobid	异步任务id

数据示例

{
    "updatevmnicipresponse": {
        "jobid": "f6506dbe-94d7-4ade-a8c1-f58d13672ffe"
    }
}

具体异步任务执行结果使用queryAsyncJobResult根据jobid查询

CloudStack API 调用失败

如果在处理API请求时发生错误，则返回指定格式的适当响应。每个错误响应包括一个错误代码和一个描述可能出错的错误文本。以下是可能的错误代码列表：

code	Descriptio
4250	“com.cloud.utils.exception.CloudRuntimeException”
4255	“com.Cloud.utils.Exction.ExceptionUtil”
4260	“com.cloud.utils.exception.ExecutionException”
4265	“com.cloud.utils.exception.HypervisorVersionChangedException”
4270	“com.cloud.utils.exception.RuntimeCloudException”
4275	“com.Cloud.Exction.CloudException”
4280	“com.Cloud.Exction.AccountLimitException”
4285	“com.cloud.exception.AgentUnavailableException”
4290	“com.cloud.exception.CloudAuthenticationException”
4295	“com.Cloud.Exction.CloudExecutionException”
4300	“com.cloud.exception.ConcurrentOperationException”
4305	“com.cloud.exception.ConflictingNetworkSettingsException”
4310	“com.cloud.exception.DiscoveredWithErrorException”
4315	“com.Cloud.Exction.HAStateException”
4320	“com.cloud.exception.InsufficientAddressCapacityException”
4325	“com.cloud.exception.InsufficientCapacityException”
4330	“com.cloud.exception.InsufficientNetworkCapacityException”
4335	“com.cloud.exception.InsufficientServerCapacityException”
4340	“com.cloud.exception.InsufficientStorageCapacityException”
4345	“com.Cloud.Exction.InternalErrorException”
4350	“com.cloud.exception.InvalidParameterValueException”
4355	“com.cloud.exception.ManagementServerException”
4360	“com.cloud.exception.NetworkRuleConflictException”
4365	“com.cloud.exception.PermissionDeniedException”
4370	“com.cloud.exception.ResourceAllocationException”
4375	“com.Cloud.Exction.ResourceInUseException”
4380	“com.cloud.exception.ResourceUnavailableException”
4385	“com.cloud.exception.StorageUnavailableException”
4390	“com.cloud.exception.UnsupportedServiceException”
4395	“com.cloud.exception.VirtualMachineMigrationException”
4400	“com.Cloud.Exction.AccountLimitException”
4405	“com.cloud.exception.AgentUnavailableException”
4410	“com.cloud.exception.CloudAuthenticationException”
4415	“com.Cloud.Exction.CloudException”
4420	“com.Cloud.Exction.CloudExecutionException”
4425	“com.cloud.exception.ConcurrentOperationException”
4430	“com.cloud.exception.ConflictingNetworkSettingsException”
4435	“com.Cloud.Exction.ConnectionException”
4440	“com.cloud.exception.DiscoveredWithErrorException”
4445	“com.Cloud.Exction.DiscoveryException”
4450	“com.Cloud.Exction.HAStateException”
4455	“com.cloud.exception.InsufficientAddressCapacityException”
4460	“com.cloud.exception.InsufficientCapacityException”
4465	“com.cloud.exception.InsufficientNetworkCapacityException”
4470	“com.cloud.exception.InsufficientServerCapacityException”
4475	“com.cloud.exception.InsufficientStorageCapacityException”
4480	“com.cloud.exception.InsufficientVirtualNetworkCapcityException”
4485	“com.Cloud.Exction.InternalErrorException”
4490	“com.cloud.exception.InvalidParameterValueException”
4495	“com.cloud.exception.ManagementServerException”
4500	“com.cloud.exception.NetworkRuleConflictException”
4505	“com.cloud.exception.PermissionDeniedException”
4510	“com.cloud.exception.ResourceAllocationException”
4515	“com.Cloud.Exction.ResourceInUseException”
4520	“com.cloud.exception.ResourceUnavailableException”
4525	“com.cloud.exception.StorageUnavailableException”
4530	“com.cloud.exception.UnsupportedServiceException”
4535	“com.cloud.exception.VirtualMachineMigrationException”
9999	“org.apache.cloudstack.api.ServerApiException”