ADC

导入 API 规范

API 规范定义了 API 的设计,包括端点、方法、参数和数据格式。导入 API 规范功能允许您导入开放 API 规范,该规范通常用于描述 REST API。 当 Web App Firewall 对用户对基于 API 的 Web 服务的请求进行验证检查时,它会根据该 Web 服务的 API 规范文件中指定的架构对请求进行验证。 NetScaler 支持对 REST API 进行架构验证,有效负载为应用程序 JSON,对于 gRPC API 请求 ProtoBuf。

NetScaler 支持以下规范格式:

  • Open API-Swagger 2.0、OAS 3.0,3.1
  • ProtoBuf-v3 和 v2

管理 API 规范文件

您可以根据导入的 API 规范验证传入的 API 流量,方法是将其分配给配置文件并设置屏蔽或允许流量的放松规则。您还可以在创建策略表达式时使用导入的 API 规范。导入 API 规范包括两个步骤:

  1. 导入 API 规范 - 通过 URL 或从系统将 API 规范导入到 NetScaler。
  2. 将 API 规范添加到 NetScaler-将 API 规范添加到 NetScaler 时,文件将经过验证,转换为内部格式,并创建 API 规范实体。创建的 API 规范实体将用于策略表达式和 Web App Firewall 配置文件。

注意:

确保上载的 Open API Swagger 2.0、OAS 3.0 和 3.1 规范文件不包含对外部文件的任何引用。如果您需要使用外部文件中的详细信息,请使用开源工具将信息合并到一个文件中,然后上载。

使用 CLI 管理 API 规范文件

CLI 命令中使用了以下参数:

  • 名称-上载的 API 规范文件的名称。
  • 来源 - 存储导入的规范文件位置的 URL(协议、主机、路径和名称)。
  • 规范名称 - 根据上载的 API 规范创建的实体的名称。
  • 类型 - API 规范的输入格式。 默认值:OAS

要导入 API 规范文件,请键入:

import api specFile <name> <src>

示例:
import apispec testapispec.json http://www.example.com/testapispec.json

要添加 API 规范文件,请键入:

add api spec <Name> -File <string> -Type <string>

示例:
add api spec testapispec -File testapispec.json -Type OAS

要更新 API 规范文件,请导入需要更新的新规范文件。

在命令提示符下,键入:

update api spec <specName> -File <string> -Type <string>

示例:
update api spec testapispec -File testapispec.json -Type OAS

注意:

如果未指定类型属性,则 OAS 是默认类型。

要查看所有端点,请键入:

show api spec <specName>

示例:

show api spec testapispec

要删除 API 规范,请键入:

rm api spec <specName>

示例:

rm api spec testapispec

注意:

在删除 API 规范之前,请确保任何配置文件或策略均未使用该规范。

使用 GUI 管理 API 规范文件

  1. 导航到“安全”>“NetScaler Web App Firewall”>“导入”
  2. 在“导入”页面上,选择“API 规范导入页面”选项卡,然后单击“添加”。
  3. API 规范导入对象 页面上,为“导入自”参数选择以下任一选项:
    1. URL: 设备可以访问的网站上的 Web URL。
    2. 文件: 本地或网络硬盘或其他存储设备上的文件。
  4. 单击继续
  5. API 规范导入对象 页面上,输入以下详细信息:
    1. API 规范名称 — 根据上载的 API 规范创建的实体的名称。 注意:输入的 API 文件名和 API 规范名称应相同。
    2. API 规格类型-选择规范的类型。

      类型:REST (OpenAPI/Swagger) 和 gRPC(PROTO)。

      默认类型:REST (OpenAPI/Swagger)

    3. 单击 Done(完成)。

新添加的实体在 API 规范导入页面选项卡下的“导入”页面中列出。

查看 API 规范和 API 终端节点的统计信息

您可以查看所有 API 规范和 API 终端节点的以下统计信息:

  • API 规范命中率-与 API 规范的任何端点匹配的请求。
  • API 规范成功验证-与 API 规范的任何端点匹配且符合 API 架构的请求。
  • API 规范不匹配的请求-与 API 规范的任何端点都不匹配的请求。
  • API 终端节点命中率-与特定终端节点匹配的请求。
  • API 端点成功验证-请求匹配特定端点并符合 API 架构。

使用 CLI 查看 API 规范和 API 终端节点统计信息

在命令提示符下,键入:

stat apispec <apispec name>

示例

stat apispec testapispec

使用 GUI 查看 API 规范和 API 端点统计信息

  1. 导航到“安全”>“NetScaler Web App Firewall”>“导入”
  2. 在“导入”页面上,选择“API 规范导入”选项卡,然后单击“统计信息”。

    将显示 API 规范摘要。

  3. 要查看端点摘要,请单击任何 API 规范。

    将显示所选 API 规范的 API 端点摘要。

导入 API 规范