产品功能对标

参考链接：

http://www.infoq.com/cn/news/2016/07/API-background-architecture-floo

一、配置中心

1、分组定义

1.1、分组的区域、独立域名和二级域名

API 分组是 API 的管理单元，分组包含名称、描述、区域（Region）、域名几大属性。

域名：分组创建时，系统会为分组分配一个二级域名。如果需要开放 API 服务，您需要为分组绑定一个在阿里云系统备案成功的独立域名，且将独立域名 CNAME 到相应的二级域名上。每个分组最多只能绑定5个独立域名。

独立域名：用于开放api

二级域名：用于测试，使用有限制

组的QPS限制:500

1.2、环境和环境变量

• 环境是 API 分组上的一个配置，每个分组有若干个环境。 API 录入后，未经发布时，就只是 API 定义。发布到某个环境后才是能够对外提供服务的 API 。

• 环境变量是在环境上用户可创建可管理的一种变量，该配置是固定于环境上的。如在线上环境创建变量，变量名为 Path，变量值为 /stage/release.

在 API 定义中的 Path 位置，写作 #Path#，即配置为变量标识，变量名为 Path。

那么将该 API 发布到线上环境时，该 API 在线上环境的运行定义，Path 处的 #Path#，会取值为 /stage/release。

而将该 API 发布到其他环境时，若环境上没有环境变量 #Path#，则无法取值，那么 API 就无法调用。

使用环境变量可以解决后端服务需要区分环境的问题，通过不同的环境上配置不同的服务地址和Path，来调用不同的后端服务，同时 API 的定义配置又是一套。使用时需要注意以下几点：

• 在 API 定义中配置了变量标识后，在 API 列表—管理—调试 页面将无法调试。
• 变量名严格区分大小写。
• 如果在 API 定义中设置了变量，那么一定要在要发布的环境上配置 变量名和变量值，否则变量无赋值， API 将无法正常调用。

1.3、https支持

后端是 https，所以还需要上传 SSL 证书，不支持上传文件，需要把内容复制进来。

若该分组下的 API 支持 HTTPS 协议，您还需要为该独立域名上 SSL 证书。不支持文件上传，需要填写证书名称、内容和私钥。

HTTPS在HTTP的基础上加入了SSL协议，对信息、数据加密，用来保证数据传输的安全。现如今被广泛使用。

API网关也支持使用HTTPS对您的API请求进行加密。可以控制到API级别，即您可以强制您的API只支持HTTP、HTTPS或者两者均支持。

如果您的API需要支持HTTPS，以下为操作流程：

步骤1:准备

您需要准备如下材料：

• 一个自有可控域名。

• 为这个域名申请一个SSL证书

  SSL证书会包含两部分内容:XXXXX.key、XXXXX.pem，可以使用文本编辑器打开

  示例：

  KEY

-----BEGIN RSA PRIVATE KEY-----

MIIEpAIBAAKCAQEA8GjIleJ7rlo86mtbwcDnUfqzTQAm4b3zZEo1aKsfAuwcvCud

....

-----END RSA PRIVATE KEY-----

• PEM

-----BEGIN CERTIFICATE-----

MIIFtDCCBJygAwIBAgIQRgWF1j00cozRl1pZ+ultKTANBgkqhkiG9w0BAQsFADBP

...

-----END CERTIFICATE-----

步骤2:绑定SSL证书

准备好以上材料，需要进行如下操作进行，登陆API网关管理控制台【开放API】-【分组管理】，单击您需要绑定SSL证书的分组，查看分组详情

在绑定SSL证书，您首先需要您在API分组上绑定【独立域名】

【独立域名】-添加SSL证书

• 证书名称：用户自定义名称，以供后续识别
• 证书内容：证书的完整内容，需要复制XXXXX.pem 中的全部内容

私钥：证书的私钥，需要复制XXXXX.key中的内容。点击【确定】后，完成SSL证书的绑定。

步骤3：API配置调整

绑定SSL证书后，您可以按API控制不同的访问方式，支持HTTP、HTTPS、HTTP和HTTPS三种，出于安全考虑，建议全部配置成HTTPS。

可以在【开放API】-【API列表】找到相应API，【API定义】-编辑-【请求基础定义】中进行修改。

API支持的协议包括：

