Sdílet prostřednictvím

Správa prostředků pomocí sady Azure SDK pro .NET

  • Článek

Knihovny pro správu Azure SDK pro .NET vám pomohou vytvářet, zřizovat a spravovat prostředky Azure v rámci aplikací .NET. Všechny služby Azure mají odpovídající knihovny pro správu.

S knihovnami pro správu (obory názvů začínajícími Azure.ResourceManager, například Azure.ResourceManager.Compute), můžete psát programy konfigurace a nasazení pro provádění stejných úloh, které můžete provádět prostřednictvím webu Azure Portal, Azure CLI nebo jiných nástrojů pro správu prostředků.

Tyto balíčky se řídí novými pokyny sady Azure SDK, které poskytují základní funkce, které jsou sdíleny mezi všemi sadami AZURE SDK, mezi které patří:

  • Intuitivní knihovna identit Azure.
  • Kanál HTTP s vlastními zásadami.
  • Zpracování chyb
  • Distribuované trasování

Poznámka

Možná si všimnete, že některé balíčky jsou stále předběžné verze. Postupné vydání dalších knihoven roviny správy služeb Azure probíhá. Pokud hledáte stabilní balíček verze pro konkrétní prostředek Azure a aktuálně je k dispozici pouze předběžná verze, nahlaste problém v úložišti Azure SDK pro .NET na GitHubu.

Začít

Požadavky

Instalace balíčku

Nainstalujte balíčky NuGet pro Azure Identity a správu prostředků Azure pro .NET. Například:

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

Ověření klienta

Výchozí možností vytvoření ověřeného klienta je použití DefaultAzureCredential. Vzhledem k tomu, že všechna rozhraní API pro správu procházejí stejným koncovým bodem, aby bylo možné pracovat s prostředky, je potřeba vytvořit pouze jeden ArmClient nejvyšší úrovně.

Pro autentizaci v Azure a vytvoření ArmClientvytvořte instanci ArmClient s uvedenými přihlašovacími údaji.

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

// Code omitted for brevity

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

Další informace o třídě Azure.Identity.DefaultAzureCredential naleznete v tématu třída DefaultAzureCredential.

Stručná nápověda k sadě SDK pro správu

Pokud chcete začít se sadou Sdk pro správu Azure pro .NET, představte si, že máte úlohu vytvoření, výpisu, aktualizace nebo odstranění typického oboru názvů služby Azure Service Bus, postupujte takto:

  1. Autentizujte se k předplatnému a skupině prostředků, se kterými chcete pracovat.
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. Vyhledejte odpovídající metodu pro správu prostředku Azure.
Operace Metoda
Získání prostředku s identifikátorem prostředku client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
Seznam resourceGroup.GetServiceBusNamespaces()
Rejstřík resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Přidání nebo aktualizace resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Obsahuje resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Vymazat client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() nebo resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Nezapomeňte, že všechny prostředky Azure, včetně samotné skupiny prostředků, je možné spravovat pomocí odpovídající sady SDK pro správu pomocí kódu podobného výše uvedenému příkladu. Pokud chcete najít správný balíček sady SDK pro správu Azure, vyhledejte balíčky s názvem s následujícím vzorem Azure.ResourceManager.{ResourceProviderName}.

Další informace o identifikátoru prostředku najdete v strukturovaném identifikátoru zdroje.

Klíčové koncepty

Principy hierarchie prostředků Azure

Abychom snížili počet klientů potřebných k provádění běžných úloh a počet redundantních parametrů, které každý z těchto klientů převezme, zavedli jsme v sadě SDK hierarchii objektů, která napodobuje hierarchii objektů v Azure. Každý klient prostředků v sadě SDK má metody pro přístup ke klientům prostředků svých podřízených, kteří jsou již přiřazeni ke správné skupině prostředků a předplatnému.

Abychom toho dosáhli, představujeme tři standardní typy pro všechny prostředky v Azure:

třídu {ResourceName}Resource

Tento typ představuje úplný objekt klienta prostředku, který obsahuje vlastnost Data, jež zpřístupňuje podrobnosti jako typ {ResourceName}Data. Má také přístup ke všem operacím s tímto prostředkem, aniž by bylo nutné předávat parametry oboru, jako je ID předplatného nebo název prostředku. Díky tomu lze pohodlně přímo provádět operace na výsledcích volání seznamu, protože vše se nyní vrací jako kompletní prostředkový klient.

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}Data třída

Tento typ představuje model, který tvoří daný prostředek. Obvykle se jedná o data odpovědí z volání služby, jako je HTTP GET, a poskytuje podrobnosti o podkladovém prostředku. Dříve ji reprezentovala třída Modelu.

{ResourceName} kolekce třída

Tento typ představuje operace, které můžete provést s kolekcí prostředků patřících do konkrétního nadřazeného prostředku. Tento objekt poskytuje většinu operací logické kolekce.

