apsara clouder基础认证API接口

ＡＰＩ简介

概念
API（APPlication programming Interface，应用程序编程接口）是预先预定一些函数，目前是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码或理解内部工作机制的细节。
特点
１.API是一个明确定义的接口，可以为其他软件提供特定服务
２.API可以小到只包含一个单独函数，也可以大到包含数以百计的类，方法，全局函数，数据类型，枚举函数和常量等
３.API的实现可以是私有的也可以是开源的
分类
面向对象语言的API
举例：Java API列表
库与框架的API
举例：WIndows API，Windows DirectX
API与协议
举例：LDAP应用程序接口
API与设备接口
例：PC BLOS调用接口，ASPLforSCSI设备接口
Web API
例：Google地图API，新浪微博API，阿里云API市场
为什么要使用ＡＰＩ
１.快速拓展功能
２.避免“造轮子”，提高开发效率
３．降低模块之间的耦合度

Web API协议

Web API一般采用HTTP作为底层协议，
HTTP请求机制如下：
客户端向服务器发送一个请求
服务器给客户端一个响应，告诉客户端
是否可以完成它请求的工作

为了构造有效的请求，客户端需要包含四部分：
URL（API调用地址）
请求方式
Headers（请求头）
Body（请求主体）

请求方式告诉服务器客户端希望它采取什么动作。常见的请求方式有四种：
GET：请求服务器获取一个资源
ＰＯＳＴ：请求服务器创建一个新的资源
　ＰＵＴ：请求服务器编辑或更新一个已经存在的资源
　ＤＥＬＥＴＥ：请求服务器删除一个资源

请求头（Ｈｅａｄｅｒｓ）
　　　提供请求元的信息，是一个简单的项目列表，其中有客户端发送
　　　请求的时间和请求主体的大小，身份认证信息。

请求体（Ｂｏｄｙ）
　　　包含客户端希望发送服务器的数据

状态码　－　成功状态

状态码　－　服务端错误码
ＡＰＩ未调试成功，则返回错误码。服务端错误码是５ＸＸ，表示服务不可用（此时建议重试或联系商品页面的ＡＰＩ服务商）

客户端错误码为４ＸＸ　，表示业务报错。此时一般为参数错误，签名错误，请求方式有误或被流控限制等业务类错误。建议详细查看错误码，针对性解决问题。

返回数据格式
ＪＳＯＮ　或者　ＸＭＬ　格式
目前最新的ＡＰＩ大多使用ＪＯＳＮ数据格式。ＪＯＳＮ（ＪａｖａＳｃｒｉｐｔ　Ｏｂｊｅｃｔ　Ｎｏｔａｔｉｏｎ）是一种轻量级的数据交换格式，采用完全独立的文本格式，易于人阅读和编写，同事也易于及其解析和生成。是一种理想的数据交换语言。

ＪＯＳＮ数据格式表示法
１.表示对象
ＪＯＳＮ最常用的格式是对象的键值对
２.表示数组
和普通的ＪＳ数组一样，ＪＯＳＮ表示数组的方式是使用方括号［］

ＡＰＩ简单的身份认证（ＡＰＰＣＯＤＥ方式）
可以使用APPCODE的方式，实现到被调用接口的身份认证，获取访问相关的API的调用权限。
使用方法：
请求Header中添加的Authorization字段；
配置Authorization 字段的值为“APPCODE+半角空格+APPCODE值”。
格式：
Authorization:APP CODE AppCode值
示例：
Authorization:APPCODE XXXXXXXXXXXX

API签名认证（AppKey & AppSecret）

AppKey 和AppSecret 相当于当前账户的另一套账号和密码机制。在云市场购买API之后，就可以在控制台找到对应的AppKey和AppSecret.
具体的签名认证方法请参见 请求头部字段 以及 请求签名说明文档

获取ＡＰＩ文档　－－创建应用－－获取授权－－调用ＡＰＩ

