Udostępnij za pośrednictwem

Jak zarządzać przypisaniami za pomocą programu PowerShell

  • Artykuł

Ważne

11 lipca 2026 r. strategia (wersja zapoznawcza) zostanie wycofana. Przeprowadź migrację istniejących definicji strategii i przypisań do szablonów specyfikacji i stosów wdrażania. Artefakty strategii mają być konwertowane na szablony JSON usługi ARM lub pliki Bicep używane do definiowania stosów wdrażania. Aby dowiedzieć się, jak utworzyć artefakt jako zasób usługi ARM, zobacz:

Przypisanie strategii można zarządzać przy użyciu modułu Az.Blueprint Azure PowerShell. Moduł obsługuje pobieranie, tworzenie, aktualizowanie i usuwanie przypisań. Moduł może również pobrać szczegóły dotyczące istniejących definicji strategii. W tym artykule opisano sposób instalowania modułu i rozpoczynania korzystania z niego.

Dodawanie modułu Az.Blueprint

Aby umożliwić Azure PowerShell zarządzanie przypisaniami strategii, należy dodać moduł. Ten moduł może być używany z lokalnie zainstalowanym programem PowerShell, programem Azure Cloud Shell lub obrazem Docker programu Azure PowerShell.

Wymagania podstawowe

Moduł Azure Blueprints wymaga następującego oprogramowania:

  • Azure PowerShell 1.5.0 lub nowszy. Jeśli jeszcze go nie zainstalowano, postępuj zgodnie z tymi instrukcjami.
  • Modułu PowerShellGet w wersji 2.0.1 lub nowszej. Jeśli jeszcze nie został on zainstalowany lub zaktualizowany, postępuj zgodnie z tymi instrukcjami.

Instalowanie modułu

Moduł Azure Blueprints dla programu PowerShell to Az.Blueprint.

  1. Za pomocą monitu administracyjnego programu PowerShell uruchom następujące polecenie:

    # Install the Azure Blueprints module from PowerShell Gallery
Install-Module -Name Az.Blueprint

    Uwaga

    Jeśli narzędzie Az.Accounts jest już zainstalowane, może być konieczne użycie -AllowClobber polecenia w celu wymuszenia instalacji.

  2. Sprawdź, czy moduł został zaimportowany i jest poprawną wersją (0.2.6):

    # Get a list of commands for the imported Az.Blueprint module
Get-Command -Module 'Az.Blueprint' -CommandType 'Cmdlet'

Pobieranie definicji strategii

Pierwszym krokiem do pracy z przypisaniem jest często uzyskanie odwołania do definicji strategii. Polecenie Get-AzBlueprint cmdlet pobiera co najmniej jedną definicję strategii. Polecenie cmdlet może pobrać definicje strategii z grupy zarządzania z subskrypcją -ManagementGroupId {mgId} lub z usługą -SubscriptionId {subId}. Parametr Name pobiera definicję strategii, ale musi być używany z identyfikatorem ManagementGroupId lub SubscriptionId. Wersję można użyć z nazwą , aby bardziej jawnie określić, która definicja strategii jest zwracana. Zamiast wersji przełącznik -LatestPublished pobiera ostatnio opublikowaną wersję.

