Apsara Clouder专项技能认证：实现调用API接口

课程学习笔记的思维导图

一.API 简介

1.API 的概念

API(Application Programming Interface应用程序编程接口)是一些预定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码或理解内部工作机制的细节

2.API 的特点

• API 是一个明确定义的接口,可以为其他软件提供特定服务
• API可以小道只包含一个单独的函数,亦可以达到包含数以百计的类,方法,全局函数,数据类型,枚举类型和常量
• API的实现可以是私有的,亦可以是开源的

3.API 的分类

• 面向对象语言的 API ，如Java API列表；
• 库与框架的 API，如Windows API、Windows DirectX；
• API 与协议，如LDAP应用程序接口；
• API 与设备接口，如PC BIOS调用接口、ASPI for SCSI设备接口
• Web API，如Google地图API、新浪微博API、阿里云API市场；

4.使用API的原因

• 快速扩展功能
• 避免"造轮子",提高开发效率
• 降低模块之间的耦合度

二.API 的请求与认证

1.Web API协议及HTTP请求

1.1 web api 一般采用 http 作为底层协议,http 请求机制如下:

客户端向服务器发送一个请求

服务器给客户端一个响应,告诉客户端是否可以完成它的请求的工作

1.2 HTTP请求包含的内容

• URL（API调用地址）
• 请求方法【get、post、put、delete】
• Headers（请求头)
• Body（请求主体

• 请求头(Headers):提供请求的元信息,是一个简短的项目列表,其中有客户端发送请求的时间和请求主体的大小,身份认证等信息
• 请求体(Body):包含客户端发送给服务器的数据

2.API请求方式

• GET:请求服务器获取一个资源
• POST:请求服务器创建一个资源
• PUT:请求服务器更新或者编辑一个资源
• DELETE:请求服务器删除一个资源

3.状态返回码

处理成功返回2xx：

HTTP状态码	语义
200 OK - [GET]	服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]	用户创建或修改数据成功
202 Accepted - [*]	表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]	用户删除数据成功

服务端错误码5xx：

错误代码	HTTP状态码	语义	解决方案
Internal Error	500	API网关内部错误	建议重试
Failed to invoke backend Service	500	底层服务错误	API提供者底层服务错误，建议重试，如果重试多次仍然不可用，可建议联系API服务商解决
Service Unavaliable	503	服务不可用	建议稍后重试
Async Aervice	504	后端服务超时	建议稍后重试

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

参考：错误代码表 https://help.aliyun.com/document_detail/43906.html
注意:有些API自定义了错误码,具体请查看该API文档中的描述。

4.返回数据格式

• JSON格式

{
    "name":"中国"，
    "province": [{
    "name":"黑龙江"。
    "cties":{"city":["哈尔滨"，"大庆"]}
}，{
    "name":"广东":
    "cties":{"city":["广州"，"深圳"，"珠海"]}
    }}
}

• XML格式

<?xml version="1.0" encoding="utf-8"?>
<country>
<name>中国</name>
<province>
    <name>黑龙江</name>
    <citys>
        <city>哈尔滨</city>
        <city>大庆</city>
    </citys>
</province>
</country>

目前最新的API大多使用JSON数据格式。JSON ( JavaScript Object Notation )是一种轻量级的数据交换格式,采用完全独
立于语言的文本格式,易于人阅读和编写,同时也易于机器解析和生成,是一种理想的数据交换语言。

JSON数据格式表示方法：

1.表示对象
JSON最常用的格式是对象的键值对

{"name":"电脑","price":"6999"}

2.表示数组
和普通的JS数组一样, JSON表示数组的方式是
使用方括[]

{
	"name":"电脑",
	"products":[
		{
			"brand":"华为",
			"price":"5489"
		},
		{
			"brand":"戴尔",
			"price":"3568"
		},
	]
}

 

5.API身份认证及签名认证

5.1 API简单身份认证(APPCODE方式)

可以通过APPCODE的方式,实现到被调用接口的身份认证,获取访问相关API的调用权限。
使用方法:

• 请求Header中添加的Authorization字段;
• 配置Authorization字段的值为"APPCODE + 半角空格 + APPCODE值"

格式:
       Authorization:APPCODE AppCode值
示例:
       Authorization:APPCODE 3F2504E04F8911D39A0C0305E82C3301

5.2 API签名认证( AppKey & AppSecret )

AppKey和AppSecret相当于当前账户的另外-套账号和密码机制。在云市场购买API之后,就可
以在控制台找到对应的AppKey和AppSecret。
 

具体的签名认证方法请参见请求头部字段以及请求签名说明文档 

三.API调试及调用

1.API调试

阿里云API市场提供了在线调试功能,以方便用户在不用写调用代码的前提下进行快速测试

2.API调用步骤

获取API文档 --- 创建应用 --- 获取授权 --- 调用API

要调用API需要三个基础条件:

• API:您即将要调用的API ,明确API参数定义。
• 应用app :作为您调用API时的身份,有AppKey和AppSecret用于验证您的身份。
• API和App的权限关系: App想调用某个API需要具有该API的权限,这个权限通过授权的功能来建立。

2.2.1.获取API文档

 

• 在云市场选择API ,在API产品页面即可找到该API的使用说明(文档)。
• 购买API服务成功后,进入云市场的管理控制台,就会看见购买的所有API服务。( 如果还没有开通API网关服务,那么会同时开通API网关服务让你使用更流畅)
• 可以跳转到API网关的控制台，在已购买API页面,展示购买的所有API服务列表,以及使用情况概况。

2.2.2.创建应用

• 应用( APP )是调用API服务时的身份。每个APP有一组Key和Secret ,可以理解为账号密码,调用API的时候需要将AppKey做参数传入, AppSecret用于签名计算,网关会校验这对密钥对你进行身份认证。
• 可以在API网关控制台应用管理页面创建APP ,创建成功后,系统会为APP分配一对AppKey和AppSecret

2.2.3.获取授权

• 授权,是指授予APP调用某个API的权限。您的APP需要获得API的授权才能调用该API。
• 如果你在市场购买了API ,就可以指定将已购买的API授权给哪些APP ,然后这些APP才能调用该API。
• 如果您没有APP,购买时云市场会为你创建一个APP，并且授权。

2.2.4.调用API

 

• 可以直接用API文档中提供的多语言调用示例来调用,如右图所示
• 也可以自行编辑HTTP(s)请求来调用API ,详见API的请求步骤

3.API调用注意事项

• 每个账号下 APP 的个数上限为10个,app 名称应用为账号下唯一
• 调用 api 的流控限制为,单个 ip,qps 不超过100
• 你有权操作购买的 api 与 app 的授权和解除授权.由服务提供方授权给你的 app 的api,你无权操作解除授权
• 你的请求需要包含签名信息