CloudStack API编程指南

角色

CloudStack API支持三种角色访问：

根域管理员
域管理员
普通用户

提交API请求

所有CloudStack API请求都是以HTTP GET/POST的形式提交，一个请求包含下面三部分：

API的URL地址：即web服务API的入口地址(如： http://www.example.com:8080/client/api)
命令：你想要执行的web服务命令，如启动一个虚拟机
参数：该命令所需要的必要或可选参数

一个API请求的例子如下：

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行表示我们想要执行的命令；
第3-6行是该命令所需的参数，命令和参数的详情具体可以参考API文档；
第7行是唯一标识用户的账户的API Key；
第8行是用来认证用户账户执行API命令权限的签名的哈希值

API请求的签名

不管你是通过HTTP还是HTTPS的方式访问CloudStack API，都必须对请求进行签名从而让CloudStack能确认调用者已经被认证和授权执行该命令。在进行签名之前先确认你拥有API Key和管理员提供给你的账户的私钥。
以上面的API请求为例子，每个API请求都包含以下几个部分：

基本的URL：http://localhost:8080
API的路径，处理请求的API Servlet的路径：/client/api?
命令字符串：包括命令，命令的参数以及标志用户账户的API Key，需要注意的是，参数的键是不区分大小写的，而参数的值是区分大小写的
签名：使用用户的私钥和HMAC SHA-1哈希算法生成的签名

生成签名的步骤：

命令字符串中的每个键值对（以&分隔开），URL对每个值进行编码从而使其能通过HTTP GET安全地发送
将命令字符串的字母全部转换成小写，并且对键值对按字母顺序进行排序，结果类似下面的形式： apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4
将排序好的命令字符串和用户的私钥使用HMAC SHA-1哈希算法进行编码，在使用Base64将结果字节数组编码成UTF-8形式，最终得到的签名为：Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

设置API调用失效时间

在不安全的通道如HTTP上，我们可以设置一个API调用逾期时间戳来防止重播攻击（replay attacks），服务器会追踪这个时间戳，并拒绝超过这个期限的后续的所有API调用。
在API请求中加入以下参数可实现这个特性：

signatureVersion=3
expires=YYYY-MM-DDThh:mm:ssZ

限制API调用频率

避免对管理服务器的恶意攻击，防止性能下降以及对所有账户提供一致性，当API调用超过一定阈值后会向这些调用返回错误信息。调用者需要等待一段时间后重试一下。可以通过一下全局参数来设置API的调用频率限制：

api.throttling.enabled：默认为false，即不限制API调用频率
api.throttling.interval ：以秒为单位，
api.throttling.max：每个间隔周期接受的最大请求数
api.throttling.cachesize：存放API调用计数器的缓存，每个账户需要一个cache来存放该账户运行的API总数

API调用频率限制的不足之处：

存在多个管理服务器的时候，不同管理服务器的cache之间不是同步的，所以可能出现允许通过的请求数比设置的值要大的情况，最糟糕的情况下可能出现允许通过的请求数为：限制值*管理服务器数量
尽管如此，CloudStack还是可以有效地避免恶意攻击导致的服务拒绝

API响应

CloudStack支持两种响应格式：XML和JSON，默认的响应是XML，可以在请求URL中使用&response=json来设置JSON格式的响应。使用JSON格式时，如果一个响应的键没有值，则该键不会出现在响应中，而XML仍会返回一个空的元素。

最大返回结果页

对于每个云，一个命令在一个页面中返回的结果数有一个默认的上限，以此来防止云服务器过载和防止DOS攻击。
每个云的默认上限值是不同的，通过全局参数default.page.size来配置。如果云上有许多用户运行了许多虚拟机的话，可以把这个值设置大一点，但要小心不要设置得太大了。

错误处理

如果在处理一个API请求的时候发生了错误，会返回特定格式的响应。每个错误信息响应包含一个错误代码和一个文本描述可能出错的原因。
如果用户的签名错误或没有权限导致请求被拒绝会返回一个HTTP 401错误

异步命令

异步命令可以隐式地执行那些耗时很长的任务，如创建一个快照。它和同步命令有以下几点不同：

API引用以一个a来区分
提交后会马上返回一个任务ID
如果是创建资源的命令，在返回任务ID的同时还会返回资源ID

使用异步命令的关键在于Job ID，它在命令被执行后马上返回。使用Job ID，通过queryAsyncJobResult命令我们可以周期性地检查任务的状态，这个命令返回3种可能的任务状态。

0-Job表示程序还在进行
1-Job表示成功地完成了
2-Job表示执行失败

查询命令执行状态的命令：command=queryAsyncJobResult&jobId=1