操作指南（开放API）

概览

使用场景

概览展示所有分组下的API按请求次数、请求流量、返回流量、响应时间、总错误次数的数据统计，方便用户全面掌握自己全部API的运行情况。

操作步骤：
1. 登录API网关控制台。
2. 在控制台顶部导航栏选择区域。
3. 在左侧菜单栏中，选择【概览】模块，进入概览页面，查看API的数据指标。

API分组

创建API分组

使用场景

API分组是同一种业务API的集合，您可通过API分组管理组内所有API，创建API前，需要先创建API分组。

操作步骤:
1. 登录API网关控制台。
2. 在控制台顶部导航栏选择区域。
3. 在左侧菜单栏中，选择【API分组】模块，进入分组列表页。
4. 单击“创建分组”按钮，弹出“创建分组”对话框，如图所示。填写“分组名称”、 “描述”。
5. 创建成功后，在【API分组】列表中就会显示该API分组，API网关会自动分配给该分组一个唯一且不可改变的三级域名，您可访问该三级域名测试该分组下的API，每天有1000次访问限制，对外开放API，需要绑定独立域名。
6. 点击“编辑”按钮，编辑该分组。
7. 点击“删除”按钮，可以对已创建的分组进行删除操作。


使用限制：

• 一个API只能属于某一个API分组。

• 每个分组中最多创建200个API。

后续操作

API分组创建成功后，您可以为此分组绑定独立域名，API调用者通过访问独立域名来调用您开放的API。

域名管理

使用场景

API 网关通过域名来定位到一个唯一的 API 分组，再通过Path+HTTPMethod 定位唯一的 API。

如要开放API服务，需要您先为分组绑定独立域名，绑定独立域名遵循的规则：

独立域名需要做备案，未备案的域名不能绑定。
将独立域名cname解析到到该分组三级域名下，先解析，后绑定。
如果API要支持https协议，则需要为该独立域名上传SSL证书，此证书不支持导入，您需要填写证书的名称、内容和密钥。
独立域名不必须是根域名，可以是二级、三级域名。

使用限制：

• 每个分组最多可以绑定5个独立域名。

• 每个三级域名每天最多可以访问1000次。

操作步骤
1. 登录API网关控制台。
2. 在控制台顶部导航栏选择区域。
3. 在左侧菜单栏中，选择【API分组】模块，进入分组列表页。
4. 选择分组名称，进入【API分组详情-域名管理】页面。也可点击“更多”按钮，选择“域名绑定”按钮，进入【API分组详情—域名管理】页面。
5. 点击“绑定域名”按钮，输入域名地址，点击确认按钮，绑定成功。注：该独立域名已备案且已解析到该分组三级域名上。
6. 当您的 API 服务支持 HTTPS 协议时，需要点击“添加SSL证书”按钮，输入证书和密钥，单击“确定”，添加SSL证书。如果需要修改，请重新输入新的证书或者密钥。
7. 如果该独立域名不再需要，点击“解除绑定”按钮，解除绑定独立域名。
后续操作

绑定独立域名成功后，您可以开始创建API，开放后端服务能力。

模型管理

使用场景

模型用于描述HTTP协议的请求数据和响应数据。API网关通过使用JSON Schema定义模型，用来描述用户API约定数据的组织方式，比如参数或者返回值有哪些字段，这些字段的取值范围等。同时，通过定义模型，并在用户创建的API中加以引用，用来做请求体参数转换，适配后端服务。

API网关模型定义基于JSON架构草案7的规范，但存在一定的条件限制：

仅支持创建元素属性为Object类型和Array类型的JSON Schema
模型Body详情字段类型type必填
Array类型的JSON Scheme, Array中每个元素仅支持设置一种类型。

API网关支持的模型可以参考如下定义：


{
 "required": ["name", "photoUrls"],
 "type": "object",
 "properties": {
  "id": {
   "format": "int64",
   "type": "integer"
  },
  "name": {
   "pattern": "^\\d{3}-\\d{2}-\\d{4}$",
   "type": "string"
  },
  "status": {
   "type": "string"
  },
  "dogProject": {
   "type": "object",
   "properties": {
    "id": {
     "format": "int64",
     "maximum": 100,
     "exclusiveMaximum": true,
     "type": "integer"
    },
    "name": {
     "maxLength": 10,
     "type": "string"
    }
   }
  }
 }
}

操作步骤
1. 登录API网关控制台。
2. 在控制台顶部导航栏选择区域。
3. 在左侧菜单栏中，选择【API分组】模块，进入分组列表页。
4. 选择分组名称，进入【API分组详情-模型管理】页面。也可点击“更多”按钮，选择“模型管理”按钮，进入【API分组详情—模型管理】页面。
5. 点击“创建模型”按钮，输入模型名称、描述、Content-Type、Body详情，点击确认按钮，创建模型成功。
6. 点击“编辑”按钮，编辑模型，判断模型有没有被API使用，若被API使用，则不能编辑此模型。
7. 如果模型不再需要，点击“删除”按钮，删除该模型。如果该模型被API正在使用，请先解除绑定，再删除模型。
8. 点击“查看”按钮，查看模型，只能查看不能修改。

环境管理

使用场景

API发布环境为测试环境、线上环境。每个分组会自动分配这两个环境，测试环境是创建API后，测试API使用。线上环境是开放API时使用，调用者可在生产环境上调用接口使用服务。

操作步骤
1. 登录API网关控制台。
2. 在控制台顶部导航栏选择区域。
3. 在左侧菜单栏中，选择【API分组】模块，进入分组列表页。
4. 选择分组名称，进入【API分组详情-环境管理】页面。也可点击“更多”按钮，选择“环境管理”按钮，进入【API分组详情—环境管理】页面。
5. 测试环境、线上环境，可复制地址调用API。

API管理

创建RESTfulAPI

使用场景

API提供方可将API接口注册在API网关中，将自身服务能力及数据开放给合作伙伴。

创建API主要分为三个步骤：

定义API请求
定义后端服务
定义返回结果


使用限制：

-   每个API最多创建100个参数。

操作步骤

一、进入控制台

登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，进入API列表页。
点击“创建API”按钮，选择“REST风格”API，进入【创建API】页面。

二、定义API请求

操作1. 请求基本定义

API名称：API名称标识需要在所属分组内唯一。
选择分组：API所属分组，如果未创建API分组，请先创建API分组，再创建API。
认证方式：

IAM认证：表示借助IAM服务进行安全认证。

APP认证：表示由API网关服务负责接口请求的安全认证。

无认证：即任何人都可访问API，网关不对其做身份认证，直接将请求转发至您的后端服务。这种方式无法保证您后端服务的安全，建议谨慎使用。
请求协议：网关支持 HTTP/HTTPS 协议。
路径：请求路径，支持 Path 参数变量，例如 /user/{user_id}
请求方法：支持 GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS
API 路径 + API 请求方法，是定位API 的唯一标识。
描述：API的备注信息

操作2. 入参定义

入参定义：API 网关支持入参映射和入参透传两种模式。
入参映射：即 API 网关在接收到您的 API 请求时，通过映射关系将请求转换成您后端服务需要的格式，定义此类 API 时，需添加前后端参数映射关系。
入参透传：即 API 网关在接收到 API 请求后，不对请求进行任何处理，直接转发到后端服务。
参数名：如果参数在“PATH”位置，那么参数名称需要和“请求路径”中的名称相同，支持 % - _ . # 特殊字符。
参数位置：选择参数在请求中的位置， Head、Query、Path。
类型：支持：String、Int、Float、Boolean。
必填：参数是否必填，如果选择是，请求API时，API 网关会校验用户的请求中是否包含了此参数，如果不包含此参数，则拒绝该请求。
默认值：当必填为否时生效。在用户请求中不包含此参数时，API 网关自动添加默认值发送给后端服务。
描述：对参数进行描述。
当请求方法为POST、PUT、PATCH时，需要设置请求body定义。

操作3. 请求示例

创建API时，请尽量填写请求示例，请求示例用于生成API文档，您可以通过API网关直接导出API文档提供给调用者参考使用。
点击“下一步”按钮，进入【定义后端服务】页面。

三、定义后端服务

操作1. 后端基础定义-HTTP/HTTPS类型

API的后端服务配置，是指配置真实的后端服务。API请求到达API网关后，API网关会根据您的后端配置映射为对应实际后端服务的请求形式，然后发送给后端服务。

后端类型目前支持HTTP/HTTPS、函数计算和Mock三种类型。如果是HTTPS 服务，需要后端服务必须有SSL 证书。

Http/Https类型后端：

后端地址：以http或https开头，域名或者IP，不包含Path
后端路径：后端服务Path是您的 API 服务在后端服务器上的实际请求路径，支持后端Path 参数变量，例如 /user/{user_id}
请求方法：支持 GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS
后端超时时间：API网关调用后端服务的响应时间，即由 API网关请求后端服务开始直至 API网关收到后端服务返回结果的时长，单位为毫秒。用户可根据自己实际情况设置，如响应时间设置为100毫秒，API网关请求后端响应时间超过该值，API网关会放弃请求后端，返回给用户相应的错误信息。

操作2. 后端基础定义-函数计算类型

API的后端服务配置，是指配置真实的后端服务。API请求到达API网关后，API网关会根据您的后端配置映射为对应实际后端服务的请求形式，然后发送给后端服务。
后端类型：后端是函数计算类型，函数计算是一个事件驱动的服务。函数的执行可以由事件驱动，即当某个事件发生时，该事件触发函数的执行。现在，函数计算支持以 API 网关作为事件源。当请求设置函数计算为后端服务的 API 时，API 网关会触发相应的函数，函数计算会将执行结果返回给 API 网关。区域选择：选择函数计算服务所在region。如果函数计算与 API 不在同一地域，将通过公网访问您的函数计算服务。若您对数据安全和网络延迟有较高要求，请选择API 与函数计算为同一地域。
选择应用：选择指定的应用
选择函数：选择指定的函数
版本：函数的版本
后端超时：API网关调用后端服务的响应时间，即由 API 网关请求后端服务开始直至 API 网关收到后端服务返回结果的时长。单位为毫秒。用户可根据自己实际情况设置，如响应时间设置为100毫秒，API网关请求后端响应时间超过该值，API网关会放弃请求后端，返回给用户相应的错误信息。

