阿里云API网关（6）用户指南（开放 API ）

网关指南： https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl

网关控制台： https://apigateway.console.aliyun.com/?spm=5176.doc42740.2.2.Q4z5ws#/cn-hangzhou/apis/list

一、概述

API 网关（API Gateway），提供高性能、高可用的API托管服务，帮助您对外开放您部署在ECS、容器服务等阿里云产品上的应用，为您提供完整的API发布、管理、维护生命周期管理。您只需简单操作，即可快速、低成本、低风险的开放数据或服务。

在 API 网关您可以：

• 管理您的 API

  您可以对API的整个生命周期进行管理，包括API的创建、测试、发布、下线、版本切换等操作。

• 便捷转换数据

  支持自定义映射规则，您可以配置映射将调用请求转换成后端需要的格式。

• 预设请求校验

  您可以预先设置参数类型、参数值（范围、枚举、正则、Json Schema）校验，由网关帮助您过滤掉非法请求，减少您的后端对非法请求的处理成本。

• 灵活控制流量

  您可以对API、用户、应用设置按分钟、小时、天的调用量控制。您还可以设置特例用户或者应用，对某个用户或应用单独配置流量控制。

• 轻松安全防护

  支持 Appkey 认证，HMAC（SHA-1,SHA-256）算法签名。

  支持 SSL/TSL 加密，并借助阿里云盾防病毒、防攻击。

• 全面监控与报警

  为您提供可视化 API 实时监控，包括：调用量、调用方式、响应时间、错误率，并支持历史情况查询，以便统筹分析。您还可以配置预警方式（短信、Email）,订阅预警信息，以便实时掌握 API 运行情况。

• 降低开放成本

  为您自动生成 API 文档和 SDK（服务端、移动端），降低 API 开放成本。

二、创建api

API 创建

更新时间：2017-07-05 14:50:55   分享：

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

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

第一部分：定义请求的基本信息

API 基本信息包括 API 分组、 API 名称、安全认证方式、 API 类型、描述。

• 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 类型分为公开和私有两种。

  1.私有 类型的 API ，当所在分组上架云市场时，默认不包括该类型的 API 。如果有用户想要调用您的 API ，您需要主动操作授权，否则用户无渠道获取 API 信息。
  2.公开 类型的 API ，所有用户均有机会在 发现 API页面看到 API 的部分信息。公开 类型的 API 都会跟 API 分组上架到云市场，供用户购买和调用。

第二部分：定义 API 请求

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

• 协议及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 的枚举等等。网关会参照校验规则对请求做初步校验，如果入参不合法，则不会到达您的后端服务，大大的降低了后端服务的压力。

第三部分：定义后端服务信息

这部分主要是定义一些参数的前后端映射，具体描述的是您后端真实服务的 API 配置。用户请求到达网关后，网关会根据您的后端配置映射为对应实际后端服务的请求形式，去请求您的后端。包括后端服务地址、后端Path、后端超时时间、参数映射、常量参数、系统参数。

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

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

  参数名称	参数含义
  CaClientIp	发送请求的客户端IP
  CaDomain	发送请求的域名
  CaRequestHandleTime	请求时间（格林威治时间）
  CaAppId	请求的APP的ID
  CaRequestId	RequestId
  CaApiName	API 名称
  CaHttpSchema	用户调用 API 使用的协议，http或者https
  CaProxy	代理（AliCloudApiGateway）

  注意：您所有录入的参数，包括 Path 中的动态参数、Headers 参数、Query 参数、Body 参数（非二进制）、常量参数、系统参数，参数名称保证全局唯一。即如果您同时在 Headers 和 Query 里各有一个名为 name 的参数，是不允许的。

完成以上定义后，您就完成了 API 的创建。下一步您可以发布、测试并开放 API 服务到市场，还可以为 API 绑定签名密钥和流量控制等安全配置。

三、开放api

