使用 SDK 调用 API

首先需要初始化一个AliyunClient,SDK的操作都是通过AliyunClient完成的。AliyunClient可以复用,建议设置成全局唯一。 了解AliyunSDK

1 Aliyun Client

2 调用接口

  • import com.aliyuncs.DefaultAcsClient;
    import com.aliyuncs.IAcsClient;

  • public class CreateAliyunClientDemo {
    private static AliyunClient client;
    static {
    String serverUrl = "";



    配置服务地址例如:
    http://ecs.aliyuncs.com/
  • String accessKeyId = "";
    String accessKeySecret = "";

    使用API和SDK之前,首先要拥有
    AccessKey,用于对请求加密签名,点击创建和管理AccessKey
  • client = new DefaultAliyunClient(serverUrl, accessKeyId, accessKeySecret);
    }

    public static void main(String[] args) {
    }
    }



    初始化一个AliyunClient
阿里云所有产品和云服务,都会陆续推出自己的API。

使用 CLI 调用 API

阿里云命令行工具AliyunCLI是基于阿里云开放API建立的手边管理工具。使用CLI用户可以用简单的命令调用API,节约操作成本,高效便捷。
右侧图为使用CLI 调用描述实例接口,返回格式为table。CLI同时还支持Json和Text格式返回。了解更多AliyunCLI的特性 >>

API 请求结构

  • 请求API样例
  • 系统返回样例
  • https://ecs.aliyuncs.com/?Action=CreateInstance
    &RegionId=cn-hangzhou
    &ImageId=_32_23c472_20120822172155_aliguest.vhd
    &SecurityGroupId=sg-c0003e8b9
    &HostName=Bctest01
    &InstanceType=ecs.t1.small



    API名称:CreateInstance
    功能:创建实例
    服务地址:ecs.aliyuncs.com
    &参数名=参数值
  • ?Format=xml
    &Version=2014-05-26



    声明返回格式(支持XML和JSON)
    声明API版本
  • &Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
    &SignatureMethod=HMAC-SHA1
    &SignatureNonce=15215528852396
    &SignatureVersion=1.0



    签名机制相关声明
  • &AccessKeyId=key-test
    &Timestamp=2012-06-01T12:00:00Z

    要使用阿里云API,您首先需要拥有AccessKey,
    用于对API请求进行加密签名。

    创建和管理AccessKey>>

实名认证

为保证阿里云平台的稳定和安全,阿里云产品的API早已接入实名认证系统,只有已进行了实名认证的账户才被允许发起API调用。
如果您未进行实名认证,调用API会出现如下错误:

错误代码描述HTTP 状态码语义
RealNameAuthenticationErrorYour account has not passed the real-name authentication yet.403用户未进行实名认证

流量控制

为了预防恶意攻击,阿里云网关网络层设置了针对IP的访问次数限制。单个IP的API调用不能超过100次/秒。同时各产品为了保障服务的稳定性,也会对一些API接口的并发量进行限制,具体请看各产品业务和资源限制说明。
如果您收到如下反馈,说明您的调用由于流量控制而失败,需要重试:

错误代码描述HTTP 状态码语义
ThrottlingRequest was denied due to request throttling.400因系统流控拒绝访问

余额不足

阿里云API可以完成资源创建、资源变配等操作,大部分的操作对象是后付费类型的资源。
用户发起API调用时,要求用户账号内余额不少于100元,否则会返回如下错误:

错误代码描述HTTP 状态码语义
InsufficientBalanceYour account does not have enough balance.400余额不足

幂等性

用户通过API进行资源创建时,如果遇到了请求超时或者服务器内部错误,客户端可以尝试重发请求。
此时客户端可以通过提供ClientToken参数保证请求的幂等性,避免资源的重复创建。
ClientToken是由客户端生成的唯一的、区分大小写、不超过64个ASCII字符的字符串。
保证ClientToken一致的同时,如果相关的其他参数不同,则会报如下错误:

错误代码描述HTTP 状态码语义
InvalidIdempotenceParameter.MismatchThe specified parameters are different from before.403幂等参数不匹配

需要注意的是,参数SignatureNonce、Timestamp和Signature参数在重试时是需要变化的,
SignatureNonce用来防止重放攻击,Timestamp用来标记请求时间,
这二者需要保持唯一性,且这两个参数的变化会导致Signature的变化。
重试或者正常调用使用用过的SignatureNonce时,会反馈如下错误:

错误代码描述HTTP 状态码语义
SignatureNonceUsedThe request signature nonce has been used.400无效的 SignatureNonce(该 SignatureNonce 值已被使用过)

错误码

API调用后返回数据具备一定的规范性。HTTP状态码均为三位数字,对应意义如下表:

HTTP状态码
(5XX表示首位是5,后面两位为任意数)
含义幂等性相关
2XX调用成功
4XX调用失败。客户端错误或者超出限制通常重试是不能成功的,
除非提示信息出现”Try it later”
5XX调用失败。服务器内部错误建议重试

服务范围

阿里云产品均会陆续开放API接口,您可以基于阿里云开源的SDK通过编写代码来调用API,也可以使用AliyunCLI工具来调用API,从而实现对应用、资源和数据进行更灵活的部署、更快速的操作、更精确的使用、更及时的监控。

服务等级指标

响应时间:

一次API调用,响应时间不超过30s。
说明:30s的时间不包括请求从用户端到服务器端的网络消耗。
部分产品响应超时会反馈为服务器错误InternalError,此时建议重试。

可用性:

API不可用定义:若一个用户某次请求收到反馈结果为服务器错误(Http码500,错误码InternalError,Http码503,错误码ServiceUnavailable),
且重试三次反馈结果均为服务器错误,则记为1分钟不可用。
API可用性定义:对于一个用户在一个计费周期内,可用性计算公式为:100% - 不可用时间/总服务时间。
阿里云承诺API可用性达到99.8%。

错误说明:

阿里云API有完善的错误码机制,API调用失败会返回响应的Http码、错误码以及错误描述。
Http码为4XX的是客户端错误,建议用户解读错误描述,修正请求。
Http码为5XX的是服务器错误,此时建议重试。

幂等性:

用户通过API进行资源创建时,如果遇到了请求超时或者服务器错误,客户端可以尝试重新发送请求。
阿里云API有完善机制来保证请求的幂等性,避免资源的重复创建。详情请您查看产品API文档。

版本维护说明:

推荐用户使用最新版本的API,旧版本的API如无通知会继续维护。
API旧版本下线周期为通知用户的时间点开始12个月。维护内容为错误修正,不做新功能。

其他

阿里云有权根据变化适时对本服务等级协议部分服务指标作出调整,
并及时在阿里云官网www.aliyun.com发布公告或发送邮件或书面通知向用户提示修改内容。

以下产品均已开放 API,选择产品查看其 API 手册