• • HTTP：只允许HTTP访问，不允许HTTPS
  • HTTPS：只允许HTTPS访问，不允许HTTP
  • HTTP和HTTPS：两者均可调整后，API支持HTTPS协议配置完成。您的API将支持HTTPS访问。

2、API定义

创建 API 即在 API 网关录入 API 的定义。您需要定义 API 的基本信息、服务信息、请求信息、返回信息。

• 网关支持您配置对入参的预校验规则，让网关成为您后端服务的第一道关卡。
• 网关支持您配置前端和后端的全映射，即参数混排。如您可以让您的用户在 Query 传入参数，但是您后端从 Header 里接收，等等。以满足您需要将服务包装变形输出。
• 网关支持您配置常量参数、系统参数，这些参数对您的用户不可见，但是网关可以在中转时将常量参数、系统参数加入请求中，传递至后端服务，满足您后端的一些业务需求。比如您需要网关每次向您发送请求都带有一个 keyword aligateway，您就可以把 aligateway 配置为常量参数，并指定接收的位置。

2.1、API的基本信息

API 的基本信息：分组、API 名称、API 类型、API 认证方式、描述。 

组内的API类型有公开、私有，私有除非有APP得到了授权，默认不会随分组上线  

• API 创建时需要选择分组。分组是 API 的管理单元，创建 API 之前您需要先创建分组（ API 分组的详细说明见 API 开放），选择分组即选择 Region。

• 安全认证方式：是 API 请求的认证方式，目前支持 阿里云APP、OpenID Connect 和 无认证 三种认证方式。

  1. 阿里云APP：认证方式即要求请求者调用该 API 时能够通过对APP的身份认证。
  2. OpenID Connect：是一套基于 OAuth 2.0 协议的轻量级规范，提供通过RESTful APIs 进行身份交互的框架。可以使用OpenID Connect和您的自有账号系统无缝对接，详细介绍请参照 OpenID Connect。
  3. 无认证：认证方式即任何人知晓该 API 的请求定义后，均可发起请求，网关不对其做身份验证，均会转发至您后端服务。

 API 类型分为公开和私有两种。

• 私有类型的API ，当所在分组上架云市场时，默认不包括该类型的 API 。如果有用户想要调用您的 API ，您需要主动操作授权，否则用户无渠道获取 API 信息。
• 公有类型的API ，所有用户

  均有机会在 发现 API 页面看到 API 的部分信息。公开 类型的 API 都会跟 API 分组上架到云市场，供用户购买和调用。

   

2.2、API的前端定义

定义用户如何请求 API ，包括协议、Method、Path、入参的定义。

录入的参数，包括 Path 中的动态参数、Headers 参数、Query 参数、Body 参数（非二进制）、常量参数、系统参数，参数名称保证全局唯一。

• 协议及method。 API 调用支持 HTTP/HTTPS 协议。
• Method 方法可选择 PUT、GET、POST、DELETE、HEAD。
• Path。Path 指相对于服务 host， API 的请求路径。请求 Path 可以与后端服务实际 Path 不同，您可以随意撰写合法的有明确语义的 Path 给用户使用。您可以在请求 Path 中配置动态参数，即要求用户在 Path 中传入参数，同时您的后端又可以不在 Path 中接收，可以映射为在 Query、Header 等位置接收。在 开放 API 接入 API 网关 中，有详细的举例说明，更有清晰的截图展示。
• 入参。定义您 API 的请求入参，即配置用户需要在什么位置传入什么参数。可选位置有Head、Query、Body、Path（Parameter Path），尤其当您在 Path 中配置了动态参数，那么在入参配置时需要对动态参数做配置说明。支持的参数类型有 String、Number、Boolean。
• 参数校验规则。每个入参后可点击 编辑更多 配置校验规则。如 String 的长度，Number 的枚举等等。网关会参照校验规则对请求做初步校验，如果入参不合法，则不会到达您的后端服务，大大的降低了后端服务的压力。

配置请求 path

Path 就是您调用 API 时，Url 中 .com 后到 ？ 之前的部分，Path 包含动态参数的情况在后续的后端配置步骤中详细说明。
举例说明：比如您调用的 Url 前部分为：https://globalservice.api.com/getapilist?command=...
那么您的 Path 就是：/getapilist 

前端入参

