腾讯轻联
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 腾讯轻联 > 控制台指南（新版） > 集成开发 > API 管理

API 管理

最近更新时间：2024-04-25 09:58:11

我的收藏

本页目录：

注意：
试用公有云版本 API 管理需扫码申请（登录 腾讯轻联控制台，单击 API 管理菜单即可申请）。
API 管理的独立环境与应用集成环境不互通。

操作场景

各大企业每天都有大量的 API 增长，同时越来越多公司开始公开 Web API，API 的使用场景正在累积。现在，每日 API 调用量在不断飙升，如何能够安全有效将这些 API 管理起来对于企业而言并不容易。 腾讯轻联提供 API 发布功能，可以一键将已发布的应用打包生成 API，方便用户进行管理和调用；同时提供了 API 管理能力，可以针对 API 进行访问权限管控和流量调度。

操作步骤

API 管理主页

登录 腾讯轻联控制台，在左侧导航栏单击 API > API 管理，即可进入 API 管理的主页。 在 API 管理主页，您可以创建或查看 API 服务、可以查看 API 目录、管理 API 订阅凭证，同时可对 API 服务进行审核管理。

API 服务列表

此页面可创建或查看 API 服务。创建完成的 API 服务展示在此列表，项目内所有成员都可查看。

enter image description here


API 服务状态有三种：配置中、运行中、已停止。鼠标可 hover 到服务域名处查看该 API 服务的发布环境和域名。
API 服务支持的操作有：查看、新建 API、上架、下架、删除、查看描述文件、查看发布历史。
注意：
只有服务状态为配置中的 API 服务才有新建 API 和删除的操作。
只有服务状态为运行中的 API 服务才可进行上架和下架的操作。
单击 API 服务的名称可跳转到 API 列表页。
支持管理服务分组，包括新建、删除、编辑服务分组。每个项目下的服务分组相互独立，互不影响。

enter image description here



新建 API 服务

API 管理功能支持 3.0.0 版本的 OpenAPI 规范。OpenAPI 3.0.0 规范的对象定义请参见 OpenAPI Specification。用户可以通过单击 新建 进入 API 服务创建界面。创建 API 服务一共有2个步骤。

方式一：导入服务

单击导入，即可支持通过上传 YAML 或 JSON 格式的文件，来导入服务。




方式二：新建服务

1. 配置服务名称，协议与描述。
服务名称和描述自定义即可，协议支持3种：HTTP、HTTPS、HTTP+HTTPS。分组可选择默认分组、新建分组。如下图所示。



2. 配置策略信息。
配置黑白名单：您可以按需开启，开启后可以输入多条 IP 进行黑白名单的访问限制。
基础流量控制：您可以按需开启，开启后可配置服务请求频率，每单位时间内允许的最大请求次数，填写范围为1 - 1000。
当上述配置全部完成后，单击完成，则会返回 API 服务列表，同时已经创建好的 API 服务信息将会展示在此处。



新建 API

当我们创建好一个 API 服务之后，可以开始编辑其具体 API 行为，包括 API 的请求路径（API Path）、请求方法、分组、鉴权策略、请求参数、策略配置、API 绑定的后端服务类型等操作。 新建 API 一共有3个步骤。

步骤一：基础配置



API 名称、描述支持自定义。分组可选择默认分组、新建分组。
请求方法支持：GET、POST、PATCH、PUT、DELETE、HEAD。
鉴权方式支持：NoAuth、BasicAuth、OAuth2.0、HMAC。
后端服务类型支持：集成流、第三方服务、数据库、Mock 类型。
请求参数支持：可自行添加请求参数，参数类型包括 integer、string、number、boolean、array、object，最多添加30条。



数据库类型支持新建或选择 MySQL、Oracle、Postgre SQL、Sql Server 类型的数据源。



策略配置：
轻联 API 管理支持多样的策略配置，如下：
IP 访问限制：
支持针对 API 接口粒度设置 IP 访问黑名单/白名单。



