Поделиться через

Управление ресурсами с помощью пакета Azure SDK для .NET

  • Статья

Библиотеки плоскости управления Azure SDK для .NET помогут вам создавать, подготавливать ресурсы Azure и управлять ими из приложений .NET. У каждой службы Azure есть своя библиотека управления.

С помощью библиотек управления (пространства имен, начиная с Azure.ResourceManager, например, Azure.ResourceManager.Computeможно написать программы конфигурации и развертывания, чтобы выполнять те же задачи, которые можно выполнять с помощью портал Azure, Azure CLI или других средств управления ресурсами.

Эти пакеты соответствуют новым рекомендациям по пакету SDK Azure, которые предоставляют основные возможности , которые используются среди всех пакетов SDK Azure, включая следующие:

  • Интуитивно понятная библиотека удостоверений Azure.
  • Конвейер HTTP с настраиваемыми политиками.
  • Обработка ошибок.
  • Распределенная трассировка.

Примечание.

Вы можете заметить, что некоторые пакеты по-прежнему являются предварительной версией, поэтапные выпуски дополнительных библиотек плоскостей управления служб Azure находятся в процессе. Если вы ищете стабильный пакет версий для определенного ресурса Azure и в настоящее время доступна только предварительная версия, создайте проблему в репозитории Azure SDK для .NET Github.

Начать

Необходимые компоненты

Установка пакета

Установите пакеты NuGet для удостоверений Azure и управления ресурсами Azure для .NET. Например:

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

аутентификация клиента;

Способ по умолчанию для создания клиента, прошедшего проверку подлинности, — использовать DefaultAzureCredential. Так как все API управления проходят через одну и ту же конечную точку, для взаимодействия с ресурсами достаточно создать только один клиент ArmClient верхнего уровня.

Чтобы выполнить проверку подлинности с помощью Azure и создать экземпляр заданных учетных данных, выполните ArmClientуказанные ArmClient действия.

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

// Code omitted for brevity

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

Дополнительные сведения о классе Azure.Identity.DefaultAzureCredential см. в статье Класс DefaultAzureCredential.

Памятка по пакету SDK для управления

Чтобы приступить к работе с пакетом SDK для управления Azure для .NET, представьте, что у вас есть задача для создания или обновления или обновления или удаления типичного пространства имен служебной шины Azure, выполните следующие действия.

  1. Проверка подлинности в подписке и группе ресурсов, над которыми вы хотите работать.
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. Найдите соответствующий метод для управления ресурсом Azure.
Операция Method
Получение ресурса с идентификатором ресурса client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
List resourceGroup.GetServiceBusNamespaces()
Указатель resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Добавление и обновление resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
Содержит resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Удаление client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() или resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Помните, что все ресурсы Azure, включая саму группу ресурсов, могут управляться соответствующим пакетом SDK для управления с помощью кода, аналогичного приведенному выше примере. Чтобы найти правильный пакет пакета SDK для управления Azure, найдите пакеты с именем со следующим шаблоном Azure.ResourceManager.{ResourceProviderName}.

Дополнительные сведения о ResourceIdentifier см. в разделе "Структурированный идентификатор ресурса".

Основные понятия

Сведения о иерархии ресурсов Azure

Чтобы уменьшить число клиентов, необходимых для выполнения общих задач, и количество избыточных параметров, которые принимают каждый из этих клиентов, мы ввели иерархию объектов в пакете SDK, который имитирует иерархию объектов в Azure. Каждый клиент ресурсов в пакете SDK имеет методы для доступа к клиентам ресурсов своих дочерних объектов, которые уже область в соответствующую подписку и группу ресурсов.

Для этого мы представляем три стандартных типа для всех ресурсов в Azure:

{ResourceName} Класс ресурсов

Этот тип представляет полный объект клиента ресурса, содержащий свойство Data , предоставляющее сведения как тип данных {ResourceName}Data . Он также имеет доступ ко всем операциям с этим ресурсом без необходимости передачи параметров области, таких как идентификатор подписки или имя ресурса. Это упрощает непосредственное выполнение операций в результате вызовов списка, так как все возвращается в качестве полного клиента ресурсов.

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} Класс данных

Этот тип представляет модель, которая составляет заданный ресурс. Как правило, это данные ответа от вызова службы, такие как HTTP GET, которые предоставляют сведения о базовом ресурсе. Ранее они были представлены классом Model.

{ResourceName} Класс Коллекции

Этот тип представляет операции, которые можно выполнять в коллекции ресурсов, принадлежащих определенному родительскому ресурсу. Этот объект предоставляет большую часть операций логической коллекции.