W poniższym przykładzie użyto Get-AzBlueprint polecenia , aby pobrać wszystkie wersje definicji strategii o nazwie "101-blueprints-definition-subscription" z określonej subskrypcji reprezentowanej jako {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get all versions of the blueprint definition in the specified subscription
$blueprints = Get-AzBlueprint -SubscriptionId '{subId}' -Name '101-blueprints-definition-subscription'

# Display the blueprint definition object
$blueprints

Przykładowe dane wyjściowe definicji strategii z wieloma wersjami wyglądają następująco:

Name                 : 101-blueprints-definition-subscription
Id                   : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101
                       -blueprints-definition-subscription
DefinitionLocationId : {subId}
Versions             : {1.0, 1.1}
TimeCreated          : 2019-02-25
TargetScope          : Subscription
Parameters           : {storageAccount_storageAccountType, storageAccount_location,
                       allowedlocations_listOfAllowedLocations, [Usergrouporapplicationname]:Reader_RoleAssignmentName}
ResourceGroups       : ResourceGroup

Parametry strategii w definicji strategii można rozszerzyć, aby uzyskać więcej informacji.

$blueprints.Parameters

Key                                                    Value
---                                                    -----
storageAccount_storageAccountType                      Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
storageAccount_location                                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
allowedlocations_listOfAllowedLocations                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
[Usergrouporapplicationname]:Reader_RoleAssignmentName Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition

Pobieranie przypisań strategii

Jeśli przypisanie strategii już istnieje, możesz uzyskać do niego odwołanie za pomocą Get-AzBlueprintAssignment polecenia cmdlet . Polecenie cmdlet przyjmuje parametr SubscriptionId i Name jako parametry opcjonalne. Jeśli parametr SubscriptionId nie jest określony, używany jest bieżący kontekst subskrypcji.

W poniższym przykładzie użyto Get-AzBlueprintAssignment metody pobierania pojedynczego przypisania strategii o nazwie "Assignment-lock-resource-groups" z określonej subskrypcji reprezentowanej jako {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -SubscriptionId '{subId}' -Name 'Assignment-lock-resource-groups'

# Display the blueprint assignment object
$blueprintAssignment

Przykładowe dane wyjściowe przypisania strategii wyglądają następująco:

Name              : Assignment-lock-resource-groups
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssignme
                    nts/Assignment-lock-resource-groups
Scope             : /subscriptions/{subId}
LastModified      : 2019-02-19
LockMode          : AllResourcesReadOnly
ProvisioningState : Succeeded
Parameters        :
ResourceGroups    : ResourceGroup

Tworzenie przypisań strategii

Jeśli przypisanie strategii jeszcze nie istnieje, możesz go utworzyć za New-AzBlueprintAssignment pomocą polecenia cmdlet . To polecenie cmdlet używa następujących parametrów:

  • Nazwa [wymagane]

    • Określa nazwę przypisania strategii
    • Musi być unikatowa i nie istnieje już w identyfikatorze SubscriptionId

  • Strategia [wymagana]

    • Określa definicję strategii do przypisania
    • Użyj Get-AzBlueprint polecenia , aby uzyskać obiekt referencyjny

  • Lokalizacja [wymagana ]

    • Określa region dla przypisanej przez system tożsamości zarządzanej i obiektu wdrożenia subskrypcji do utworzenia w programie

  • Subskrypcja (opcjonalnie)

    • Określa subskrypcję, do których jest wdrażane przypisanie
    • Jeśli nie zostanie podana, wartość domyślna bieżącego kontekstu subskrypcji

  • Blokada (opcjonalnie)

    • Definiuje blokadę zasobu strategii do użycia dla wdrożonych zasobów
    • Obsługiwane opcje: None, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Jeśli nie zostanie podana, wartość domyślna to None

  • SystemAssignedIdentity (opcjonalnie)

    • Wybierz, aby utworzyć tożsamość zarządzaną przypisaną przez system dla przypisania i wdrożyć zasoby
    • Ustawienie domyślne dla zestawu parametrów "identity"
    • Nie można używać z identyfikatorem UserAssignedIdentity

  • UserAssignedIdentity (opcjonalnie)

    • Określa tożsamość zarządzaną przypisaną przez użytkownika do użycia na potrzeby przypisania i wdrażania zasobów
    • Część zestawu parametrów "identity"
    • Nie można używać z identyfikatorem SystemAssignedIdentity

  • Parametr (opcjonalnie)

    • Tabela skrótów par klucz/wartość do ustawiania parametrów dynamicznych w przypisaniu strategii

    • Wartość domyślna parametru dynamicznego to wartość domyślna w definicji

    • Jeśli parametr nie jest podany i nie ma wartości domyślnej, parametr nie jest opcjonalny

      Uwaga

      Parametr nie obsługuje bezpiecznych ciągów.

  • ResourceGroupParameter (opcjonalnie)

    • Tabela skrótów artefaktów grupy zasobów
    • Każdy symbol zastępczy artefaktu grupy zasobów ma pary klucz/wartość, aby dynamicznie ustawiać wartość Name (Nazwa ) i Location (Lokalizacja) dla artefaktu tej grupy zasobów
    • Jeśli parametr grupy zasobów nie jest podany i nie ma wartości domyślnej, parametr grupy zasobów nie jest opcjonalny

  • AssignmentFile (opcjonalnie)

    • Ścieżka do pliku JSON reprezentującego przypisanie strategii
    • Ten parametr jest częścią zestawu parametrów programu PowerShell, który zawiera tylko parametry Name, Blueprint i SubscriptionId.

Przykład 1. Podaj parametry

W poniższym przykładzie utworzono nowe przypisanie wersji "1.1" definicji strategii "my-blueprint" pobranej z parametrem Get-AzBlueprint, ustawia tożsamość zarządzaną i lokalizację obiektu przypisania na "westus2", blokuje zasoby za pomocą elementu AllResourcesReadOnly i ustawia tabele skrótów dla parametru i parametru ResourceGroupParameter dla określonej subskrypcji reprezentowanej jako {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters

Przykładowe dane wyjściowe tworzenia przypisania strategii wyglądają następująco:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesReadOnly
ProvisioningState : Creating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

Przykład 2. Używanie pliku definicji przypisania JSON

Poniższy przykład tworzy prawie to samo przypisanie co przykład 1. Zamiast przekazywać parametry do polecenia cmdlet, w przykładzie pokazano użycie pliku definicji przypisania JSON i parametru AssignmentFile . Ponadto właściwość excludedPrincipals jest skonfigurowana jako część blokad. Nie ma parametru programu PowerShell dla wartości excludedPrincipals , a właściwość można skonfigurować tylko przez ustawienie go za pomocą pliku definicji przypisania JSON.

{
  "identity": {
    "type": "SystemAssigned"
  },
  "location": "westus2",
  "properties": {
    "description": "Assignment of the 101-blueprint-definition-subscription",
    "blueprintId": "/subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101-blueprints-definition-subscription",
    "locks": {
      "mode": "AllResourcesReadOnly",
      "excludedPrincipals": [
          "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
          "38833b56-194d-420b-90ce-cff578296714"
      ]
    },
    "parameters": {
      "storageAccount_storageAccountType": {
        "value": "Standard_GRS"
      }
    },
    "resourceGroups": {
      "ResourceGroup": {
        "name": "storage_rg",
        "location": "westus2"
      }
    }
  }
}

# Login first with Connect-AzAccount if not using Cloud Shell

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -SubscriptionId '{subId}' `
    -AssignmentFile '.\assignment.json'

Przykład pliku definicji przypisania JSON dla tożsamości zarządzanej przypisanej przez użytkownika zawiera treść żądania w temacie Przykład: Przypisanie przy użyciu tożsamości zarządzanej przypisanej przez użytkownika dla interfejsu API REST.

Aktualizowanie przypisań strategii

Czasami konieczne jest zaktualizowanie przypisania strategii, które zostało już utworzone. Polecenie Set-AzBlueprintAssignment cmdlet obsługuje tę akcję. Polecenie cmdlet przyjmuje większość tych samych parametrów, które New-AzBlueprintAssignment wykonuje polecenie cmdlet, umożliwiając aktualizację dowolnego elementu ustawionego na przypisaniu. Wyjątki to Nazwa, Strategia i Identyfikator subskrypcji. Zaktualizowano tylko podane wartości.

Aby zrozumieć, co się dzieje podczas aktualizowania przypisania strategii, zobacz reguły aktualizowania przypisań.

  • Nazwa [wymagane]

    • Określa nazwę przypisania strategii do aktualizacji
    • Służy do lokalizowania przypisania do aktualizacji, a nie zmiany przypisania

  • Strategia [wymagana]

    • Określa definicję strategii przypisania strategii
    • Użyj Get-AzBlueprint polecenia , aby uzyskać obiekt referencyjny
    • Służy do lokalizowania przypisania do aktualizacji, a nie zmiany przypisania

  • Lokalizacja (opcjonalnie)

    • Określa region dla przypisanej przez system tożsamości zarządzanej i obiektu wdrożenia subskrypcji do utworzenia w programie

  • Subskrypcja (opcjonalnie)

    • Określa subskrypcję, do których jest wdrażane przypisanie
    • Jeśli nie zostanie podana, wartość domyślna bieżącego kontekstu subskrypcji
    • Służy do lokalizowania przypisania do aktualizacji, a nie zmiany przypisania

  • Blokada (opcjonalnie)

    • Definiuje blokadę zasobu strategii do użycia dla wdrożonych zasobów
    • Obsługiwane opcje: None, AllResourcesReadOnly, AllResourcesDoNotDelete

  • SystemAssignedIdentity (opcjonalnie)

    • Wybierz, aby utworzyć tożsamość zarządzaną przypisaną przez system dla przypisania i wdrożyć zasoby
    • Ustawienie domyślne dla zestawu parametrów "identity"
    • Nie można używać z identyfikatorem UserAssignedIdentity

  • UserAssignedIdentity (opcjonalnie)

    • Określa tożsamość zarządzaną przypisaną przez użytkownika do użycia na potrzeby przypisania i wdrażania zasobów
    • Część zestawu parametrów "identity"
    • Nie można używać z identyfikatorem SystemAssignedIdentity

  • Parametr (opcjonalnie)

    • Tabela skrótów par klucz/wartość do ustawiania parametrów dynamicznych w przypisaniu strategii

    • Wartość domyślna parametru dynamicznego to wartość domyślna w definicji

    • Jeśli parametr nie jest podany i nie ma wartości domyślnej, parametr nie jest opcjonalny

      Uwaga

      Parametr nie obsługuje bezpiecznych ciągów.

  • ResourceGroupParameter (opcjonalnie)

    • Tabela skrótów artefaktów grupy zasobów
    • Każdy symbol zastępczy artefaktu grupy zasobów ma pary klucz/wartość, aby dynamicznie ustawiać wartość Name (Nazwa ) i Location (Lokalizacja) dla artefaktu tej grupy zasobów
    • Jeśli parametr grupy zasobów nie jest podany i nie ma wartości domyślnej, parametr grupy zasobów nie jest opcjonalny

Poniższy przykład aktualizuje przypisanie wersji "1.1" definicji strategii "my-blueprint" pobranej za Get-AzBlueprint pomocą zmiany trybu blokady:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete

Przykładowe dane wyjściowe tworzenia przypisania strategii wyglądają następująco:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesDoNotDelete
ProvisioningState : Updating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

Usuwanie przypisań strategii

Gdy nadszedł czas na usunięcie przypisania strategii, Remove-AzBlueprintAssignment polecenie cmdlet obsługuje tę akcję. Polecenie cmdlet przyjmuje wartość Name lub InputObject , aby określić, które przypisanie strategii ma zostać usunięte. Identyfikator subskrypcji jest wymagany i musi być podany we wszystkich przypadkach.

Poniższy przykład pobiera istniejące przypisanie strategii za pomocą Get-AzBlueprintAssignment polecenia , a następnie usuwa go z określonej subskrypcji reprezentowanej jako {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -Name 'Assignment-lock-resource-groups'

# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $blueprintAssignment -SubscriptionId '{subId}'

Przykładowy kod

Łącząc wszystkie kroki, poniższy przykład pobiera definicję strategii, a następnie tworzy, aktualizuje i usuwa przypisanie strategii w określonej subskrypcji reprezentowanej jako {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

#region GetBlueprint
# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'
#endregion

#region CreateAssignment
# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters
#endregion CreateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region UpdateAssignment
# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete
#endregion UpdateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region RemoveAssignment
# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $bpAssignment -SubscriptionId '{subId}'
#endregion

Następne kroki