Udostępnij przez

Zarządzanie zasobami przy użyciu zestawu Azure SDK dla platformy .NET

  • Artykuł

Biblioteki płaszczyzny zarządzania platformy .NET zestawu Azure SDK dla platformy .NET ułatwiają tworzenie, aprowizację i zarządzanie zasobami platformy Azure z poziomu aplikacji platformy .NET. Wszystkie usługi platformy Azure mają odpowiednie biblioteki zarządzania.

Dzięki bibliotekom zarządzania (przestrzeniom nazw rozpoczynającym się od Azure.ResourceManager, na przykład Azure.ResourceManager.Compute), można napisać programy konfiguracji i wdrażania, aby wykonywać te same zadania, które można wykonywać za pośrednictwem witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub innych narzędzi do zarządzania zasobami.

Te pakiety są zgodne z nowymi wytycznymi dotyczącymi zestawu Azure SDK, które zapewniają podstawowe możliwości, które są współużytkowane przez wszystkie zestawy SDK platformy Azure, w tym:

  • Intuicyjna biblioteka tożsamości platformy Azure.
  • Potok HTTP z zasadami niestandardowymi.
  • Obsługa błędów.
  • Śledzenie rozproszone.

Uwaga

Możesz zauważyć, że niektóre pakiety są nadal wersją wstępną, etapowe wydania dodatkowych bibliotek płaszczyzny zarządzania usług platformy Azure są w toku. Jeśli szukasz stabilnego pakietu wersji dla określonego zasobu platformy Azure i obecnie dostępna jest tylko wersja wstępna, zgłoś problem w zestawie Azure SDK dla repozytorium Github platformy .NET

Rozpocznij

Wymagania wstępne

Instalowanie pakietu

Zainstaluj pakiety NuGet zarządzania tożsamościami i zasobami platformy Azure dla platformy .NET. Na przykład:

Install-Package Azure.Identity
Install-Package Azure.ResourceManager
Install-Package Azure.ResourceManager.Resources
Install-Package Azure.ResourceManager.Compute
Install-Package Azure.ResourceManager.Network

Uwierzytelnianie użytkownika

Domyślną opcją utworzenia uwierzytelnionego klienta jest użycie polecenia DefaultAzureCredential. Ponieważ wszystkie interfejsy API zarządzania przechodzą przez ten sam punkt końcowy, aby wchodzić w interakcje z zasobami, należy utworzyć tylko jeden najwyższy poziom ArmClient .

Aby uwierzytelnić się za pomocą platformy Azure i utworzyć wystąpienie danych ArmClientArmClient poświadczeń:

using Azure.Identity;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;

// Code omitted for brevity

ArmClient client = new ArmClient(new DefaultAzureCredential());

Aby uzyskać więcej informacji na temat Azure.Identity.DefaultAzureCredential klasy, zobacz DefaultAzureCredential Class (Klasa DefaultAzureCredential).

Ściągawka dotycząca zestawu SDK zarządzania

Aby rozpocząć pracę z zestawem Azure Management SDK dla platformy .NET, wyobraź sobie, że masz zadanie tworzenia/tworzenia/wyświetlania/aktualizowania/usuwania typowej przestrzeni nazw usługi Azure Service Bus, wykonaj następujące kroki:

  1. Uwierzytelnij się w subskrypcji i grupie zasobów, nad którą chcesz pracować.
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ServiceBus;

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = client.GetDefaultSubscription();
ResourceGroupResource resourceGroup =
    client.GetDefaultSubscription().GetResourceGroup(resourceGroupName);
  1. Znajdź odpowiednią metodę zarządzania zasobem platformy Azure.
Operacja Method
Pobieranie zasobu z identyfikatorem zasobu client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List resourceGroup.GetServiceBusNamespaces()
Indeks resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Dodawanie/aktualizowanie resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Contains resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Delete client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() lub resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Pamiętaj, że wszystkie zasoby platformy Azure, w tym sama grupa zasobów, mogą być zarządzane przez odpowiedni zestaw SDK zarządzania przy użyciu kodu podobnego do powyższego przykładu. Aby znaleźć prawidłowy pakiet zestawu SDK zarządzania platformy Azure, poszukaj pakietów o nazwie z następującym wzorcem Azure.ResourceManager.{ResourceProviderName}.

