このセクションでは、HTTP PATCH メソッドの使用方法について説明します。
NSX Advanced Load Balancer では、PATCH を使用して次の操作を実行できます。
スカラー フィールド(文字列、ブール、int32 など)を更新する。
オブジェクト内のリストに新しいエントリを追加する。
オブジェクト内のリストにあるエントリを更新する。
スカラー フィールドの設定を解除する。これにより、フィールドがデフォルト値にリセットされます(該当する場合)。
オブジェクト内のリストからエントリを削除する。RFC2616 のセクション 5.1.1 では、「メソッド トークンは、Request-URI が識別するリソースに対して実行されるメソッドを示す。メソッドは大文字と小文字を区別する」と規定されています。そのため、HTTP PATCH 要求の実行時に NSX Advanced Load Balancer から「400 bad request」エラーが返されないように、「PATCH」と表記します。
ネストされたフィールドの編集
現在のリリースでは、PATCH を使用した、ネストされたフィールドの編集は、フィールドの深さが 1 の場合にのみサポートされています。ネストの深さが大きいオブジェクトの編集では、PATCH はサポートされていません。ネストされたフィールドを編集する場合、PATCH はデータが次の形式であることを想定します。
{ "add": { } }
または
{ "replace": { } }
または
{ "delete": { } }
スカラー フィールドの場合、add と replace はどちらも、スカラー フィールドの値を指定された値に置き換えることを意味します。リストの場合、add は指定された一連のエントリをリストに追加する必要があることを示し、replace はリスト自体が要求で指定されたものに置き換えられることを示します。アクションの削除は、指定されたエントリをリストから削除するために使用されます。
例
次の例では、PATCH を使用してプール内のサーバ情報を更新します。プールは UUID で識別されます。
プールにサーバを追加する - NSX Advanced Load Balancer API へのこの要求は、2 台の新しいサーバ(1.1.1.1 と 1.1.1.2)を既存のプールに追加します。
API: /api/pool/pool_uuid Data: { "add": { "servers": [ { "ip": { "addr": "1.1.1.1", "type": "V4" } }, { "ip": { "addr": "1.1.1.2", "type": "V4" } } ] } }
プールのサーバ情報を更新する - NSX Advanced Load Balancer API へのこの要求は、既存のプール内にあるいずれかのサーバを更新します。
API: /api/pool/pool_uuid Data: { "add": { "servers": [ { "ip": { "addr": "1.1.1.1", "type": "V4" }, "ratio": 10 } ] } }
フィールドが構造体の配列である場合、各構造体は通常、キー(構造体内のフィールドの組み合わせ)によって識別されます。これは、更新するリスト内の要素を識別するために使用されます。プール サーバの場合、サーバ キーは IP アドレスとポートで識別されます。
プール内のサーバを新しいサーバ セットに置き換える - この要求は、サーバ リスト全体を新しいサーバ リストに置き換えます。プールの他のフィールドは変わりません。
API: /api/pool/pool_uuid Data: { "replace": { "servers": [ { "ip": { "addr": "3.3.3.3", "type": "V4" }, }, { "ip": { "addr": "3.3.3.4", "type": "V4" }, } ] } }
プールからサーバを削除する - この要求は、既存のプールからサーバの 1 つを削除します。
API: /api/pool/pool_uuid Data: { "delete": { "servers": [ { "ip": { "addr": "3.3.3.3", "type": "V4" }, } ] } }
スカラー フィールドを更新する - このセクションの例は、いくつかのスカラー フィールドを設定します。次の要求は HTTP 要求のキュー登録を有効にし、デフォルトのサーバ ポートを 8080 に設定します。
API: /api/pool/pool_uuid Data: { "replace": { "request_queue_enabled": True, "default_server_port": 8080 } }
次の要求は、プールから明示的な設定を削除することで、デフォルトのサーバ ポートをシステムのデフォルトにリセットします。
API: /api/pool/pool_uuid Data: { "delete": { "default_server_port": 8080 } }
サポート対象オブジェクト
PATCH は、次のオブジェクトとフィールドを正式にサポートしています。
オブジェクト |
フィールド |
---|---|
クラウド |
linuxserver.hosts |
GslbService |
enabled |
IpAddrGroup |
addrs |
prefixes |
|
ranges |
|
MicroServiceGroup |
service_refs |
プール |
health_monitor_refs |
サーバ |
|
StringGroup |
kv |
type |
|
SystemConfiguration |
dns_virtualservice_refs |
global_tenant_config |
|
snmp_configuration.community |
|
VirtualService |
http_policies |
非同期パッチ
プールの追加と削除を高レートで行うには、パッチの適用も高レートで行う必要があります。展開する環境のサイズが大きいと、通常、コントローラにかかる負荷は増え、遅延も増加します。
非同期パッチ機能を使用すると、パッチ要求をキューに登録し、固定間隔で統合し、最小限の遅延で更新できます。
この機能は、展開規模が大きい場合にのみ推奨されます。
コントローラ プロパティで async_patch_merge_period が 0 の場合、プールでのすべての ?async_mode=true
の PATCH 呼び出しが同期呼び出しに変換され、200 応答が返されます。
非同期パッチ アップデートの使用
デフォルトでは、この機能は無効に設定されています。非同期パッチを有効にするには、次の手順を実行します。
コントローラ プロパティの async_patch_merge_period を 0(デフォルト値)から目的の間隔(30 ~ 120 秒)に変更します。
パッチ要求のクエリ パラメータとして async_mode を渡します。たとえば、PATCH /api/pool/<pool-uuid>?async_mode です。応答には一意の patch_id が表示されます。これは、要求の状態を表示するために使用できます。パッチ統合が開始され、キュー内の保留中の要求がマージされます。
/api/pool-async/status/<patch_id> の GET 要求を使用して状態を確認します。状態は次のように表示されます。
{ "uuid": <uuid of the pool>, "status": "QUEUED | IN_PROGRESS | SUCCESS | FAIL", "created": <timestamp of request creation>, "error_message": <error message in case of failure>, "status_code": <status code for server PATCH> }
注意事項
現在、この機能はプール オブジェクトのサーバ フィールド (IP4) でのみ使用できます。
この機能は、プールでのサーバの追加または削除のみに限定されます。
async_patch_merge_period 内のコントローラに対するすべてのパッチ要求は、同じ API バージョン (HTTP_X_AVI_VERSION) であることが必要です。
パッチの更新は、時間間隔で定義されている次の更新サイクルまでインストールされません。そのため、パッチの更新はリアルタイムでは行われません。