基础流量控制：
支持针对 API 接口粒度设置基础流量控制，包括 API 请求频率（该 API 被请求的最大频率）和源 IP 请求频率（该 API 被同一源 IP 请求的最大频率），周期时长包括：秒、时、日、7日、30日、365日。



请求包大小限制：
支持针对 API 接口粒度设置请求包大小限制，指定请求 body 大小。



防重放攻击：
支持针对 API 接口粒度设置防重放攻击，开启后需配置 header 请求参数 X-Ca-Nonce 和 X-Ca-Timestamp，并在每次请求时传入这两个参数：X-Ca-Timestamp 代表请求时刻时间戳（秒级），X-Ca-Nonce 代表请求的唯一标识（每个有效时长内不允许重复）。基于这两个参数来保障有效时长内请求的唯一性，保障 API 安全。
nonce 有效时长代表底层存储每个 API 请求唯一标识的时长，如果太大可能影响校验性能。并且会将 nonce 有效时长视作正常 API 请求从发出到到达服务端的最大时间差，如果太小可能误判正常请求。



熔断降级：
支持针对 API 接口粒度设置熔断降级策略，当每个统计周期内该 API 发生的错误（按错误定义）达到错误次数后，即会触发熔断并维持断路持续时长，此期间所有请求均转发到降级后端配置，从而适应 API 请求高并发场景。




步骤二：后端配置




选择集成流时：需选择 webhook 触发的且在运行中的集成流。
后端超时时间：可默认系统预设的，也可自定义。
请求方法：根据用户需求选择即可。支持：GET、POST、PATCH、PUT、DELETE、HEAD。
参数定义：支持配置前后端参数映射。

步骤三：响应配置

支持配置响应示例，以及错误码配置。


当上述配置全部完成后，单击完成，则会返回 API 列表，同时已经创建好的 API 信息将会展示在此处。

API 列表页

创建好的 API 会展示在 API 列表中，此页面可新建、查看和编辑 API。可发布 API、可设置、查看 API 描述文件和调用凭证，可查看 API 的订阅详情。



左侧是 API 列表，右侧默认 tab 页是 API 的详细配置信息：API 的访问路径、请求方法、参数、后端服务类型等都可在此处查看。
1. 单击调试 tab 页，进入 API 调试页面。在 API 调试页面，您可以配置此 API Endpoint 的请求 Header 和 Body 内容，并单击发送请求。



2. 随后即可获取到测试的结果。我们会将后端服务返回的 Response 状态码和结果返回给用户，方便进行进一步的调试工作。
3. 右上角单击发布，可发布此 API 到多个环境。
4. 发布后，发布后的 API 状态为运行中。
5. 右上角的复制，可将当前版本覆盖到配置中的版本。复制后，API 服务可以再次发布。一个 API 服务可以发布到多个环境。
6. 可在 API 详情页可查看其日志和监控。日志与监控详细信息参见 运维中心-监控管理 和 运维中心-运行日志。
7. 发布后的 API 服务可停止服务。

描述文件

描述文件是针对当前 API 服务的说明，左侧展示 YAML/JSON 格式文件，右侧对应展示 Swagger 可视化内容。
支持将 API 文档导出为 Markdown 格式文件，方便调用方查看。

enter image description here



调用凭证

创建 API 服务时，若选择的鉴权策略为 NoAuth，则可忽略此选项，反之，若 API 服务需要鉴权，则需在此页面配置调用凭证。通过当前服务下的任意调用凭证，即可调用服务下任意 API。


上图为凭证列表页，创建好的凭证会展示在此处，选择新建凭证，即可创建新的凭证。自定义凭证的信息，保存即可。




订阅详情

上架后的 API 服务，可以被该企业主 UIN 下的所有子 UIN 订阅并调用。该菜单可以查看当前 API 服务被订阅的情况。


此处可以看到订阅该 API 的所有用户名单，同时，可以移除某用户的订阅。

脱敏策略

支持针对 API 服务设置脱敏策略，上架后被订阅时可以选择绑定脱敏策略，从而实现对订阅者返回按脱敏策略处理过的响应报文。

enter image description here


