API-интерфейс службы вычислительной сети узла (HCN) для виртуальных машин и контейнеров

2025-07-14
Применяется к: ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016, ✅ Azure Local 2311.2 and later

API службы "Вычислительная сеть узла" (HCN) — это общедоступный API Win32, который предоставляет доступ на уровне платформы для управления виртуальными сетями, конечными точками виртуальных сетей и связанными с ними политиками. Вместе это обеспечивает подключение и безопасность для виртуальных машин и контейнеров, работающих на узле Windows.

Разработчики используют API службы HCN для управления сетями для виртуальных машин и контейнеров в рабочих процессах приложений. API HCN разработан для обеспечения оптимального интерфейса для разработчиков. Конечные пользователи не взаимодействуют с этими API напрямую.

Функции API службы HCN

Реализован как API C, размещенный службой сети узла (HNS) в onCore/VM.
Предоставляет возможность создавать, изменять, удалять и перечислять объекты HCN, такие как сети, конечные точки, пространства имен и политики. Операции выполняются с дескрипторами объектов (например, сетевой дескриптор), а внутренние эти дескрипторы реализуются с помощью дескрипторов контекста RPC.
Schema-based. Большинство функций API определяют входные и выходные параметры в виде строк, содержащих аргументы вызова функции в виде документов JSON. Документы JSON основаны на строго типизированных и версиях схем, эти схемы являются частью общедоступной документации.
Api обратного вызова подписки и обратного вызова предоставляется для того, чтобы клиенты могли регистрировать уведомления о событиях на уровне службы, таких как создание сети и удаление.
API HCN работает в мост для классических приложений приложениях (a.a. Centennial), работающих в системных службах. API проверяет ACL, извлекая маркер пользователя из вызывающего средства.

Tip

API службы HCN поддерживается в фоновых задачах и окнах, отличных от переднего плана.

Терминология: узел и вычисления

Служба вычислений узла позволяет вызывающим пользователям создавать виртуальные машины и контейнеры на одном физическом компьютере и управлять ими. Оно называется для того, чтобы следовать терминологии отрасли.

Host is widely used in the virtualization industry to refer to the operating system that provides virtualized resources.
Compute is used to refer to virtualization methods that are broader than just virtual machines. Служба вычислительной сети узла позволяет вызывающим пользователям создавать сети и управлять ими для виртуальных машин и контейнеров на одном физическом компьютере.

Документы конфигурации на основе схемы

Документы конфигурации на основе четко определенных схем — это стандартный отраслевый стандарт в пространстве виртуализации. Большинство решений виртуализации, таких как Docker и Kubernetes, предоставляют API на основе документов конфигурации. Several industry initiatives, with the participation of Microsoft, drive an ecosystem for defining and validating these schemas, such as OpenAPI. Эти инициативы также управляют стандартизацией конкретных определений схем для схем, используемых для контейнеров, таких как Open Container Initiative (OCI).

The language used for authoring configuration documents is JSON, which you use in combination with:

Определения схемы, определяющие объектную модель для документа
Проверка соответствия документа JSON схеме
Автоматическое преобразование документов JSON в собственные представления этих схем на языках программирования, используемых вызывающими API

Frequently used schema definitions are OpenAPI and JSON Schema, which lets you specify the detailed definitions of the properties in a document, for example:

Допустимый набор значений для свойства, например 0–100 для свойства, представляющего процент.
Определение перечислений, представленных как набор допустимых строк для свойства.
Регулярное выражение ожидаемого формата строки.

В рамках документирования API HCN мы планируем опубликовать схему наших документов JSON в качестве спецификации OpenAPI. На основе этой спецификации представления схемы на языке, зависящие от языка, могут позволить типобезопасно использовать объекты схемы на языке программирования, используемом клиентом.

Example

Ниже приведен пример этого рабочего процесса для объекта, представляющего контроллер SCSI в документе конфигурации виртуальной машины.

enum IpamType
{
    [NewIn("2.0")] Static,
    [NewIn("2.0")] Dhcp,
};
class Ipam
{
    // Type : dhcp
    [NewIn("2.0"),OmitEmpty] IpamType   Type;
    [NewIn("2.0"),OmitEmpty] Subnet     Subnets[];
};
class Subnet : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] string         IpAddressPrefix;
    [NewIn("2.0"),OmitEmpty] SubnetPolicy   Policies[];
    [NewIn("2.0"),OmitEmpty] Route          Routes[];
};
enum SubnetPolicyType
{
    [NewIn("2.0")] VLAN
};
class SubnetPolicy
{
    [NewIn("2.0"),OmitEmpty] SubnetPolicyType                 Type;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Common.PolicySettings Data;
};
class PolicySettings
{
    [NewIn("2.0"),OmitEmpty]  string      Name;
};
class VlanPolicy : HCN.Schema.Common.PolicySettings
{
    [NewIn("2.0")] uint32 IsolationId;
};
class Route
{
    [NewIn("2.0"),OmitEmpty] string NextHop;
    [NewIn("2.0"),OmitEmpty] string DestinationPrefix;
    [NewIn("2.0"),OmitEmpty] uint16 Metric;
};

