本节介绍了 HTTP PATCH 方法的用法。

NSX Advanced Load Balancer 支持使用 PATCH 执行以下操作：

  • 更新标量字段（字符串、布尔、int32 等）。

  • 在对象中添加新列表条目。

  • 在对象中更新列表条目。

  • 取消设置标量字段 - 这会导致字段重置为其默认值（如果可行）。

  • 在对象中删除列表条目 - 根据 RFC2616 第 5.1.1 节，“方法标记指示将对通过请求 URI 标识的资源所执行的方法。方法区分大小写。”因此，应拼写为“PATCH”，以避免在执行 HTTP PATCH 请求时，NSX Advanced Load Balancer 出现“400 错误请求”(400 bad request) 错误。

编辑嵌套字段

在当前版本中，仅当字段深度为 1 时，才支持使用 PATCH 编辑嵌套字段。不支持使用 PATCH 编辑具有深度嵌套特征的对象。要完成对嵌套字段的编辑，PATCH 要求数据采用以下格式：

{
    "add": {

    }
}

或

{
    "replace": {

    }
}

或

{
    "delete": {

    }
}

对于标量字段，add 或 replace 是等效的，因为它们都会将标量字段的值替换为提供的值。对于列表，add 表示需要将指定的一组条目添加到列表中，而 replace 则表示将列表本身替换为请求中指定的内容。delete 操作用于从列表中移除指定的条目。

示例

以下示例使用 PATCH 更新池中的服务器信息。池通过其 UUID 进行标识。

  • 将服务器添加到池 - 此 NSX Advanced Load Balancer API 请求会将两个新服务器（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"
                },
            }
        ]
    }
}

  • 从池中删除服务器 - 此请求会从现有池中删除一个服务器。

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：

对象

字段

Cloud

linuxserver.hosts

GslbService

enabled

IpAddrGroup

addrs

prefixes

ranges

MicroServiceGroup

service_refs

Pool

health_monitor_refs

servers

StringGroup

kv

type

SystemConfiguration

dns_virtualservice_refs

global_tenant_config

snmp_configuration.community

VirtualService

http_policies

异步 PATCH

要快速添加池和删除池，需要以较高的速率应用 PATCH。部署规模通常会增加控制器上的负载并增加延迟。

异步 PATCH 功能允许将 PATCH 请求排入队列、以固定时间间隔进行整合并一起进行更新，同时将延迟降到最低。

注：

仅当部署规模较大时，才建议使用此功能。

当控制器属性中的 async_patch_merge_period 为 0 时，对池执行的所有带有 ?async_mode=true 的 PATCH 调用都将转换为同步调用，并返回 200 响应。

使用异步 PATCH 更新

默认情况下，此功能处于禁用状态。要启用异步 PATCH，请执行以下操作：

  1. 将控制器属性中的 async_patch_merge_period 从 0（默认值）更改为所需的时间间隔（30-120 秒）。

  2. 将 async_mode 作为 PATCH 请求中的一个查询参数进行传递。例如，PATCH /api/pool/<pool-uuid>?async_mode。响应将显示一个唯一的 patch_id，可用于查看请求状态。将启动 PATCH 整合，从而合并队列中待处理的请求。

  3. 对 /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>
    
            }

注意事项

  • 目前，此功能仅适用于池对象中的 servers 字段（使用 IP4）。

  • 此功能只能用于在池中添加或删除服务器

  • 在 async_patch_merge_period 内向控制器发出的所有 PATCH 请求必须具有相同的 API 版本 (HTTP_X_AVI_VERSION)

  • PATCH 更新要到下一个更新周期（通过时间间隔定义）才会安装。因此，PATCH 更新不是实时的。