操作3. 后端基础定义-Mock类型

API的后端服务配置，是指配置真实的后端服务。API请求到达API网关后，API网关会根据您的后端配置映射为对应实际后端服务的请求形式，然后发送给后端服务。
后端类型：后端是Mock类型，Mock一般用于开发联调阶段。在项目初始阶段，后端服务没有开发完成的情况下，可以使用Mock模式，将预期结果固定返回给API调用方，以便调用者进行项目开发。
Mock 返回结果（必填）：可以填写您真实的返回结果。目前支持是 Json、XMl、文本等格式作为 Mock 返回结果。
Mock返回状态码：（选填，不填默认200）只能是数字。
Mock header：选填，返回header内容

操作4. 后端参数映射
映射参数：参数映射用于将API请求中的入参映射为实际后端服务的参数。映射参数默认会将入参以相同名称和参数位置进行映射。您也可以根据需求，变更参数的映射方式，例如将来源于

Path 的入参，映射为后端服务中 Query 参数。

操作5. 后端常量设置

您可以根据实际需求配置常量参数，常量参数不可见，API网关会在中转请求时，附带这些参数在请求的指定位置传递给后端，常量参数在每次 API 调用中都保持不变。

操作6. 映射模板

当定义API请求页面设置的请求方法为POST、PUT和PATCH时，您可以选择映射模板对请求body进行转换。关于如何填写映射模板请点击文本框上方链接“如何填写模板”。

如果解析模板失败，可以选择透传body或者返回415状态码。

操作7. 如何填写模板

通过映射模板将请求body转换成需要发送给上游服务的格式。映射模板基于lua脚本语言，根据映射后body的格式可能需要在模板中内嵌lua脚本代码

参考：

支持以下标签

<% lua_code -%>逐字运行lua代码

<%= lua_expression -%>填充lua表达式的结果

任何嵌入的Lua标签都使用-%>结束标签

例子:

原始body:

{
  "department": "produce",
  "categories": [
    "fruit",
    "vegetables"
  ],
  "bins": [
    {
      "category": "fruit",
      "type": "apples",
      "price": 1.99,
      "unit": "pound",
      "quantity": 232
    },
    {
      "category": "fruit",
      "type": "bananas",
      "price": 0.19,
      "unit": "each",
      "quantity": 112
    },
    {
      "category": "vegetables",
      "type": "carrots",
      "price": 1.29,
      "unit": "bag",
      "quantity": 57
    }
  ]
}

映射模板：

{
  "choices": [
    <% for i, item in pairs(bins) do -%>
    {
      "kind": "<%= item.type -%>",
      "suggestedPrice": "<%= item.price .. ' per ' .. item.unit -%>",
      "available": "<%= item.quantity -%>" 
    }
      <% if next(bins, i) then -%>
        ,
      <% end -%>
    <% end -%>
  ]
}

映射模板说明：


{
  "choices": [
    -- 此行是内嵌的lua代码，表示遍历原始body的对象数组bins，并以key-value的形式存储在i-item变量中
    -- 此时i的值为数组索引1，2，3...，item为bins中的json对象
    <% for i, item in pairs(bins) do -%>
      {
        -- 嵌入lua表达式，表示bins数组中每个json对应字段的值，通过..符号连接字符串
        "kind": "<%= item.type -%>",
        -- 单引号内为字符串常量，如需空格也要加入在单引号内，例如' per '
        "suggestedPrice": "<%= item.price .. 'per' .. item.unit -%>",
        "available": "<%= item.quantity -%>" 
      }
      -- 判断bins对象数组是否为最后一个索引，在除了最后一个元素后添加逗号
      <% if next(bins, i) then -%>
        ,
      <% end -%>
    <% end -%>
  ]
}

映射结果：

{
  "choices": [
    {
      "kind": "apples",
      "suggestedPrice": "1.99 per pound",
      "available": 232
    },
    {
      "kind": "bananas",
      "suggestedPrice": "0.19 per each",
      "available": 112
    },
    {
      "kind": "carrots",
      "suggestedPrice": "1.29 per bag",
      "available": 57
    }
  ]
}

四、定义返回结果

操作1. 错误码定义：可以定义错误码和错误信息并进行描述

操作2. 最终响应Header：定义最终响应Header参数

操作3. 最终响应Body示例

最终响应Body示例填写，生成API文档使用。

操作4. 后端响应Header映射

当您希望对后端服务返回的响应header及body内容映射最终响应Header时，您选择后端响应Header映射。关于如何填写参数名称，请点击文本框上方链接“使用详情”查看。

操作5. 后端响应Body映射

当您希望对后端服务返回的响应body内容进行映射的时候，您可以选择映射模板对后端服务响应body进行转换。关于如何填写映射模板请点击文本框上方链接“如何填写模板”。如果解析模板失败，模板错误会在最终响应body显示。

测试模板解析：点击模板内容右上角的测试模板解析，弹出模板在线测试页面，对输入的后端响应body通过模板内容进行转换，并显示映射结果。如下图所示，左侧为后端响应body，右侧为通过映射模板解析出的转换结果（最终给客户返回的body）。

如何填写模板：同请求body映射，请参考前文：【三、定义后端服务】-【5.如何填写模板】。

操作6. 点击“提交”按钮，进入【API管理】列表页面。

后续操作

API创建成功后，发布API上线，您即可对外开放API。

创建AWS风格API

（REST风格API转换成AWS风格API）

操作步骤

一、进入控制台

登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，进入API列表页。
点击“创建API”按钮，选择“AWS风格”API，进入【创建API】页面。

二、定义API请求

API请求格式为：AWS风格

操作1. 请求基本定义

API名称：API名称标识需要在所属分组内唯一。
选择分组：API所属分组，如果未创建API分组，请先创建API分组，再创建API。
认证方式：目前仅支持IAM认证和无认证（即任何人都可访问API，网关不对其做身份认证，直接将请求转发至您的后端服务。这种方式不安全，不建议使用）方式。
请求协议：网关支持 HTTP/HTTPS 协议。
路径：/ ,只支持根目录。
请求方法：GET，无其他请求方法
描述：API的备注信息

操作2. 入参定义

入参定义：API 网关支持入参映射和入参透传两种模式。
入参映射：即 API 网关在接收到您的 API 请求时，通过映射关系将请求转换成您后端需要的格式，定义此类 API 时，需添加前后端参数映射关系。
入参透传：即 API 网关在接收到 API 请求后，不对请求进行任何处理，直接转发到后端服务。
参数名：参数的名称
类型：支持：String、Int、Float、Boolean。
必填：参数是否必填，如果选择是，请求API时，API 网关会校验用户的请求中是否包含了此参数，如果不包含此参数，则拒绝该请求。
默认值：“Action”做OpenAPI的公共参数，参数的默认值必须要填写，作为路径，定位API。由于AWS风格API的路由都是/，Kong识别不出来区别，所以需要人为的指定这个Action参数作为伪路由，供kong标识AWS风格API。
其它参数默认值选填.
描述：对参数进行描述。

操作3. 请求示例

请求示例填写，生成API文档使用。

点击“下一步”按钮，进入【定义后端服务】页面。

三、定义后端服务

API请求为AWS风格API，后端服务是REST风格API，前端和后端需要做转换。

操作1. 后端基础定义

API 的后端服务配置，是指配置真实的后端服务。API请求到达API网关后，API 网关会根据后端配置进行参数转换，然后发送给后端服务。

后端类型：目前支持 HTTP和HTTPS类型，如果是HTTPS 服务，需要后端服务必须有 SSL 证书。
后端地址：以http或https开头，域名或者IP，不包含Path
后端路径：后端服务Path是您的 API 服务在后端服务器上的实际请求路径，支持后端 Path 参数变量，例如 /user/{user_id}
请求方法：支持 GET、POST、DELETE、PUT、PATCH、HEAD、OPTIONS
后端超时时间：API网关调用后端服务的响应时间，即由 API 网关请求后端服务开始直至 API 网关收到后端返回结果的时长，单位为毫秒。用户可根据自己实际情况设置，如响应时间设置为100毫秒，API网关请求后端响应时间超过该值，API网关会放弃请求后端，返回给用户相应的错误信息。

操作2. 后端参数映射

映射参数：参数映射用于将API请求中的入参映射为实际后端服务的参数。映射参数默认会将入参以相同名称进行映射，后端参数位置需要选择。您也可以根据需求，变更参数的映射方式，例如参数aaa，映射为后端服务中Head参数。

当请求方法为POST、PUT、PATCH时，需要设置后端body定义。后端body定义完成(也就是选择模型)之后，body参数映射将请求参数映射到后端body里面的参数（参数分层级展示），其中body里定义的必填参数，在参数映射中必须要有请求参数与之一一映射，后端参数位置默认为body。注：请求参数不能为空，后端body提供了多个参数，其中body里必填参数必须和请求参数一一映射。

操作3. 后端常量设置

您可以根据实际需求配置常量参数，常量参数不可见，API网关会在中转请求时，附带这些参数在请求的指定位置传递给后端，常量参数在每次 API 调用中都保持不变。

操作4. 点击“下一步”按钮，进入【定义返回结果】页面。

四、定义返回结果

后端基础定义返回结果基础定义：Content-Type、成功返回示例、失败返回示例、错误码定义
点击“提交”按钮，进入【API管理】列表页面。

后续操作

API创建成功后，发布API上线，您即可对外开放API。

API流量管理