API 创建完成后，您就可以开放 API 服务了。要开放 API 服务您需要绑定一个在阿里云系统备案成功的独立域名，且该域名要完成 CNAME 解析。而独立域名是绑定在 API 分组上面的，所以在这个部分为您详细说明一下开放 API 服务需要了解的 API 分组和域名。

第一部分：API 分组

API 分组是 API 的管理单元。您创建 API 之前，需要先创建分组，然后在某个分组下创建 API。分组包含名称、描述、区域（Region）、域名几大属性。

• 分组的区域（Region）在分组创建时选定不可更改。创建 API 时，如果选定分组那么 Region 也一同选定，不可更改。
• 每个账号 API 分组个数上限为50个，每个分组 API 个数上限为200个。
• 域名。分组创建时，系统会为分组分配一个二级域名。如果需要开放 API 服务，您需要为分组绑定一个在阿里云系统备案成功的独立域名，且将独立域名 CNAME 到相应的二级域名上。每个分组最多只能绑定5个独立域名。具体请看下文——域名及证书。

第二部分：环境管理

关于环境需要理解两个概念，环境和环境变量。

• 环境是 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 将无法正常调用。

第三部分：域名及证书

API 网关通过域名来定位到一个唯一的 API 分组，再通过 Path+HTTPMethod 确定唯一的 API 。如果要开放 API 服务，您需要了解 二级域名 和 独立域名。

• 二级域名是分组创建时系统分配的，唯一且不可更改。在您还没有独立域名之前，您可以通过访问二级域名来测试调用您的 API 。二级域名仅能用于测试，默认每天只能请求1000次。

• 独立域名即自定义域名，是您开放 API 服务需要绑定的，用户通过访问您的独立域名来调用您开放的 API 服务。您可以为一个分组绑定多个独立域名，上限为5个。对于独立域名的配置您需要注意以下几点：

  • 独立域名不必须是根域名，可以是二级、三级域名。

  • 独立域名如果尚未备案，则可以在阿里云做 首次备案。

  • 独立域名若已在其他系统备案，则需要在阿里云做 备案接入。

  • 独立域名需要 CNAME 解析到分组的二级域名上。

  • 满足上述的备案和解析两个要求，域名才能成功绑定。

• 当您的 API 服务支持 HTTPS 协议时，需要为该域名上传 SSL 证书，在 分组详情 页面进行添加即可。SSL 证书上传不支持文件上传，需要填写 证书名称、内容 和 私钥。

第四部分：测试、线上、授权

通过上述操作您已经完成 API 的创建和域名绑定，接下来就可以将 API 发布到测试或者线上环境，进行调试和开放了。其中一个重要的环节是授权，授权即授予某个 APP 可以调用某个 API 的权限。

• 当您完成 API 创建之后，您就可以将 API 发布到测试或者线上，并给自己创建的 APP 授权，通过访问二级域名来调用指定环境中的 API，进行测试。
• 成功绑定独立域名之后，您的 API 就可以在市场上架，供客户购买、调用。您还可以不经过购买将 API 授权给合作伙伴的 APP，供其调用。

至此，您完成 API 服务的开放。在 API 创建到开放的整个过程中，您还可以随时操作 API 的创建、修改、删除、查看、测试、发布、下线、授权、解除授权、发布历史及版本切换等操作。

四、管理API

API 定义就是指您创建 API 时对 API 的请求结构的各方面定义。您可以在控制台完成 API 定义的查看、编辑、删除、创建、复制。您需要注意以下几点：

• 当您需要编辑某个 API 的定义时，如果该 API 已经发布，对定义的修改不会对线上产生影响，定义修改后需要再次发布才能把修改后的定义同步到线上环境。
• 当您想要删除某个 API，如果该 API 已经发布，则不允许直接删除 API 定义，需要先将 API 下线，然后删除。
• API 网关为您提供了复制定义的功能。您可以从测试环境/线上环境复制线上的定义覆盖当前的最新定义，然后重新点击编辑进行修改。