Aby dowiedzieć się więcej na temat zasobuIdentifier, zapoznaj się z tematem Ustrukturyzowany identyfikator zasobu.

Najważniejsze pojęcia

Informacje o hierarchii zasobów platformy Azure

Aby zmniejszyć liczbę klientów potrzebnych do wykonywania typowych zadań i liczbę nadmiarowych parametrów, które przyjmują każdy z tych klientów, wprowadziliśmy hierarchię obiektów w zestawie SDK, który naśladuje hierarchię obiektów na platformie Azure. Każdy klient zasobów w zestawie SDK ma metody uzyskiwania dostępu do klientów zasobów swoich elementów podrzędnych, które są już ograniczone do odpowiedniej subskrypcji i grupy zasobów.

W tym celu wprowadzamy trzy standardowe typy dla wszystkich zasobów na platformie Azure:

{ResourceName} Klasa zasobów

Ten typ reprezentuje pełny obiekt klienta zasobu, który zawiera właściwość Dane uwidaczniającą szczegóły jako {ResourceName}Typ danych . Ma również dostęp do wszystkich operacji na tym zasobie bez konieczności przekazywania parametrów zakresu, takich jak identyfikator subskrypcji lub nazwa zasobu. Ułatwia to bezpośrednie wykonywanie operacji na wyniku wywołań listy, ponieważ wszystko jest zwracane jako pełny klient zasobów.

ArmClient client = new ArmClient(new DefaultAzureCredential());
string resourceGroupName = "myResourceGroup";
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
await foreach (VirtualMachineResource virtualMachine in resourceGroup.GetVirtualMachinesAsync())
{
    //previously we would have to take the resourceGroupName and the vmName from the vm object
    //and pass those into the powerOff method as well as we would need to execute that on a separate compute client
    await virtualMachine.PowerOffAsync(WaitUntil.Completed);
}

{ResourceName} Klasa danych

Ten typ reprezentuje model tworzący dany zasób. Zazwyczaj są to dane odpowiedzi z wywołania usługi, takie jak HTTP GET i szczegółowe informacje na temat bazowego zasobu. Wcześniej była to reprezentowana przez klasę Model .

{ResourceName} Klasa Kolekcji

Ten typ reprezentuje operacje, które można wykonać w kolekcji zasobów należących do określonego zasobu nadrzędnego. Ten obiekt zapewnia większość operacji zbierania logicznego.

Zachowanie kolekcji Collection, metoda
Iteracja/lista GetAll()
Indeks Get(nazwa ciągu)
Dodaj CreateOrUpdate(Azure.WaitUntil waitUntilUntil, nazwa ciągu, {ResourceName}Dane)
Contains Exists(nazwa ciągu)

W większości przypadków element nadrzędny zasobu to ResourceGroup, ale w niektórych przypadkach sam zasób ma zasób podrzędny, na przykład podsieć jest elementem podrzędnym sieci wirtualnej. Sama grupa zasobów jest elementem podrzędnym subskrypcji

Zebranie wszystkich elementów

Załóżmy, że nasza firma wymaga otagowania wszystkich maszyn wirtualnych z właścicielem. Zadaniem jest napisanie programu w celu dodania tagu do wszystkich brakujących maszyn wirtualnych w danej grupie zasobów.

// First we construct our armClient
ArmClient client = new ArmClient(new DefaultAzureCredential());

// Next we get a resource group object
// ResourceGroup is a {ResourceName}Resource object from above
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup =
   await subscription.GetResourceGroupAsync("myRgName");

// Next we get the collection for the virtual machines
// vmCollection is a {ResourceName}Collection object from above
VirtualMachineCollection virtualMachineCollection = await resourceGroup.GetVirtualMachines();

// Next we loop over all vms in the collection
// Each vm is a {ResourceName}Resource object from above
await foreach(VirtualMachineResource virtualMachine in virtualMachineCollection)
{
   // We access the {ResourceName}Data properties from vm.Data
   if(!virtualMachine.Data.Tags.ContainsKey("owner"))
   {
       // We can also access all operations from vm since it is already scoped for us
       await virtualMachine.AddTagAsync("owner", GetOwner());
   }
}