使用场景

流量控制可限制单位时间内API的被调用次数，保护后端服务，您可以为单个API绑定流量策略。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择【流量管理】，进入【流量管理】页面。
点击“绑定策略”，弹出“绑定策略”对话框，同一个环境中，一个API只能被一个流控策略绑定。
点击“确认”按钮，绑定成功。

API授权应用

使用场景

使用APP认证的API，需要在API网关中创建一个应用（用户需要创建应用作为调用API时的身份），以生成应用ID和密钥对（AppKey、AppSecret）。将创建的应用绑定API后，才可以使用APP认证调用API。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择【授权应用】，进入【授权应用】页面。
点击“添加授权”，弹出“添加授权”对话框。非APP认证的API, 不能授权应用，“添加授权”按钮置灰，只有APP认证的API才可以被应用绑定。
- 选择要授权API
- 环境：线上或者测试
- 授权有效期：长期或者短期
- 应用：选择授权的应用
点击“解绑”，弹出“解除授权”对话框。

生成应用ID和密钥对的SDK如下：

python

API访问控制

使用场景

访问控制通过给API设置IP地址的黑白名单来允许/拒绝某个IP地址访问该API，保护后端服务，您可以为单个API绑定访问控制。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择【访问控制】，进入访问控制页面。
点击“绑定访问控制”，弹出“绑定访问控制”对话框。
- 环境：线上或者测试
- 访问控制：选择具体的访问控制
- 点击“解绑访问控制”，弹出“解绑访问控制”对话框。

API熔断策略

使用场景可以在“熔断管理”为熔断策略绑定API，也可以在“API管理”中为API绑定策略。API只能绑定一个熔断策略，如果已经绑定熔断策略，则新绑定的策略会替换原先的策略。
操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择“熔断策略”标签页，进入“绑定熔断策略”页面。
点击“绑定熔断策略”按钮，弹出对话框

绑定熔断策略之后，如果服务出现故障错误，且错误超过一定阈值，就会返回设定的服务信息。

API插件管理

使用场景在API管理中同样可以对插件进行管理，比如绑定、解绑、搜索等
操作步骤
登录API网关控制台
在控制台顶部导航栏选择“区域”
在左侧菜单栏，选择【API管理】，选中某个API，进行API详情页面，选择“插件管理”标签页
点击“绑定插件”按钮，弹出“绑定插件”对话框，选择插件

API签名密钥

使用场景

签名密钥用于后端服务验证API网关的身份，在API网关请求后端服务时，保障后端服务的安全。

签名密钥是由一对Key和Secret组成，签名密钥需要绑定到API才能生效。当签名密钥绑定API后，API网关向后端服务发送此API的请求时，会增加相应的签名信息，此时需要后端服务按照同样方式进行签名，通过比对后端签名结果和API网关传过来的签名是否一致来校验API请求的合法性。

同一个环境中一个API只能被一个签名密钥绑定，一个签名密钥可以绑定多个API。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择【签名密钥】，进入签名密钥页面。
点击“绑定签名密钥”，弹出“绑定签名密钥”对话框。
- 环境：线上或者测试
- 签名密钥：选择具体的签名密钥
- 点击“解绑签名密钥”，弹出“解绑签名密钥”对话框。

数据统计（线上）

使用场景

图表：分别从请求次数（次）、2xx请求次数（次）、4xx请求次数（次）、5xx异常次数（次）、响应时间（ms）、返回流量（byte）、请求流量（byte）和总的错误次数（次）8个维度展示近1小时、近24小时、近7天或近30天内的API调用情况。其中近1小时，指标颗粒度为1分钟展示；近24小时，指标颗粒度为1小时；近7天和近30天，指标颗粒度为1天。

访问排行：按照请求次数、请求流量和返回流量统计单个API调用情况，方便用户掌握调用者调用API的详情。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择数据统计标签页，进入数据统计页面。其中图表展示可开启自动刷新开关，每隔60秒，图表数据会自动刷新。也可以点击刷新按钮，手动更新图表数据展示。

点击“详情”，转换至云监控页面，查看更加全面的数据指标。

API链路拓扑

使用场景

API网关创建的API在安装链路拓扑插件之后，单个API将作为一个服务实例接入APTS，当发布线上环境的API调用时将会对API各项指标进行链路拓扑数据观测，进而帮助用户提高开发过程中的问题诊断效率。

链路拓扑服务的使用主要分为两个部分：

链路拓扑服务的开通
API调用后链路拓扑服务的各项数据查看
操作步骤
开通链路拓扑服务前需要先创建API，该过程请参考API创建部分的说明。开通链路拓扑服务要求API的后端服务必须是http(s)类型，其它类型暂时不支持该服务。
使用链路拓扑的API需要先发布线上环境，API发布后，点击API进入API详情页面，选择【链路拓扑】，进入链路拓扑展示页。
选择”安装插件”进行该API的链路拓扑插件的安装。
首次安装时需要创建项目，请点击”创建项目”链接进入应用性能追踪服务中进行创建。
创建项目后，在选择项目的下拉框中选择已经创建好的项目，点击”确定”，此时插件创建完成。
安装插件后，进行线上API的调用，此时API详情中【链路拓扑】的展示页将展示API调用时的性能分析信息。
Apdex性能指数： Apdex（Application Performance Index），是由Apdex联盟开发的用于评估应用性能的工业标准。取值范围为0～1。计算方式：Apdex = (满意样本 + 可容忍样本 * 0.5) / 样本总数。响应时间作为样本的判别标准，阈值为500ms
点击”查看调用链”可以查看API的调用追踪链路信息，包括调用开始时间、总调用时间、调用结果等信息。

发布历史

使用场景

发布历史中展示当前API在每个环境的发布历史记录。用户可浏览已发布的API历史详情，或将已发布的API切换到某个历史版本。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择发布历史标签页，进入发布历史页面。列表按发布时间倒叙排列，每个环境的版本只记录最新10条数据。多于10个版本，比如第11次发布，那么第11次将覆盖第1次发布的版本。点击查看版本按钮，可查看历史发布API详情，点击切换至此版本，弹出弹窗，确认切换后版本切换成功。

注：切换历史版本后，这个API不会改变，只是当前已发布的API版本变了，也就是说“API详情”和“发布历史”版本切换无关。流量管理、访问控制、签名秘钥和授权应用还是按照最后一次设置的使用，和“发布历史”版本切换无关。

API调试

使用场景

API创建后需要验证服务是否正常，API网关提供调试功能，您可以调试API接口。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，点击单个API，进入API详情页面，选择API调试，进入【API调试】页面。
填写参数（Path、Header、Query、Body）及选择认证方式。
填写请求参数后，单击“发送请求”，右侧返回结果回显区域打印API调用的返回结果信息。
1. 调用成功时，返回HTTP状态码为“200”和Response信息。
2. 调试失败时，返回HTTP状态码为4xx或5xx，具体错误信息请参见错误码。
您可以通过调整请求参数与参数值，发送不同的请求，验证API服务。

使用限制：

-   1. 只有发布到线上环境或测试环境的API才可以调试

-   2. APP认证，若未授权应用，则不能调试

网关实现跨域资源共享

一、跨域带来的安全问题及浏览器的限制访问

当一个资源从与该资源本身所在的服务器不同的域或端口请求一个资源时，资源会发起一个跨域 HTTP 请求。比如，站点 http://www.test.com/ 的某 HTML 页面通过img的src请求http://cloud.test.com/网络上的许多页面都会加载来自不同域的CSS样式表，图像和脚本等资源。出于安全原因，浏览器限制从页面脚本内发起的跨域请求，有些浏览器不会限制跨域请求的发起，但是会将结果拦截了。这意味着使用这些API的Web应用程序只能加载同一个域下的资源，除非使用CORS机制（Cross-Origin Resource Sharing 跨源资源共享）获取目标服务器的授权来解决这个问题。上图画的是典型的跨域场景，目前主流浏览器为了用户的安全，都会默认禁止跨域访问，但是主流浏览器都支持W3C推荐了一种跨域资源共享机制（CORS）。服务器端配合浏览器实现CORS机制，可以突破浏览器对跨域资源访问的限制，实现跨域资源请求。

二、跨域资源共享CORS介绍

2.1 两种验证模式

跨域资源共享CORS的验证机制分两种模式：简单请求和预先请求。当请求同时满足下面三个条件时，CORS验证机制会使用简单模式进行处理。 1.请求方法是下列之一：

GET
HEAD
POST

2.请求头中的Content-Type请求头的值是下列之一：

application/x-www-form-urlencoded
multipart/form-data
text/plain

3.Fetch规范定义了CORS安全头的集合（跨域请求中自定义的头属于安全头的集合）该集合为：

Accept
Accept-Language
Content-Language
Content-Type （需要注意额外的限制）
DPR
Downlink
Save-Data
Viewport-Width
Width

否则CORS验证机制会使用预先请求模式进行处理。

2.2 简单请求模式

简单请求模式，浏览器直接发送跨域请求，并在请求头中携带Origin的头，表明这是一个跨域的请求。服务器端接到请求后，会根据自己的跨域规则，通过Access-Control-Allow-Origin和Access-Control-Allow-Methods响应头，来返回验证结果。

应答中携带了跨域头 Access-Control-Allow-Origin。使用 Origin 和 Access-Control-Allow-Origin 就能完成最简单的访问控制。本例中，服务端返回的 Access-Control-Allow-Origin: * 表明，该资源可以被任意外域访问。如果服务端仅允许来自 http://www.test.com 的访问，该首部字段的内容如下：

Access-Control-Allow-Origin: http://www.test.com

现在，除了 http://www.test.com，其它外域均不能访问该资源。

2.3 预先请求模式

