首页 >阿里云SDK >阿里云 OpenAPI 概念 >阿里云 OpenAPI 概述

阿里云 OpenAPI 概述

本文介绍阿里云公共云 OpenAPI 的主要概念,包含云服务、地域、资源、操作、权限等。

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

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

在具体的通过工具使用 OpenAPI 之前,您有必要先了解一下阿里云关于 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://next.api.aliyun.com/product/Ims#endpoint 查看所有地域下的 Endpoint。

VPC Endpoint 类型

需要注意的是,由于默认的 Endpoint 是公网可访问的,因此实际使用时会消耗公网流量。阿里云提供了 VPC 类型的 Endpoint,俗称内网 Endpoint。VPC Endpoint 除了提供内网访问,可节省流量,提升访问速度外,还提供更安全的访问保护。对于中心化和区域化的 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 的场景里,我们主要是用 Access Key 来作为凭证,它是一对 Access Key Id 和 Access Key Secret 的字符串。您可以通过 RAM 控制台来管理你的 Access Key。但主账号的 Access Key 因为具备的权限过大,泄漏后的安全风险较高,不推荐直接使用。我们推荐使用子账户,通过精细化的授权,保证权限的粒度较小,来保障安全。

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

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

  1. 通过 ECS RAM Role 的机制

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

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

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

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

签名机制

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

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

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

权限

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

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

流控

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

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

阿里云首页 阿里云SDK 相关技术圈