参数映射：请求参数映射，前端和后端都支持参数映射，path中支持动态参数！
结果映射： 返回结果目前是直接转发给前端的。
参数类型：
head参数、请求参数、动态参数
body参数：post模式下使用，二进制方式和form方式二选一 
常量参数和系统参数 API 的请求者不可见，由网关在请求后端服务时添加上。 
常量参数：比如您的后端需要接收一个常量，但是这个常量您不希望被您的客户看见，那么就设置一个常量参数，可以在 Header 或者 Query 里面接收。 
系统参数：比如您需要获取客户调用 API 时用的 APP 的 ID 来做日志统计，可在系统参数配置，在 Header 或者 Query 里面接收。建议后端接收 CaRequestId 字段，每个请求一个 ID 唯一，便于问题定位和建立全量日志，再如clientIp。

body是否二进制：只能前后端都为二进制或者都为 form

参数校验：支持参数类型、参数值（范围、枚举、正则、Json Schema）校验，无效校验直接会被 API 网关拒绝

另外，API 网关入参配置是支持混排的，把所有参数在一起配置，然后选择参数的位置是 Header、Query 还是 Body，甚至是在 Path上。

2.3、API的后端定义

定义一些参数的前后端映射，具体描述的后端真实服务的 API 配置。

用户请求到达网关后，网关会根据后端配置映射为对应实际后端服务的请求形式，去请求后端。

API的后端定义包括后端服务地址、后端Path、后端超时时间、参数映射、常量参数、系统参数。

• 后端访问协议定义：http、https
• 后端服务地址。后端服务的 host，可以是一个域名，也可以是 http(s)://host:port 的形式。
• 后端 Path。Path 是您的 API 服务在您后端服务器上的请求路径，实际请求路径。若您后端 Path 需要接收动态参数，那么需要声明该参数是调用者从哪个位置哪个参数传入的，即声明映射关系。
• 后端超时时间。指 API 请求到达网关后，网关去调 API 后端服务的响应时间。由网关请求后端开始到网关收到后端返回结果。该值不能超过30秒。超过该值网关会放弃请求后端服务，并给用户返回相应的错误信息。
• 参数映射。网关支持参数在前端、后端的全映射，包括名称映射和位置映射。位置映射包括 Path、Header、Query、Body 的混排映射。也就是说，您可以将您的后端服务通过映射完成包装成更规范、更专业的 API 形态。这部分就是在声明前后端 API 映射关系的。在 开放 API 接入 API 网关 中，有详细的举例说明，更有清晰的截图展示。注意前后端参数名称不能重复。
• 常量参数。比如您需要网关每次请求您后端时都带有标记 apigateway，那么您可以直接将标记配置为常量参数。常量参数对您的用户不可见，请求达到网关后，网关会自动在指定位置加上该参数再去请求您的后端。

• 系统参数。指 API 网关的系统参数，这些参数默认不会传递给您，但是如果您需要获取，您可以在 API 里配置接收位置和名称。具体内容如下表：

2.4、API 的结果定义

返回类型及示例，目前网关对于返回结果不做处理，直接透传给请求者。后续会支持用户定制化、格式化的定义返回信息。

多端输出：只需调整API定义，即可实现对APP、设备、web端等多种终端的支持

3、API文档生成

自动生成 API 文档，可供在线查看！ 

https://apigateway.console.aliyun.com/?spm=5176.doc29496.2.1.cEmnVJ#/cn-hangzhou/apis/detail/66bc382db8344b3b93056c696fab49a8/749965cee13e40af9b2487d0b3380cde/definition

4、API SDK文档下载

  

5、以函数计算作为 API 网关后端服务

API网关调用函数服务时，会将API的相关数据包装为一个Map形式传给函数计算服务，函数计算服务处理后，需要按照图中Output Format的格式返回statusCode，headers，body等相关数据，API gateway再将函数计算返回的内容映射到statusCode，header,body等位置返回给客户端。

函数计算（Function Compute）是一个事件驱动的服务，通过函数计算，用户无需管理服务器等运行情况，只需编写代码并上传，函数计算准备计算资源，并以弹性伸缩的方式运行用户代码。而用户只需根据实际代码运行所消耗的资源付费。

详细了解请查看函数计算帮助文档。

API网关与函数计算对接，可以让您以API形式开放您的函数，并且解决认证、流量控制、数据转换等问题(查看API网关功能） ，让您的函数服务可以安全、简单的以API形式对外开放。