浏览器在发现页面发出的请求非简单请求，并不会立即执行对应的请求代码，而是会触发预先请求模式。预先请求模式会先发送Preflighted requests（预先验证请求），Preflighted requests是一个OPTION请求，用于询问要被跨域访问的服务器，是否允许当前域名下的页面发送跨域的请求。在得到服务器的跨域授权后才能发送真正的HTTP请求。 OPTIONS请求头部中会包含以下头部：Origin、Access-Control-Request-Method、Access-Control-Request-Headers。服务器收到OPTIONS请求后，设置Access-Control-Allow-Origin、Access-Control-Allow-Method、Access-Control-Allow-Headers、Access-Control-Max-Age头部与浏览器沟通来判断是否允许这个请求。如果Preflighted requests验证通过，浏览器才会发送真正的跨域请求。

请求中的跨域头 Access-Control-Request-Method 告知服务器，实际请求将使用 GET 方法。请求中的跨域头 Access-Control-Request-Headers 告知服务器，实际请求将携带两个自定义请求首部字段：x-ca-nonce 与 content-type。服务器据此决定该实际请求是否被允许。应答中的跨域头 Access-Control-Allow-Methods 表明服务器允许客户端使用 GET 方法发起请求。值为逗号分割的列表。应答中的跨域头 Access-Control-Allow-Headers 表明服务器允许请求中携带字段 x-ca-nonce 与 content-type。与 Access-Control-Allow-Methods 一样，Access-Control-Allow-Headers 的值为逗号分割的列表。应答中的跨域头 Access-Control-Max-Age 表明该响应的有效时间为 86400 秒，也就是 24 小时。在有效时间内，浏览器无须为同一请求再次发起预检请求。请注意，浏览器自身维护了一个最大有效时间，如果该首部字段的值超过了最大有效时间，将不会生效。

三、在API网关实现CORS跨域资源共享

3.1实现API支持CORS跨域请求

API 网关创建 API 时选择开启跨域，网关默认支持该 API 的简单请求与预先请求：

3.1.1实现简单请求模式

客户端的API请求

GET /simple HTTP/1.1
Host: www.test.com
orgin: http://cloud.test.com/
content-type: application/x-www-form-urlencoded; charset=utf-8
accept: application/json; charset=utf-8
date: Mon, 18 Sep 2017 09:53:23 GMT

后端服务应答

HTTP/1.1 200 OK
Date: Mon, 18 Sep 2017 09:53:23 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 12
{"200","OK"}

API网关应答

HTTP/1.1 200 OK
Date: Mon, 18 Sep 2017 09:53:23 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Vary: Origin
Access-Control-Expose-Headers: X-CustomHeader,ordersource,Keep-Alive,User-Agent,If-Modified-Since,Cache-Control,Attributes,Authorization, Origin, X-Requested-With, Content-Type,X-Custom-Header,region, errorignore
X-Ca-Request-Id: 104735BD-8968-458F-9929-DBFA43F324C6
Content-Type: application/json; charset=UTF-8
Content-Length: 12
{"200","OK"}

从上面三个报文可以看出，API网关会对用户的后端服务应答做一定修改，增加一个跨域头：

Access-Control-Allow-Origin: *

这个跨域头的意思是，本API允许所有域的请求访问。如果用户需要定制针对简单请求的应答的跨域头，只需要在后端服务应答中，增加Access-Control-Allow-Origin这个跨域头即可，后端服务应答中的头会默认覆盖掉API网关自己增加的头。下面是一个例子，这个例子中的API只允许http://www.test.com 这一个域访问： 客户端的API请求

GET /simple HTTP/1.1
Host: cloud.test.com
orgin: http://www.test.com/
content-type: application/x-www-form-urlencoded; charset=utf-8
accept: application/json; charset=utf-8
date: Mon, 18 Sep 2017 09:53:23 GMT

后端服务应答

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://www.test.com
Date: Mon, 18 Sep 2017 09:53:23 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 12
{"200","OK"}

API网关应答

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://www.test.com
X-Ca-Request-Id: 104735BD-8968-458F-9929-DBFA43F324C6
Date: Mon, 18 Sep 2017 09:53:23 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 12
{"200","OK"}

3.1.2实现预先请求模式

用户可以是用CURL方法来测试自己的跨域API应答情况，下面是针对一个开启跨域的API访问的一个示例：

sudo curl -X OPTIONS -H "Access-Control-Request-Method:POST" -H "Access-Control-Request-Headers:X-CUSTOM-HEADER" http://47a8fb06-83b6-487a-9858-3e21809940b7.apig-cn-north-3.testcloud.cn/optinstest -i
HTTP/1.1 200 OK
Server: Tengine
Date: Sun, 02 Sep 2018 15:32:19 GMT
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: X-CustomHeader,ordersource,Keep-Alive,User-Agent,If-Modified-Since,Cache-Control,Attributes,Authorization, Origin, X-Requested-With, Content-Type,X-Custom-Header,region, errorignore
Access-Control-Max-Age: 172800
X-Ca-Request-Id: 1016AC86-E345-405C-8049-A6C24078F65F

下面是一个完整的预先请求模式的请求与应答示例。 客户端的方法为允许跨域的API请求

OPTIONS /simple HTTP/1.1
Host: cloud.test.com
orgin: http://www.test.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-CUSTOM-HEADER
accept: application/json; charset=utf-8
date: Mon, 18 Sep 2017 09:53:23 GMT

API网关应答

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://www.test.com 
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: X-CUSTOM-HEADER
Access-Control-Max-Age: 10000
X-Ca-Request-Id: 104735BD-8968-458F-9929-DBFA43F324C6
Date: Mon, 18 Sep 2017 09:53:23 GMT
Content-Type: application/json; charset=UTF-8

客户端发送正常业务请求

GET /simple HTTP/1.1
Host: cloud.test.com
orgin: http://www.test.com
content-type: application/x-www-form-urlencoded; charset=utf-8
accept: application/json; charset=utf-8
date: Mon, 18 Sep 2017 09:53:23 GMT

后端服务应答

HTTP/1.1 200 OK
Date: Mon, 18 Sep 2017 09:53:23 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 12
{"200","OK"}

API网关应答

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH
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
Access-Control-Max-Age: 172800
Vary: Origin
X-Ca-Request-Id: 104735BD-8968-458F-9929-DBFA43F324C6
Date: Mon, 18 Sep 2017 09:53:23 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 12
{"200","OK"}

防重放攻击

一、重放攻击带来的安全问题

API重放攻击（Replay Attacks）又称重播攻击、回放攻击，这种攻击会不断恶意或欺诈性地重复一个有效的API请求。攻击者利用网络监听或者其他方式盗取API请求，进行一定的处理后，再把它重新发给认证服务器，是黑客常用的攻击方式之一。重放攻击无疑会给服务带来访问压力，而防止重放攻击的方案都需要签名进行支持，因此选择在APP认证中增加防止重放攻击特性。

二、防重放功能的使用

使用场景

在进行创建或编辑APP认证的API时网关提供防重放攻击的开关选择，帮助拦截恶意的重放攻击请求，保护后端服务安全。

操作步骤

用户在进行创建或编辑API时，认证方式选择【APP认证】时，将会产生【防重放攻击】的选择开关，选择开启后将自动开启该功能。（该功能默认关闭）

三、防重放功能调用说明

调用方式

对于开启防重放功能的API，除了需要携带APP认证的必要参数，还需要额外携带一个nonce值去发起http请求，否则将会被视为非法请求而被网关拦截。nonce值为代码随机生成的随机数，该值将会在使用客户端鉴权的SDK获取认证信息时一并被获取到。

nonce数值传递方式

nonce值传递与客户端鉴权的参数传递类似，将nonce随机数与客户端鉴权参数一起加入到header中即可：

x-auth-nonce：   开启防重放时携带的随机数

x-auth-app-key：   创建应用时的 app_key 
x-auth-time：      UTC时间秒为单位的时间戳 
X-auth-sign：      计算得到的签名

防重放功能原理

发布的API如果使用APP认证方式（APPKey和APPSecret），开启防重放后，客户端在调用API时，除了会进行客户端鉴权外，还会额外验证nonce的判断发起请求的时间戳与当前时间的差值，如果超过设定的时间范围（目前设定为60s），则认为是非法请求。如果是在时间范围之内，则判断nonce是否存在于redis，如果存在，则认为是非法请求；如果不存在，则将nonce参数保存在redis，同时将该nonce的失效时间设定为时间戳判别的时间范围，比如如上所述的60s。

流量管理

使用场景

API提供方可以在API网关中添加API的流量控制策略来限制API的访问次数，保护后端服务。

绑定流控策略主要分为两个步骤：

定义流控策略
绑定流控策略
操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【流量管理】模块，进入【流控管理】页面。
在左侧菜单栏中，选择【创建策略】模块，进入创建策略页。
- 策略名称：策略名称标识具有唯一性。
- 策略单位：策略单位区分了流量控制的限制级别，区分天、时、分、秒四种限制级别。
- API流量限制：单位时间内的单个API请求次数上限。
- 用户流量控制：单位时间内的单个用户请求次数上限。
- 应用流量控制：单位时间内的单个应用请求次数上限。
（API流量>=用户流量，API流量>=应用流量。）
- 描述：对策略进行基本描述
打开策略详情页面
绑定流控策略，点击“绑定API”按钮，弹出绑定API弹框，选择分组和API发布的环境查看发布的API，选择需要绑定的API进行绑定。
- 后续操作
流控策略绑定成功后，当绑定的API的访问次数超过限制次数则会报错。

访问控制

使用场景

访问控制是API网关提供的API安全防护组件之一，您可以通过设置IP地址的黑白名单来允许/拒绝某个IP地址访问API。

绑定访问控制主要分为两个步骤：

