API - HTTP PATCH のサポート

このセクションでは、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
StringGroup	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) であることが必要です。
パッチの更新は、時間間隔で定義されている次の更新サイクルまでインストールされません。そのため、パッチの更新はリアルタイムでは行われません。

ネストされたフィールドの編集

例

サポート対象オブジェクト

非同期パッチ

非同期パッチ アップデートの使用

注意事項

非同期パッチアップデートの使用