Citrix ADC SDX

REST Webサービス

February 1, 2022

寄稿者:

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 のリクエスト本文で、実行するオペレーションとそのオペレーションのパラメータを指定します。

NetScaler SDX NITRO APIは、APIの範囲と目的に応じて、システムAPIと構成APIに分類されます。

システム API

NITRO を使用する最初のステップは、NetScaler SDXアプライアンスとのセッションを確立し、管理者の資格情報を使用してセッションを認証することです。

ログインオブジェクトにユーザ名とパスワードを指定する必要があります。作成されるセッション ID は、セッション内のそれ以降のすべての操作のリクエストヘッダーで指定する必要があります。

注:そのアプライアンスにはユーザーアカウントが必要です。実行できる設定は、アカウントに割り当てられている管理者の役割によって制限されます。

HTTPSプロトコルを使用して、IPアドレスが10.102.31.16のNetScaler 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。 https://10.102.31.16/nitro/v2/config/ns/
HTTP メソッド。POST

要求。

Header

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

Payload</span>

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

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

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

URL。 https://10.102.31.16/nitro/v2/config/login/
HTTP メソッド。DELETE

要求。

Header

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

設定 API

NITRO プロトコルは、NetScaler SDXアプライアンスのリソースを構成するために使用できます。

各NetScaler SDXリソースには、実行する操作の種類に応じて一意のURLが関連付けられています。設定操作のURLの形式はhttp://\<IP\>/nitro/v2/config/\<resource\_type\>です。

リソースを作成する

NetScaler SDXアプライアンスに新しいリソース（NetScalerインスタンスなど）を作成するには、特定のリソースオブジェクトにリソース名とその他の関連する引数を指定します。たとえば、vpx1という名前のNetScalerインスタンスを作成するには、次のようにします。

URL。 https://10.102.31.16/nitro/v2/config/ns/
HTTP メソッド。POST

要求。

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

リソースの詳細と統計の取得

NetScaler SDXリソースの詳細は、次のようにして取得できます。

NetScaler 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ページ）に分割し、サーバーからページごとに取得するように構成できます。

pagesize クエリ文字列パラメーターでページ数を指定し、pageno クエリ文字列パラメーターを使用して取得するページ番号を指定します。

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://10.102.31.16/nitro/v2/config/ns/123456a
HTTP メソッド。GET

リソースを更新する

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

URL。 https://10.102.31.16/nitro/v2/config/ns/
HTTP メソッド。

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

Header

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

Payload</span>

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

リソースを削除する**

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

URL。 http://10.102.31.16/nitro/v2/config/ns/123456a
HTTP メソッド。DELETE

要求。

Header

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

一括操作

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

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

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

注:X-NITRO-ONERROR パラメーターを使用して、要求ヘッダーで必要な動作を設定する必要があります。

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

URL。 http://10.102.29.60/nitro/v2/config/ns/
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"
         }
     ]
 }
 <!--NeedCopy-->

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

URL。 https://10.102.29.60/nitro/v2/config/ns/
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-->

例外ハンドリング

更新日:2014年6月11日

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

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

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

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

REST Webサービス

February 1, 2022

寄稿者:

February 1, 2022

寄稿者: