API de serviço HCN (Host Compute Network) para VMs e contêineres

Aplica-se a: ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016, ✅ Azure Local 2311.2 and later

A API de serviço da Host Compute Network (HCN) é uma API Win32 voltada para o público que fornece acesso no nível da plataforma para gerenciar as redes virtuais, pontos de extremidade de rede virtual e políticas associadas. Juntos, isso fornece conectividade e segurança para máquinas virtuais (VMs) e contêineres executados em um host Windows.

Os desenvolvedores usam a API de serviço HCN para gerenciar a rede para VMs e contêineres em seus fluxos de trabalho de aplicativos. A API HCN foi projetada para fornecer a melhor experiência para os desenvolvedores. Os usuários finais não interagem diretamente com essas APIs.

Recursos da API de serviço HCN

Implementado como C API hospedado pelo Host Network Service (HNS) no OnCore/VM.
Fornece a capacidade de criar, modificar, excluir e enumerar objetos HCN, como redes, pontos de extremidade, namespaces e políticas. As operações são realizadas em identificadores de objetos (por exemplo, um identificador de rede) e, internamente, esses identificadores são implementados usando identificadores de contexto RPC.
Schema-based. A maioria das funções da API define parâmetros de entrada e saída como cadeias de caracteres contendo os argumentos da chamada de função como documentos JSON. Os documentos JSON são baseados em esquemas fortemente tipados e versionados, esses esquemas fazem parte da documentação pública.
Uma API de inscrição/retorno de chamada é fornecida para permitir que os clientes se registrem para notificações de eventos globais de serviço, como criações e eliminações de rede.
A API HCN funciona em aplicativos do Desktop Bridge (também conhecidos como Centennial) executados em serviços do sistema. A API verifica a ACL recuperando o token de usuário do chamador.

Tip

A API de serviço HCN é suportada em tarefas em segundo plano e janelas que não são de primeiro plano.

Terminologia: Host vs. Computação

O serviço de computação do host permite que os chamadores criem e gerenciem máquinas virtuais e contêineres em um único computador físico. Está designado para seguir a terminologia da indústria.

O host é amplamente utilizado no setor de virtualização para se referir ao sistema operacional que fornece recursos virtualizados.
A computação é usada para se referir a métodos de virtualização que são mais amplos do que apenas máquinas virtuais. O Host Compute Network Service permite que os chamadores criem e gerenciem redes para máquinas virtuais e contêineres em um único computador físico.

Documentos de configuração baseados em esquema

Documentos de configuração baseados em esquemas bem definidos é um padrão estabelecido do setor no espaço de virtualização. A maioria das soluções de virtualização, como Docker e Kubernetes, fornece APIs baseadas em documentos de configuração. Várias iniciativas do setor, com a participação da Microsoft, impulsionam um ecossistema para definir e validar esses esquemas, como o OpenAPI. Essas iniciativas também impulsionam a padronização de definições de esquema específicas para os esquemas usados para contêineres, como a Open Container Initiative (OCI).

A linguagem usada para criar documentos de configuração é JSON, que você usa em combinação com:

Definições de esquema que definem um modelo de objeto para o documento
Validação de se um documento JSON está em conformidade com um esquema
Conversão automatizada de documentos JSON de e para representações nativas desses esquemas nas linguagens de programação usadas pelos chamadores das APIs

As definições de esquema usadas com freqüência são OpenAPI e JSON Schema, que permitem especificar as definições detalhadas das propriedades em um documento, por exemplo:

O conjunto válido de valores para uma propriedade, como 0-100 para uma propriedade que representa uma porcentagem.
A definição de enumerações, que são representadas como um conjunto de cadeias de caracteres válidas para uma propriedade.
Uma expressão regular para o formato esperado de uma cadeia de caracteres.

Como parte da documentação das APIs HCN, estamos planejando publicar o esquema de nossos documentos JSON como uma especificação OpenAPI. Com base nessa especificação, representações específicas da linguagem do esquema podem permitir o uso seguro dos objetos do esquema na linguagem de programação usada pelo cliente.

Example

A seguir está um exemplo desse fluxo de trabalho para o objeto que representa um controlador SCSI no documento de configuração de uma VM.

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

As anotações [NewIn("2.0") fazem parte do suporte de versionamento para as definições de esquema. A partir desta definição interna, geramos as especificações OpenAPI para o esquema:

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

Você pode usar ferramentas, como Swagger, para gerar representações específicas da linguagem de programação de esquemas usada por um cliente. Swagger suporta uma variedade de linguagens como C#, Go, Javascript e Python).

Exemplo de código C# gerado para o objeto IPAM & Subnet de nível superior.
Exemplo de código Go gerado para o objeto IPAM & Subnet de nível superior. Go é usado pelo Docker e Kubernetes, que são dois dos consumidores das APIs do Host Compute Network Service. O Go tem suporte integrado para serializar tipos de Go de e para documentos JSON.

Além da geração e validação de código, você pode usar ferramentas para simplificar o trabalho com documentos JSON, ou seja, Visual Studio Code.

Objetos de nível superior definidos no esquema HCN

Os objetos de nível superior são:

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

Próximos passos

Saiba mais sobre os cenários comuns de HCN.
Saiba mais sobre os identificadores de contexto RPC para HCN.
Saiba mais sobre os esquemas de documento JSON da HCN.

Feedback

Esta página foi útil?

Last updated on 2025-08-16