Поведение коллекции Метод сбора
Итерация/Список GetAll()
Указатель Get(string name)
Добавить CreateOrUpdate(Azure.WaitUntil waitUntil, имя строки, {ResourceName}Data)
Содержит Существует(строковое имя)

В большинстве случаев родительский элемент ресурса — ResourceGroup, но в некоторых случаях сам ресурс имеет вложенный ресурс, например подсеть является дочерним элементом виртуальной сети. Сама ResourceGroup является дочерним элементом подписки

Сборка

Предположим, что нашей компании требуется, чтобы все виртуальные машины были помечены тегом владельца. Нам поручили написать программу, которая добавляет тег к виртуальным машинам в заданной группе ресурсов.

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

Структурированный идентификатор ресурса

Идентификаторы ресурсов содержат полезные сведения о самом ресурсе, но они — обычные строки, которые необходимо проанализировать. Вместо реализации собственной логики синтаксического анализа можно использовать ResourceIdentifier объект, который будет выполнять синтаксический анализ.

Пример: анализ идентификатора с помощью объекта 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}");

Однако следует помнить, что некоторые из этих свойств могут иметь значение null. Обычно можно определить строку идентификатора, тип которой имеет идентификатор ресурса. Но если вы не уверены, проверка, если свойства имеют значение NULL.

Пример: генератор идентификаторов ресурсов

Возможно, вы не хотите вручную создать его resourceId из чистого string. Каждый {ResourceName}Resource класс имеет статический метод, который поможет вам создать строку идентификатора ресурса.

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

Управление существующими ресурсами

Выполнение операций с существующими ресурсами является распространенным вариантом использования библиотек клиента управления. В этом сценарии обычно используется идентификатор ресурса, с которым вы будете работать в виде строки. Хотя новая иерархия объектов отлично подходит для подготовки и работы в области указанного родительского объекта, в этом конкретном сценарии она не очень эффективна.

Ниже приведен пример того, как получить доступ к объекту AvailabilitySetResource и управлять им напрямую с помощью идентификатора ресурса:

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

Этот подход требует большого количества вызовов кода и трех вызовов API в Azure. То же самое можно сделать с меньшим количеством кода и без вызовов API с помощью методов расширения, предоставленных самим клиентом. Эти методы расширения позволяют передавать идентификатор ресурса и получать клиент ресурса с областью действия. Возвращенный объект — это ресурс {ResourceName}. Так как он еще не обратился к Azure для получения данных, вызывая Data это свойство, вызовет исключение, можно использовать HasData свойство, чтобы определить, содержит ли экземпляр ресурса данные или GetGetAsync метод в ресурсе, чтобы получить данные ресурса.

Так что предыдущий пример в итоге будет выглядеть следующим образом:

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

Проверка наличия ресурса

Если вы не уверены, существует ли ресурс или вы хотите проверка, если он существует, можно использовать Exists() или ExistsAsync() методы, которые можно вызвать из любого {ResourceName}Collection класса.

Exists() возвращает некоторое Response<bool> время ExistsAsync() в качестве асинхронной версии Task<Response<bool>>. В объекте Response<bool> можно посетить его Value свойство, чтобы проверка, если ресурс существует. false Если Value ресурс не существует, и наоборот.

В предыдущих версиях пакетов необходимо было перехватывать RequestFailedException и проверять код состояния на предмет 404. С этим новым API мы надеемся, что это может повысить производительность разработки и оптимизировать доступ к ресурсам.

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

Теперь с помощью этих удобных методов мы можем просто сделать следующее.

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

Примеры

Создание или изменение группы ресурсов

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

Список всех групп ресурсов

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

Обновление группы ресурсов

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

Удаление группы ресурсов

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

Для получения более подробных примеров ознакомьтесь с доступными образцами.

Устранение неполадок

  • Если у вас есть ошибка, о которой нужно сообщить, или предложение, создайте сообщение о проблеме через Проблемы GitHub и убедитесь, что к этой проблеме добавлена метка "предварительная версия".
  • Если вам нужна помощь, проверка предыдущие вопросы или задать новые в StackOverflow с помощью тегов Azure и .NET.
  • При возникновении проблем с проверкой подлинности см. документацию по DefaultAzureCredential.

Следующие шаги

Больше примеров кода

Дополнительная документация

Если вы переносите старый пакет SDK на эту предварительную версию, проверка из этого руководства по миграции.

Дополнительные сведения о выпуске пакета SDK для Azure см. в статье "Выпуски пакета SDK Azure".