创建访问控制
绑定访问控制
操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【访问控制】模块，进入访问控制页。
点击【创建访问控制】按钮，弹出弹框，创建访问控制。
- 名称：1~40个字符，支持汉字、英文、数字、下划线，且只能以英文字母或汉字开头，分组名称必须唯一
- 类型：允许或者禁止。允许相当于IP白名单，被定义为允许类型的IP才可访问，其余IP全不能访问。禁止相当于IP黑名单，被定义成禁止的IP都不能访问，其他IP可以访问。
- IP地址：请填写IP或IP地址段，多个请以;分隔。
打开访问控制详情页面
给API绑定访问控制
- 点击绑定API按钮
- 弹出绑定API选择框
- 选择分组和API发布的环境查看发布的API
后续操作

访问控制绑定成功后，API网关会根据访问控制来允许/拒绝某个IP地址访问API。

签名密钥

使用场景

签名密钥用于后端服务验证API网关的身份，在API网关请求后端服务时，保障后端服务的安全。

绑定签名密钥主要分为两个步骤：

创建签名密钥
绑定签名密钥
操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【签名密钥】模块，进入签名密钥页。
点击【创建签名密钥】按钮，弹出弹框，创建签名。
- 名称：1~40个字符，支持汉字、英文、数字、下划线，且只能以英文字母或汉字开头，名称必须唯一
- key：8-32个字符，只能以英文或数字开头，支持英文、数字、下划线、中划线，如果为空后台自动生成Key
- secret：16-64个字符，只能以英文或数字开头，支持英文、数字、下划线、中划线，还支持英文特殊字符!@#$%，如果为空后台自动生成Secret
打开签名密钥详情页面
给API绑定签名密钥
- 点击绑定API按钮
- 弹出绑定API选择框
- 选择分组和API发布的环境查看发布的API

签名密钥加密算法

使用签名密钥需要后端提供验证的能力，通过从请求header中获取到加密的信息，经过算法计算验证加密信息是否正确

从请求header中获取以下三个参数

X-Signature-Key：   签名key
X-Signature-Time：  UTC时间秒为单位的时间戳
X-Signature-Sign：  签名结果

验证签名一致性的方法

String signatureKey = request.getHeader("X-Signature-Key");
String signatureTimeStr = request.getHeader("X-Signature-Key");
String signatureSign = request.getHeader("X-Signature-Sign");
Long signatureTime = Long.valueOf(request.getHeader("X-Signature-Time"));
//判断时间有效性
Date date = new Date(signatureTime * 1000);
long duration = Math.abs(System.currentTimeMillis() - date.getTime());
if (duration <= num) {
    //根据key获取对应的secret
    String signingSecret = secrets.get(signatureKey);
    if (signingSecret != null) {
        //验证签名
        String signStr = "signature_key=" + signatureKey + "&signature_time=" + signatureTime;
        byte[] signBytes = new HmacUtils(HmacAlgorithms.HMAC_SHA_1, signingSecret).hmac(signStr);
        String signatureResult = Base64.getEncoder().encodeToString(signBytes);
        //验证签名结果
        boolean verify = signatureResult.equals(signatureSign);
        ......
    }
}

Swagger导入导出

Swagger是一种用于定义API管理的规范，被广泛应用于定义和描述后端服务API。

网关支持导入Swagger 2.0版本的文件来创建API，因为Swagger与API网关的定位不同，原生的Swagger文件并不能够直接导入API网关用来创建Api。详细来说，Swagger通常用于定义和管理真实服务API，所以其定义的“访问相关属性”均为服务实际API的属性，如服务地址以及传入的参数。因此，Swagger并无类似于“API后端”相关的属性。

对于API网关，参数映射及后端服务定义是其不可或缺的特性。对此，API网关实现了一些Swagger扩展属性，只需对原生Swagger进行简单修改，便能够将其Swagger描述的API托管至API网关进行管理。

Swagger扩展

Swagger扩展主要是对于Swagger原生OpenAPI Specification进行扩展。所有扩展属性均以x-inspurcloud-apig-开头，具体扩展内容如下：

1. x-inspurcloud-apig-model：分组模型

分组模型，应用于Swagger Object，用于描述API分组下所有的模型信息。

属性说明：

属性名称	类型	描述
description	string	选填，模型描述
Content-Type	string	必填，内容类型
detail	string	必填，模型内容

示例：

...
"x-inspurcloud-apig-model": {
        "测试模型": {
            "description":"",
            "Content-Type":"application/json",
            "detail":"{\n    \"type\": \"object\",\n    \"properties\": {\n        \"name\": {\n            \"type\": \"string\"\n        },\n        \"description\": {\n            \"type\": \"string\"\n        }\n    }\n}"
        }
    }
...

2. x-inspurcloud-apig-auth：认证方式

认证方式，应用于Operation Object，用来描述API的认证方式

取值范围：“iam”和“app”。“iam”为IAM认证；"app"为APP认证

示例：

...
"x-inspurcloud-apig-auth":"iam"
...

3. x-inspurcloud-apig-api-model：API请求模型

API请求模型，应用于Operation Object，用来描述API请求Body定义

属性说明：

属性名称	类型	描述
requestModel	string	必填，模型名称，用于匹配`x-inspurcloud-apig-model`扩展中的模型信息

示例：

...
"x-inspurcloud-apig-api-model": {
    "requestModel":"模型测试"
}
...

4. x-inspurcloud-apig-request-sample：请求示例

请求示例，应用于Operation Object，用来描述API的请求示例信息

示例：

...
"x-inspurcloud-apig-request-sample":"curl -X POST -H 'content-type: application/json' -d 'json内容' URL"
...

5. x-inspurcloud-apig-backend-info：后端定义

后端定义，应用于Operation Object，用来描述API网关后端配置信息

属性说明：

属性名称	类型	描述
httpEndpoints	object	必填，后端基础定义
parameters	[object]	选填，后端参数映射和后端常量设置
requestTemplate	object	选填，后端请求Body模板

5.1. httpEndpoints：后端基础定义

后端基础定义，分为后端类型为HTTP(s)类型和MOCK

5.1.1. 后端类型：HTTP(s)

取值范围：

method："get"，"post"，"patch"，"put"，"options"，"delete"和"head"

timeout：1至2147483647的整数类型

属性说明：

属性名称	类型	描述
scheme	[string]	必填，后端类型
address	string	必填，后端地址
path	string	必填，后端路径
method	string	必填，请求方法
timeout	integer	必填，后端超时时间（ms）

示例：

...
"httpEndpoints": {
                        "scheme": [
                            "http",
                            "https"
                        ],
                        "address":"http://www.abc.com",
                        "path":"/get/{id}",
                        "method":"post",
                        "timeout":3000
                    }
...

5.1.2. 后端类型：MOCK

取值范围：

statusCode：“2”、“3”、“4”或“5”开头的3位整数

属性说明：

属性名称	类型	描述
scheme	[string]	必填，后端类型
body	string	必填，MOCK返回结果
statusCode	integer	选填，状态码
headers	object	选填，MOCK Header

示例：

...
"httpEndpoints": {
                        "scheme": [
                            "mock"
                        ],
                        "body":"{\"hello\":\"100\"}",
                        "statusCode":200,
                        "headers": {

                        }
                    }
...

5.2. parameters：后端参数映射和后端常量设置

取值范围：

in：“path”，“header”，“query”或“body”，RESTful风格API不支持body

origin：REQUEST或CONSTANT。REQUEST为后端参数映射参数；CONSTANT为后端常量设置参数

属性说明：

属性名称	类型	描述
name	string	必填，后端参数名称
in	string	必填，后端参数位置
origin	string	必填，参数来源，
value	string	必填，请求参数名称
default	string	必填，后端常量设置参数默认值

示例：

...
"parameters": [
                        {
                            "name":"passwd",
                            "in":"header",
                            "origin":"REQUEST",
                            "value":"passwd"
                        },
                        {
                            "name":"name",
                            "in":"query",
                            "origin":"REQUEST",
                            "value":"name"
                        },
                        {
                            "name":"id",
                            "in":"path",
                            "origin":"REQUEST",
                            "value":"id"
                        },
                        {
                            "name":"weight",
                            "description":"",
                            "in":"header",
                            "origin":"CONSTANT",
                            "default":"50"
                        }
                    ]
...

5.3. requestTemplate：后端请求Body模板

取值范围：

parseRule：“415”或“Penetrate”。“415”为模板匹配失败返回415状态码；“Penetrate”为模板匹配失败透传body

属性说明：

属性名称	类型	描述
template	string	必填，模板内容
parseRule	string	必填，解析规则，透传或返回415状态码

示例：

...
"requestTemplate": {
                        "template":"{\n  \"choices\": [\n    <% for i, item in pairs(bins) do -%>\n    {\n      \"kind\": \"<%= item.type -%>\",\n      \"suggestedPrice\": \"<%= item.price .. ' per ' .. item.unit -%>\",\n      \"available\": \"<%= item.quantity -%>\"\n    }\n      <% if next(bins, i) then -%>\n        ,\n      <% end -%>\n    <% end -%>\n  ]\n}",
                        "parseRule":"Penetrate"
                    }
...

6. x-inspurcloud-apig-response-success-sample：成功返回示例

成功返回示例，应用于Operation Object，用来描述API调用的成功返回示例

示例：

...
"x-inspurcloud-apig-response-success-sample":"{\"result\"::\"1\"}"
...

7. x-inspurcloud-apig-response-fail-sample：失败返回示例

失败返回示例，应用于Operation Object，用来描述API调用的失败返回示例

示例：

...
"x-inspurcloud-apig-response-fail-sample":"{\"result\"::\"0\"}"
...

8. x-inspurcloud-apig-response-template：响应模板

响应模板，应用于Operation Object，用来描述API响应Body转换模板

示例：

...
"x-inspurcloud-apig-response-template":"{\n  \"choices\": [\n    <% for i, item in pairs(bins) do -%>\n    {\n      \"available\": \"<%= item.quantity -%>\"\n    }\n      <% if next(bins, i) then -%>\n        ,\n      <% end -%>\n    <% end -%>\n  ]\n}"
...

