Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
本页内容
 

RESTful API 概述

熟悉表述性状态转移 （REST），了解如何在瞻博网络 Mist™ 中使用 RESTful API。

瞻博网络 Mist 的 100% API 架构支持瞻博网络 Mist 门户中的所有可见功能。在门户中可以执行的任何操作，都可以使用 API 大规模实现自动化。表述性状态转移 （REST） 是一种具有统一接口的无状态客户端/服务器架构。由于机器不使用用户界面，因此 API 允许机器以一种定义且更快的方式相互通信。

REST API 使您能够创建与系统和应用程序交互的方式。您甚至可以创建自定义功能。REST API 的其他常见用例包括应用程序之间的通信和数据交换、应用程序和服务器之间的数据交换、应用程序内微服务之间的通信等等。REST 是无状态的，这使其成为基于云的服务的理想选择。

任何拥有瞻博网络 Mist 帐户的客户均可使用瞻博网络 Mist API。

另请参阅 Mist API 参考。这包含面向开发人员的附加文档，以及测试 API 调用的功能。

瞻博网络 Mist API 架构

瞻博网络 Mist 使用 REST API，这些 API 使用 HTTP 方法（GET、POST、PUT 和 DELETE）以 JavaScript Object Notation （JSON） 格式传输数据。

RESTful API 请求

使用 RESTful API 的做法与开发中使用的 CRUD（CREATE、READ、UPDATE、DELETE）方法类似。以下是处理数据时使用的四个基本操作或函数。

表 1：基本 CRUD 操作
粗鲁 HTTP/REST
创建 发布
阅读 获取
更新 放
删除 删除

API 端点 URL 格式

API 端点 URL 由两部分组成：

  • API 主机（或端点）— 与瞻博网络 Mist 组织关联的全球区域的端点。这些端点在 API 端点和全局区域中列出。

  • 函数 - API 端点之后的所有内容表示 API 将调用的函数。

示例

https://{api-host}/api/v1/sites/{site_id}/stats/devices/{device_id}。

https://{api-host}/api/v1/sites/13b0ee00-121a-456e-84e0-ead3008bc2f2/stats/devices/00000000-0000-0000-1000-d420b08532eb

注意：

重复使用代码块时，请将占位符值替换为实际值，例如 API 令牌、组织 ID、站点 ID、接入点名称等。

{api-host} 之后的所有内容都是函数。呼叫将转到全局云，并请求指定站点上指定设备的统计信息。

下一节将更深入地了解构成 API 调用的结构。

API 调用结构

下图是 API 调用及其组成的不同组件的示例。

表 2：API 调用组件

API 调用组件

描述

HTTP 方法

  • POST - 创建对象。- POST 使用有效负载中包含的值覆盖任何现有值。POST 有效负载中未指定的值将恢复为其原始值。

  • GET - 列出对象。- GET 返回资源或资源列表的值，具体取决于是否指定了标识符。

    • GET /api/v1/orgs/:org_id

      根据指定的 ：org_id 返回有关组织的信息。

    • GET /api/v1/orgs/:org_id/site

      返回属于 ：org_id 的站点列表。

    • GET /api/v1/sites/:site_id

      返回有关 ：site_id 指定的站点的信息。

  • PUT - 更新对象。- PUT 修改有效负载中的所有指定值。使用 PUT 进行更新时，有效负载中未指定的简单值（字符串或数字）将保留其现有值。如果值包含数组或对象等数据结构，则有效负载中包含的值将完全替换该结构。请记住这一点，以避免对现有值进行不必要的更改。

  • DELETE - 移除对象。- DELETE 移除资源。

主机（或 API 端点）

确定要使用的 Mist 云（全球 01、欧洲、中东和非洲 01 等）。与瞻博网络 Mist 组织关联的全球区域的端点。请参阅 API 端点和全局区域。

版本

要使用的 API 版本（目前所有 API 都使用 v1）。

范围

指示正在执行请求的级别。示例包括 msp、org、site、self、register、installer、const 等。

范围 ID

标识要使用的范围。

