2. 主页
  4. 文档
  6. NDI 设备 HTTP API(Version 1.0)
  8. 2. 安全性规则

2. 安全性规则

为保证网络安全性，HTTP API需要您按照本节所描述的安全性规则进行安全授权，否则设备将拒绝您的HTTP请求。

如非特殊情况，我们强烈建议您使用HTTPS（而不是HTTP）来执行HTTP API。HTTP可能为您带来泄露敏感信息（例如用户名、密码）的安全隐患。

授权

在您使用任何本文档所描述的HTTP API之前，您必须先获得使用HTTP API的授权。

NDI Devices授权的机制简单描述如下：

1) 首先，您需要提供一个有效的用户名和密码，NDI Device需要校验您的用户名和密码的合法性；

2) 如果您的用户名和密码校验正确，NDI Device将为您生成一对随机的Session ID和Authorization Token，并在响应中返回给您。

3) 您必须记录这对Session ID和Authorization Token。在您接下来的每一个HTTP API请求中，您都必须传递Session ID和Authorization Token在HTTP的请求Headers或参数中。这有三种可选择的传递方式：

  • 通过HTTP GET/POST参数；
  • 通过HTTP Headers字段；
  • 通过HTTP Cookie。

授权本身也是一个HTTP API，不过它与其它的API不同之处在于，它不检查和校验 Session ID 和 Authorization Token，而是通过检查您提交的用户名和密码来为您生成Session ID和Authorization Token。

API URL

**/api/v1/user/authorize**

Request

Method：**GET/POST**
参数 Value 说明
username [STRING] ,Required 请求授权的有效用户名。
password [STRING] ,Required 请求授权用户的密码。

Response

格式（Example）：

{
    "result": "ok",
    "data": {
        "session": "559dee0bd779a894618d6e044c35a3fc",
        "token": "4345cd7b092d762bd4a646a98aa9f8ff"
    }
}

Data字段说明：

Field Value 说明
session [STRING] 随机的Session ID。
Session ID和Authorization Token将在您没有任何HTTP API操作之后的10分钟内失效。
token [STRING] 随机的Authorization Token。
您应该记录下session & token 的值，并在后续其它的HTTP API请求中传递这两个值。

一些建议：

1) 提醒您注意！最好不要使用系统内建的管理员用户"admin"进行API授权，这会有严重的安全风险！您可以在NDI Devices的Web UI中创建其他的用户，并使用这些用户来执行HTTP API请求。

2) 使用HTTPS而不是HTTP来请求授权，否则您有泄露用户名和密码的风险！

在HTTP API请求中传递Session ID和Authorization Token

如果您按照授权所描述的方法请求授权成功，您将获得NDI Device为您生成的Session ID和Authorization Token。接下来，您请求任何其它的HTTP API，NDI Device都将需要验证您的Session ID和Authorization Token是否合法。如果您没有提供Session ID和Authorization Token，或者您提供了非法的值，您的HTTP API请求将返回如下错误 (example)：

{
    "result": "auth-failed",
    "msg": "...error message..."
}

有三种方法传递Session ID和Authorization Token：

A. [建议方法] 通过HTTP Request Headers传递

在HTTP Request Headers中，添加 "API-Session" Header field表示Session ID，以及添加 "API-Token" Header field表示Authorization Token。例如：

POST /api/v1/your/api HTTP/1.1
...
API-Session: 559dee0bd779a894618d6e044c35a3fc
API-Token: 4345cd7b092d762bd4a646a98aa9f8ff
...

<BODY>

如果使用curl进行测试，命令如下：

$ curl -H 'API-Session: 4345cd7b092d762bd4a646a98aa9f8ff' -H 'API-Token: 4345cd7b092d762bd4a646a98aa9f8ff' https://192.168.100.168/api/v1/your/api

B. 通过Cookie传递

通过HTTP Cookie字段 "session" 传递Session ID，以及字段 "token" 传递Authorization Token。例如：

POST /api/v1/your/api HTTP/1.1
...
Cookie: session=4345cd7b092d762bd4a646a98aa9f8ff;token=4345cd7b092d762bd4a646a98aa9f8ff
...

<BODY>

如果使用curl进行测试，命令如下：

$ curl -b 'session=4345cd7b092d762bd4a646a98aa9f8ff;token=4345cd7b092d762bd4a646a98aa9f8ff' https://192.168.100.168/api/v1/your/api

C. 通过GET/POST参数传递 [不建议]

如果方法 A 和方法 B 都不适用于您，那么您也可以通过 GET/POST 的参数来传递Session ID以及Authorization Token。但我们非常不建议您采用这种方式，因为这会破坏HTTP API参数的规范性，使得HTTP API的参数看起来混乱不堪。

在确有必要的情况下，您可以在HTTP GET/POST参数中传递 "api-session"作为Session ID，以及"api-token"作为Authorization Token。例如：

https://<device-ip>/api/v1/your/api?api-session=4345cd7b092d762bd4a646a98aa9f8ff&api-token=4345cd7b092d762bd4a646a98aa9f8ff

我们要如何帮助您？