Interfejs API usługi Host Compute Network (HCN) dla maszyn wirtualnych i kontenerów

Dotyczy: ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016, ✅ Azure Local 2311.2 and later

Interfejs API usługi Host Compute Network (HCN) to publiczny interfejs API Win32, który zapewnia dostęp na poziomie platformy do zarządzania sieciami wirtualnymi, punktami końcowymi sieci wirtualnej i skojarzonymi zasadami. Razem zapewnia to łączność i zabezpieczenia dla maszyn wirtualnych i kontenerów działających na hoście systemu Windows.

Deweloperzy używają interfejsu API usługi HCN do zarządzania siecią dla maszyn wirtualnych i kontenerów w przepływach pracy aplikacji. Interfejs API HCN został zaprojektowany w celu zapewnienia najlepszego środowiska dla deweloperów. Użytkownicy końcowi nie korzystają bezpośrednio z tych interfejsów API.

Funkcje interfejsu API usługi HCN

Zaimplementowano jako interfejs API języka C hostowany przez usługę sieciową hosta (HNS) na OnCore/maszynie wirtualnej.
Umożliwia tworzenie, modyfikowanie, usuwanie i wyliczanie obiektów HCN, takich jak sieci, punkty końcowe, przestrzenie nazw i zasady. Operacje są wykonywane na uchwytach obiektów (np. uchwyt sieciowy), a wewnętrznie te uchwyty są implementowane przy użyciu kontekstowych uchwytów RPC.
Schema-based. Większość funkcji interfejsu API definiuje parametry wejściowe i wyjściowe jako ciągi zawierające argumenty wywołania funkcji jako dokumenty JSON. Dokumenty JSON są oparte na silnie typiowanych i wersjonowanych schematach. Te schematy są częścią publicznej dokumentacji.
Interfejs API do subskrypcji/wywołania zwrotnego umożliwia klientom rejestrowanie się na powiadomienia o zdarzeniach obejmujących całą usługę, takich jak tworzenie i usuwanie sieci.
Interfejs API HCN działa w aplikacjach Desktop Bridge (znanych także jako Centennial) uruchamianych w usługach systemowych. Interfejs API sprawdza ACL, pobierając token użytkownika od wywołującego.

Tip

Interfejs API usługi HCN jest obsługiwany w zadaniach w tle i oknach niebędących na pierwszym planie.

Terminologia: Host a Obliczenia

Usługa obliczeniowa hosta umożliwia użytkownikom tworzenie i zarządzanie zarówno maszynami wirtualnymi, jak i kontenerami na jednym komputerze fizycznym. Nazwa jest nazwana w celu przestrzegania terminologii branżowej.

Host jest powszechnie używany w branży wirtualizacji do odwoływania się do systemu operacyjnego, który zapewnia zwirtualizowane zasoby.
Komputacja odnosi się do metod wirtualizacji, które są bardziej wszechstronne niż tylko maszyny wirtualne. Usługa sieci hosta umożliwia użytkownikom tworzenie i zarządzanie sieciami zarówno dla maszyn wirtualnych, jak i kontenerów na jednym komputerze fizycznym.

Dokumenty konfiguracyjne oparte na schemacie

Dokumenty konfiguracji oparte na dobrze zdefiniowanych schematach są ustalonym standardem branżowym w przestrzeni wirtualizacji. Większość rozwiązań wirtualizacji, takich jak Docker i Kubernetes, udostępnia interfejsy API oparte na dokumentach konfiguracji. Kilka inicjatyw branżowych, z udziałem firmy Microsoft, napędza ekosystem do definiowania i weryfikowania tych schematów, takich jak OpenAPI. Inicjatywy te napędzają również standaryzację określonych definicji schematu dla schematów używanych dla kontenerów, takich jak Open Container Initiative (OCI).

Język używany do tworzenia dokumentów konfiguracji to JSON, który jest używany w połączeniu z:

Definicje schematu definiujące model obiektów dla dokumentu
Sprawdzanie, czy dokument JSON jest zgodny ze schematem
Automatyczna konwersja dokumentów JSON na i z natywnych reprezentacji tych schematów w językach programowania używanych przez osoby wywołujące interfejsy API

Często używane definicje schematu to OpenAPI i schemat JSON, który umożliwia określenie szczegółowych definicji właściwości w dokumencie, na przykład:

Prawidłowy zestaw wartości dla właściwości, na przykład 0–100 dla właściwości reprezentującej wartość procentową.
Definicja enumeracji, które są oznaczane jako zestaw prawidłowych wartości ciągów dla właściwości.
Wyrażenie regularne dla oczekiwanego formatu ciągu.

W ramach dokumentowania interfejsów API HCN planujemy opublikować schemat naszych dokumentów JSON jako specyfikację interfejsu OpenAPI. Na podstawie tej specyfikacji reprezentacje schematu specyficzne dla języka mogą umożliwiać bezpieczne użycie obiektów schematu w języku programowania używanym przez klienta.

Example

Poniżej przedstawiono przykład tego przepływu pracy dla obiektu reprezentującego kontroler SCSI w dokumencie konfiguracji maszyny wirtualnej.

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

Adnotacje [NewIn("2.0")] stanowią część wsparcia dla wersjonowania definicji schematu. Na podstawie tej definicji wewnętrznej generujemy specyfikacje interfejsu OpenAPI dla schematu:

{
    "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"
                }
            }
        }
    }
}

Możesz użyć narzędzi, takich jak Swagger, aby wygenerować specyficzne dla języka reprezentacje schematu języka programowania używanego przez klienta. Program Swagger obsługuje różne języki, takie jak C#, Go, Javascript i Python.

Przykład wygenerowanego kodu C# dla obiektu IPAM i podsieci najwyższego poziomu.
Przykład wygenerowanego kodu języka Go dla obiektu IPAM i podsieci najwyższego poziomu. Środowisko Go jest używane przez platformę Docker i platformę Kubernetes, które są dwoma użytkownikami interfejsów API usługi sieci obliczeniowej hosta. W języku Go istnieje wbudowana obsługa konwersji typów Go do formatu JSON i odwrotnie.

Oprócz generowania i walidacji kodu można użyć narzędzi, aby uprościć pracę z dokumentami JSON — czyli visual Studio Code.

Obiekty najwyższego poziomu zdefiniowane w schemacie HCN

Obiekty najwyższego poziomu to:

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[];
};

Dalsze kroki

Dowiedz się więcej na temat typowych scenariuszy HCN.
Dowiedz się więcej o uchwytach kontekstu RPC dla HCN.
Dowiedz się więcej o schematach dokumentów JSON HCN.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-08-16