API layanan Host Compute Network (HCN) untuk VM dan kontainer

2025-07-14
Berlaku untuk: ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016, ✅ Azure Local 2311.2 and later

API layanan Host Compute Network (HCN) adalah API Win32 yang menghadap publik yang menyediakan akses tingkat platform untuk mengelola jaringan virtual, titik akhir jaringan virtual, dan kebijakan terkait. Bersama-sama ini menyediakan konektivitas dan keamanan untuk komputer virtual (VM) dan kontainer yang berjalan pada host Windows.

Pengembang menggunakan API layanan HCN untuk mengelola jaringan untuk VM dan kontainer dalam alur kerja aplikasi mereka. API HCN telah dirancang untuk memberikan pengalaman terbaik bagi pengembang. Pengguna akhir tidak berinteraksi dengan API ini secara langsung.

Fitur API Layanan HCN

Diimplementasikan sebagai C API yang dihosting oleh Host Network Service (HNS) pada OnCore/VM.
Menyediakan kemampuan untuk membuat, memodifikasi, menghapus, dan menghitung objek HCN seperti jaringan, titik akhir, namespace layanan, dan kebijakan. Operasi dilakukan pada handel ke objek (misalnya, handel jaringan), dan secara internal handel ini diimplementasikan menggunakan handel konteks RPC.
Schema-based. Sebagian besar fungsi API menentukan parameter input dan output sebagai string yang berisi argumen panggilan fungsi sebagai dokumen JSON. Dokumen JSON didasarkan pada skema yang diketik dan diberi versi yang kuat, skema ini adalah bagian dari dokumentasi publik.
API langganan/panggilan balik disediakan untuk memungkinkan klien mendaftar untuk pemberitahuan peristiwa di seluruh layanan seperti pembuatan dan penghapusan jaringan.
HCN API berfungsi di aplikasi Desktop Bridge (alias Centennial) yang berjalan di layanan sistem. API memeriksa ACL dengan mengambil token pengguna dari pemanggil.

Tip

API layanan HCN didukung dalam tugas latar belakang dan jendela non-latar depan.

Terminologi: Host vs. Komputasi

Layanan komputasi host memungkinkan penelepon untuk membuat dan mengelola komputer virtual dan kontainer pada satu komputer fisik. Ini dinamai untuk mengikuti terminologi industri.

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. Layanan Jaringan Komputasi Host memungkinkan penelepon untuk membuat dan mengelola jaringan untuk komputer virtual dan kontainer pada satu komputer fisik.

Dokumen konfigurasi berbasis skema

Dokumen konfigurasi berdasarkan skema yang ditentukan dengan baik adalah standar industri yang mapan di ruang virtualisasi. Sebagian besar solusi virtualisasi, seperti Docker dan Kubernetes, menyediakan API berdasarkan dokumen konfigurasi. Several industry initiatives, with the participation of Microsoft, drive an ecosystem for defining and validating these schemas, such as OpenAPI. Inisiatif ini juga mendorong standarisasi definisi skema tertentu untuk skema yang digunakan untuk kontainer, seperti Open Container Initiative (OCI).

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

Definisi skema yang menentukan model objek untuk dokumen
Validasi apakah dokumen JSON sesuai dengan skema
Konversi otomatis dokumen JSON ke dan dari representasi asli skema ini dalam bahasa pemrograman yang digunakan oleh pemanggil 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:

Kumpulan nilai yang valid untuk properti, seperti 0-100 untuk properti yang mewakili persentase.
Definisi enumerasi, yang direpresentasikan sebagai sekumpulan string yang valid untuk properti.
Ekspresi reguler untuk format string yang diharapkan.

Sebagai bagian dari mendokumentasikan API HCN, kami berencana untuk menerbitkan skema dokumen JSON kami sebagai Spesifikasi OpenAPI. Berdasarkan spesifikasi ini, representasi khusus bahasa dari skema dapat memungkinkan penggunaan objek skema yang aman untuk jenis dalam bahasa pemrograman yang digunakan oleh klien.

Example

Berikut ini adalah contoh alur kerja ini untuk objek yang mewakili pengontrol SCSI dalam dokumen konfigurasi 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

Anotasi [NewIn("2.0") adalah bagian dari dukungan penerapan versi untuk definisi skema. Dari definisi internal ini, kami menghasilkan spesifikasi OpenAPI untuk skema:

{
    "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 mendukung berbagai bahasa seperti C#, Go, Javascript, dan Python).

Contoh kode C# yang dihasilkan untuk ipam tingkat atas & objek Subnet.
Contoh kode Go yang dihasilkan untuk objek IPAM &Subnet tingkat atas. Go digunakan oleh Docker dan Kubernetes yang merupakan dua dari konsumen API Layanan Jaringan Komputasi Host. Go memiliki dukungan bawaan untuk jenis Marshaling Go ke dan dari dokumen JSON.

Selain pembuatan dan validasi kode, Anda dapat menggunakan alat untuk menyederhanakan pekerjaan dengan dokumen JSON—yaitu Visual Studio Code.

Objek tingkat atas yang ditentukan dalam skema HCN

Objek tingkat atas adalah:

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

Pelajari selengkapnya tentang skenario HCN umum.
Pelajari selengkapnya tentang handel konteks RPC untuk HCN.
Pelajari selengkapnya tentang skema dokumen JSON HCN.