要调用ＡＰＩ需要三个基础条件：
　　ＡＰＩ：您即将要调用的ＡＰＩ，明确ＡＰＩ参数定义。
　　应用ａｐｐ：作为您调用ＡＰＩ时的身份，有ＡｐｐＫｅｙ和ＡｐｐＳｅｃｒｅｔ用于验证您的身份。
　　ＡＰＩ和Ａｐｐ的权限关系：Ａｐｐ想调用某个ＡＰＩ需要具有该ＡＰＩ的权限，这个权限通过授权的功能来建立

创建应用
应用（ＡＰＰ）是调用ＡＰＩ服务时的身份。每个ＡＰＰ有一组Ｋｅｙ和Ｓｅｃｒｅｔ，可理解为账号和密码，调用API的时候需要将APPKEy做参数传入，APPSecret用于签名计算，网关会校验这对秘钥对你进行身份认证。
可以在API网关控制台应用管理页面创建APP，创建成功后，系统会为APP分配一对AppKey 和AppSecret

调用API
可以直接用API文档中提供的多种语言调用示例来调用
也可以自行编辑HTTP（s）请求来调用API

API调用注意事项
每个账号下ＡＰＰ个数上限为１０个，ＡＰＰ名称应为账号下唯一。
调用ＡＰＩ的流控限制为，单ＩＰ，ＱＲＳ不超过一百个
你有权操作购买的ＡＰＩ与APP的授权和解除授权。由服务提供方授权给你的APP的API，你无权操作解除授权
你的请求需要包括签名信息