新建脱敏策略时，支持选择运行中的 API 服务，目前支持的脱敏规则如下，支持在一个脱敏策略中新增多个脱敏设置（每个脱敏设置对应一个 API 接口）。可以设置脱敏规则为：不脱敏直接返回、不返回、脱敏。

enter image description here


当选择脱敏时，支持选择预置脱敏规则和自定义脱敏规则。

enter image description here


自定义脱敏规则如下，支持设置掩码、哈希、关键字替换的脱敏算法。




服务操作

删除 API 服务

单击删除，可删除当前 API 服务。删除后，该 API 服务下的所有配置将被清空，且无法恢复。运行中的服务不可直接删除，需先停止再删除。

API 上架与下架

上架：运行中的 API 服务，可通过上架功能共享给企业的其他员工使用。在 API 服务 > 操作 > 更多 > 上架路径提交上架申请，提交后的 API 服务会被企业管理员审核，审核通过后可展示在 API 目录中，支持被当前主账号下的所有子账号订阅。
下架：上架后的 API 服务，若不想继续被其他员工订阅，则可通过下架来完成。在 API 服务 > 操作 > 更多 > 下架路径提交下架申请，提交申请后需联系系统管理员或该项目的项目管理员进行审核，审核通过后即可下架，API 下架后不能被订阅。下架后的 API 服务会移出 API 目录。




查看上线历史

发布后的 API 服务可以更改状态、环境等。在 API 服务 > 操作 > 更多 > 查看发布历史路径。此功能可查看到 API 服务发布后的历史情况（最多显示10条）。

enter image description here



API 概览

支持查看 API 概览，包括服务数量统计，指标数据概览和查看已关注服务。可以在左上角选择全局概览（仅系统管理员可以查看）或项目概览（仅系统管理员和对应项目管理员可以查看）。

enter image description here


如图为查看 API 服务的总数统计，可以看到每个项目下的服务总数、每个服务下的 API 明细。



也支持查看项目统计图示，以及单击导入导出项目、服务、API 明细列表。

enter image description here


支持设置关注服务，从而在 API 概览中直接查看其关键指标。

enter image description here



API 目录

API 目录展示已上架的 API 服务。类似一个 API 服务市场，上架后的服务，不局限项目维度，可以被当前主账号下的所有子账号查看、订阅并调用。此页面可通过 API 服务的属性快速搜索服务。同时，可申请订阅或取消订阅 API 服务。

enter image description here



申请订阅

申请订阅 API 服务时，需选择或新建订阅凭证。将凭证与 API 服务关联上。待系统管理员审核后，即可成功订阅。




取消订阅

取消订阅后将不能调用该 API 服务，此操作无需系统管理员审核。

订阅凭证

此列表可展示或搜索所有的订阅凭证，同时，可新建凭证。订阅凭证用于订阅 API 目录中的服务。凭证即为某 API 服务的钥匙。在申请订阅 API 服务时将凭证与 API 服务关联上，调用的时候填写该凭证，即可成功调用该服务。同时，能看到该凭证各种鉴权类型的 Key 和 Secret，调用时直接复制即可使用。

enter image description here


一个凭证支持与多个 API 服务关联。可在订阅的 API tab 页查看此凭证关联的所有 API 服务。

enter image description here


新建凭证时，自定义相关属性即可。

审核管理

审核管理分两个功能：我提交的和我审核的。涉及到审核的事项都在此功能页处理。
我提交的：展示个人提交的所有审核信息。全部角色都可见。

enter image description here


我审核的：此页面展示需审核的信息。只有系统管理员和项目管理员角色能看到。其他角色访问页面数据为空。

enter image description here


系统管理员审批全部项目 API 服务上下架或 API 服务订阅的请求。
项目管理员审批所在项目内的 API 服务上下架或 API 服务订阅的请求。

规范管理

支持系统管理员对全部 API 接口按所选检查策略进行规范检查，得出每一个 API 接口的检查明细、得分，并支持导出检查报告 Excel 文件，以作进一步分析。
规范配置：系统默认提供一个“默认策略”，其中包括针对请求路径、请求方法、鉴权方式、请求参数、后端资源路径的规范检查项配置。用户也可以自行新建检查策略。

