Chapter 1. FXOS REST API 简介

您可以通过 HTTPS 使用 FXOS 具象状态传输 (REST) 应用编程接口 (API)，以利用客户端程序与 FXOS 设备交互。REST API 使用 JavaScript 对象表示法 (JSON) 格式表示对象。

“FXOS API”包括平台和 Firepower 机箱服务 API，包括配置和监控 API。这些 API 仅用于 Firepower 可扩展操作系统 (FXOS) 提供的平台服务。

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

您还可以在 https://developer.cisco.com/docs/cisco-firepower-chassis-manager-rest-api-reference/#!cisco-firepower-chassis-manager-rest-api-reference/introduction上找到参考信息和示例。

- 访问 FXOS API 管理器

- 此 API 指南的受众

访问 FXOS API 管理器

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

过程

步骤 1

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

步骤 2

登录 Firepower 机箱管理器。

步骤 3

通过执行以下任一操作打开 FXOS API 管理器：

1. 编辑 URL 以指向 /api/api-explorer/index.html。

例如 https://fcm.example.com/api/api-explorer/index.html。

2. 打开 FCM 帮助菜单，然后选择 API 管理器。

FXOS API 管理器将在单独窗口中打开。

此 API 指南的受众

本指南假设您对编程有基本认识并对 REST API 和 JSON 有特定理解。如果您不熟悉这些技术，请参阅一些常规 REST API 参考材料。

Chapter 2. FXOS REST API 入门

您可以使用任何 REST API 客户端访问 FXOS REST API。通常，REST API 客户端作为浏览器插件提供，但允许使用任何 REST API 客户端。

- 基本 URL

- 客户端身份验证

- 支持的 HTTP 方法

- Accept 报头和内容类型

- HTTP 错误代码

基本 URL

所有用户必须使用 HTTPS 通过设备的配置端口访问 FXOS API。通常，所有 API 请求的基本 URL 如下所示：

https://<Firepower_Chassis_fqdn>[:management_port]/api/

Cisco 建议使用 Firepower 机箱完全限定域名 (chassis_fqdn) 而不是 IP 地址，以便 REST 客户端能够对受管设备进行身份验证；不过仍可使用 IP 地址。Firepower 机箱将使用提供的凭证对 REST 客户端进行身份验证。有关其他详细信息，请参阅客户端身份验证。

客户端身份验证

FXOS REST API 使用基于会话的身份验证方法，需要 HTTP TOKEN 报头才能对来自 API 客户端的每个请求进行身份验证。

除 /api/login 之外的所有 API 必须包括此 HTTP TOKEN 报头，TOKEN 值是 /api/login 响应中包含的实际令牌。如果未在 TOKEN 中指定令牌，REST API 将返回“需要身份验证”错误代码。

要获取身份验证令牌，API 客户端必须执行 POST /api/login 调用并使用以下 HTTP 报头：username: <name_of_user> password: <user_password>。

注

这些用户凭证必须已存在于机箱中，否则将返回“身份验证失败”错误。此外，如果用户密码为 URL 编码，则身份验证将失败。

成功的 /api/login 调用将返回 HTTP 200 代码并包含以下负载：

{
"refreshPeriod": "string",
"token": "string"
}

例如：

{
"refreshPeriod": "0",
"token": "a205739a4d56359730c08ee7bda559cd6e4dd36ad65bb10a17f71d4cea356028"
}

提交所有其他 API 方法请求时，必须提取此令牌并将其包含在 HTTP 报头中，并且令牌的报头字段名称必须为 TOKEN。

身份验证失败时，API 将返回 HTTP 400 代码并包含以下负载：{ "error-code": "551", "error-description": "Authentication failed", "error-nr": "unidentified-fail" }

身份验证失败时，如果令牌无效，API 将返回 HTTP 400 代码并包含以下负载：{ "error-code": "552", "error-description": "Authorization required", "error-nr": "service-unavailable" }

要进行注销，客户端必须提交 POST /api/logout 请求并包含以下 HTTP 报头："TOKEN"= "<authentication_token>"

找到会话并终止会话时，将返回 HTTP 200 代码。

如果未找到指定令牌的有效会话，将返回 HTTP 555 代码并包含以下负载：{ "error-code": "555", "error-description": "Authorization required", "error-nr": "service-unavailable" }

支持的 HTTP 方法

可使用以下 HTTP 方法：

- GET - 检索指定对象。查询在 URL 中提交，输出将包含在响应正文中。

- POST - 创建对象。路径在 URL 中提交，输出包含在响应正文中。

- PUT - 完全更新对象。如果未在负载中指定只读属性，则将忽略只读属性，并将可写属性设置为其默认值。如果未在请求负载中指定子对象，则将删除子对象（自动创建的对象除外）。

- PATCH - 部分更新在 URL 中指定的对象。仅更新指定对象的包含属性。其他现有属性将保留其以前的值。

- DELETE - 删除指定对象。

Accept 报头和内容类型

所有 REST API 客户端必须发送设置为 application/json 的 HTTP Accept 报头。否则，将返回 406 不可接受错误。

当上传 JSON 对象（POST 用于创建对象，PUT 用于更新对象）时，Content-type HTTP 报头必须设置为 application/json。否则，API 将返回 415 不支持的内容类型错误。当上传 Firepower 机箱基础设施捆绑包或 CSP 二进制文件时，REST API 客户端必须将 Content-type HTTP 报头设置为 multipart/binary。

HTTP 错误代码

执行 REST API 方法时，可能的 HTTP 错误代码如下：

- 200 - 成功并包含输出。方法成功，并返回同等 JSON 对象。

- 204 - 成功但输出为空。方法成功，但内容为空。

- 400 - 请求失败。请参阅错误消息了解详细信息。

- 403 - 禁止。权限被拒绝。不允许当前用户执行此操作。

- 404 - 未找到对象。未找到请求的对象。

- 405 - 方法不受支持。API 不支持请求的方法。

- 406 - 不可接受。当客户端请求 application/json 以外的任何内容时，返回此代码。

- 415 - 不支持的内容类型。当客户端发送 application/json 以外的任何内容类型时，返回此代码。

- 500 - 内部错误。API 在处理请求时遇到错误。

Full Cisco Trademarks with Software License

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

All printed copies and duplicate soft copies of this document are considered uncontrolled. See the current online version for the latest version.

Cisco has more than 200 offices worldwide. Addresses and phone numbers are listed on the Cisco website at www.cisco.com/go/offices.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: https://www.cisco.com/c/en/us/about/legal/trademarks.html. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1721R)