Identyfikator zasobu ustrukturyzowanego

Identyfikatory zasobów zawierają przydatne informacje o samym zasobie, ale są to zwykłe ciągi, które muszą być analizowane. Zamiast implementować własną logikę ResourceIdentifier analizowania, możesz użyć obiektu, który wykona analizowanie.

Przykład: analizowanie identyfikatora przy użyciu obiektu ResourceIdentifier

string resourceId = "/subscriptions/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resourceGroups/workshop2021-rg/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet";
ResourceIdentifier id = new ResourceIdentifier(resourceId);
Console.WriteLine($"Subscription: {id.SubscriptionId}");
Console.WriteLine($"ResourceGroup: {id.ResourceGroupName}");
Console.WriteLine($"Vnet: {id.Parent.Name}");
Console.WriteLine($"Subnet: {id.Name}");

Należy jednak pamiętać, że niektóre z tych właściwości mogą mieć wartość null. Zazwyczaj można określić sam ciąg identyfikatora, który wpisz identyfikator zasobu. Jeśli jednak nie masz pewności, sprawdź, czy właściwości mają wartość null.

Przykład: Generator identyfikatorów zasobów

Możesz nie chcieć ręcznie utworzyć obiektu resourceId na podstawie czystego stringelementu . Każda {ResourceName}Resource klasa ma metodę statyczną, która może pomóc w utworzeniu ciągu identyfikatora zasobu.

ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "resourceGroupName",
        "resourceName");

Zarządzanie istniejącymi zasobami

Wykonywanie operacji na zasobach, które już istnieją, jest typowym przypadkiem użycia w przypadku korzystania z bibliotek klienckich zarządzania. W tym scenariuszu zazwyczaj masz identyfikator zasobu, nad którym chcesz pracować jako ciąg. Mimo że nowa hierarchia obiektów doskonale nadaje się do aprowizacji i pracy w zakresie danego elementu nadrzędnego, nie jest to najbardziej wydajne, jeśli chodzi o ten konkretny scenariusz.

Oto przykład sposobu uzyskiwania AvailabilitySetResource dostępu do obiektu i zarządzania nim bezpośrednio przy użyciu jego identyfikatora zasobu:

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.Compute;
using System;
using System.Threading.Tasks;

// Code omitted for brevity

ResourceIdentifier subscriptionId =
    SubscriptionResource.CreateResourceIdentifier("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");

ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        subscriptionId.SubscriptionId,
        "resourceGroupName",
        "resourceName");

// We construct a new armClient to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the specific subscription this resource belongs to
SubscriptionResource subscription = client.GetSubscriptionResource(subscriptionId);
// Next we get the specific resource group this resource belongs to
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceId.ResourceGroupName);
// Finally we get the resource itself
// Note: for this last step in this example, Azure.ResourceManager.Compute is needed
AvailabilitySetResource availabilitySet = await resourceGroup.GetAvailabilitySetAsync(resourceId.Name);

To podejście wymaga dużo kodu, a trzy wywołania interfejsu API są wykonywane na platformie Azure. Można to zrobić przy użyciu mniejszej ilości kodu i bez żadnych wywołań interfejsu API przy użyciu metod rozszerzeń podanych na samym kliencie. Te metody rozszerzenia umożliwiają przekazanie identyfikatora zasobu i pobranie klienta zasobów o określonym zakresie. Zwrócony obiekt jest zasobem {ResourceName}. Ponieważ nie skontaktowano się z platformą Azure w celu pobrania danych, wywołanie Data właściwości zgłosi wyjątek, możesz użyć HasData właściwości , aby określić, czy wystąpienie zasobu zawiera dane lub wywoła metodę Get lub GetAsync w zasobie w celu pobrania danych zasobów.

W związku z tym poprzedni przykład wygląda następująco:

ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "resourceGroupName",
        "resourceName");