对象

要使用的对象类型（设备、WLAN 等）。

对象 ID

标识要请求的对象。

要在 REST API 上执行上述任何 REST 命令（POST、GET、PUT、DELETE），您需要在每个请求中满足一些要求，例如：

  • 身份验证：

    • 您可以使用 API 令牌、瞻博网络 Mist 登录凭据（此身份验证类型将于 2026 年 9 月弃用）或外部 OAuth2 提供程序来指示您是谁以及您在身份验证过程中有权访问的内容。

    • 有关各种身份验证方法的更多详细信息，请参阅 身份验证。

      注意：

      如果您已经登录 manage.mist.com，只需打开一个新的浏览器选项卡，然后转到 https://{api-host}/api/v1/self/apitokens，然后单击 POST 按钮。这将自动创建一个新的 API 用户令牌。要查找您的主机（API 端点），请参阅 API 端点和全局区域。

      有关令牌的更多信息，请参阅 创建 API 令牌 。

  • HTTP 标头：此标头指定内容和授权类型，如下所示：

    • 对于瞻博网络 Mist，内容类型始终为 application/json。

    • 授权可以是令牌或 Cookie（包括 CSRF 令牌和会话 ID）。

  • 与瞻博网络 Mist 组织关联的全球区域的端点。请参阅 API 端点和全局区域。

  • JSON 有效负载

下表提供了构成 RESTful API 请求的不同部分的示例。

表 3：RESTful API 请求示例

CRUD 操作

HTTP 报头认证

端点 URL

有效负载 （JSON）

获取

API 令牌

https://api.mist.com/api/v1/sites/:site_id/wlans

  

删除

CSRF 令牌、会话 ID

https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id

  

发布

CSRF 令牌、会话 ID

https://api.mist.com/api/v1/orgs/:org_id/inventory

{[“<claim_code>”]}

放

API 令牌

https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id

{“ssid” ： “新名称”}

JSON 有效负载

不同的函数在 JSON 有效负载中需要不同的元素。您可以在 API 文档中查看所需的详细信息。

下面是示例 API 调用和响应（JSON 有效负载）。

API 调用：

响应（JSON 有效负载）：

API 速率限制

瞻博网络 Mist 将 API 调用限制为每小时 5,000 次。如果您需要每小时拨打超过 5,000 个电话，请 创建支持工单。

对于大型部署，建议您在组织级别进行 API 调用，以避免快速达到 API 调用限制。

注意：

为防止暴力攻击，登录 API （/api/v1/login） 在 3 次登录失败后会进行速率限制。

API 身份验证选项

瞻博网络 Mist API 支持三种请求身份验证选项：

  • 基本身份验证 — 令牌

    • 就像密码一样妥善保管。

    • 有关创建 API 令牌的说明，请参阅 创建 API 令牌。

    注意：为了增强安全性并与行业最佳实践保持一致，Mist 将于 2026 年 9 月起弃用所有用例（包括管理员登录和脚本）的基本身份验证。在 2026 年 9 月之前，所有集成都必须过渡到基于令牌的身份验证，以确保不间断的访问和支持。请参阅 创建 API 令牌。

  • HTTP 登录 — 用户名和密码

    • 就像通过仪表板登录

    • 可以是双因素身份验证。

  • OAuth2

    • 帐户必须链接到 OAuth 提供商。

    • 需要浏览器访问权限。

有关身份验证的更多信息，请参阅 Mist API 参考。

一个简单的 API 示例

Django API 接口是一个基于 Web 的界面，您可以在其中执行 API 内的 CRUD 操作。请参阅 使用 Django Web 界面进行 API 更改。

使用 Django API 接口，你可以进行第一次 API 调用。登录 Mist 后，使用同一浏览器打开一个新窗口，然后输入 URL https://{api-host}/api/v1/self。这是全球 01 云的 URL。如果您使用的是其他云，则此 URL 将有所不同。

这相当于进行此 API 调用 GET /api/v1/self。

结果（如上所示）显示分配给您的与您关联的组织和站点的权限。

相关文档