9. x-inspurcloud-apig-response-content-type：API响应内容类型

API响应内容类型，应用于Operation Object，用来描述API响应的内容类型

取值范围：“application/json”，“application/xml”，“HTML”和“TEXT”，RESTful风格API仅支持application/json

示例：

"x-inspurcloud-apig-response-content-type":"application/json"

10. x-inspurcloud-apig-final-response-header：最终响应header

最终响应header，应用于Operation Object，用来描述API网关最终响应header参数

属性说明：

参数名称	类型	描述
name	string	必填，最终响应header参数名称
description	string	选填，参数描述

示例：

...
"x-inspurcloud-apig-final-response-header": [
                    {
                        "name":"finalTerm",
                        "description":""
                    }
                ]
...

11. x-inspurcloud-apig-backend-response-header：后端响应header

后端响应header，应用于Operation Object，用来描述上游服务响应参数

取值范围：

in：header或body

属性说明：

参数名称	类型	描述
name	string	必填，后端响应参数名称
in	string	必填，参数位置
value	string	必填，最终响应header参数名称

示例：

...
"x-inspurcloud-apig-backend-response-header": [
                    {
                        "name":"term",
                        "in":"header",
                        "value":"finalTerm"
                    }
                ]
...

12. x-inspurcloud-apig-error-info：错误码定义错误信息

应用于Responses Object，用来描述错误码信息

属性说明：

参数名称	类型	描述
x-inspurcloud-apig-error-info	string	必填，错误码定义错误信息

示例：

...
"responses": {
                    "400": {
                        "description":"Invalid ID supplied",
                        "x-inspurcloud-apig-error-info":"invalid..."
                    },
                    "404": {
                        "description":"Pet not found",
                        "x-inspurcloud-apig-error-info":"not found..."
                    },
                    "405": {
                        "description":"Validation exception",
                        "x-inspurcloud-apig-error-info":"exception..."
                    }
                }
...

13. x-inspurcloud-apig-aws-paths：自定义Paths Object

自定义Paths Object，用于描述分组下所有AWS风格的API。由于每个AWS风格API请求方法和路径都是一样的，故不能与RESTful风格API那样用Paths Object描述

属性说明：

参数名称	类型	描述
x-inspurcloud-apig-aws-paths	[object]	选填

示例：

...
"x-inspurcloud-apig-aws-paths": [
        {
            "/": {
                "get": {
                    "tags": [
                        "仅aws导出测试"
                    ],
                    "operationId":"仅aws导出测试",
                    "description":"",
                    "summary":"",
                    "x-inspurcloud-apig-style":"aws",
                    "schemes": [
                        "http"
                    ]
                    "parameters": [
                        {
                            "name":"Action",
                            "description":"",
                            "in":"query",
                            "type":"string",
                            "default":"0001",
                            "required":true
                        },
                        {
                            "name":"name",
                            "description":"",
                            "in":"query",
                            "type":"string",
                            "default":"",
                            "required":true
                        }
                    ],
                    "x-inspurcloud-apig-backend-info": {
                        "httpEndpoints": {
                            "scheme": [
                                "http",
                                "https"
                            ],
                            "address":"http://www.baidu.com",
                            "path":"/ccccc",
                            "method":"post",
                            "timeout":3000
                        },
                        "parameters": [
                            {
                                "name":"Action",
                                "in":"query",
                                "origin":"REQUEST",
                                "value":"Action"
                            },
                            {
                                "name":"xingming",
                                "in":"body",
                                "origin":"REQUEST",
                                "value":"name"
                            }
                        ]
                    },
                    "x-inspurcloud-apig-response-content-type":"application/json",
                    "responses": {
                        "200": {
                            "description":"",
                            "x-inspurcloud-apig-error-info":"request successful"
                        }
                    }
                }
            }
        }
    ]
...

14. x-inspurcloud-apig-style：API风格

API风格，应用于Operation Object，用于区分RESTful风格和AWS风格API，当API风格为AWS时，会展示该扩展属性

示例：

...
"x-inspurcloud-apig-style":"aws"
...

15. securityDefinitions：安全认证定义

安全认证定义，应用于Swagger Object，用来描述API支持的身份认证参数

属性说明：

属性名称	类型	描述
IAMAuthSignAlgorithm	object	必填，IAM认证哈希算法，支持sha1、md5、sha256
IAMAuthSecretId	object	必填，IAM认证Access Key Id（即AK）
IAMAuthTime	object	必填，IAM认证13位毫秒级时间戳
IAMAuthRandom	object	必填，IAM认证随机字符串
IAMAuthSign	object	必填，IAM认证签名运算后得到的签名值signatrue
APPAuthAppKey	object	必填，APP认证API绑定的APP Key
APPAuthTime	object	必填，APP认证UTC 时间秒为单位的时间戳
APPAuthSign	object	必填，APP认证计算得到的签名

示例：

"securityDefinitions": {
    "IAMAuthSignAlgorithm": {
        "type":"apiKey",
        "in":"header",
        "name":"x-sign-algorithm"
    },
    "IAMAuthSecretId": {
            "type":"apiKey",
            "in":"header",
            "name":"x-secret-id"
        },
    "IAMAuthTime": {
            "type":"apiKey",
            "in":"header",
            "name":"x-time"
        },
     "IAMAuthRandom": {
            "type":"apiKey",
            "in":"header",
            "name":"x-random"
        },
        "IAMAuthSign": {
            "type":"apiKey",
            "in":"header",
            "name":"x-sign"
        },

        "APPAuthAppKey": {
            "type":"apiKey",
            "in":"header",
            "name":"x-auth-app-key"
        },
        "APPAuthTime": {
            "type":"apiKey",
            "in":"header",
            "name":"x-auth-time"
        },
        "APPAuthSign": {
            "type":"apiKey",
            "in":"header",
            "name":"x-auth-sign"
        }
    }

Swagger导入

使用场景

使用从API网关中导出的Swagger文件或者基于Swagger 2.0原生文件和API网关Swagger扩展属性编写适用于API网关的Swagger文件，通过Swagger导入功能来批量创建或更新API。

Swagger导入主要分为三个步骤：

选择导入的分组
选择是否覆盖
添加Swagger文件

使用限制：

导入文件为JSON，内容大小限制为1MB。
操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API管理】模块，进入API列表页。
点击“Swagger导入”按钮，进入Swagger导入页面。
Swagger导入
- 选择分组：API所属分组，如果未创建API分组，请先创建API分组，再进行导入
- 选择是否覆盖：当选择覆盖时，如果遇到请求路径和http请求冲突时，自动覆盖（更新）原有API；当不选择覆盖时，如果遇到请求路径和http请求冲突时，返回错误提示
- 选择要导入的Swagger文件：导入文件格式为 .JSON，内容大小限制为1MB
- 点击导入后即可进行API的批量创建或更新，以及分组模型的创建或更新
- 您也可以修改Swagger文件中的参数值来创建您需要的API
后续操作

Swagger文件导入成功后，API管理列表页面就会显示导入的API。

Swagger导出

使用场景

在API网关中，将某分组下的API和模型全部导出，从而导入到新的region，通过该方式来批量创建或更新API。

使用限制：

目前只支持分组内存在发布到线上环境API的导出并且导出格式只支持JSON格式
后端类型是函数计算的API，将不会被导出
操作步骤
登录API网关控制台
在控制台顶部导航栏选择区域
在左侧菜单栏中选择【API分组】模块，进入API分组列表页面或者选择【API管理】模块，进入API列表页面
点击“导出API”按钮，弹出【导出API】弹框，点击”导出“按钮即可导出分组API。
导出的Swagger文件格式
样例