enter image description here


系统默认会给所有API服务，都关联默认检查策略。

enter image description here


规范检查：
进入规范检查菜单，可以按指引启动规范检查，检查结束后可以查看检查列表，呈现每个 API 接口对应的待修正检查项，检查结果，结果分值。

enter image description here


支持单击待修正检查项，查看详细的不规范项内容。

enter image description here


还支持单击右上角导出检查报告，以及设置检查结果分档。

API 调用步骤

从用户侧用不同鉴权方式调用 API（以 postman 为例）

API 服务无需验证的情况：



API 服务需要 Basic Auth 的情况：
1.1 复制 API 的调用地址（需先成功发布 API 服务）：



1.2 进入 API 服务详情页面，新建或打开已有调用凭证，即可查看用于 Basic Auth 的 AK/SK 信息：



1.3 打开 postman，将上述获取的 API 调用地址和用于 Basic Auth 的 AK/SK 信息分别填入：



API 服务需要 OAuth2.0 的情况：
1.1 复制 API 的调用地址（需先成功发布 API 服务），方法同上，不再附图。
1.2 进入 API 服务详情页面，新建或打开已有调用凭证，即可查看用于 OAuth2.0 的 AK/SK 信息：



1.3 进入 API 服务详情页面，单击并复制对应 API 的 Token 获取链接。



1.4 在 postman 中创建一个新的请求，来获取 accsee_token。
1.4.1 首先，在输入栏中输入第3步获取的 Token 获取链接，并选择 GET 请求方法。
1.4.2 其次，选择 Params 标签页，分别输入第2步获得的用于 OAuth2.0 的 AK/SK 信息（格式见下图）。
1.4.3 最后，单击 send，即可生成下图中的 access_token 内容，将其复制。



1.5 在 postman 重新打开一个请求界面，填入第1步获取的 API 调用地址，Type 选择 OAuth2.0 模式。并在右侧填入第4步获取的 accsee_token，单击 send，即可看到访问结果（如果配置 API 时还设置了请求参数，这里也要按位置输入）。



1.6 当 access_token 过期（24h）之后，需要借助 refresh_token 获取新的 access_token：
在1.4步骤中 access_token 接口的返回值中会包含 refresh_token，利用 refresh_token 请求 refresh_token 接口，可以拿到最新的 access_token。



API 服务需要 HMAC Auth 的情况：
1.1 复制 API 的调用地址（需先成功发布 API 服务），方法同上，不再附图。
1.2 进入 API 服务详情页面，新建或打开已有调用凭证，即可查看用于 HMAC 的 AK/SK 信息：



1.3 打开 postman，在输入框填入第1步获取的 API 调用地址。
1.4 将 postman 切换到 Pre-request Script 标签下，粘贴下方代码段（注意用第2步获取的 HMAC 的 Key 和 Secret，分别来替换代码段中的 hmac_key 和 hmac_secret 变量值）。



var hmac_key = "2e4d0bbad47e3b5e3a0c";
var hmac_secret = "815ba6d666d58ef1e79b";
var time = new Date().toUTCString();
console.log("time:" + time)
var signed_headers_string = "";
signing_string= pm.request.method + "\\n" + pm.request.url.getPath() + "\\n" + pm.request.url.getQueryString() + "\\n" + hmac_key + "\\n" + time + "\\n" + signed_headers_string;
console.log("signing_string:\\n" + signing_string);
var signatureBytes = CryptoJS.HmacSHA256(signing_string, hmac_secret);
var requestSignatureBase64String = CryptoJS.enc.Base64.stringify(signatureBytes);
console.log("requestSignatureBase64String:" + requestSignatureBase64String)
//将下面变量记录下来，在请求的Header中进行引用
pm.globals.set("sign", requestSignatureBase64String); //hmac签名
pm.globals.set("hmac_key", hmac_key); //hmac key
pm.globals.set("date", time); //请求时间
1.5 将 postman 切换到 Headers 标签下，输入下图中的4个 KEY-VALUE 对。最后，单击 send，即可看到调用 API 的返回结果。



中国站