REST Web 服务
REST（代表性状态传输）是一种基于客户端和服务器之间简单 HTTP 请求和响应的架构样式。REST 用于查询或更改服务器端对象的状态。在 REST 中，服务器端被建模为一组实体，其中每个实体都由唯一的 URL 标识。
每个资源还有一个状态，可以在该状态下执行以下操作：
- 创建。客户端可以在“容器”资源上创建新的服务器端资源。您可以将容器资源视为文件夹，将子资源视为文件或子文件夹。调用客户端为要创建的资源提供状态。可以在请求中使用 XML 或 JSON 格式指定状态。客户端还可以指定用于标识新对象的唯一 URL。或者，服务器可以选择并返回标识所创建对象的唯一 URL。用于创建请求的 HTTP 方法是 POST。
- 读。客户端可以通过使用 HTTP GET 方法指定资源的 URL 来检索资源的状态。响应消息包含以 JSON 格式表示的资源状态。
- 更新。您可以使用 PUT HTTP 方法在 JSON 或 XML 中指定标识该对象及其新状态的 URL，从而更新现有资源的状态。
- 删除。您可以使用 DELETE HTTP 方法和标识要删除的资源的 URL 来销毁服务器端存在的资源。
除了这四个 CRUD 操作（创建、读取、更新和删除）之外，资源还可以支持其他操作或操作。这些操作使用 HTTP POST 方法，JSON 格式的请求正文指定要执行的操作以及该操作的参数。
SDX NITRO API 根据 API 的范围和用途分为系统 API 和配置 API。
系统接口
使用 NITRO 的第一步是与 SDX 设备建立会话，然后使用管理员的凭据对会话进行身份验证。
在登录对象中指定用户名和密码。创建的会话 ID 必须在会话中所有后续操作的请求标头中指定。
注意：您必须在该设备上拥有用户帐户。您可以执行的配置受分配给帐户的管理角色的限制。
要使用 HTTPS 协议连接到 IP 地址为 10.102.31.16 的 SDX 设备，请执行以下操作：
-
URL
https://10.102.31.16/nitro/v2/config/login/ - HTTP 方法 POST
-
请求
-
标头
Content-Type:application/vnd.com.citrix.sdx.login+json <!--NeedCopy-->注意： 也可以使用早期版本的 NITRO 中支持的内容类型，例如“application/x-www-form-urlencoded”。确保负载与早期版本中使用的负载相同。本文档中提供的有效负载仅在内容类型为“application/vnd.com.citrix.sdx.login+json”的形式时才适用。
-
有效负载
{ "login": { "username":"nsroot", "password":"verysecret" } } <!--NeedCopy-->
-
-
响应有效负载
-
标头
HTTP/1.0 201 Created Set-Cookie: NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2 <!--NeedCopy-->
-
注意： 在对设备进行的所有其他 NITRO 操作中使用会话 ID。
注意： 默认情况下，与设备的连接将在处于非活动状态 30 分钟后过期。您可以通过在 登录对象中指定新的超时周期（以秒为单位）来修改超时期限。例如，要将超时期限修改为 60 分钟，请求负载为：
{
"login":
{
"username":"nsroot",
"password":"verysecret",
"timeout":3600
}
}
<!--NeedCopy-->
您还可以通过在操作的请求标头中指定用户名和密码来连接到设备以执行单个操作。例如，要在创建 NetScaler 实例时连接到设备，请执行以下操作：
- URL
- HTTP 方法
-
请求
-
标头
X-NITRO-USER:nsroot X-NITRO-PASS:verysecret Content-Type:application/vnd.com.citrix.sdx.ns+json <!--NeedCopy--> -
有效负载
{ "ns": { ... } } <!--NeedCopy-->
-
-
响应。
-
标头
HTTP/1.0 201 Created <!--NeedCopy-->
-
要断开与设备的连接，请使用 DELETE 方法：
- URL
- HTTP 方法 DELETE
-
请求
-
标头
Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.login+json <!--NeedCopy-->
-
配置 API
NITRO 协议可用于配置 SDX 设备的资源。
每个 SDX 资源都有一个与之关联的唯一 URL，具体取决于要执行的操作类型。用于配置操作的 URL 的格式如下： http://<IP>/nitro/v2/config/<resource_type>
创建资源
要在 SDX 设备上创建资源（例如，NetScaler 实例），请在特定资源对象中指定资源名称和其他相关参数。例如，要创建名为 vpx1 的 NetScaler 实例，请执行以下操作：
- URL
- HTTP 方法
-
请求
-
标头
Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json <!--NeedCopy--> -
有效负载
{ "ns": { "name":"vpx1", "ip_address":"192.168.100.2", "netmask":"255.255.255.0", "gateway":"192.168.100.1", "image_name":"nsvpx-9.3-45_nc.xva", "vm_memory_total":2048, "throughput":1000, "pps":1000000, "license":"Standard", "profile_name":"ns_nsroot_profile", "username":"admin", "password":"admin", "network_interfaces": [ { "port_name":"10/1" }, { "port_name":"10/2" } ] } } <!--NeedCopy-->
-
检索资源详细信息和统计信息
可以按如下方式检索 SDX 资源详细信息：
-
要检索 SDX 设备上特定资源的详细信息，请在 URL 中指定资源的 ID。
-
要根据某个过滤器检索资源的属性，请在 URL 中指定过滤条件。
该 URL 的格式为：
http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value> -
如果您的请求可能导致从设备返回许多资源，则可以通过将这些结果划分为“页面”并逐页检索它们来以区块形式检索这些结果。
例如，假设您要在包含 53 个 NetScaler 实例的 SDX 上检索所有 NetScaler 实例。与其在一个大型响应中检索全部 53 个，不如将结果配置为分成每页 10 个 NetScaler 实例（共 6 页）。然后，逐页从服务器中检索它们。
您可以使用页码查询字符串参数指定页数，然后使用页码查询字符串参数指定要检索的页码。 该 URL 的格式为：
http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>您不必按顺序检索所有页面或检索页面。每个请求都是独立的，您甚至可以在请求之间更改页面大小设置。
注意： 要了解请求可能返回的资源数量，您可以使用 count query string 参数来请求要返回的资源的计数，而不是资源本身。要获取可用的 NetScaler 实例的数量，URL 应为
http://<IP>/nitro/v2/config/<resource_type>?count=yes
要检索 ID 为 123456a 的 NetScaler 实例的配置信息，请执行以下操作：
- URL
- HTTP 方法 GET
更新资源
要更新现有的 SDX 资源，请使用 PUT HTTP 方法。在 HTTP 请求负载中，指定名称和其他必须更改的参数。例如，要将 ID 为 123456a 的 NetScaler 实例的名称更改为 vpx2：
- URL
- HTTP 方法
-
请求有效负载
-
标头
Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json <!--NeedCopy--> -
有效负载
{ "ns": { "name":"vpx2", "id":"123456a" } } <!--NeedCopy-->
-
删除资源
要删除现有资源，请在 URL 中指定要删除的资源的名称。例如，要删除 ID 为 123456a 的 NetScaler 实例，请执行以下操作：
- URL
- HTTP 方法
-
请求
-
标头
Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json <!--NeedCopy-->
-
批量操作
您可以同时查询或更改多个资源，从而最大限度地减少网络流量。例如，您可以在同一个操作中添加多个 NetScaler SDX 设备。您还可以在一个请求中添加不同类型的资源。
为了解决批量操作中某些操作失败的原因，NITRO 允许您配置以下行为之一：
- 退出。遇到第一个错误时，执行将停止。在错误发生之前运行的命令将被提交。
- 继续。即使某些命令失败，也会运行列表中的所有命令。
注意： 使用 X-NITRO-ONERROR 参数在请求标头中配置所需的行为。
要在一个操作中添加 2 个 NetScaler 资源并在一个命令失败时继续操作，请执行以下操作：
- URL。
- HTTP 方法。
-
请求有效负载。
-
标头
Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue <!--NeedCopy--> -
有效负载
{ "ns": [ { "name":"ns_instance1", "ip_address":"10.70.136.5", "netmask":"255.255.255.0", "gateway":"10.70.136.1" }, { "name":"ns_instance2", "ip_address":"10.70.136.8", "netmask":"255.255.255.0", "gateway":"10.70.136.1" } ] } <!--NeedCopy-->
-
要在一次操作中添加多个资源（NetScaler 和两个 MPS 用户），并在一个命令失败时继续：
- URL。
- HTTP 方法。POST
-
请求有效负载。
-
标头
Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue <!--NeedCopy--> -
有效负载
{ "ns": [ { "name":"ns_instance1", "ip_address":"10.70.136.5", "netmask":"255.255.255.0", "gateway":"10.70.136.1" }, { "name":"ns_instance2", "ip_address":"10.70.136.8", "netmask":"255.255.255.0", "gateway":"10.70.136.1" } ], "mpsuser": [ { "name":"admin", "password":"admin", "permission":"superuser" }, { "name":"admin", "password":"admin", "permission":"superuser" } ] } <!--NeedCopy-->
-
异常处理
错误代码字段指示操作的状态。
- 错误代码为 0 表示操作成功。
- 非零错误代码表示处理 NITRO 请求时出错。
错误消息字段提供了故障的简要说明和故障性质。