{
    "swagger":"2.0",
    "info": {
        "title":"API网关跨域-无认证",
        "description":"",
        "version":"2021-04-19 08:31:43"
    },
    "host":"test01.com.cn",
    "basePath":"/",
    "schemes": [
        "http",
        "https"
    ],
    "x-inspurcloud-apig-model": {
        "API分组创建或编辑": {
            "description":"",
            "Content-Type":"application/json",
            "detail":"{\n    \"type\": \"object\",\n    \"properties\": {\n        \"name\": {\n            \"type\": \"string\"\n        },\n        \"description\": {\n            \"type\": \"string\"\n        }\n    }\n}"
        }
    },
    "paths": {
        "/apig/apps/v1/groups/{id}": {
            "get": {
                "tags": [
                    "查看API网关分组详情后端GET"
                ],
                "operationId":"查看API网关分组详情后端GET",
                "description":"",
                "summary":"",
                "schemes": [
                    "http"
                ],
                "parameters": [
                    {
                        "name":"id",
                        "description":"",
                        "in":"path",
                        "type":"string",
                        "default":"",
                        "required":true
                    },
                    {
                        "name":"Authorization",
                        "description":"",
                        "in":"header",
                        "type":"string",
                        "default":"",
                        "required":true
                    }
                ],
                "x-inspurcloud-apig-response-template":"",
                "x-inspurcloud-apig-backend-info": {
                    "httpEndpoints": {
                        "scheme": [
                            "http",
                            "https"
                        ],
                        "address":"https://cn-north-3.inspurcloud.cn",
                        "path":"/apig/apps/v1/groups/{id}",
                        "method":"get",
                        "timeout":2000
                    },
                    "parameters": [
                        {
                            "name":"id",
                            "in":"path",
                            "origin":"REQUEST",
                            "value":"id"
                        },
                        {
                            "name":"Authorization",
                            "in":"header",
                            "origin":"REQUEST",
                            "value":"Authorization"
                        }
                    ],
                    "requestTemplate": {
                        "template":"",
                        "parseRule":"415"
                    }
                },
                "x-inspurcloud-apig-response-content-type":"application/json",
                "responses": {
                    "200": {
                        "description":"",
                        "x-inspurcloud-apig-error-info":"request successful"
                    }
                }
            }
        }
    },
    "x-inspurcloud-apig-aws-paths": [
        {
            "/": {
                "get": {
                    "tags": [
                        "aws2"
                    ],
                    "operationId":"aws2",
                    "description":"",
                    "summary":"",
                    "x-inspurcloud-apig-style":"aws",
                    "schemes": [
                        "http"
                    ],
                    "parameters": [
                        {
                            "name":"Action",
                            "description":"",
                            "in":"query",
                            "type":"string",
                            "default":"3000",
                            "required":true
                        }
                    ],
                    "x-inspurcloud-apig-backend-info": {
                        "httpEndpoints": {
                            "scheme": [
                                "http",
                                "https"
                            ],
                            "address":"http://www.baidu.com",
                            "path":"/rrrrr",
                            "method":"get",
                            "timeout":2000
                        },
                        "parameters": [
                            {
                                "name":"Action",
                                "in":"query",
                                "origin":"REQUEST",
                                "value":"Action"
                            },
                            {
                                "name":"ccc",
                                "description":"",
                                "in":"query",
                                "origin":"CONSTANT",
                                "default":"3"
                            }
                        ]
                    },
                    "x-inspurcloud-apig-response-content-type":"application/xml",
                    "responses": {
                        "200": {
                            "description":"",
                            "x-inspurcloud-apig-error-info":"request successful"
                        }
                    }
                }
            }
        }
    ],
    "tags": [
        {
            "name":"查看API网关分组详情后端GET",
            "description":""
        }
    ],
    "securityDefinitions": {
        "IAMAuthSign": {
            "type":"apiKey",
            "in":"header",
            "name":"x-sign"
        },
        "IAMAuthTime": {
            "type":"apiKey",
            "in":"header",
            "name":"x-time"
        },
        "APPAuthAppKey": {
            "type":"apiKey",
            "in":"header",
            "name":"x-auth-app-key"
        },
        "IAMAuthSecretId": {
            "type":"apiKey",
            "in":"header",
            "name":"x-secret-id"
        },
        "IAMAuthRandom": {
            "type":"apiKey",
            "in":"header",
            "name":"x-random"
        },
        "APPAuthTime": {
            "type":"apiKey",
            "in":"header",
            "name":"x-auth-time"
        },
        "APPAuthSign": {
            "type":"apiKey",
            "in":"header",
            "name":"x-auth-sign"
        },
        "IAMAuthSignAlgorithm": {
            "type":"apiKey",
            "in":"header",
            "name":"x-sign-algorithm"
        }
    }
}

后续操作

API导出成功后，即可在新的region通过Swagger导入功能来批量创建或更新API。

下载API文档

使用场景

API网关为您提供了API文档自动生成功能，当您注册并发布API到线上后，即可点击“生成API文档”按钮，下载接口文档，避免您重复撰写文档及维护文档版本的工作。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【API分组】模块，进入分组列表页。
点击“更多”按钮，选择“生成API文档”按钮，直接生成markdown文档，并下载到本地。
分组中只要有API的运行环境为线上（部分API为线上，部分API为测试环境）直接把线上环境的API自动生成文档，点击即下载API文档即可。
如果分组中所有的API运行环境为测试时，则“生成API文档”按钮会置灰。
如果分组中无API，则“生成API文档”按钮会置灰。

熔断管理

使用场景 API网关可以通过熔断策略为上游服务提供保护，避免可能的服务调用雪崩，从而提高系统的稳定性与用户体验。

绑定熔断策略的步骤如下：

登录API网关控制台
在控制台导航栏选择区域
在左侧菜单栏，选择【开放API】，选择【熔断管理】，进入“熔断管理”页面
点击“创建熔断策略”，进入“创建熔断策略”页面
- 名称：策略名称标识具有唯一标识性
- 熔断类型：当前提供后端错误码类型
- 窗口时长：在该时间范围内会统计错误次数
- 阈值：当错误次数超过阈值，熔断进入Open状态
- 熔断时长：熔断持续时间，超过这个时间，熔断进入half-open状态
- 错误码：当熔断类型为错误码时，为错误码数组
- Mock后端：当服务熔断时，会返回此处设置的信息
创建成功之后，返回“熔断管理”页面，点击熔断策略，打开详情页面
为熔断策略绑定API，点击“绑定API”按钮，弹出对话框，选择API进行绑定

绑定熔断策略之后，如果服务出现故障错误，且错误超过一定阈值，就会返回设定的服务信息。

如果，对API绑定不满意，可以点击“解绑API”操作。

插件管理

插件是API网关的特色，通过提供多样的插件丰富并增强API网关的功能。当前提供的插件包括：路由选择插件、灰度发布插件、数据缓存插件。

插件概览

插件使用规则

一个API只能绑定一个相同类型的插件
插件策略与API独立管理，将插件绑定到API指定环境，插件策略才会对绑定API起作用
插件绑定的API，必须是已经发布的API
插件的绑定、解绑、更新会实时生效，不需要重新发布API
API的下线操作不影响插件的绑定关系，再次发布会后仍然会带有下线前绑定的插件
如果插件上有绑定的API，则插件无法删除

支持插件列表

目前API网关支持的插件包括：

路由选择插件
灰度发布插件
数据缓存插件

快速使用

登录API网关控制台
在控制台导航栏选择“区域”
在左侧菜单栏，选择【开放API】，选择【插件管理】，进入“插件管理”页面
点击“创建插件”按钮，今年入“创建插件”页面，其表单选项如下所示：
- 名称：插件名称，插件的唯一性标识
- 插件类型：当前选项包括路由选择、灰度发布、数据缓存
- 描述：插件详细信息描述
- 插件配置：不同的插件类型的配置以模板形式提供，用户可以仿照模板修改
创建成功之后，将返回列表页，点击创建的插件，可以查看插件详情
为插件绑定API，点击“绑定API”按钮，弹出“绑定API”对话框，选择绑定的API
如果对绑定的API不满意，可以选择解绑。

路由选择插件

路由选择插件可以根据请求的参数，变更后端地址。

路由选择插件通过YAML格式配置，配置模板如下所示：

---
routes:
- name: mock-route                                                                      # 路由名称
  condition: "path.var1=='a001'"                                                        # 条件表达式
  verifyExpression: "path={};path.var1 = 'a001';"                                       # 条件校验初始化表达式
  backend:
    type: MOCK                                                                          # 后端类型: HTTP或MOCK
    statusCode: 201                                                                     # 响应状态码
    body: "{'result':'0'}"                                                              # 响应body
    headers: {'content-type':'application/json'}                                        # 响应header

配置模板的根对象是routes，可以包含多个route，每个route指定一条路由，每个route包含以下部分：

name：表示路由的名字，大小写英文字母和数字，每个插件保持唯一，如果路由命中，则响应header中x-apig-router参数即为该路由name
condition：路由的条件表达式。如果当前请求符合条件表达式，则本条路由命中路由。路由选择插件会根据配置顺序从上到下判断，如果路由命中，则会忽略该路由后面的记录。
verifyExpression：条件校验初始化表达式，仅用于condition内容校验
backend：后端描述，后端会在原有API的后端上覆盖backend配置。
constant-parameters：可以自行设置路由的常量参数，常量参数会附加在命中路由的后端请求。

condition条件表达式

Condition是对路由请求中的参数进行判断，参数的位置通常是：header、path、query。因此，如果需要对某个参数进行判断，则先选择参数位置，比如header，然后将参数作为header的属性进行判断。

由于condition是条件表达式，因此可以使用and、or等进行连接。

verifyExpression主要用于condtion内容校验。

condition表达式样例

query.a=='a01' # 请求参数a值为t01时，为真
header.b==1    # 请求头参数b值为1时，为真
path.c=='c01'  # 请求路径参数c值为c01时，为真

Backend配置 Backend的配置与创建API时后端配置类似，这里仅支持HTTP与Mock两种类型。

HTTP(S)

  backend:                                                     
    type: HTTP                                                                          
    url: "http://httpbin.local/items"                                          
    method: GET                                                                         
    timeout: 2000                                                                       
    constantParameters:                                                                 
    - name: param1                                                       
      location: header                                                                 
      value: "p001"

constantParameters中的location参数主要包括4个位置：path、header、query、body

MOCK

  backend:
    type: MOCK                                                                          
    statusCode: 201                                                                     
    body: "{'result':'0'}"                                                              
    headers: {'content-type':'application/json'}

灰度发布插件

灰度发布插件主要是帮助API进行流量切换。比如，当前服务存在两个服务版本v1、v2,。你希望80%的流量依然走v1，但是20%的流量走v2，这是就可以使用灰度发布插件。

灰度发布插件的配置如下所示：

routes:
- name: Candary_Example                                                                         
  condition: "random() < 0.2"                                          
  verifyExpression: "1=1;"                        
  backend:                                                     
    type: HTTP                                                                          
    url: "http://v2.example.com/"                                          
    method: GET                                                                         
    timeout: 2000

灰度发布插件与路由选择插件十分相似，主要区别是condition表达式内容。在灰度发布插件中，condition需要借助random()来实现流量的切分。

数据缓存插件

数据缓存插件可以将请求响应缓存，当再次调用时响应会首先从缓存中获取，可以提高请求响应速率，有效降低后端的负荷，仅缓存GET方法的应答。

数据缓存插件的配置内容如下所示：

---
byParameters:             # 按照不同的参数取值来区分缓存内容
- name: userId            # 参数名称，这里写映射后的参数名称,仅支持header、query或path位置
  position: path          # 参数位置
cacheableHeaders:         # 允许缓存的后端Headers, 默认只缓存`Content-Type`和`Content-Length`
- X-Customer-Token        # 允许缓存的Header名称
duration: 3600            # 默认超期的秒数

byParameters：根据参数进行缓存，用于缓存的参数主要位于header、query、path
cacheableHeaders：允许缓存的后端Headers，默认只缓存Content-Type和Content-Length
duration：缓存的超时时间