API 发布管理

当您完成 API 的创建后，您可以将 API 发布到测试或者线上。也可以将测试或者线上的 API 下线。您需要注意以下几点：

• API 创建完成后，发布到某环境，通过二级域名或者独立域名访问时，需要在请求的Header指定要请求的环境，参见 请求示例。
• 当您要发布某个 API 时，如果该 API 在测试或者线上已经有版本在运行，您的此次发布将使测试或者线上的该 API 被覆盖，实时生效。但是历史版本及定义会有记录，您可以快速回滚。
• 您可以将测试或者线上的某个 API 下线，下线之后，与策略、密钥、 APP 的绑定或者授权关系依然存在，再次上线时会自动生效。如果要解除关系，需要专门操作删除。

API 授权管理

您的 API 如果上架到市场，那么购买者有权利操作给自己的某个 APP 授权。

如果不经过购买行为，您需要在线下跟合作伙伴建立使用关系，那么您需要通过授权来建立 API 和 APP 的权限关系。您将 API 发布到线上环境后，需要给客户的 APP 授权，客户才能用该 APP 进行调用。您有权对此类授权操作建立或者解除某个 API 与某个 APP 的授权关系， API 网关会对权限关系进行验证。操作授权时，您需要注意以下几点：

• 您可以将一个或者多个 API 授权给一个或者多个 APP 。批量操作时，建议不要同时操作多个分组下的 API 。
• 批量操作时，先选择 API 后选择环境。比如一个 API 在测试和线上均有发布，最后选择了测试，就只会将测试下的该 API 授权。
• 您可以通过客户提供给您的AppID或者阿里云邮箱账号来定位 APP 。
• 当您需要解除某个 API 下某个 APP 的授权时，您可以查看 API 的授权列表，在列表页进行解除。

历史与版本切换

您可以查看您每个 API 的发布历史记录，包括每次发布的版本号、说明、环境、时间和具体定义内容。

查看历史时，您可以选定某个版本然后操作切换到此版本，该操作会使该版本直接在指定环境中替换之前的版本，实时生效。

五、签名密钥

什么是签名密钥

签名密钥是由您创建的一对 Key 和 Secret，相当于您给网关颁发了一个账号密码，网关向您后端服务请求时会将密钥计算后一起传过去，您后端获取相应的字符串做对称计算，就可以对网关做身份验证。使用时您需要了解以下几点：

• 创建密钥时需要选择 Region，Region 一旦选定不能更改，而且密钥只能被绑定到同一个 Region 下的API上。
• 一个 API 仅能绑定一个密钥，密钥可以被替换和修改，可以与 API 绑定或者解绑。
• 您将密钥绑定到 API 之后，由网关抛向您服务后端的该 API 的请求均会加上签名信息。您需要在后端做对称计算来解析签名信息，从而验证网关的身份。具体 HTTP 加签说明请查看文档——后端签名密钥说明文档

密钥泄露 修改替换

当您遇到如下情况：

• 您的某一个密钥发生了泄露，您可能想要保留该密钥与 API 的绑定关系，但是想要修改密钥的 Key 和 Secret。

• 当您操作将密钥应用于 API 时，可能该 API 已经绑定了某个密钥，需要替换密钥。

以上两种情况都建议按照下面的流程来操作：

1. 先在后端同时支持两个密钥：原来的密钥和即将修改或替换的密钥，确保切换过程中的请求能够通过签名验证，不受修改或替换的影响。
2. 后端配置完备后，完成修改，确定新 Key 和 Secret 生效后再将之前已泄露或废弃的密钥删除。

六、流量控制策略

流量控制策略和 API 分别是独立管理的，操作两者绑定后，流控策略才会对已绑定的 API 起作用。

在已有的流量控制策略上，可以额外配置特殊用户和特殊应用（APP），这些特例也是针对当前策略已绑定的API生效。

