REST Web 服务

Last published : Oct 06, 2026
REST（表征性状态传输）是一种基于客户端和服务器之间简单 HTTP 请求和响应的架构风格。REST 用于查询或更改服务器端对象的状态。在 REST 中，服务器端被建模为一组实体，其中每个实体都由唯一的 URL 标识。
每个资源还具有一个状态，可以对其执行以下操作：
  • 创建。 客户端可以在“容器”资源上创建新的服务器端资源。您可以将容器资源视为文件夹，将子资源视为文件或子文件夹。调用客户端提供要创建资源的状态。状态可以通过使用 XML 或 JSON 格式在请求中指定。客户端还可以指定标识新对象的唯一 URL。或者，服务器可以选择并返回标识所创建对象的唯一 URL。用于创建请求的 HTTP 方法是 POST。
  • 读取。 客户端可以通过使用 HTTP GET 方法指定资源的 URL 来检索其状态。响应消息包含以 JSON 格式表示的资源状态。
  • 更新。 您可以使用 PUT HTTP 方法，通过指定标识该对象的 URL 及其在 JSON 或 XML 中的新状态来更新现有资源的状态。
  • 删除。 您可以使用 DELETE HTTP 方法和标识要删除资源的 URL 来销毁服务器端存在的资源。
除了这四个 CRUD 操作（创建、读取、更新和删除）之外，资源还可以支持其他操作或动作。这些操作使用 HTTP POST 方法，请求正文以 JSON 格式指定要执行的操作及其参数。
SDX NITRO API 根据其范围和目的分为系统 API 和配置 API。
Related information
NITRO 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
      注意： 也可以使用早期版本 NITRO 支持的内容类型，例如“application/x-www-form-urlencoded”。请确保负载与早期版本中使用的负载相同。本文档中提供的负载仅适用于内容类型为“application/vnd.com.citrix.sdx.login+json”的情况。
    • 负载
      {
          "login":
          {
              "username":"nsroot",
              "password":"verysecret"
          }
      }
  • 响应负载
    • 标头
      HTTP/1.0 201 Created
      Set-Cookie:
      NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2
注意： 在设备上的所有后续 NITRO 操作中，请使用会话 ID。
注意： 默认情况下，与设备的连接在 30 分钟不活动后过期。您可以通过在 登录对象中指定新的超时时间（以秒为单位）来修改超时时间。例如，要将超时时间修改为 60 分钟，请求负载为：
{
    "login":
    {
        "username":"nsroot",
        "password":"verysecret",
        "timeout":3600
    }
}
您还可以通过在操作的请求标头中指定用户名和密码来连接到设备以执行单个操作。例如，在创建 NetScaler 实例时连接到设备：
  • URL
  • HTTP 方法
  • 请求
    • 标头
      X-NITRO-USER:nsroot
      X-NITRO-PASS:verysecret
      Content-Type:application/vnd.com.citrix.sdx.ns+json
    • 负载
      {
          "ns":
          {
              ...
          }
      }
  • 响应。
    • 标头
      HTTP/1.0 201 Created
要从设备断开连接，请使用 DELETE 方法：
  • URL
  • HTTP 方法 DELETE
  • 请求
    • 标头
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.login+json

配置 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
    • 有效负载
      {
          "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"
                  }
              ]
          }
      }

获取资源详细信息和统计信息

SDX 资源详细信息可以按如下方式检索：
  • 要在 SDX 设备上检索特定资源的详细信息，请在 URL 中指定资源的 ID。
  • 要根据某些筛选器检索资源的属性，请在 URL 中指定筛选条件。
    URL 格式为：http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>
  • 如果您的请求可能会从设备返回许多资源，您可以将这些结果分成“页面”并逐页检索，从而分块检索这些结果。
    例如，假设您要检索 SDX 上所有 53 个 NetScaler 实例。与其在一个大型响应中检索所有 53 个实例，不如将结果配置为每页 10 个 NetScaler 实例（总共 6 页）。然后，逐页从服务器检索它们。
    您可以使用页面大小查询字符串参数指定页面计数，并使用页码查询字符串参数指定要检索的页码。 URL 格式为：http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>
    您不必检索所有页面，也不必按顺序检索页面。每个请求都是独立的，您甚至可以在请求之间更改页面大小设置。
    注意： 为了了解请求可能返回的资源数量，您可以使用 count 查询字符串参数来请求返回资源的计数，而不是资源本身。要获取可用 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
    • 负载
      {
          "ns":
          {
              "name":"vpx2",
              "id":"123456a"
          }
      }

删除资源

要删除现有资源，请在 URL 中指定要删除的资源的名称。例如，要删除 ID 为 123456a 的 NetScaler 实例：
  • URL
  • HTTP 方法
  • 请求
    • 标头
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.ns+json

批量操作

您可以同时查询或更改多个资源，从而最大限度地减少网络流量。例如，您可以在同一操作中添加多个 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
    • 负载
      {
          "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"
              }
          ]
      }
要在一次操作中添加多个资源（NetScaler 和两个 MPS 用户），并在一个命令失败时继续执行：
  • URL。
  • HTTP 方法。 POST
  • 请求负载。
    • 请求头
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.ns+json
      X-NITRO-ONERROR:continue
    • 有效负载
      {
          "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"
              }
          ]
      }

异常处理

错误代码字段指示操作的状态。
  • 错误代码为 0 表示操作成功。
  • 非零错误代码表示处理 NITRO 请求时出错。
错误消息字段提供简要说明以及故障的性质。