文档

阿里云OpenAPI和SDK

更新时间:
一键部署

OpenAPI是阿里云产品提供的开放应用程序接口,是除了控制台外,主要的服务形式之一。开发者可以通过编程的方式来使用阿里云产品提供的服务,相比于控制台,使用 OpenAPI 具有规模化、自动化、定制化的优势,是将业务和云服务集成的不二选择。

阿里云为开发者提供了多种编程语言(Java、C#、Go、Python、Node.js/TypeScript、PHP、C++ 等)的 SDK、CLI来简化OpenAPI的使用过程。同时,对于一些特殊的场景,比如资源编排,阿里云提供了 Terraform、ROS CDK等工具。这些SDK和工具都是基于OpenAPI的能力而构建。

在使用阿里云SDK和工具之前,您需要先了解一下阿里云关于OpenAPI的一些基本概念,这有助于提升开发效率和体验。

云服务

云服务实际上是指由云产品提供的OpenAPI服务。但云服务不等同于云产品,因为一个云产品可能会提供多种云服务,如RAM(访问控制)这个产品,按能力的不同,它提供了2种云服务,STS(令牌服务)、IMS(身份管理服务)。

阿里云的云服务涵盖了不同领域,如计算、存储、网络、机器学习、通信、DevOps等等,从使用的侧重不同,大致可以分为以下三类:

  • 管理类

    指开发者主要通过OpenAPI进行资源管理类操作。如ECS、SLB、VPC、RDS、OSS等,大部分IaaS产品提供此类服务。

  • 能力类

    指开发者主要通过OpenAPI来使用云产品的能力。如短信服务、邮件推送等流量产品,机器翻译、人脸识别等机器学习产品提供此类服务。

  • 支持类

    支持类云服务是指一些偏横向支持性的服务。比如账单、权限、审计等产品提供此类服务。

需要注意的是,云服务不一定只属于某个分类。以OSS为例,它的部分API属于管理类,部分则属于能力类。

跟控制台的要求一样,在云服务之前,也需要先开通服务,否则会报“服务未开通”的错误。为了适应OpenAPI的自动化需求,有的云服务是免开通的,有的则是提供了用于开通的OpenAPI。

地域与 Endpoint

在进入云服务的具体能力之前,需要理解的是云服务的部署形式。一个云产品将服务部署在一个地域,称之为中心化部署;将服务部署在多个地域,则称之为区域化部署。不论是什么类型的部署,云服务都提供了Endpoint作为OpenAPI的入口。

  • 对于中心化部署,它的Endpoint为 <service code>.aliyuncs.com 的形式。以IMS为例,它的Endpoint是 ims.aliyuncs.com

  • 对于区域化部署,它的Endpoint为 <service code>.<region id>.aliyuncs.com 的形式。以STS为例,它在杭州的Endpoint为 sts.cn-hangzhou.aliyuncs.com ,在北京的Endpoint为 sts.cn-beijing.aliyuncs.com

阿里云在 OpenAPI 开发者门户 上为每个云服务提供了Endpoint的展示,以IMS为例,可以访问:https://api.aliyun.com/product/Ims#endpoint 查看所有地域下的Endpoint。

VPC Endpoint 类型

需要注意的是,由于默认的Endpoint是公网可访问的,因此实际使用时会消耗公网流量。阿里云提供了VPC类型的Endpoint,俗称内网Endpoint。VPCEndpoint除了提供内网访问,可节省流量,提升访问速度外,还提供更安全的访问保护。对于中心化和区域化的VPC Endpoint地址形式分别为:<service code>.vpc-proxy.aliyuncs.com<service code>-vpc.<region id>.aliyuncs.com 。具体云服务的VPC Endpoint一样可以通过 OpenAPI 开发者门户进行查询。

版本(分组)

云服务会在不同时期,推出不同的OpenAPI分组,因此一个云服务下会存在多个OpenAPI分组的情况。比如ECS提供的主要OpenAPI分组是 2014-05-26 ,它代表在这个时期推出的一批OpenAPI。不同时期推出的OpenAPI分组可能存在延续性,也可能不存在延续性。

在过去,这种分组也被理解为OpenAPI组的版本,但实际上这个日期版本号仅代表OpenAPI分组的时期,起到辨识的作用。而与真正版本化概念并不是一回事,真正的版本化是每次变更都会涉及到版本号的变化,而这里的Date Version只是标识作用。

资源

与RESTful的设计一样,云服务的OpenAPI也主要是围绕资源来提供各种操作,如创建、查询、修改、删除等。

资源类型

以ECS为例,它的主要资源类型是Instance。你可以调用相关的OpenAPI来进行对实例的创建、查询、修改、删除等操作。

资源类型与资源类型之间通常有一定的关联性,比如Instance上还需要有Disk。有的资源则是虚拟的分组形式,比如UserGroup,UserGroup和User之间只是从属关系,但它们之间是可以互相独立存在的。

操作类型

一个具体的OpenAPI归属于一种具体的操作类型。比如DescribeRegions,是相对Region这种资源类型的查询(列表)操作。

我们在 OpenAPI 开发者门户上对每一个OpenAPI标识了它的具体操作类型。这些操作类型在OpenAPI调用审计(ActionTail)上,也有体现。

OpenAPI 风格

说明

本节仅供需要自研SDK的开发者阅读,普通读者可跳过。

一组OpenAPI有属于自己的设计风格。一种设计风格包含的内容有URL的设计,参数的形式,传输格式等。业界常见的RESTful就是一种典型的设计风格,利用HTTP Method作为动词,URL中的路径作为资源,JSON格式作为传输格式,是它的主要特点。

阿里云的OpenAPI由于涉及的产品较多,风格也比较多样化,但最主要的几种风格是:

  • RPC

  • ROA

  • OSS

以RPC为例,它的形式是 http://{{Endpoint}}/?Action={{API NAME}} 。ROA的形式则是 http://{{Endpoint}}/{{Resources}} ,ROA的风格更接近于RESTful。

OpenAPI风格的不同,影响SDK对它的封装形式。阿里云官方提供的SDK,尽量封装了不同风格带来的细节。

身份、认证和权限

阿里云的OpenAPI分为两种,一种是匿名OpenAPI,一种是需要身份认证的OpenAPI。对于匿名OpenAPI,不需要额外的流程,只要请求是符合OpenAPI的风格,则可以顺利调用。

对于需要身份认证的OpenAPI,其调用过程相对复杂,涉及到身份、认证、权限三个概念。

身份与凭证

身份其实就是阿里云的用户,包含主账号和子账号。云服务通过对凭证的识别来达到认证的目的。

以用户在登录控制台为例,就是通过密码的形式来实现身份的认证。在这里,邮箱/密码,是用户所使用的凭证。

在OpenAPI的场景里,我们主要是用AccessKey来作为凭证,它是一对AccessKey Id和AccessKey Secret的字符串。您可以通过RAM 控制台来管理您的AccessKey。但阿里云账号(主账号)的 AccessKey因为具备的权限过大,泄漏后的安全风险较高,不推荐直接使用。我们推荐使用RAM用户(子账号),通过精细化的授权,保证权限的粒度较小,来保障安全。

除了AccessKey外,阿里云还提供安全临时令牌的服务。相比长期性的AccessKey,临时性的STS因为具有时效性,它具有更高级别的安全保障。STS是一个三元组字符串,由AccessKey Id/AccessKey Secret/Security Token 组成。

STS无法直接创建,它的获得主要有以下方式:

  1. 通过ECS RAM Role的机制

  2. 通过RAM Role ARN的角色扮演机制

  3. 通过Cloud SSO的登录机制换取

  4. 通过Public Key/Private Key证书(备注:仅日本站支持,未来会淘汰)

由于STS具有时效性,支持它的SDK需要具备自动刷新STS的能力。

签名机制

不论是AccessKey,还是STS,在实际的OpenAPI调用中,不会将AccessKey Secret发布给网关的形式来进行认证,而是采用非对称加密的形式来对请求的内容进行签名。网关会根据获取的AccessKey Id获得对应的AccessKey Secret,并对收到的请求进行签名,通过对比签名是否一致,从而判断凭证的有效性完成认证。

具体的签名过程,请参见下面的过程:

因为安全性的原因,OpenAPI的调用过程显得较复杂,如果从头完成整个调用过程的研发,需要花费3-5天的时间。因此除非特别的原因,推荐使用官方提供的SDK/CLI等工具,它们封装了整个复杂的过程,使开发者可以将精力关注在OpenAPI的业务上,而不是浪费在技术细节上。

权限

再说说权限。一个用户的凭证通过认证后,只能说明这个身份的有效性,但这不意味着用户就可以调用该OpenAPI。要能成功调用一个OpenAPI,除了身份凭证正确,签名过程正确外,还需要用户本身具有调用该OpenAPI的权限。如果您使用的是子账户,可以在RAM控制台进行完整的权限控制。

OpenAPI开发者门户会透出每个OpenAPI所需要的权限。

流控

因为云服务的不同,每个OpenAPI的流控程度不同。开发者需要注意调用的并发程度,以保障调用过程不被流控错误中断。

OpenAPI开发者门户在每一个API的文档页面上都提供了相关的流控信息。

  • 本页导读 (1)
文档反馈