// We construct a new armClient to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the AvailabilitySet resource client from the armClient
// The method takes in a ResourceIdentifier but we can use the implicit cast from string
AvailabilitySetResource availabilitySet = client.GetAvailabilitySetResource(resourceId);
// At this point availabilitySet.Data will be null and trying to access it will throw exception
// If we want to retrieve the objects data we can simply call get
availabilitySet = await availabilitySet.GetAsync();
// we now have the data representing the availabilitySet
Console.WriteLine(availabilitySet.Data.Name);

Sprawdzanie, czy zasób istnieje

Jeśli nie masz pewności, czy zasób, który chcesz uzyskać, lub chcesz sprawdzić, czy istnieje, możesz użyć metody Exists() lub ExistsAsync() , które można wywołać z dowolnej {ResourceName}Collection klasy.

Exists()Funkcja zwraca czasExistsAsync(), Response<bool> ponieważ jego wersja asynchronizna zwraca wartość Task<Response<bool>>. Response<bool> W obiekcie można odwiedzić jego Value właściwość, aby sprawdzić, czy zasób istnieje. Wartość Value jest false , jeśli zasób nie istnieje i na odwrót.

W poprzednich wersjach pakietów należy przechwycić RequestFailedException kod stanu i sprawdzić go pod kątem wartości 404. Mając ten nowy interfejs API, mamy nadzieję, że może to zwiększyć produktywność deweloperów i zoptymalizować dostęp do zasobów.

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";

try
{
    ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
    // At this point, we are sure that myRG is a not null Resource Group, so we can use this object to perform any operations we want.
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine($"Resource Group {resourceGroupName} does not exist.");
}

Teraz przy użyciu tych metod wygody możemy po prostu wykonać następujące czynności.

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";

bool exists = await subscription.GetResourceGroups().ExistsAsync(resourceGroupName).Value;

if (exists)
{
    Console.WriteLine($"Resource Group {resourceGroupName} exists.");

    // We can get the resource group now that we know it exists.
    // This does introduce a small race condition where resource group could have been deleted between the check and the get.
    ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
}
else
{
    Console.WriteLine($"Resource Group {rgName} does not exist.");
}

Przykłady

Tworzenie grupy zasobów

// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Now we get a ResourceGroup collection for that subscription
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroupCollection = subscription.GetResourceGroups();

// With the collection, we can create a new resource group with an specific name
string resourceGroupName = "myRgName";
AzureLocation location = AzureLocation.WestUS2;
ResourceGroupData resourceGroupData = new ResourceGroupData(location);
ResourceGroupResource resourceGroup = (await resourceGroupCollection.CreateOrUpdateAsync(resourceGroupName, resourceGroupData)).Value;

Wyświetlanie listy wszystkich grup zasobów

// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
// Now we get a ResourceGroup collection for that subscription
ResourceGroupCollection resourceGroupCollection = subscription.GetResourceGroups();
// With GetAllAsync(), we can get a list of the resources in the collection
await foreach (ResourceGroupResource resourceGroup in resourceGroupCollection)
{
    Console.WriteLine(resourceGroup.Data.Name);
}

Aktualizowanie grupy zasobów

// Note: Resource group named 'myRgName' should exist for this example to work.
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
resourceGroup = await resourceGroup.AddTagAsync("key", "value");

Usuwanie grupy zasobów

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
await resourceGroup.DeleteAsync();

Aby uzyskać bardziej szczegółowe przykłady, zapoznaj się z dostępnymi przykładami .

Rozwiązywanie problemów

  • Jeśli masz usterkę do raportowania lub masz sugestię, zgłoś problem za pośrednictwem usługi GitHub i upewnij się, że do problemu jest dodana etykieta "Wersja zapoznawcza".
  • Jeśli potrzebujesz pomocy, sprawdź poprzednie pytania lub zadaj nowe pytania w witrynie StackOverflow przy użyciu tagów platformy Azure i platformy .NET.
  • Jeśli masz problemy z uwierzytelnianiem, zobacz dokumentację DefaultAzureCredential.

Następne kroki

Więcej przykładów kodu

Dodatkowa dokumentacja

Jeśli migrujesz ze starego zestawu SDK do tej wersji zapoznawczej, zapoznaj się z tym przewodnikiem migracji.

Aby uzyskać więcej informacji na temat zestawu Azure SDK, zobacz Wydania zestawu Azure SDK.