流量控制策略可以配置对 API、用户、应用三个对象的流控值，流控的单位可以是分钟、小时、天。使用流量控制策略您需要了解以下几点：

• 流量控制策略可以涵盖下表中的维度：

  API 流量限制	该策略绑定的API在单位时间内被调用的次数不能超过设定值，单位时间可选分钟、小时、天，如5000次/分钟。
  APP 流量限制	每个APP对该策略绑定的任何一个API在单位时间内的调用次数不能超过设定值。如50000次/小时。
  用户流量限制	每个阿里云账号对该策略绑定的任何一个 API 在单位时间内的调用次数不能超过设定值。一个阿里云账号可能有多个 APP，所以对阿里云账号的流量限制就是对该账号下所有 APP 的流量总和的限制。如 50 万次/天。

  此外，您可以在流控策略下添加特殊应用（APP）和特殊用户。对于特例，流控策略基础的 API 流量限制 依然有效，您需要额外设定一个阈值作为该 APP 或者该用户的流量限制值，该值不能超过策略的 API流量限制 值，同时流控策略基础的 APP流量限制 和 用户流量限制 对该 APP 或用户失效。

• 与签名密钥相似，当您创建流量控制策略时，需要选择 Region，Region 一旦选定不可更改，且仅能被应用于同一个 Region 下的 API。

• 由于 API 网关限制，当您设置 API 流量限制 值时，考虑每个 API 分组的默认流控上限是500QPS（该值可以通过提交工单申请提高）。

• 绑定 API。您可以将策略绑定于多个 API，流控策略的限制值和特例将对该策略绑定的每一个 API 单独生效。当您绑定 API 时，如果该 API 已经与某个策略绑定，您的此次操作将替换之前的策略，实时生效。

• 特殊对象。如果您想要添加特殊应用或者特殊用户，您需要获得应用 ID 即 AppID 或者用户的阿里云邮箱账号。

• 在 API 网关控制台，您可以完成对流量控制策略的创建、修改、删除、查看等基本操作。还有流控策略与 API 的绑定解绑，流量控制策略特殊对象的添加删除等操作。

七、监控预警

• API网关为您提供可视化的实时监控和预警。您可以获得您开放的API被调用数据，包括调用量、流量、响应时间、错误分布等多个维度、多种时间单位的数据统计结果。同时支持历史数据查询，以便您统筹分析。
• 后续我们会陆续支持报表输出，给您提供最周到的数据支持。
• 您还可以配置预警，以便实时掌握API运行情况。

八、使用限制

九、专属VDC环境

十、MOCK api

在项目开发过程中，往往是多个合作方一同开发，多个合作方相互依赖，而这种依赖在项目过程中会造成相互制约，理解误差也会影响开发进度，甚至影响项目的工期。所以在开发过程中，一般都会使用 Mock 来模拟最初预定的返回结果，来降低理解偏差，从而提升开发效率。

API 网关也支持 Mock 模式的简单配置。

配置 Mock

在 API 编辑页面——后端基础定义，来配置 Mock。

1. 选择 Mock 模式

   可以选择使用 Mock 或者不使用 Mock，选择使用 Mock 时会进行二次确认

   

2. 填写 Mock 返回结果

   Mock 返回结果，可以填写您真实的返回结果。目前支持是 Json、XMl、文本等格式作为 Mock 返回结果。如

   1. {
   2. "result": {
   3. "title": " API 网关 Mock 测试",
   5. }
   6. }

   保存后 Mock 设置成功，请根据实际需要 发布 到测试或线上环境进行测试，也可以在 API 调试页面进行调试。

3. 调试

   可以在调试 API 页面发起 API 调用来测试设置结果：

   

   这表示 Mock 设置成功。

解除 Mock

若您需要解除 Mock，可以将第一幅图中的 Mock，修改为 不使用 Mock 即可，而 Mock 返回结果中的值不会被清除，以便您进行下一次的 Mock 。修改完成后请 发布，只有发布后才会真正生效。