Chování kolekce Metoda sběru
Iterace nebo seznam GetAll()
Index Get(název řetězce)
Přidat CreateOrUpdate(Azure.WaitUntil waitUntil, string name, {ResourceName}Data data)
Obsahuje Exists(název řetězce)

Ve většině případů je nadřazený prostředek ResourceGroup, ale v některých případech má samotný prostředek dílčí prostředek, například Subnet je podřízeným VirtualNetwork. Skupina prostředků je sama o sobě podřízená předplatnému.

Dáváme to všechno dohromady

Představte si, že naše společnost vyžaduje, aby všechny virtuální počítače byly označené vlastníkem. Máme za úkol napsat program, který přidá značku do všech chybějících virtuálních počítačů v dané skupině prostředků.

// 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());
   }
}

Identifikátor strukturovaného prostředku

ID prostředků obsahují užitečné informace o samotném prostředku, ale jedná se o prosté řetězce, které je potřeba analyzovat. Místo implementace vlastní logiky analýzy můžete použít objekt ResourceIdentifier, který provede analýzu za vás.

Příklad: Analýza ID pomocí objektu 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}");

Mějte však na paměti, že některé z těchto vlastností mohou být null. Obvykle snadno poznáte přímo z řetězce ID, o jaký typ ID prostředku se jedná. Pokud si ale nejste jistí, zkontrolujte, jestli jsou vlastnosti null.

Příklad: Generátor identifikátorů prostředků

Je možné, že nebudete chtít ručně vytvořit resourceId z čistého string. Každá třída {ResourceName}Resource má statickou metodu, která vám může pomoct vytvořit řetězec identifikátoru prostředku.

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

Správa existujících prostředků

Provádění operací na zdrojích, které již existují, je běžným případem použití při využívání knihoven klientů pro správu. V tomto scénáři obvykle máte identifikátor prostředku, s nímž chcete pracovat, ve formě řetězce. I když je nová hierarchie objektů skvělá pro zřizování a práci v rámci rozsahu daného nadřazeného objektu, není to nejúčinnější, pokud jde o tento konkrétní scénář.

Tady je příklad, jak můžete přistupovat k objektu AvailabilitySetResource a spravovat ho přímo pomocí jeho identifikátoru prostředku:

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);

Tento přístup vyžaduje velké množství kódu a tři volání rozhraní API se provádí v Azure. Totéž lze provést s menším kódem a bez jakýchkoli volání rozhraní API pomocí rozšiřujících metod, které jsme poskytli na samotném klientovi. Tyto metody rozšíření umožňují předat identifikátor prostředku a získat klienta prostředku s omezeným rozsahem. Vrácený objekt je {ResourceName}Zdroj. Vzhledem k tomu, že se ještě nespojilo s Azure, aby načetlo data, volání vlastnosti Data způsobí vyvolání výjimky. Můžete buď použít vlastnost HasData k určení, zda instance prostředku obsahuje data, nebo zavoláte metody Get nebo GetAsync na prostředku pro načtení dat prostředku.

Předchozí příklad by tedy vypadal takto:

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);

Zjistit, jestli zdroj existuje

Pokud si nejste jistí, jestli prostředek, který chcete získat, skutečně existuje, nebo ho chcete jen zkontrolovat, můžete použít metody Exists() nebo ExistsAsync(), které lze vyvolat z libovolné třídy {ResourceName}Collection.

Exists() vrátí Response<bool>, zatímco ExistsAsync() jako asynchronní verze vrátí Task<Response<bool>>. V objektu Response<bool> můžete navštívit jeho vlastnost Value a zkontrolovat, jestli prostředek existuje. Value je false, pokud prostředek neexistuje a naopak.

V předchozích verzích balíčků byste museli zachytit RequestFailedException a zkontrolovat stavový kód 404. S tímto novým rozhraním API doufáme, že to může zvýšit produktivitu vývojářů a optimalizovat přístup k prostředkům.

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.");
}

Teď s těmito metodami pohodlí můžeme jednoduše provést následující akce.

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.");
}

Příklady

Vytvoření skupiny prostředků

// 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;

Výpis všech skupin prostředků

// 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);
}

Aktualizujte skupinu prostředků

// 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");

Smazat skupinu prostředků

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

Podrobnější příklady najdete v ukázkách , které máme k dispozici.

Řešení problémů

  • Pokud máte chybu nahlásit nebo navrhnout, vytvořte problém prostřednictvím problémů na GitHubu a ujistěte se, že k problému přidáte popisek Preview.
  • Pokud potřebujete pomoc, projděte si předchozí otázky, nebo položte nové otázky na StackOverflow využitím značek Azure a .NET.
  • Pokud máte potíže s ověřováním, podívejte se do dokumentace k DefaultAzureCredential .

Další kroky

Další ukázkový kód

Další dokumentace

Pokud migrujete ze staré sady SDK do této verze Preview, podívejte se na tohoto průvodce migrací .

Další informace o sadě Azure SDK najdete pod verze Azure SDK.