附录：常见的错误码
HttpCode Code Message Advice
500 InternalError The request processing has failed due to some unknown error. 给您带来的不便，深感抱歉，请稍后再试。
503 ServiceUnavailable The request has failed due to a temporary failure of the server. 给您带来的不便，深感抱歉，请稍后再试。
504 ServiceTimeout The request processing has failed due to timeout. 请稍后再试。
503 SecurityToken.CheckFailed The security token check has failed due to some internal error. STS token 权限检查过程中，由于内部调用失败导致检查失败，请稍后再试。
503 SecurityToken.DecodeFailed The security token decode has failed due to some internal error. STS token 解码过程中，由于内部调用失败导致解码失败，请稍后再试。
503 SubRam.CheckFailed The sub user ram check has failed due to some internal error. 主子账号权限检查过程中，由于内部调用失败导致检查失败，请稍后再试。
503 VpcRam.CheckFailed The Vpc ram check has failed due to some internal error. Vpc 权限检查过程中，由于内部调用失败导致检查失败，请稍后再试。
503 VpcSubRam.CheckFailed The Vpc sub user ram check has failed due to some internal error. Vpc 主子账号检查过程中，由于内部调用失败导致检查失败，请稍后再试。
400 MissingParameter.callerUid Parameter callerUid is mandatory for this action. 请加入callerUid请求参数。
400 MissingParameter.RegionId Parameter RegionId in endpoint is mandatory for this action. 请在域名中加入RegionId字段信息。
400 MissingParameter.VSwitchId Parameter VSwitchId is mandatory for this action. 请加入VSwitchId请求参数。
400 MissingParameter.VpcId Parameter VpcId is mandatory for this action. 请加入VpcId请求参数。
400 InvalidParameter.StorageType Parameter StorageType is mandatory for this action. 合法的StorageType请求参数有Performance和Capacity。
400 InvalidParameter.ProtocalType Parameter ProtocalType is mandatory for this action. 合法的ProtocalType请求参数有NFS和SMB。
400 InvalidParameter.Description Parameter Description is mandatory for this action. Description的合法字符包括中英文和以下字符：@、#、$、_、+ 和 -。
404 InvalidFileSystem.NotFound The specified FileSystem does not exist. 您指定的文件系统不存在或已删除。
403 InvalidFileSystem.AlreadyExisted The specified FileSystem has been already existed. 您指定的文件系统已存在，您可以通过调用DescribeFileSystems并指定该文件系统id查看相关信息。
404 InvalidMountTarget.NotFound The specified MountTarget does not exist. 您指定的挂载点不存在或已删除。
404 InvalidAccessGroup.NotFound The specified AccessGroup does not exist. 您指定的权限组不存在或已删除。
403 InvalidAccessGroup.AlreadyExisted The specified AccessGroup has been already existed. 您指定的权限组已存在，您可以通过调用DescribeMountTargets并指定该权限组查看相关信息。
403 InvalidAccessGroup.AlreadyAttached The specified AccessGroup is still attached by some MountTarget(s). 指定权限组还绑有相关挂载点，请先解绑相关挂载点再删除该权限组。
404 InvalidAccessRule.NotFound The specified AccessRule does not exist. 您指定的权限规则不存在或已删除。
404 InvalidLocatin.NotFound The specified Location is not found or is not supported. 请求的 Location 不存在或暂未提供服务。
404 InvalidRegionId.NotFound The specified Region is not found. 请求的 Region 不存在或暂未提供服务。
404 InvalidAZone.NotFound The specified AZone is not found. 请求的 Zone 不存在或暂未提供服务。
404 InvalidVpc.NotFound The specified Vpc is not found. 您指定的 Vpc 不存在，请先创建专有网络 VPC。
404 InvalidVip.NotFound The specified Vip is not found. 您指定的 Vpc 没有找到，请检查您的 Vpc 信息正确有效。
404 InvalidLBid.NotFound The specified LBid is not found. 系统创建 LBid 失败，请稍后重试。
404 InvalidVpcTunnelId.NotFound The specified vpc tunnelId is not found. 指定的 Vpc tunnelId不存在，请先检查 Vpc 信息。
404 InvalidVpc.CreationFailed The specified vpc instance creation failed. 指定的 Vpc 实例创建失败，请检查您的 Vpc 信息正确有效且有可用 IP 空间可供创建，并再次重试。
403 OperationDenied.DefaultAccessGroupCannotDelete The default AccessGroup can not be deleted. 您可以编辑操作自定义的权限组。
403 OperationDenied.DefaultAccessGroupCannotModify The default AccessGroup can not be modified. 您可以编辑操作自定义的权限组。
403 OperationDenied.NetworkTypeNotMatched The NetworkType of MountTarget is not matched with AccessGroup. 请确保挂载点的 NetworkType与权限组的 AccessGroupType保持一致。
403 OperationDenied.MountTargetNotEmpty There are still MountTarget(s) on the specified FileSystem. 指定文件系统仍存在挂载点，请先删除挂载点。
403 OperationDenied.FileSystemCountsExceeded The amount of FileSystem has reached its limits(maximum 10).
如需提高上限，请提交工单。

403 OperationDenied.MountTargetCountsExceeded The amount of MountTarget has reached its limits(maximum 2 per FileSystem).
如需提高上限，请提交工单。

403 OperationDenied.AccessGroupCountsExceeded The amount of AccessGroup has reached its limits.
如需提高上限，请提交工单。

403 OperationDenied.AccessRuleCountsExceeded The amount of AccessRule has reached its limits.
如需提高上限，请提交工单。

403 User.Disabled Your account does not open Nas Service yet or balance is insufficient.
若您尚未开通 NAS 服务，请先前往开通 NAS 服务。

403 Forbidden.InvalidUserType The operation is not permitted due to type of account. NAS API 暂不支持您的账户类型，请见谅。
403 Forbbiden.Ram User not authorized to operate on the specified resource, or this API doesn’t support RAM. 您的账户 RAM 权限校验失败，请前往 RAM 确保授权 NAS 相关权限。
403 Forbidden.EcsTokenNotAuthorized User not authorized to check ecs on creating MountTarget of classic network type. 请前往 RAM 授权 NAS 访问 ECS 校验接口。
403 NotQualified User has not been approved for the trail application.
请您先发起相关新特性的试用申请，若长时间未审批通过，请提交工单。