十一、以函数计算作为api

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

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

1 实现原理

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

2 快速配置API

配置方法：

2.1 创建函数计算的Function

1）到函数计算控制台创建Service。去往 函数计算控制台。如果您已经创建过Function，可以忽略此步。

2）在刚创建的Service下创建Function，点击“新建函数”。并输入您的代码,详细操作请参照创建函数。

3）触发器页面点击“跳过” 即可，最后点击完成。

2.2 配置跨服务授权Role和policy

在此步，您需要将此函数的调用权限授权给API网关。

1）到RAM控制台创建角色，去往RAM控制台。在“角色管理”页面，点击“创建角色”。

2) 绑定角色授权策略

该授权策略能访问账号下所有的Function。如果想限制授权范围，可以按照下面步骤新创建自定义策略，然后绑定。

3）创建自定义策略。在“策略管理”页面，点击“新建授权策略”。

图中策略内容为：

1. {
2. "Version": "1",
3. "Statement": [
4. {
5. "Effect": "Allow",
6. "Action": [
7. "fc:InvokeFunction"
8. ],
9. "Resource": [
10. "acs:fc:*:1227466664334133:services/apitest/functions/*"
11. ]
12. }
13. ]
14. }

其中的Resource代表要授权的资源，需要更改为自己账号下的资源。

• 当限定到某个具体的Function时，格式为 "acs:fc:*:[AccountId]:services/[ServiceName]/functions/[FunctionName]".

• 当要授权某个账号下的所有Function时，可以为"acs:fc:*:[AccountId]:services/*"

注意:当授权策略为单个Function时，后续更改Function，还需要重新修改该策略或者新增策略。

2.3 配置函数计算作为API后端服务

在API编辑中，在选择API后端服务时，选择“FunctionCompute”.

• 区域：函数计算对应的区域，当API和函数计算区域相同时，API通过内网调用函数计算，当区域不一样时，则走公网。
• RoleArn：因为最终是由API网关去调用函数计算，为跨服务调用，因此需要用户授权后，API网关才能成功调用。RoleArn为授权角色上的Arn. 可到RAM控制台角色详情中查看。

3 API网关和函数计算对接的格式要求

3.1 API网关给函数计算的输入格式

当以函数计算作为API网关的后端服务时，API网关会把请求参数通过一个固定的Map结构传给函数计算的入参event，函数计算通过如下结构去获取需要的参数，然后进行处理，该结构如下：

1. {
2. "path":"api request path",
3. "httpMethod":"request method name",
4. "headers":{all headers,including system headers},
5. "queryParameters":{query parameters},
6. "pathParameters":{path parameters},
7. "body":"string of request payload",
8. "isBase64Encoded":"true|false, indicate if the body is Base64-encode"
9. }

需要特别说明的是：当isBase64Encoded=true时，表明API网关传给函数计算的body内容是经过Base64编码的，函数计算需要先对body内容进行Base64解码后再处理。反之，isBase64Encoded=false时，表明API网关没有对body内容进行Base64编码。

3.2 函数计算给API网关的输出格式

同时，函数计算需要将输出内容通过如下JSON格式返回给API网关，方便API网关解析。

1. {
2. "isBase64Encoded":true|false,
3. "statusCode":httpStatusCode,
4. "headers":{response headers},
5. "body":"..."
6. }

说明：

1) 当body内容为二进制时，需在函数计算中对body内容进行Base64编码，同时设置isBase64Encoded=true。如果body无需Base64编码，isBase64Encoded可以设置为false。API网关会对isBase64Encoded=true的body内容进行Base64解码后再透出给客户端。

2) 在nodejs版本的函数计算中，callback需要根据不同的情况进行设置。 当返回一个成功的请求， callback{null,{“statusCode”:200,”body”:”…”}}。需要抛一个异常时，callback{new Error(‘internal server error’),null}。当返回一个客户端错误 callback{null,{“statusCode”:400,”body”:”param error”}}。

