阿里云API网关(6)用户指南(开放 API )

时间:2021-06-16 14:36:35

网关指南: 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运行情况。

八、使用限制

阿里云API网关(6)用户指南(开放 API )

九、专属VDC环境

阿里云API网关(6)用户指南(开放 API )

十、MOCK api

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

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

配置 Mock

在 API 编辑页面——后端基础定义,来配置 Mock。阿里云API网关(6)用户指南(开放 API )

  1. 选择 Mock 模式

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

    阿里云API网关(6)用户指南(开放 API )

  2. 填写 Mock 返回结果

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

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

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

  3. 调试

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

    阿里云API网关(6)用户指南(开放 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等位置返回给客户端。

阿里云API网关(6)用户指南(开放 API )

2 快速配置API

配置方法:

阿里云API网关(6)用户指南(开放 API )

2.1 创建函数计算的Function

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

阿里云API网关(6)用户指南(开放 API )

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

阿里云API网关(6)用户指南(开放 API )

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

2.2 配置跨服务授权Role和policy

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

1)到RAM控制台创建角色,去往RAM控制台。在“角色管理”页面,点击“创建角色”。阿里云API网关(6)用户指南(开放 API )

阿里云API网关(6)用户指南(开放 API )

阿里云API网关(6)用户指南(开放 API )

2) 绑定角色授权策略

阿里云API网关(6)用户指南(开放 API )

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

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

阿里云API网关(6)用户指南(开放 API )

阿里云API网关(6)用户指南(开放 API )

图中策略内容为:

  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网关(6)用户指南(开放 API )

  • 区域:函数计算对应的区域,当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. };
  25. //对body内容进行Base64编码,可根据需要处理
  26. var base64EncodeStr=new Buffer(JSON.stringify(responseBody)).toString('base64');
  27. //FC给API网关返回的格式,须如下所示。isBase64Encoded根据body是否Base64编码情况设置
  28. var response = {
  29. isBase64Encoded:true,
  30. statusCode: responseCode,
  31. headers: {
  32. "x-custom-header" : "header value"
  33. },
  34. body: base64EncodeStr
  35. };
  36. console.log("response: " + JSON.stringify(response));
  37. callback(null, response);
  38. };

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

  1. /fc/test/invoke/[type]。
  1. POST http://test.alicloudapi.com/fc/test/invoke/test?param1=aaa&param2=bbb
  2. "X-Ca-Signature-Headers":"X-Ca-Timestamp,X-Ca-Version,X-Ca-Key,X-Ca-Stage",
  3. "X-Ca-Signature":"TnoBldxxRHrFferGlzzkGcQsaezK+ZzySloKqCOsv2U=",
  4. "X-Ca-Stage":"RELEASE",
  5. "X-Ca-Timestamp":"1496652763510",
  6. "Content-Type":"application/x-www-form-urlencoded; charset=utf-8",
  7. "X-Ca-Version":"1",
  8. "User-Agent":"Apache-HttpClient\/4.1.2 (java 1.6)",
  9. "Host":"test.alicloudapi.com",
  10. "X-Ca-Key":"testKey",
  11. "Date":"Mon, 05 Jun 2017 08:52:43 GMT","Accept":"application/json",
  12. "headerParam":"testHeader"
  13. {"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
  11. {"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网关(6)用户指南(开放 API )

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

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

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

4.1 配置方法

4.1.1 定义环境变量

1)您可以在【开放API】-【API分组】菜单找到环境配置按钮:阿里云API网关(6)用户指南(开放 API )

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

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

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

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

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

下面以Service为例介绍:

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

那么我需要测试、预发、线上分别定义一个Service的变量,并填写相应Value阿里云API网关(6)用户指南(开放 API )

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

4.1.2 定义API

在定义API是可以在Service、Function的位置用“#”隔开,输入您环境变量的Name,如图:阿里云API网关(6)用户指南(开放 API )

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

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分组上绑定【独立域名】阿里云API网关(6)用户指南(开放 API )

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

阿里云API网关(6)用户指南(开放 API )

  • 证书名称:用户自定义名称,以供后续识别
  • 证书内容:证书的完整内容,需要复制XXXXX.pem 中的全部内容
  • 私钥:证书的私钥,需要复制XXXXX.key中的内容。点击【确定】后,完成SSL证书的绑定。

    步骤3:API配置调整

阿里云API网关(6)用户指南(开放 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访问。