REST Web サービス

最終公開日 : Sep 25, 2026
REST (Representational State Transfer) は、クライアントとサーバー間のシンプルな HTTP リクエストとレスポンスに基づいたアーキテクチャスタイルです。REST は、サーバー側のオブジェクトの状態を照会または変更するために使用されます。REST では、サーバー側はエンティティのセットとしてモデル化され、各エンティティは一意の URL によって識別されます。
各リソースには状態もあり、その状態に対して以下の操作を実行できます。
  • 作成。 クライアントは、「コンテナ」リソース上に新しいサーバー側リソースを作成できます。コンテナリソースはフォルダ、子リソースはファイルまたはサブフォルダと考えることができます。呼び出し元のクライアントは、作成するリソースの状態を提供します。状態は、XML または JSON 形式を使用してリクエストで指定できます。クライアントは、新しいオブジェクトを識別する一意の URL を指定することもできます。あるいは、サーバーが作成されたオブジェクトを識別する一意の URL を選択して返すこともできます。作成リクエストに使用される HTTP メソッドは POST です。
  • 読み取り。 クライアントは、HTTP GET メソッドでリソースの URL を指定することにより、リソースの状態を取得できます。レスポンスメッセージには、JSON 形式で表現されたリソースの状態が含まれます。
  • 更新。 既存のリソースの状態は、そのオブジェクトを識別する URL と、JSON または XML での新しい状態を、PUT HTTP メソッドを使用して指定することで更新できます。
  • 削除。 サーバー上に存在するリソースは、DELETE HTTP メソッドと、削除するリソースを識別する URL を使用して破棄できます。
これら4つのCRUD操作（作成、読み取り、更新、削除）に加えて、リソースは他の操作やアクションをサポートできます。これらの操作はHTTP POSTメソッドを使用し、JSON形式のリクエストボディで実行する操作とその操作のパラメータを指定します。
SDX NITRO API は、API のスコープと目的に応じて、システム API と構成 API に分類されます。
Related information

システム API

NITRO を使用するための最初のステップは、SDX アプライアンスとのセッションを確立し、管理者の資格情報を使用してセッションを認証することです。
ログインオブジェクトにユーザー名とパスワードを指定します。作成されたセッション ID は、セッション内のそれ以降のすべての操作のリクエストヘッダーで指定する必要があります。
注: そのアプライアンスにユーザーアカウントが必要です。実行できる構成は、アカウントに割り当てられた管理者ロールによって制限されます。
IP アドレス 10.102.31.16 の SDX アプライアンスに HTTPS プロトコルを使用して接続するには:
  • 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>
  • アプライアンスから多数のリソースが返される可能性が高いリクエストの場合、結果を「ページ」に分割し、ページごとに取得することで、これらの結果をチャンクで取得できます。
    たとえば、53個のNetScalerインスタンスを持つSDX上のすべてのNetScalerインスタンスを取得したいとします。53個すべてを1つの大きな応答で取得する代わりに、結果をそれぞれ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アプライアンスを追加できます。また、1つのリクエストで異なるタイプのリソースを追加することもできます。
バルク操作内の一部の操作の失敗を考慮して、NITROでは以下のいずれかの動作を構成できます。
  • 終了。 最初のエラーが発生すると、実行は停止します。エラーの前に実行されたコマンドはコミットされます。
  • 続行。 一部のコマンドが失敗しても、リスト内のすべてのコマンドが実行されます。
注: X-NITRO-ONERROR パラメータを使用して、リクエストヘッダーで必要な動作を構成します。
1つの操作で2つのNetScalerリソースを追加し、1つのコマンドが失敗しても続行するには：
  • 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"
              }
          ]
      }
1つの操作で複数のリソース（NetScalerと2人のMPSユーザー）を追加し、1つのコマンドが失敗しても続行するには：
  • 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リクエストの処理におけるエラーを示します。
エラーメッセージフィールドは、簡単な説明と障害の性質を提供します。