Zarządzanie zasobami przy użyciu zestawu Azure SDK dla platformy .NET
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
- Subskrypcja platformy Azure
- Implementacja TokenCredential , taka jak typ poświadczeń biblioteki tożsamości platformy Azure.
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 ArmClient
ArmClient
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:
- 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);
- 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 string
elementu . 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
- Zarządzanie grupami zasobów
- Tworzenie sieci wirtualnej
- Przykłady kodu biblioteki zarządzania platformy .NET
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.