用于虚拟机和容器的主机计算网络 (HCN) 服务 API
适用于：Windows Server 2022、Windows Server 2019
主机计算网络 (HCN) 服务 API 是一个面向公众的 Win32 API，提供平台级访问权限来管理虚拟网络、虚拟网络终结点和相关策略。 它们共同为 Windows 主机上运行的虚拟机 (VM) 和容器提供连接性和安全性。
开发人员使用 HCN 服务 API 来管理其应用程序工作流中的虚拟机和容器的网络。 HCN API 旨在为开发人员提供最佳体验。 最终用户不直接与这些 API 交互。
HCN 服务 API 的功能
由 OnCore/VM 上的主机网络服务 (HNS) 托管的 C API 实现。
提供创建、修改、删除和枚举 HCN 对象（如网络、终结点、命名空间和策略）的功能。 操作在对象的句柄（例如，网络句柄）上执行，并且在内部使用 RPC 上下文句柄来实现这些句柄。
基于架构。 API 的大多数函数将输入和输出参数定义为字符串，其中包含作为 JSON 文档的函数调用的参数。 JSON 文档基于强类型和版本控制架构，这些架构是公共文档的一部分。
提供订阅/回调 API 以使客户端能够注册诸如网络创建和删除之类的服务范围事件的通知。
HCN API 在系统服务中运行的桌面桥（又名 Centennial）应用程序中工作。 API 通过从调用方检索用户令牌来检查 ACL。
提示
在后台任务和非前台窗口中支持 HCN 服务 API.
术语：主机与计算
主机计算服务允许调用方在一台物理计算机上创建和管理虚拟机和容器。 此服务的命名遵循行业术语。
“主机”在虚拟化行业中被广泛用于指提供虚拟化资源的操作系统。
“计算”用于指比虚拟机更广泛的虚拟化方法。 “主机计算网络服务”允许调用方为单个物理计算机上的虚拟机和容器创建和管理网络。
基于架构的配置文档
基于定义完善的架构的配置文档是虚拟化领域已确立的行业标准。 大多数虚拟化解决方案（如 Docker 和 Kubernetes）都提供基于配置文档的 API。 在 Microsoft 的参与下，一些行业计划推动了定义和验证这些架构的生态系统，例如 OpenAPI。 这些计划还推动了用于容器的模式的特定模式定义的标准化，例如开放容器计划 (OCI)。
用于编写配置文档的语言是 JSON，你可以将其与以下语言结合使用：
- 为文档定义对象模型的架构定义
- 验证 JSON 文档是否符合架构符合
- 在 API 调用者使用的编程语言中，JSON 文档与这些模式的本机表示之间的自动转换
经常使用的架构定义是 OpenAPI 和 JSON 架构，它们允许你指定文档中属性的详细定义，例如：
- 属性的有效值集合，例如表示百分比的属性为 0-100。
- 枚举的定义，表示为属性的一组有效字符串。
- 字符串的预期格式的正则表达式。
作为记录 HCN API 的一部分，我们计划将 JSON 文档的架构发布为 OpenAPI 规范。 基于该规范，架构的特定于语言的表示可以允许在客户端所使用的编程语言中以类型安全的方式使用架构对象。
示例
以下是虚拟机配置文档中代表 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;
};
提示
[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"
}
}
}
}
}
你可以使用工具（如 Swagger）来生成客户端所使用的模式编程语言的特定于语言的表示。 Swagger 支持多种语言（如 C#、Go、JavaScript 和 Python）。
为顶级 IPAM 和子网对象生成的 C# 代码示例。
为顶级 IPAM 和子网对象生成的 Go 代码的示例。 Go 由 Docker 和 Kubernetes 使用，它们是主机计算网络服务 API 的两个使用者。 Go 内置了将 Go 类型封送到 JSON 文档和从 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[];
};
后续步骤
详细了解公共 HCN 方案。
详细了解 HCN 的 RPC 上下文句柄。
详细了解 HCN JSON 文档架构。