3) 如果函数计算返回不符合上面的格式要求，API网关将返回503 Service Unavailable给客户端。

3.3 示例

如在函数计算中配置一个demo程序：

这是一个撞墙式返回程序的代码示例，会原装返回您所有的请求内容。

1. module.exports.handler = function(event, context, callback) {
2. var responseCode = 200;
3. console.log("request: " + JSON.stringify(event.toString()));
4. //将event转化为JSON对象
5. event=JSON.parse(event.toString());
6. var isBase64Encoded=false;
7. //根据用户输入的statusCode返回，可用于测试不同statusCode的情况
8. if (event.queryParameters !== null && event.queryParameters !== undefined) {
9. if (event.queryParameters.httpStatus !== undefined && event.queryParameters.httpStatus !== null && event.queryParameters.httpStatus !== "") {
10. console.log("Received http status: " + event.queryParameters.httpStatus);
11. responseCode = event.queryParameters.httpStatus;
12. }
13. }
14. //如果body是Base64编码的，FC中需要对body内容进行解码
15. if(event.body!==null&&event.body!==undefined){
16. if(event.isBase64Encoded!==null&&event.isBase64Encoded!==undefined&&event.isBase64Encoded){
17. event.body=new Buffer(event.body,'base64').toString();
18. }
19. }
20. //input是API网关给FC的输入内容
21. var responseBody = {
22. message: "Hello World!",
23. input: event
24. };
26. //对body内容进行Base64编码，可根据需要处理
27. var base64EncodeStr=new Buffer(JSON.stringify(responseBody)).toString('base64');
29. //FC给API网关返回的格式，须如下所示。isBase64Encoded根据body是否Base64编码情况设置
30. var response = {
31. isBase64Encoded:true,
32. statusCode: responseCode,
33. headers: {
34. "x-custom-header" : "header value"
35. },
36. body: base64EncodeStr
37. };
38. console.log("response: " + JSON.stringify(response));
39. callback(null, response);
40. };

以POST form形式请求如下一个API的url, path为：

1. /fc/test/invoke/[type]。

1. POST http://test.alicloudapi.com/fc/test/invoke/test?param1=aaa&param2=bbb
3. "X-Ca-Signature-Headers":"X-Ca-Timestamp,X-Ca-Version,X-Ca-Key,X-Ca-Stage",
4. "X-Ca-Signature":"TnoBldxxRHrFferGlzzkGcQsaezK+ZzySloKqCOsv2U=",
5. "X-Ca-Stage":"RELEASE",
6. "X-Ca-Timestamp":"1496652763510",
7. "Content-Type":"application/x-www-form-urlencoded; charset=utf-8",
8. "X-Ca-Version":"1",
9. "User-Agent":"Apache-HttpClient\/4.1.2 (java 1.6)",
10. "Host":"test.alicloudapi.com",
11. "X-Ca-Key":"testKey",
12. "Date":"Mon, 05 Jun 2017 08:52:43 GMT","Accept":"application/json",
13. "headerParam":"testHeader"
15. {"bodyParam":"testBody"}

API网关返回内容：

