Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
在此页面上
 

RESTful API 概述

瞻博网络 Mist 的 100% API 架构支持瞻博网络 Mist 门户中的所有可见功能。可以在门户中执行的任何操作，都可以使用 API 大规模自动化。具象状态传输 （REST） 是具有统一接口的无状态客户端/服务器体系结构。由于机器对用户界面没有用处，因此 API 允许机器以定义且更快的方式相互通信。API 还使您和其他用户能够创建自己的与系统和应用程序交互的方式。您甚至可以创建自定义功能。

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

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

瞻博网络 Mist API 架构

瞻博网络 Mist 使用 REST API，后者使用 HTTP 方法（GET、POST、PUT 和 DELETE）以 JavaScript 对象符号 （JSON） 格式传输数据。

RESTful API 请求

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

表 1：基本 CRUD 操作
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.mist.com/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/site

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

    • GET /api/v1/sites/:site_id

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

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

  • 删除 - 删除对象。- 删除删除资源。

主机（或 API 端点）

确定要使用的 Mist 云（Global 01、EMEA 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 登录凭据或外部 OAuth2 提供商来表明您是谁以及在身份验证过程中您有权访问的内容。

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

      注意：

      如果您已经在 manage.mist.com 上登录，您只需打开一个新的浏览器选项卡并转到 https://api.mist.com/api/v1/self/apitokens 并单击 POST 按钮。这将自动创建新的 api 用户令牌。

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

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

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

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

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

  • JSON 有效负载

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

表 3：RESTful API 请求示例

克鲁德操作

HTTP 标头身份验证

端点网址

有效负载 （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/v1/login） 在三次登录失败后会受到速率限制。

API 身份验证选项

瞻博网络 Mist API 允许三个选项来请求身份验证：

  • 基本身份验证 - 令牌

    • 像密码一样保护它。

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

  • HTTP 登录 — 用户名和密码

    • 就像仪表板登录一样。

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

  • OAuth2

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

    • 需要浏览器访问权限。

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

一个简单的 API 示例

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

使用 Django API 接口，你可以进行第一次 API 调用。登录 Mist 后，使用相同的浏览器打开一个新窗口并输入 https://api.mist.com/api/v1/selfURL .这是全局 01 云的 URL。如果您使用的是其他云，则此 URL 将有所不同。请参阅 API 端点 URL 列表。

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

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

相关文档