API Explorer

使用 API Explorer 了解 REST API。您还可以测试各种方法和资源，以验证您的配置是否正确。您可以将 JSON 模型复制粘贴到代码中作为起始点。


提示

API Explorer 旨在帮助您了解 API。通过 API Explorer 测试调用需要创建访问锁定，而这可能会干扰常规运行。建议您在非生产设备上使用 API Explorer。

打开 API Explorer

API Explorer 介绍了可用于编程用途的所有资源和 JSON 对象。Explorer 提供有关各对象中属性值对的详细信息，您可以尝试不同的 HTTP 方法，确保了解使用各资源所需的编码。

过程

步骤 1

使用浏览器打开系统主页，例如 https://ftd.example.com。

步骤 2

登录 设备管理器。

步骤 3

（6.4 及更早版本。）编辑 URL，使其指向 /#/api-explorer，例如 https://ftd.example.com/#/api-explorer。

步骤 4

（6.5 及更高版本。）点击“更多选项”按钮 (更多选项按钮。) 并选择 API Explorer。

系统会在单独的选项卡或窗口中打开 API Explorer，具体取决于您的浏览器设置。

探索 API Explorer

进入 API Explorer 后，您会看到资源组列表。这些组包括 API 中可用的资源。下图显示的是示例列表的一小部分。


API Explorer 中的资源列表。

这些组名是链接：点击链接可打开组，从而查看可用于组中资源的方法。各组还包括右侧的以下命令：

  • 显示/隐藏打开和关闭组。这与点击组名的作用相同。最初，展开操作仅显示方法（与列表操作相同），但系统会记住最后的展开状态（在关闭前）并重新打开到相同的展开级别。

  • 列表操作显示可用于组中各资源的 HTTP 方法。信息包括各资源的统一资源定位符 (URL) 模板的相对路径。路径变量由标准约定表示：{variable} 。需要用适当的值替换 {variable} ，包括大括号。必须将基准 URL 添加至这一相对路径；请参阅API 基准 URL。

    点击操作 URL 模板，查看该方法的完整文档。

  • 展开操作打开组中可用的所有 HTTP 方法和资源。

一些组具有许多子资源。例如，DataInterface ManagementAccess 组包括 /devicesettings/default/managementaccess 的 GET、POST 和 DELETE 操作，以及 /devicesettings/default/managementaccess/{objId} 的 GET 和 PUT 操作。


API Explorer 中的类别资源列表。

查看有关资源的文档

每个资源中的属性记录在 API Explorer 中。

过程

步骤 1

详细了解特定资源和您感兴趣的方法。

步骤 2

在响应类 (Response Class) 部分，点击模型 (Model) 选项卡。

模型将列出属性以及说明和数据类型。对于 GET，还有用于可能返回的对象的分页选项。如果对象数量超出返回的对象数量，您将获得下一批和上一批对象的 URL。

例如，下图显示了 POST /object/tcpports 方法和资源，并且选中了模型选项卡。默认情况下，系统将选中示例值 (Example Value) 选项卡，因此必须始终点击模型 (Model) 才能查看文档。


API Explorer 中的 POST object/tcpports 文档。

查找对象 ID (objId) 和父 ID

某些资源需要 URL 中的对象 ID 或相关父 ID，如下所示：

  • PUT /object/networks/{objId}

  • GET /policy/intrusionpolicies/{parentId}/intrusionrules

在大多数情况下，可使用资源层次结构中较高级的 GET 方法获取对象或父 ID。object/parent ID 是给定对象的 id 参数 UUID。

例如，GET/object/networks 返回当前定义的所有网络对象的列表。您可能需要执行多次调用才可遍历列表获取所需对象，或纳入 limit 查询参数以增加为调用返回的对象数。各对象具有以下格式；对象 ID 突出显示。 


{
      "version": "9bbb9e5d-8115-11e7-8cb4-772d7eb1894d",
      "name": "any-ipv4",
      "description": null,
      "subType": "NETWORK",
      "value": "0.0.0.0/0",
      "isSystemDefined": true,
      "id": "9bbbc56e-8115-11e7-8cb4-01865c95f930",
      "type": "networkobject",
      "links": {
        "self": "https://ftd.example.com/api/fdm/最新/object/networks/
9bbbc56e-8115-11e7-8cb4-01865c95f930"
      }

注

在某些情况下，{objId} 出现在层次结构的顶层。在这些情况下，有时可输入任何对象 ID 值并获得相同的结果。在其他情况下，检查对象模型文档以获取有效对象类型的信息；ID 是有效的对象类型之一。这些总是 GET 调用。例如，GET /operational/systeminfo/{objId} 和 GET /operational/featureinfo/{objId}。

查看错误目录并评估错误消息

作为 REST API，如果对不存在的对象执行 GET，则系统会返回标准 HTTP 错误代码，例如 404。

此外，系统还包括许多错误消息，这些错误消息会更具体地解释错误。如果 API 调用导致错误，则响应正文可能包括这些更具体的消息。

例如，如果尝试对以下网络对象 POST /object/networks 操作，会收到错误消息。在此例中，您正在尝试指定网络，但却忘了包含网络掩码（即，该值应为 10.10.10.0/24 或 10.10.10.0/255.255.255.0）： 


{
  "name": "test-network",
  "subType": "NETWORK",
  "value": "10.10.10.0",
  "type": "networkobject"
}

结果将产生 HTTP 响应代码 422，以及包含特定错误消息的响应正文：


{
  "error": {
    "severity": "ERROR",
    "key": "Validation",
    "messages": [
      {
        "description": "The type Network requires a netmask. To specify a single host, either use the type Host, or use {0}/255.255.255.255.",
        "code": "networkWithoutNetmask",
        "location": "value"
      }
    ]
  }
}

以下操作步骤介绍如何查看可在响应正文中返回的可能错误消息列表。

过程

步骤 1

在 设备管理器 中，点击“更多选项”按钮 (更多选项按钮。) 并选择 API Explorer。

步骤 2

点击目录中的错误目录 (Error Catalog)。

这些消息具有以下组成部分。

  • 类别 - 一般消息类型。此值显示在错误响应正文的 key 属性中。类别包括“验证”、“常规”和“部署”。

  • 代码 - 标识错误消息的唯一字符串。此值显示在错误响应正文的 code 属性中。可以使用浏览器的“在页面上查找”功能在目录中找到使用该值的消息。

  • 消息 - 解释错误的特定消息。此值显示在错误响应正文的 description 属性中。消息中的变量表示为 {0}、{1} 等。