当API网关命中Cache后，返回的应用中包含响应头x-apig-cache

操作指南（调用API）

应用管理

使用场景

使用APP认证的API，需要在API网关中创建一个应用（APP）作为您调用API的身份，以生成应用ID和密钥对（AppKey、AppSecret）。将创建的应用绑定API后，才可以使用APP认证调用API，API网关服务根据密钥对进行身份核对，完成鉴权。

操作步骤
登录API网关控制台。
在控制台顶部导航栏选择区域。
在左侧菜单栏中，选择【应用管理】模块，进入【应用管理】页面。
点击“创建应用”按钮，弹出“创建应用”对话框。
- 名称：1~40个字符，支持汉字、英文、数字、下划线，且只能以英文字母或汉字开头，应用名称必须唯一
- 描述：不超过200个字符
点击“修改”按钮，弹出“修改应用”对话框。
点击“删除”按钮，弹出“删除应用”对话框。注：1. 当前应用绑定了API不能执行删除操作。
点击“批量删除”按钮，弹出“批量删除”对话框。注：1. 当前应用绑定了API不能执行删除操作。2. 请先选择需要执行删除的应用。
点击单个“应用名称”按钮，进入应用详情页面，该页面由“基本信息”、“已绑定API”、“APPKey”组成。
在“已绑定API”页面，点击“绑定API”按钮，弹出“绑定API”对话框。
- 选择分组和环境
- 授权有效期，长期还是短期
- 选择单个或多个API
在“批量解绑API”页面，弹出“批量解绑API”对话框。
点击在“APPKey”页面，显示APPKey和APPSecret详情。创建应用完毕后，会自动分配一个APPkey及APPSecret。点击隐藏“APPSecret”按钮，隐藏APPSecret。点击显示“APPSecret”按钮，显示APPSecret。
在“APPKey”页面，点击“重置APPSecret”按钮，弹出“重置APPSecret”对话框，重置后，展示新的APPSecret，旧的APPSecret被覆盖。

客户端鉴权使用说明

使用场景

发布的API如果使用APP认证方式（APPKey和APPSecret），客户端在调用API时，需要使用签名秘钥对请求内容进行签名计算，并将签名同步传输给服务器端进行签名验证。

签名与验签原理

客户可以在API网关控制台生成应用，每个应用包含一对签名密钥（AppKey 和AppSecret），客户可以对接口和应用进行绑定。绑定应用的接口需要通过签名密钥进行签名，接口携带签名才能访问成功。

客户端调用 API时，需要使用已授权签名秘钥进行加密签名计算，并且将AppKey和加密后生成的字符串放在请求的 Header 或者 query中传输给API网关，API网关会读取请求中的AppKey的信息，并根据AppKey的值查询到对应的AppSecret的值，使用APPSecret对收到的请求中的关键数据进行签名计算，并且使用自己的生成的签名和客户端传上来的签名进行比对，来验证签名的正确性。只有签名验证通过的请求才会发送给后端服务，否则API网关会认为该请求为非法请求，直接返回错误应答。

生成与传递签名
1. 签名算法
2. 构造数据内容data： auth_app_key=[app_key]&auth_time=[auth_time], app_key 和 auth_time 参与签名, auth_time 为当前 UTC 时间戳。
3. 将上述签名内容通过 base64_safe(HMAC-SHA1(app_secret, data)) 计算生成签名 sign, 注意这里一定要使用 url 安全的 base64 签名，并去掉转码后最后的等号（=）。
4. 认证参数传递
  
  请求认证支持两种携带参数的方法，通过 header 传参和通过 query 传参。
  
  如果通过 header 传参，则 header 中传入如下参数:
```
X-Auth-App-Key：   创建应用时的 app_key 
X-Auth-Time：      UTC时间秒为单位的时间戳 
X-Auth-Sign：      计算得到的签名
```
  如果通过 query 传参，则 query 中携带如下参数:
```
auth_app_key：   创建应用时的 app_key
auth_time：      UTC 时间秒为单位的时间戳 
auth_sign：      计算得到的签名
```
  举例：
```
http://xxxx.com?auth_app_key=xxxxxx&auth_time=1599270802&auth_sign=xxxxxxxxxxx
```

SDK

Java

使用场景

当使用Java语言调用APP认证的API时，您需要先获取SDK并导入工程，获取到签名信息后按照认证参数传递规则调用API。

获取SDK

下载SDK，获取“app-sign-sdk-0.0.2.jar”包并复制到工程根目录lib文件夹下。

如果使用maven构建，dependencies标签中添加app-sign-sdk的依赖配置后重新构建即可。

<dependency>
    <groupId>com.inspur.cloud</groupId>
    <artifactId>app-sign-sdk</artifactId>
    <version>0.0.2</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/app-sign-sdk-0.0.2.jar</systemPath>
</dependency>

如果使用gradle构建，dependencies中添加app-sign-sdk的依赖配置后重新构建即可。

compile files("lib/app-sign-sdk-0.0.2.jar")

生成签名

import com.inspur.cloud.apig.sdk.util.AppSign;
...
Map<String,String> signInfo = AppSign.appSign("163524980934926","C5ABD29977411042C927FA5ECE55B0F5");
String xAuthAppKey= signInfo.get("x-auth-app-key");
String xAuthTime= signInfo.get("x-auth-time");
String xAuthSign= signInfo.get("x-auth-sign");
...

将生成的签名信息按照认证参数传递传参调用API。

使用场景

使用Go语言调用APP认证的API时，您需要先获取SDK并引入到工程中，获取到签名信息后按照认证参数传递规则调用API。

获取SDK

下载SDK，获取“app-sign-go-sdk.zip”压缩包，解压目录结构如下：

名称	说明
sign\signer.go	SDK代码
demo.go	示例代码
go.mod	依赖包管理

将解压后的sign文件夹复制到工程的自定义依赖目录下，参考demo.go导入SDK。

生成签名

获取签名示例

s := sign.Signer{
        Key:    "163524980934926",
        Secret: "C5ABD29977411042C927FA5ECE55B0F5",
    }
    result := s.Sign()
    for key,value:= range result{
        fmt.Printf("%s=>%s\n",key,value)
    }

生成签名信息

x-auth-app-key=>163524980934926
x-auth-time=>1637201932
x-auth-sign=>L5wO3U-poIAWBYZwRo3CvanxTqU

将生成的签名信息按照认证参数传递传参调用API。

Python

使用场景

使用Python语言调用APP认证的API时，您需要先获取SDK并引入到工程中，获取到签名信息后按照认证参数传递规则调用API。

获取SDK

下载SDK，获取“app-sign-python-sdk.zip”压缩包，解压目录结构如下：

名称说明
sign\signer.py SDK代码
main.py 示例代码

将解压后的sign文件夹复制到工程的自定义依赖目录下，参考main.py导入SDK。

生成签名

获取签名示例
```
#  coding=utf-8
from sign import signer

if __name__ == '__main__':
    print(signer.sign( '163524980934926', 'C5ABD29977411042C927FA5ECE55B0F5'))
```
生成签名信息
```
{"x-auth-app-key": "163524980934926", "x-auth-time": 1637203421, "x-auth-sign": "B0qRgVeyoc8MTz5ccayqHkeEiTM"}
```
将生成的签名信息按照认证参数传递传参调用API。

JavaScript

使用场景

使用JavaScript语言调用APP认证的API时，需要先通过签名函数得到签名信息，然后按照认证参数传递规则调用API。

环境准备

通过Node安装crypto-js依赖包

npm install crypto-js

签名函数

引入HmacSha1和Base64算法库

...
import HmacSha1 from 'crypto-js/hmac-sha1';
import Base64 from 'crypto-js/enc-base64';
...

签名函数如下：

...
sign(key,secret) {
    let now = new Date();
    let utcTimestamp = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), now.getUTCHours(), now.getUTCMinutes(), now.getUTCSeconds());
    let xAuthTime = utcTimestamp / 1000;
    let signStr = "auth_app_key=" + key + "&auth_time=" + xAuthTime;
    let sign = Base64.stringify((HmacSha1(signStr, secret)));
    sign = sign.replace(/\//g, '_');
    sign = sign.replace(/[+]/g, '-');
    sign = sign.replace(/=/g, '');
    let result = {
      "x-auth-app-key": key,
      "x-auth-time": xAuthTime,
      "x-auth-sign": sign
    };
    return result;
  }
...
// print result
console.log(sign("163524980934926", "C5ABD29977411042C927FA5ECE55B0F5"));
...

生成签名信息

{
    "x-auth-app-key": "163524980934926",
    "x-auth-time": 1637203421,
    "x-auth-sign": "B0qRgVeyoc8MTz5ccayqHkeEiTM"
}

将生成的签名信息按照认证参数传递传参调用API。

PHP

使用场景

使用PHP语言调用APP认证的API时，您需要先获取SDK并引入到工程中，获取到签名信息后按照认证参数传递规则调用API。

获取SDK

下载SDK，获取“app-sign-php-sdk.zip”压缩包，解压目录结构如下：

名称说明
Sign\Signer.php SDK代码
main.php 示例代码

将解压后的Sign文件夹复制到工程的自定义依赖目录下，参考main.php导入SDK。

生成签名

获取签名示例
```
<?php

require_once "./Sign/Signer.php";

$appAuthKey = "163524980934926";
$appAuthSecret = "C5ABD29977411042C927FA5ECE55B0F5";

$signInfo = new \Signer($appAuthKey, $appAuthSecret);
// 签名 demo
echo $signInfo->sign();
```
生成签名信息
```
{"x-auth-app-key": "163524980934926", "x-auth-time": 1637203421, "x-auth-sign": "B0qRgVeyoc8MTz5ccayqHkeEiTM"}
```
将生成的签名信息按照认证参数传递传参调用API。