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 的创建、修改、删除、查看、测试、发布、下线、授权、解除授权、发布历史及版本切换等操作。

十、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 测试",
   4. }
   5. }

   保存后 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. };
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网关，为避免用户测试、线上不停变化后端地址，增加环境级变量参数的来实现请求的自动路由。

环境级变量参数，即在每个环境中可以自定义公共常量参数。当用户发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访问。