1. 200
2. Date: Mon, 05 Jun 2017 08:52:43 GMT
3. Content-Type: application/json; charset=UTF-8
4. Content-Length: 429
5. Access-Control-Allow-Origin: *
6. Access-Control-Allow-Methods: GET,POST,PUT,DELETE,HEAD,OPTIONS , PATCH
7. Access-Control-Allow-Headers: X-Requested-With, X-Sequence,X-Ca-Key,X-Ca-Secret,X-Ca-Version,X-Ca-Timestamp,X-Ca-Nonce,X-Ca-API-Key,X-Ca-Stage,X-Ca-Client-DeviceId,X-Ca-Client-AppId,X-Ca-Signature,X-Ca-Signature-Headers,X-Forwarded-For,X-Ca-Date,X-Ca-Request-Mode,Authorization,Content-Type,Accept,Accept-Ranges,Cache-Control,Range,Content-MD5
8. Access-Control-Max-Age: 172800
9. X-Ca-Request-Id: 16E9D4B5-3A1C-445A-BEF1-4AD8E31434EC
10. x-custom-header: header value
12. {"message":"Hello World!","input":{"body":"{\"bodyParam\":\"testBody\"}","headers":{"X-Ca-Api-Gateway":"16E9D4B5-3A1C-445A-BEF1-4AD8E31434EC","headerParam":"testHeader","X-Forwarded-For":"100.81.146.152","Content-Type":"application/x-www-form-urlencoded; charset=UTF-8"},"httpMethod":"POST","isBase64Encoded":false,"path":"/fc/test/invoke/test","pathParameters":{"type":"test"},"queryParameters":{"param1":"aaa","param2":"bbb"}}}

4. 多环境

可以通过API网关的环境管理功能来实现测试环境的管理。目前每个API分组可以有三个环境：测试、预发和线上（后续会开放多个，实现自助管理）。

API网关，为避免用户测试、线上不停变化后端地址，增加环境级变量参数的来实现请求的自动路由。

环境级变量参数，即在每个环境中可以自定义公共常量参数。当用户发API调用时，可以在放置请求任意位置，传递给后端服务，以实现网关对请求的路由。

API网关将适配您请求中的环境参数信息来区分请求环境。

4.1 配置方法

4.1.1 定义环境变量

1)您可以在【开放API】-【API分组】菜单找到环境配置按钮：

2)在测试、预发、线上环境，分别新增一个变量。

• Name：是变量的名称，可以自行定义，但要保持三个环境中都有相同的变量名称。

  小提示：您如果有多个API，建议Name标识有实际意义，以便后续查询。

• Value：对应你在函数服务中的Service或者Function名称。

  注意：请按您实际的名称填写，否则可能造成无法调用。

下面以Service为例介绍：

比如：我有个函数服务，测试、预发、线上的名称分别为：TestServiceD、PreServiceD、ServiceD。

那么我需要测试、预发、线上分别定义一个Service的变量，并填写相应Value

函数名称，也可以同理录入，您可以录入一个叫Function的环境变量。

4.1.2 定义API

在定义API是可以在Service、Function的位置用“#”隔开，输入您环境变量的Name，如图：

注意：使用多环境后，将暂时无法使用“调试”功能

4.2 调用多环境API

发布您的API后，您即可发起API调用。

4.1 正式环境

直接发起您的API调用，即调用测试环境。

4.2 预发环境

您只需要在调用API时，在Header中增加入参X-Ca-Stage: RELEASE 即可访问预发环境的API。

4.2 测试环境

您只需要在调用API时，在Header中增加入参X-Ca-Stage: TEST 即可访问测试环境的API。

5. FAQ

1. 为什么我无法录入我已有的Function？

   函数计算服务由很严格的权限控制机制，所以您必须授权API网关可以使用，因此请在确认您的Function存在，并且可用的情况下，检查一下授权关系是否存在。

2. 我是否可以将多个Function作为API的后端服务？

   不可以，目前API和Function是一对一的关系存在。

十二、支持HTTPS

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

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

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

步骤1:准备

您需要准备如下材料：

• 一个自有可控域名。

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

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

  示例：

  KEY

  1. -----BEGIN RSA PRIVATE KEY-----
  2. MIIEpAIBAAKCAQEA8GjIleJ7rlo86mtbwcDnUfqzTQAm4b3zZEo1aKsfAuwcvCud
  3. ....
  4. -----END RSA PRIVATE KEY-----

  PEM

  1. -----BEGIN CERTIFICATE-----
  2. MIIFtDCCBJygAwIBAgIQRgWF1j00cozRl1pZ+ultKTANBgkqhkiG9w0BAQsFADBP
  3. ...
  4. -----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访问。