Tip

Заметки [NewIn("2.0") являются частью поддержки управления версиями для определений схем. Из этого внутреннего определения мы создадим спецификации OpenAPI для схемы:

{
    "swagger" : "2.0",
    "info" : {
       "version" : "2.1",
       "title" : "HCN API"
    },
    "definitions": {
        "Ipam": {
            "type": "object",
            "properties": {
                "Type": {
                    "type": "string",
                    "enum": [
                        "Static",
                        "Dhcp"
                    ],
                    "description": " Type : dhcp"
                },
                "Subnets": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Subnet"
                    }
                }
            }
        },
        "Subnet": {
            "type": "object",
            "properties": {
                "ID": {
                    "type": "string",
                    "pattern": "^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$"
                },
                "IpAddressPrefix": {
                    "type": "string"
                },
                "Policies": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/SubnetPolicy"
                    }
                },
                "Routes": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Route"
                    }
                }
            }
        },
        "SubnetPolicy": {
            "type": "object",
            "properties": {
                "Type": {
                    "type": "string",
                    "enum": [
                        "VLAN",
                        "VSID"
                    ]
                },
                "Data": {
                    "$ref": "#/definitions/PolicySettings"
                }
            }
        },
        "PolicySettings": {
            "type": "object",
            "properties": {
                "Name": {
                    "type": "string"
                }
            }
        },
        "VlanPolicy": {
            "type": "object",
            "properties": {
                "Name": {
                    "type": "string"
                },
                "IsolationId": {
                    "type": "integer",
                    "format": "uint32"
                }
            }
        },
        "Route": {
            "type": "object",
            "properties": {
                "NextHop": {
                    "type": "string"
                },
                "DestinationPrefix": {
                    "type": "string"
                },
                "Metric": {
                    "type": "integer",
                    "format": "uint16"
                }
            }
        }
    }
}

You can use tools, such as Swagger, to generate language-specific representations of the schema programming language used by a client. Swagger поддерживает различные языки, такие как C#, Go, Javascript и Python).

Пример созданного кода C# для объекта IPAM и подсети верхнего уровня.
Пример созданного кода Go для объекта IPAM верхнего уровня и подсети. Go используется Docker и Kubernetes, которые являются двумя потребителями API-интерфейсов службы вычислительной сети узла. Go имеет встроенную поддержку маршалинг типов Go в документы JSON и из него.

Помимо создания и проверки кода можно использовать средства для упрощения работы с документами JSON, то есть Visual Studio Code.

Объекты верхнего уровня, определенные в схеме HCN

Объекты верхнего уровня:

class HostComputeNetwork : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.NetworkMode          Type;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.NetworkPolicy        Policies[];
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.MacPool              MacPool;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.DNS                  Dns;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Ipam                 Ipams[];
};
class HostComputeEndpoint : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] string                                     HostComputeNetwork;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Endpoint.EndpointPolicy Policies[];
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Endpoint.IpConfig       IpConfigurations[];
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.DNS                     Dns;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Network.Route                   Routes[];
    [NewIn("2.0"),OmitEmpty] string                                     MacAddress;
};
class HostComputeNamespace : HCN.Schema.Common.Base
{
    [NewIn("2.0"),OmitEmpty] uint32                                    NamespaceId;
    [NewIn("2.0"),OmitEmpty] Guid                                      NamespaceGuid;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Namespace.NamespaceType        Type;
    [NewIn("2.0"),OmitEmpty] HCN.Schema.Namespace.NamespaceResource    Resources[];
};
class HostComputeLoadBalancer : HCN.Schema.Common.Base
{
    [NewIn("2.0"), OmitEmpty] string                                               HostComputeEndpoints[];
    [NewIn("2.0"), OmitEmpty] string                                               VirtualIPs[];
    [NewIn("2.0"), OmitEmpty] HCN.Schema.Network.Endpoint.Policy.PortMappingPolicy PortMappings[];
    [NewIn("2.0"), OmitEmpty] HCN.Schema.LoadBalancer.LoadBalancerPolicy           Policies[];
};

Next steps

Дополнительные сведения о распространенных сценариях HCN.
Дополнительные сведения о дескрипторах контекста RPC для HCN.
Дополнительные сведения о схемах документов JSON HCN.