NetScaler SDX

REST ウェブサービス

November 23, 2023

寄稿者:

REST (表現状態転送) は、クライアントとサーバー間の単純な HTTP リクエストとレスポンスに基づくアーキテクチャースタイルです。REST は、サーバー側でオブジェクトの状態を照会または変更するために使用されます。REST では、サーバー側はエンティティのセットとしてモデル化され、各エンティティは一意の URL によって識別されます。

各リソースには、次の操作を実行できる状態もあります。

作成。クライアントは「コンテナ」リソース上に新しいサーバー側リソースを作成できます。コンテナリソースはフォルダ、子リソースはファイルまたはサブフォルダと考えることができます。呼び出し側クライアントは、作成されるリソースの状態を提供します。この状態は、XML または JSON 形式を使用してリクエストで指定できます。クライアントは、新しいオブジェクトを識別する一意の URL を指定することもできます。また、サーバーは作成されたオブジェクトを識別する一意の URL を選択して返すこともできます。作成リクエストに使用される HTTP メソッドは POST です。
読み取り。クライアントは HTTP GET メソッドで URL を指定することで、リソースの状態を取得できます。レスポンスメッセージには、JSON 形式で表現されたリソースの状態が含まれます。
[更新]。PUT HTTP メソッドを使用して、JSON または XML でオブジェクトとその新しい状態を識別する URL を指定することで、既存のリソースの状態を更新できます。
[削除]。サーバー側に存在するリソースを破棄するには、DELETE HTTP メソッドと、削除するリソースを識別する URL を使用します。

この 4 つの CRUD 操作 (作成、読み取り、更新、削除) に加えて、リソースは他の操作やアクションをサポートできます。これらのオペレーションでは HTTP POST メソッドを使用し、JSON のリクエスト本文で、実行するオペレーションとそのオペレーションのパラメータを指定します。

SDX NITRO API は、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
リクエスト
- Header
```
 Content-Type:application/vnd.com.citrix.sdx.login+json
 
```
  注: 以前のバージョンの NITRO でサポートされていた「application/x-www-form-urlencoded」などのコンテンツタイプも使用できます。ペイロードが以前のバージョンで使用されていたものと同じであることを確認します。このドキュメントに記載されているペイロードは、コンテンツタイプが「application/vnd.com.citrix.sdx.login+json」の形式である場合にのみ適用されます。
- Payload
```
 {
     "login":
     {
         "username":"nsroot",
         "password":"verysecret"
     }
 }
 
```

レスポンスペイロード

Header

 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-->

また、操作の要求ヘッダーにユーザー名とパスワードを指定することで、アプライアンスに接続して 1 回の操作を実行することもできます。たとえば、NetScalerインスタンスの作成中にアプライアンスに接続するには、以下を実行します。

URL
HTTP メソッド

リクエスト

Header

 X-NITRO-USER:nsroot
 X-NITRO-PASS:verysecret
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "ns":
     {
         ...
     }
 }
 <!--NeedCopy-->

応答。
- Header
```
 HTTP/1.0 201 Created
 
```

アプライアンスから切断するには、DELETE メソッドを使用します。

URL
HTTP メソッド削除

リクエスト

Header

 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 メソッド

リクエスト

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "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個ある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のインスタンスの構成情報を取得するには：

URL
HTTP メソッド GET

リソースを更新する

既存の SDX リソースを更新するには、PUT HTTP メソッドを使用します。HTTP リクエストペイロードで、名前と、変更する必要のあるその他の引数を指定します。たとえば、IDが123456aのNetScalerインスタンスの名前をvpx2に変更するには、

URL
HTTP メソッド

ペイロードのリクエスト

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "ns":
     {
         "name":"vpx2",
         "id":"123456a"
     }
 }
 <!--NeedCopy-->

リソースを削除する

既存のリソースを削除するには、削除するリソースの名前を URL に指定します。たとえば、ID が123456a のNetScaler ADC インスタンスを削除するには、次のようにします。

URL
HTTP メソッド

リクエスト

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

一括操作

複数のリソースを同時に照会または変更できるため、ネットワークトラフィックを最小限に抑えることができます。たとえば、同じ操作で複数のNetScaler SDXアプライアンスを追加できます。1 つのリクエストで、異なるタイプのリソースを追加することもできます。

NITRO では、一括操作内の一部の操作が失敗したことを考慮して、次のいずれかの動作を構成できます。

出口。最初のエラーが発生すると、実行は停止します。エラー発生前に実行されたコマンドがコミットされます。
続ける。一部のコマンドが失敗した場合でも、リスト内のすべてのコマンドが実行されます。

注:X-NITRO-ONERROR パラメータを使用して、リクエストヘッダーで必要な動作を設定します。

1回の操作で2つのNetScaler ADCリソースを追加し、1つのコマンドが失敗した場合に続行するには：

URL。
HTTP メソッド。

ペイロードをリクエストします。

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 X-NITRO-ONERROR:continue
 <!--NeedCopy-->

Payload

 {
     "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-->

1つの操作で複数のリソース（NetScalerと2人のMPSユーザー）を追加し、1つのコマンドが失敗しても続行するには：

URL。
HTTP メソッド。POST

ペイロードをリクエストします。

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 X-NITRO-ONERROR:continue
 <!--NeedCopy-->

Payload

 {
     "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-->

例外ハンドリング

errorcode フィールドはオペレーションのステータスを示します。

エラーコード 0 は、操作が成功したことを示します。
0 以外のエラーコードは、NITRO 要求の処理中にエラーが発生したことを示します。

エラーメッセージフィールドには、簡単な説明と失敗の性質が表示されます。

このコンテンツの正式なバージョンは英語で提供されています。Cloud Software Groupドキュメントのコンテンツの一部は、お客様の利便性のみを目的として機械翻訳されています。Cloud Software Groupは機械翻訳されたコンテンツを管理していないため、誤り、不正確な情報、不適切な用語が含まれる場合があります。英語の原文から他言語への翻訳について、精度、信頼性、適合性、正確性、またはお使いのCloud Software Group製品またはサービスと機械翻訳されたコンテンツとの整合性に関する保証、該当するライセンス契約書またはサービス利用規約、あるいはCloud Software Groupとのその他すべての契約に基づき提供される保証、および製品またはサービスのドキュメントとの一致に関する保証は、明示的か黙示的かを問わず、かかるドキュメントの機械翻訳された範囲には適用されないものとします。機械翻訳されたコンテンツの使用に起因する損害または問題について、Cloud Software Groupは責任を負わないものとします。

REST ウェブサービス

November 23, 2023

寄稿者:

November 23, 2023

寄稿者: