用於虛擬器和容器的 Host Compute Network (HCN) 服務 API
適用於︰Windows Server 2022、Windows Server 2019
Host Compute Network (HCN) 服務 API 是面向大眾的 Win32 API，提供平台級存取權限來管理虛擬網路、虛擬網路端點和相關策略。 這共同為 Windows 主機上執行的虛擬器 (VM) 和容器提供了連接性和安全性。
開發人員使用 HCN 服務 API 來管理應用程式工作流程中虛擬器和容器的網路。 HCN API 旨在為開發人員提供最佳體驗。 最終使用者不直接與這些 API 互動。
HCN 服務 API 的功能
作為由 OnCore/VM 上的 Host Network Service (HNS) 託管的 C API 實作。
提供建立、修改、刪除和列舉 HCN 物件（例如網路、端點、命名空間和策略）的能力。 對物件的句柄（例如網路句柄）執行操作，並且在內部這些句柄是使用 RPC 內文句柄實現的。
基於模式。 API 的大多數函數將輸入和輸出參數設置為字串，其中包含 JSON 資料形式的函數呼叫參數。 JSON 資料基於強類型和版本化模式，這些模式是公共資料的一部分。
提供訂閱/回呼 API 以使客戶端能夠註冊服務範圍事件（例如網路建立和刪除）的通知。
HCN API 適用於在系統服務中執行的 Desktop Bridge（又稱 Centennial）應用程式。 API 透過從呼叫方檢索使用者通關來檢查 ACL。
提示
後台任務和非前台視窗支援 HCN 服務 API。
術語：主機與計算
主機運算服務允許呼叫者在單一實體電腦上建立和管理虛擬器和容器。 它的命名遵循行業術語。
主機在虛擬化產業中廣泛使用，指的是提供虛擬化資源的作業系統。
計算用於指比虛擬器更廣泛的虛擬化方法。 Host Compute Network Service 允許呼叫者在單一實體電腦上建立和管理虛擬器和容器的網路。
基於模式的設置文檔
基於明確設置的模式的設置資料是虛擬化領網域的既定行業標準。 大多數虛擬化解決方案，例如 Docker 和 Kubernetes，都提供基於設置資料的 API。 在 Microsoft 的參與下，多項產業措施推動了設置和驗證這些模式的生態系統，例如 OpenAPI。 這些計劃還推動了用於容器的模式的特定模式設置的標準化，例如 Open Container Initiative (OCI)。
用於編寫設置資料的語言是 JSON，您可以將其與以下內容結合使用：
- 設置文檔物件模型的模式設置
- 驗證 JSON 資料是否符合架構
- 自動將 JSON 資料與 API 呼叫者使用的程式語言中這些模式的本機代表形式進行轉換
常用的模式設置是 OpenAPI 和 JSON Schema，它們可以讓您指定資料中屬性的詳細設置，例如：
- 屬性的有效值集，例如代表百分比的屬性為 0-100。
- 枚舉的設置，代表為屬性的一組有效字串。
- 字串預期格式的正規代表式。
作為記錄 HCN API 的一部分，我們計劃將 JSON 資料的架構作為 OpenAPI 規範發布。 基於此規範，模式的特定於語言的代表可以允許客戶端使用的程式語言中類型安全地使用模式物件。
範例
以下是代表 VM 設置資料中 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 &代碼的生成範例。 Docker 和 Kubernetes 使用 Go，它們是主機運算網路服務 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 資料架構的更多資訊。