Używanie skryptów wdrażania w szablonach usługi ARM

  • Artykuł

Dowiedz się, jak używać skryptów wdrażania w szablonach usługi Azure Resource Manager (ARM). deploymentScripts Za pomocą zasobu użytkownicy mogą wykonywać skrypty we wdrożeniach usługi ARM i przeglądać wyniki wykonywania.

Napiwek

Zalecamy Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza w użyciu. Aby dowiedzieć się więcej, zobacz Skrypt wdrażania.

Te skrypty mogą służyć do wykonywania niestandardowych kroków, takich jak:

  • Dodaj użytkowników do katalogu.
  • Wykonywanie operacji płaszczyzny danych, na przykład kopiowania obiektów blob lub bazy danych inicjacyjnej.
  • Wyszukaj i zweryfikuj klucz licencji.
  • Utwórz certyfikat z podpisem własnym.
  • Utwórz obiekt w identyfikatorze Entra firmy Microsoft.
  • Wyszukaj bloki adresów IP z systemu niestandardowego.

Zalety skryptu wdrażania:

  • Łatwe w kodzie, użyciu i debugowanie. Skrypty wdrażania można opracowywać w ulubionych środowiskach deweloperskich. Skrypty można osadzać w szablonach lub w zewnętrznych plikach skryptów.
  • Możesz określić język skryptu i platformę. Obecnie obsługiwane są skrypty wdrażania programu Azure PowerShell i interfejsu wiersza polecenia platformy Azure w środowisku systemu Linux.
  • Zezwalaj na przekazywanie argumentów wiersza polecenia do skryptu.
  • Może określać dane wyjściowe skryptu i przekazywać je z powrotem do wdrożenia.

Zasób skryptu wdrażania jest dostępny tylko w regionach, w których jest dostępne wystąpienie kontenera platformy Azure. Zobacz Dostępność zasobów dla usługi Azure Container Instances w regionach świadczenia usługi Azure. Obecnie skrypt wdrażania używa tylko sieci publicznej.

Ważne

Usługa skryptu wdrażania wymaga dwóch zasobów pomocniczych na potrzeby wykonywania skryptów i rozwiązywania problemów: konta magazynu i wystąpienia kontenera. Możesz określić istniejące konto magazynu, w przeciwnym razie usługa skryptu utworzy je dla Ciebie. Te dwa automatycznie utworzone zasoby pomocnicze są zwykle usuwane przez usługę skryptów, gdy wykonanie skryptu wdrażania jest w stanie terminalu. Opłaty są naliczane za zasoby pomocnicze do momentu ich usunięcia. Aby uzyskać informacje o cenach, zobacz Cennik usługi Container Instances i Cennik usługi Azure Storage. Aby dowiedzieć się więcej, zobacz Zasoby skryptu wdrażania oczyszczania.

Uwaga

Logika ponawiania prób logowania do platformy Azure jest teraz wbudowana w skrypt otoki. Jeśli przyznasz uprawnienia w tym samym szablonie co skrypty wdrażania, usługa skryptu wdrażania ponawia próbę logowania przez 10 minut z 10-sekundowym interwałem do momentu zreplikowania przypisania roli tożsamości zarządzanej.

Zasoby szkoleniowe

Jeśli wolisz dowiedzieć się więcej o skryptach wdrażania za pomocą szczegółowych wskazówek, zobacz Rozszerzanie szablonów usługi ARM przy użyciu skryptów wdrażania.

Konfigurowanie minimalnych uprawnień

W przypadku interfejsu API skryptu wdrażania w wersji 2020-10-01 lub nowszej istnieją dwa podmioty zabezpieczeń związane z wykonywaniem skryptu wdrażania:

  • Jednostka wdrożenia (podmiot zabezpieczeń używany do wdrożenia szablonu): ten podmiot zabezpieczeń służy do tworzenia podstawowych zasobów wymaganych do wykonania zasobu skryptu wdrożenia — konta magazynu i wystąpienia kontenera platformy Azure. Aby skonfigurować uprawnienia z najmniejszymi uprawnieniami, przypisz rolę niestandardową z następującymi właściwościami do jednostki wdrożenia:

    {
  "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
  "description": "Configure least privilege for the deployment principal in deployment script",
  "type": "customRole",
  "IsCustom": true,
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/*",
        "Microsoft.ContainerInstance/containerGroups/*",
        "Microsoft.Resources/deployments/*",
        "Microsoft.Resources/deploymentScripts/*"
      ],
    }
  ],
  "assignableScopes": [
    "[subscription().id]"
  ]
}

    Jeśli dostawcy zasobów usługi Azure Storage i wystąpienia kontenera platformy Azure nie zostały zarejestrowane, należy również dodać Microsoft.Storage/register/action usługę i Microsoft.ContainerInstance/register/action.

  • Jednostka skryptu wdrażania: ten podmiot zabezpieczeń jest wymagany tylko wtedy, gdy skrypt wdrożenia musi uwierzytelnić się na platformie Azure i wywołać interfejs wiersza polecenia platformy Azure/program PowerShell. Istnieją dwa sposoby określania jednostki skryptu wdrożenia:

    • Określ tożsamość zarządzaną przypisaną przez użytkownika we identity właściwości (zobacz Przykładowe szablony). Po określeniu usługa skryptu wywołuje wywołania Connect-AzAccount -Identity przed wywołaniem skryptu wdrażania. Tożsamość zarządzana musi mieć wymagany dostęp, aby ukończyć operację w skrycie. Obecnie tylko tożsamość zarządzana przypisana przez użytkownika jest obsługiwana identity dla właściwości . Aby zalogować się przy użyciu innej tożsamości, użyj drugiej metody na tej liście.
    • Przekaż poświadczenia jednostki usługi jako bezpieczne zmienne środowiskowe, a następnie może wywołać polecenie Połączenie-AzAccount lub az login w skrypcie wdrażania.

    Jeśli jest używana tożsamość zarządzana, jednostka wdrożenia wymaga roli Operatora tożsamości zarządzanej (wbudowanej roli) przypisanej do zasobu tożsamości zarządzanej.

Przykładowe szablony

Poniższy kod JSON jest przykładem. Aby uzyskać więcej informacji, zobacz najnowszy schemat szablonu.

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "runPowerShellInline",
  "location": "[resourceGroup().location]",
  "tags": {
    "tagName1": "tagValue1",
    "tagName2": "tagValue2"
  },
  "kind": "AzurePowerShell", // or "AzureCLI"
  "identity": {
    "type": "userAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {}
    }
  },
  "properties": {
    "forceUpdateTag": "1",
    "containerSettings": {
      "containerGroupName": "mycustomaci"
    },
    "storageAccountSettings": {
      "storageAccountName": "myStorageAccount",
      "storageAccountKey": "myKey"
    },
    "azPowerShellVersion": "9.7",  // or "azCliVersion": "2.47.0",
    "arguments": "-name \\\"John Dole\\\"",
    "environmentVariables": [
      {
        "name": "UserName",
        "value": "jdole"
      },
      {
        "name": "Password",
        "secureValue": "jDolePassword"
      }
    ],
    "scriptContent": "
      param([string] $name)
      $output = 'Hello {0}. The username is {1}, the password is {2}.' -f $name,${Env:UserName},${Env:Password}
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    ", // or "primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",
    "supportingScriptUris":[],
    "timeout": "PT30M",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}

Uwaga

Przykład służy do celów demonstracyjnych. Właściwości scriptContent i primaryScriptUri nie mogą współistnieć w szablonie.

Uwaga

SkryptContent przedstawia skrypt z wieloma wierszami. W witrynie Azure Portal i potoku usługi Azure DevOps nie można przeanalizować skryptu wdrażania z wieloma wierszami. Możesz połączyć polecenia programu PowerShell (przy użyciu średników lub \r\n lub \n) w jednym wierszu albo użyć primaryScriptUri właściwości z zewnętrznym plikiem skryptu. Dostępnych jest wiele bezpłatnych narzędzi ucieczki/unescape ciągu JSON. Na przykład https://www.freeformatter.com/json-escape.html.

Szczegóły wartości właściwości:

  • identity: W przypadku interfejsu API skryptu wdrażania w wersji 2020-10-01 lub nowszej tożsamość zarządzana przypisana przez użytkownika jest opcjonalna, chyba że musisz wykonać jakiekolwiek akcje specyficzne dla platformy Azure w skrycie. W przypadku interfejsu API w wersji 2019-10-01-preview tożsamość zarządzana jest wymagana, ponieważ usługa skryptu wdrażania używa go do wykonywania skryptów. Po określeniu właściwości tożsamości usługa skryptu wywołuje przed Connect-AzAccount -Identity wywołaniem skryptu użytkownika. Obecnie obsługiwana jest tylko tożsamość zarządzana przypisana przez użytkownika. Aby zalogować się przy użyciu innej tożsamości, możesz wywołać polecenie Połączenie-AzAccount w skrypcie.

  • tags: tagi skryptu wdrożenia. Jeśli usługa skryptu wdrożenia generuje konto magazynu i wystąpienie kontenera, tagi są przekazywane do obu zasobów, które mogą służyć do ich identyfikowania. Innym sposobem identyfikacji tych zasobów jest ich sufiksy, które zawierają "azscripts". Aby uzyskać więcej informacji, zobacz Monitorowanie i rozwiązywanie problemów ze skryptami wdrażania.

  • kind: określ typ skryptu. Obecnie obsługiwane są skrypty programu Azure PowerShell i interfejsu wiersza polecenia platformy Azure. Wartości to AzurePowerShell i AzureCLI.

  • forceUpdateTag: zmiana tej wartości między wdrożeniami szablonów wymusza ponowne wykonanie skryptu wdrażania. Jeśli używasz newGuid() funkcji lub utcNow() , obie funkcje mogą być używane tylko w wartości domyślnej dla parametru. Aby dowiedzieć się więcej, zobacz Uruchamianie skryptu więcej niż raz.

  • containerSettings: określ ustawienia, aby dostosować wystąpienie kontenera platformy Azure. Skrypt wdrażania wymaga nowego wystąpienia kontenera platformy Azure. Nie można określić istniejącego wystąpienia kontenera platformy Azure. Można jednak dostosować nazwę grupy kontenerów przy użyciu polecenia containerGroupName. Jeśli nie zostanie określona, nazwa grupy zostanie wygenerowana automatycznie.

  • storageAccountSettings: określ ustawienia, które mają być używane na istniejącym koncie magazynu. Jeśli storageAccountName nie zostanie określony, zostanie automatycznie utworzone konto magazynu. Zobacz Używanie istniejącego konta magazynu.

  • azPowerShellVersion/azCliVersion: określ wersję modułu, która ma być używana. Zobacz listę obsługiwanych wersji programu Azure PowerShell. Wersja określa, który obraz kontenera ma być używany:

    • Moduł Az w wersji nowszej lub równej 9 używa systemu Ubuntu 22.04.
    • Wersja Az większa niż lub równa 6, ale mniejsza niż 9 używa systemu Ubuntu 20.04.
    • Moduł Az w wersji mniejszej niż 6 używa systemu Ubuntu 18.04.

    Ważne

    Zaleca się uaktualnienie do najnowszej wersji systemu Ubuntu, ponieważ ubuntu 18.04 zbliża się do końca życia i nie będzie już otrzymywać aktualizacji zabezpieczeń poza 31 maja 2023 r.

    Zobacz listę obsługiwanych wersji interfejsu wiersza polecenia platformy Azure.

    Ważne

    Skrypt wdrażania używa dostępnych obrazów interfejsu wiersza polecenia z usługi Microsoft Container Registry (MCR). Zazwyczaj do certyfikowania obrazu interfejsu wiersza polecenia na potrzeby skryptu wdrażania trwa około jednego miesiąca. Nie używaj wersji interfejsu wiersza polecenia, które zostały wydane w ciągu 30 dni. Aby znaleźć daty wydania obrazów, zobacz Informacje o wersji interfejsu wiersza polecenia platformy Azure. Jeśli jest używana nieobsługiwana wersja, komunikat o błędzie zawiera listę obsługiwanych wersji.

  • arguments: Określ wartości parametrów. Wartości są oddzielone spacjami.

    Skrypty wdrażania dzielą argumenty na tablicę ciągów, wywołując wywołanie systemu CommandLineToArgvW . Ten krok jest niezbędny, ponieważ argumenty są przekazywane jako właściwość polecenia do usługi Azure Container Instance, a właściwość polecenia jest tablicą ciągów.

    Jeśli argumenty zawierają znaki ucieczki, użyj JsonEscaper , aby dwukrotnie uniknąć znaków. Wklej oryginalny ciąg ucieczki do narzędzia, a następnie wybierz pozycję Ucieczka. Narzędzie generuje podwójny ciąg ucieczki. Na przykład w poprzednim przykładowym szablonie argument to -name \"John Dole\". Ciąg ucieczki to -name \\\"John Dole\\\".

    Aby przekazać parametr szablonu usługi ARM typu obiektu jako argument, przekonwertuj obiekt na ciąg przy użyciu funkcji string(), a następnie użyj funkcji replace(), aby zamienić dowolny \" obiekt na \\\". Na przykład:

    replace(string(parameters('tables')), '\"', '\\\"')

    Aby uzyskać więcej informacji, zobacz przykładowy szablon.

  • environmentVariables: Określ zmienne środowiskowe, które mają być przekazywane do skryptu. Aby uzyskać więcej informacji, zobacz Tworzenie skryptów wdrażania.

  • scriptContent: określ zawartość skryptu. Aby uruchomić skrypt zewnętrzny, zamiast tego użyj polecenia primaryScriptUri . Przykłady można znaleźć w temacie Use inline script (Używanie skryptu wbudowanego) i Use external script (Używanie skryptu zewnętrznego).

  • primaryScriptUri: określ publicznie dostępny adres URL podstawowego skryptu wdrażania z obsługiwanymi rozszerzeniami plików. Aby uzyskać więcej informacji, zobacz Używanie skryptów zewnętrznych.

  • supportingScriptUris: określ tablicę publicznie dostępnych adresów URL do plików pomocniczych, które są wywoływane w elemecie scriptContent lub primaryScriptUri. Aby uzyskać więcej informacji, zobacz Używanie skryptów zewnętrznych.

  • timeout: określ maksymalny dozwolony czas wykonywania skryptu określony w formacie ISO 8601. Wartość domyślna to P1D.

  • cleanupPreference. Określ preferencję czyszczenia dwóch pomocniczych zasobów wdrażania, konta magazynu i wystąpienia kontenera, gdy wykonanie skryptu zostanie w stanie terminalu. Ustawienie domyślne to Zawsze, co oznacza usunięcie zasobów pomocniczych pomimo stanu terminalu (Powodzenie, Niepowodzenie, Anulowanie). Aby dowiedzieć się więcej, zobacz Oczyszczanie zasobów skryptu wdrażania.

  • retentionInterval: określ interwał, dla którego usługa zachowuje zasób skryptu wdrożenia po osiągnięciu stanu terminalu przez wykonanie skryptu wdrożenia. Zasób skryptu wdrażania jest usuwany po wygaśnięciu tego czasu trwania. Czas trwania jest oparty na wzorcu ISO 8601. Interwał przechowywania wynosi od 1 do 26 godzin (PT26H). Ta właściwość jest używana, gdy cleanupPreference jest ustawiona na Wartość OnExpiration. Aby dowiedzieć się więcej, zobacz Oczyszczanie zasobów skryptu wdrażania.

Więcej przykładów

  • Przykład 1: utwórz magazyn kluczy i użyj skryptu wdrażania, aby przypisać certyfikat do magazynu kluczy.
  • Przykład 2: utwórz grupę zasobów na poziomie subskrypcji, utwórz magazyn kluczy w grupie zasobów, a następnie użyj skryptu wdrażania, aby przypisać certyfikat do magazynu kluczy.
  • Przykład 3: tworzenie tożsamości zarządzanej przypisanej przez użytkownika, przypisywanie roli współautora do tożsamości na poziomie grupy zasobów, tworzenie magazynu kluczy, a następnie przypisywanie certyfikatu do magazynu kluczy za pomocą skryptu wdrażania.
  • Przykład 4: jest to ten sam scenariusz co przykład 1 na tej liście. Zostanie utworzona nowa grupa zasobów w celu uruchomienia skryptu wdrażania. Ten szablon jest szablonem na poziomie subskrypcji.
  • Przykład 5: jest to ten sam scenariusz co przykład 4. Ten szablon jest szablonem na poziomie grupy zasobów.
  • Przykład 6: ręcznie utwórz tożsamość zarządzaną przypisaną przez użytkownika i przypisz jej uprawnienie do używania interfejsu API programu Microsoft Graph do tworzenia aplikacji Microsoft Entra; w szablonie usługi ARM użyj skryptu wdrażania, aby utworzyć aplikację i jednostkę usługi Microsoft Entra oraz wyświetlić identyfikatory obiektów i identyfikatory klienta.

Korzystanie ze skryptów wbudowanych

Poniższy szablon ma jeden zasób zdefiniowany z typem Microsoft.Resources/deploymentScripts . Wyróżniona część jest wbudowanym skryptem.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "\\\"John Dole\\\""
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runPowerShellInlineWithOutput",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "scriptContent": "
          param([string] $name)
          $output = \"Hello {0}\" -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "arguments": "[concat('-name', ' ', parameters('name'))]",
        "timeout": "PT1H",
        "cleanupPreference": "OnSuccess",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('runPowerShellInlineWithOutput').outputs.text]",
      "type": "string"
    }
  }
}

Uwaga

Ponieważ skrypty wdrożenia wbudowanego są ujęte w cudzysłowy, ciągi wewnątrz skryptów wdrażania muszą zostać uniknięci za pomocą ukośnika odwrotnego (\) lub ujętego w pojedynczy cudzysłów. Możesz również rozważyć użycie podstawienia ciągu, jak pokazano w poprzednim przykładzie JSON.

Skrypt przyjmuje jeden parametr i zwraca wartość parametru. DeploymentScriptOutputs służy do przechowywania danych wyjściowych. W sekcji dane wyjściowe wiersz pokazuje, value jak uzyskać dostęp do przechowywanych wartości. Write-Output służy do debugowania. Aby dowiedzieć się, jak uzyskać dostęp do pliku wyjściowego, zobacz Monitorowanie i rozwiązywanie problemów ze skryptami wdrażania. Opisy właściwości można znaleźć w temacie Przykładowe szablony.

Aby uruchomić skrypt, wybierz pozycję Wypróbuj , aby otworzyć usługę Cloud Shell, a następnie wklej następujący kod w okienku powłoki.

$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.json"

Write-Host "Press [ENTER] to continue ..."

Dane wyjściowe wyglądają następująco:

Zrzut ekranu przedstawiający dane wyjściowe skryptu wdrożenia szablonu usługi Resource Manager hello world.

Używanie skryptów zewnętrznych

Oprócz wbudowanych skryptów można również używać zewnętrznych plików skryptów. Obsługiwane są tylko podstawowe skrypty programu PowerShell z rozszerzeniem pliku ps1 . W przypadku skryptów interfejsu wiersza polecenia skrypty podstawowe mogą mieć dowolne rozszerzenia (lub bez rozszerzenia), o ile skrypty są prawidłowymi skryptami powłoki Bash. Aby użyć plików skryptów zewnętrznych, zastąp ciąg scriptContent .primaryScriptUri Na przykład:

"primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",

Aby uzyskać więcej informacji, zobacz przykładowy szablon.

Pliki skryptów zewnętrznych muszą być dostępne. Aby zabezpieczyć pliki skryptów przechowywane na kontach usługi Azure Storage, wygeneruj token SAS i dołącz go do identyfikatora URI szablonu. Ustaw czas wygaśnięcia, aby umożliwić wystarczającą ilość czasu na ukończenie wdrożenia. Aby uzyskać więcej informacji, zobacz Wdrażanie prywatnego szablonu usługi ARM przy użyciu tokenu SAS.

Odpowiadasz za zapewnienie integralności skryptów, do których odwołuje się skrypt wdrożenia, primaryScriptUri lub supportingScriptUris. Odwołanie tylko do zaufanych skryptów.

Korzystanie ze skryptów pomocniczych

Skomplikowane logiki można oddzielić od jednego lub większej liczby plików skryptów pomocniczych. Właściwość supportingScriptUris umożliwia podanie tablicy identyfikatorów URI do plików skryptów pomocniczych w razie potrzeby:

"scriptContent": "
    ...
    ./Create-Cert.ps1
    ...
"

"supportingScriptUris": [
  "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/create-cert.ps1"
],

Pliki skryptów pomocniczych mogą być wywoływane zarówno ze skryptów wbudowanych, jak i plików skryptów podstawowych. Pliki skryptów pomocniczych nie mają ograniczeń dotyczących rozszerzenia pliku.

Pliki pomocnicze są kopiowane do azscripts/azscriptinput środowiska uruchomieniowego. Użyj ścieżki względnej, aby odwołać się do plików pomocniczych ze skryptów wbudowanych i plików skryptów podstawowych.

Praca z danymi wyjściowymi ze skryptów programu PowerShell

Poniższy szablon przedstawia sposób przekazywania wartości między dwoma deploymentScripts zasobami:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "John Dole"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate1",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-name', ' ', concat('\\\"', parameters('name'), '\\\"'))]",
        "scriptContent": "
          param([string] $name)
          $output = 'Hello {0}' -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    },
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate2",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "dependsOn": [
        "scriptInTemplate1"
      ],
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-textToEcho', ' ', concat('\\\"', reference('scriptInTemplate1').outputs.text, '\\\"'))]",
        "scriptContent": "
          param([string] $textToEcho)
          Write-Output $textToEcho
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $textToEcho
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('scriptInTemplate2').outputs.text]",
      "type": "string"
    }
  }
}

W pierwszym zasobie zdefiniujesz zmienną o nazwie $DeploymentScriptOutputsi użyjesz jej do przechowywania wartości wyjściowych. Aby uzyskać dostęp do wartości wyjściowej z innego zasobu w szablonie, użyj:

reference('<ResourceName>').outputs.text

Praca z danymi wyjściowymi skryptów interfejsu wiersza polecenia

W przeciwieństwie do skryptów wdrażania programu Azure PowerShell interfejs wiersza polecenia/powłoka bash nie uwidacznia wspólnej zmiennej do przechowywania danych wyjściowych skryptu. Zamiast tego używa zmiennej środowiskowej o nazwie AZ_SCRIPTS_OUTPUT_PATH , aby wskazać lokalizację pliku wyjściowego skryptu. Podczas wykonywania skryptu wdrażania w szablonie usługi ARM powłoka powłoki Bash automatycznie konfiguruje tę zmienną środowiskową. Jego wstępnie zdefiniowana wartość jest ustawiana jako /mnt/azscripts/azscriptoutput/scriptoutputs.json. Dane wyjściowe są wymagane do zachowania zgodności z prawidłową strukturą obiektów ciągów JSON. Zawartość pliku powinna być sformatowana jako para klucz-wartość. Na przykład tablica ciągów powinna zostać zapisana jako { "MyResult": [ "foo", "bar"] }. Przechowywanie tylko wyników tablicy, takich jak [ "foo", "bar" ], jest uznawane za nieprawidłowe.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "identity": {
      "type": "string"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runBashWithOutputs",
      "location": "[resourceGroup().location]",
      "kind": "AzureCLI",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[parameters('identity')]": {
          }
        }
      },
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "AzCliVersion": "2.40.0",
        "timeout": "PT30M",
        "arguments": "'foo' 'bar'",
        "environmentVariables": [
          {
            "name": "UserName",
            "value": "jdole"
          },
          {
            "name": "Password",
            "secureValue": "jDolePassword"
          }
        ],
        "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo \"arg2 is: $2\"; echo \"Username is: $UserName\"; echo \"password is: $Password\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
        "cleanupPreference": "OnExpiration",
        "retentionInterval": "P1D"

W poprzednim przykładzie użyto języka jq . Jest on dostarczany z obrazami kontenerów. Zobacz Konfigurowanie środowiska projektowego.

Korzystanie z istniejącego konta magazynu

Konto magazynu i wystąpienie kontenera są potrzebne do wykonywania skryptu i rozwiązywania problemów. Dostępne są opcje określania istniejącego konta magazynu. W przeciwnym razie konto magazynu wraz z wystąpieniem kontenera jest tworzone automatycznie przez usługę skryptu. Wymagania dotyczące korzystania z istniejącego konta magazynu:

  • Obsługiwane rodzaje kont magazynu to:

    SKU Obsługiwany rodzaj
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Storage, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Storage, StorageV2
    Standard_RAGRS Storage, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

    Te kombinacje obsługują udziały plików. Aby uzyskać więcej informacji, zobacz Tworzenie udziału plików platformy Azure i typy kont magazynu.

  • Reguły zapory konta magazynu nie są jeszcze obsługiwane. Aby uzyskać więcej informacji, zobacz Konfigurowanie zapór i sieci wirtualnych usługi Azure Storage.

  • Jednostka wdrożenia musi mieć uprawnienia do zarządzania kontem magazynu, które obejmuje odczyt, tworzenie, usuwanie udziałów plików.

Aby określić istniejące konto magazynu, dodaj następujący kod JSON do elementu właściwości :Microsoft.Resources/deploymentScripts

"storageAccountSettings": {
  "storageAccountName": "myStorageAccount",
  "storageAccountKey": "myKey"
},

  • storageAccountName: określ nazwę konta magazynu.

  • storageAccountKey: określ jeden z kluczy konta magazynu. Aby pobrać klucz, możesz użyć funkcji listKeys( ). Na przykład:

    "storageAccountSettings": {
    "storageAccountName": "[variables('storageAccountName')]",
    "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

Zobacz Przykładowe szablony , aby uzyskać pełną Microsoft.Resources/deploymentScripts definicję.

Gdy jest używane istniejące konto magazynu, usługa skryptu tworzy udział plików o unikatowej nazwie. Zobacz Czyszczenie zasobów skryptu wdrażania, aby dowiedzieć się, jak usługa skryptu czyści udział plików.

Opracowywanie skryptów wdrażania

Obsługa błędów nieokreślonych

Możesz kontrolować, jak program PowerShell reaguje na błędy nieokreślone, używając zmiennej $ErrorActionPreference w skrypicie wdrożenia. Jeśli zmienna nie jest ustawiona w skrypsie wdrożenia, usługa skryptu używa wartości domyślnej Kontynuuj.

Usługa skryptu ustawia stan aprowizacji zasobu na Niepowodzenie, gdy skrypt napotka błąd pomimo ustawienia .$ErrorActionPreference

Używanie zmiennych środowiskowych

Skrypt wdrażania używa następujących zmiennych środowiskowych:

Zmienna środowiskowa Domyślna wartość Zarezerwowana przez system
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud N
AZ_SCRIPTS_CLEANUP_PREFERENCE OnExpiration N
AZ_SCRIPTS_OUTPUT_PATH <>AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY/<AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME> Y
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput Y
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput Y
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME Azure PowerShell: userscript.ps1; Interfejs wiersza polecenia platformy Azure: userscript.sh Y
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config Y
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config Y
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json Y
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json Y
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY /Subskrypcji/ N

Aby uzyskać więcej informacji na temat korzystania z programu AZ_SCRIPTS_OUTPUT_PATH, zobacz Praca z danymi wyjściowymi ze skryptu interfejsu wiersza polecenia.

Przekazywanie zabezpieczonych ciągów do skryptu wdrożenia

Ustawienie zmiennych środowiskowych (EnvironmentVariable) w wystąpieniach kontenera umożliwia zapewnienie dynamicznej konfiguracji aplikacji lub skryptu uruchamianego przez kontener. Skrypt wdrażania obsługuje niezabezpieczone i zabezpieczone zmienne środowiskowe w taki sam sposób jak wystąpienie kontenera platformy Azure. Aby uzyskać więcej informacji, zobacz Ustawianie zmiennych środowiskowych w wystąpieniach kontenera. Przykład można znaleźć w temacie Przykładowe szablony.

Maksymalny dozwolony rozmiar zmiennych środowiskowych to 64 KB.

Monitorowanie i rozwiązywanie problemów ze skryptami wdrażania

Usługa skryptu tworzy konto magazynu (chyba że określisz istniejące konto magazynu) i wystąpienie kontenera na potrzeby wykonywania skryptu. Jeśli te zasoby są tworzone automatycznie przez usługę skryptów, oba zasoby mają azscripts sufiks w nazwach zasobów.

Zrzut ekranu przedstawiający nazwy zasobów skryptu wdrażania szablonu usługi Resource Manager.

Skrypt użytkownika, wyniki wykonywania i plik stdout są przechowywane w udziałach plików konta magazynu. Istnieje folder o nazwie azscripts. W folderze znajdują się jeszcze dwa foldery dla plików wejściowych i wyjściowych: azscriptinput i azscriptoutput.

Folder wyjściowy zawiera executionresult.json i plik wyjściowy skryptu. W executionresult.json jest wyświetlany komunikat o błędzie wykonywania skryptu. Plik wyjściowy jest tworzony tylko wtedy, gdy skrypt zostanie wykonany pomyślnie. Folder input zawiera systemowy plik skryptu programu PowerShell i pliki skryptów wdrożenia użytkownika. Możesz zastąpić plik skryptu wdrożenia użytkownika poprawionym plikiem i ponownie uruchomić skrypt wdrożenia z wystąpienia kontenera platformy Azure.

Korzystanie z witryny Azure Portal

Po wdrożeniu zasobu skryptu wdrażania zasób jest wyświetlany w grupie zasobów w witrynie Azure Portal. Poniższy zrzut ekranu przedstawia stronę Przegląd zasobu skryptu wdrażania:

Zrzut ekranu przedstawiający przegląd portalu skryptu wdrażania szablonu usługi Resource Manager.

Na stronie przeglądu są wyświetlane ważne informacje o zasobie, takie jak stan aprowizacji, konto magazynu, wystąpienie kontenera i dzienniki.

W menu po lewej stronie możesz wyświetlić zawartość skryptu wdrożenia, argumenty przekazane do skryptu i dane wyjściowe. Można również wyeksportować szablon skryptu wdrożenia, w tym skrypt wdrożenia.

Użyj PowerShell

Za pomocą programu Azure PowerShell można zarządzać skryptami wdrażania w zakresie subskrypcji lub grupy zasobów:

Dane Get-AzDeploymentScript wyjściowe są podobne do następujących:

Name                : runPowerShellInlineWithOutput
Id                  : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0618rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput
ResourceGroupName   : myds0618rg
Location            : centralus
SubscriptionId      : 01234567-89AB-CDEF-0123-456789ABCDEF
ProvisioningState   : Succeeded
Identity            : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/mydentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 9.7
StartTime           : 5/11/2023 7:46:45 PM
EndTime             : 5/11/2023 7:49:45 PM
ExpirationDate      : 5/12/2023 7:49:45 PM
CleanupPreference   : OnSuccess
StorageAccountId    : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0618rg/providers/Microsoft.Storage/storageAccounts/ftnlvo6rlrvo2azscripts
ContainerInstanceId : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0618rg/providers/Microsoft.ContainerInstance/containerGroups/ftnlvo6rlrvo2azscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole

RetentionInterval   : P1D
Timeout             : PT1H

Interfejs wiersza polecenia platformy Azure

Za pomocą interfejsu wiersza polecenia platformy Azure można zarządzać skryptami wdrażania w zakresie subskrypcji lub grupy zasobów:

Dane wyjściowe polecenia listy są podobne do następujących:

[
  {
    "arguments": "'foo' 'bar'",
    "azCliVersion": "2.40.0",
    "cleanupPreference": "OnExpiration",
    "containerSettings": {
      "containerGroupName": null
    },
    "environmentVariables": null,
    "forceUpdateTag": "20231101T163748Z",
    "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runBashWithOutputs",
    "identity": {
      "tenantId": "01234567-89AB-CDEF-0123-456789ABCDEF",
      "type": "userAssigned",
      "userAssignedIdentities": {
        "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myidentity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
          "clientId": "01234567-89AB-CDEF-0123-456789ABCDEF",
          "principalId": "01234567-89AB-CDEF-0123-456789ABCDEF"
        }
      }
    },
    "kind": "AzureCLI",
    "location": "centralus",
    "name": "runBashWithOutputs",
    "outputs": {
      "Result": [
        {
          "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/mytest/providers/Microsoft.KeyVault/vaults/mykv1027",
          "resourceGroup": "mytest"
        }
      ]
    },
    "primaryScriptUri": null,
    "provisioningState": "Succeeded",
    "resourceGroup": "mytest",
    "retentionInterval": "1 day, 0:00:00",
    "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "status": {
      "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/mytest/providers/Microsoft.ContainerInstance/containerGroups/eg6n7wvuyxn7iazscripts",
      "endTime": "2023-11-01T16:39:12.080950+00:00",
      "error": null,
      "expirationTime": "2023-11-02T16:39:12.080950+00:00",
      "startTime": "2023-11-01T16:37:53.139700+00:00",
      "storageAccountId": null
    },
    "storageAccountSettings": {
      "storageAccountKey": null,
      "storageAccountName": "dsfruro267qwb4i"
    },
    "supportingScriptUris": null,
    "systemData": {
      "createdAt": "2023-10-31T19:06:57.060909+00:00",
      "createdBy": "someone@contoso.com",
      "createdByType": "User",
      "lastModifiedAt": "2023-11-01T16:37:51.859570+00:00",
      "lastModifiedBy": "someone@contoso.com",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "timeout": "0:30:00",
    "type": "Microsoft.Resources/deploymentScripts"
  }
]

Korzystanie z interfejsu API REST

Informacje o wdrożeniu zasobu skryptu wdrażania można uzyskać na poziomie grupy zasobów i na poziomie subskrypcji przy użyciu interfejsu API REST:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>?api-version=2020-10-01

/subscriptions/<SubscriptionID>/providers/microsoft.resources/deploymentScripts?api-version=2020-10-01

W poniższym przykładzie użyto elementu ARMClient:

armclient login
armclient get /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

Dane wyjściowe są podobne do następujących:

{
  "kind": "AzurePowerShell",
  "identity": {
    "type": "userAssigned",
    "tenantId": "01234567-89AB-CDEF-0123-456789ABCDEF",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myidentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
        "principalId": "01234567-89AB-CDEF-0123-456789ABCDEF",
        "clientId": "01234567-89AB-CDEF-0123-456789ABCDEF"
      }
    }
  },
  "location": "centralus",
  "systemData": {
    "createdBy": "someone@contoso.com",
    "createdByType": "User",
    "createdAt": "2023-05-11T02:59:04.7501955Z",
    "lastModifiedBy": "someone@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-05-11T02:59:04.7501955Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "forceUpdateTag": "20220625T025902Z",
    "azPowerShellVersion": "9.7",
    "scriptContent": "\r\n          param([string] $name)\r\n          $output = \"Hello {0}\" -f $name\r\n          Write-Output $output\r\n          $DeploymentScriptOutputs = @{}\r\n          $DeploymentScriptOutputs['text'] = $output\r\n        ",
    "arguments": "-name \\\"John Dole\\\"",
    "retentionInterval": "P1D",
    "timeout": "PT1H",
    "containerSettings": {},
    "status": {
      "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.ContainerInstance/containerGroups/64lxews2qfa5uazscripts",
      "storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.Storage/storageAccounts/64lxews2qfa5uazscripts",
      "startTime": "2023-05-11T02:59:07.5951401Z",
      "endTime": "2023-05-11T03:00:16.7969234Z",
      "expirationTime": "2023-05-12T03:00:16.7969234Z"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "runPowerShellInlineWithOutput"
}

Następujący interfejs API REST zwraca dziennik:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>/logs?api-version=2020-10-01

Działa tylko przed usunięciem zasobów skryptu wdrożenia.

Aby wyświetlić zasób deploymentScripts w portalu, wybierz pozycję Pokaż ukryte typy:

Zrzut ekranu przedstawiający skrypt wdrażania szablonu usługi Resource Manager z opcją wyświetlania ukrytych typów w portalu.

Czyszczenie zasobów skryptu wdrażania

Te dwa automatycznie utworzone zasoby pomocnicze nigdy nie przeżyją deploymentScript zasobu, chyba że wystąpią błędy, które je usuwają. Cykl życia zasobów pomocniczych jest kontrolowany przez cleanupPreference właściwość, cykl deploymentScript życia zasobu jest kontrolowany retentionInterval przez właściwość :

  • cleanupPreference: Określ preferencję czyszczenia dwóch zasobów pomocniczych, gdy wykonanie skryptu zostanie w stanie terminalu. Obsługiwane wartości to:

    • Zawsze: usuń dwa zasoby pomocnicze, gdy wykonanie skryptu zostanie w stanie terminalu. Jeśli jest używane istniejące konto magazynu, usługa skryptu usuwa udział plików utworzony przez usługę. deploymentScripts Ponieważ zasób może być nadal obecny po wyczyszczeniu zasobów pomocniczych, usługa skryptu utrwala wyniki wykonywania skryptu, na przykład stdout, outputs i zwraca wartość przed usunięciem zasobów.

    • OnSuccess: Usuń dwa zasoby pomocnicze tylko wtedy, gdy wykonanie skryptu zakończy się pomyślnie. Jeśli jest używane istniejące konto magazynu, usługa skryptu usuwa udział plików tylko wtedy, gdy wykonanie skryptu zakończy się pomyślnie.

      Jeśli wykonanie skryptu nie powiedzie się, usługa skryptu czeka na retentionInterval wygaśnięcie, zanim wyczyści zasoby pomocnicze, a następnie zasób skryptu wdrażania.

    • OnExpiration: Usuń dwa zasoby pomocnicze tylko wtedy, gdy retentionInterval ustawienie wygasło. Jeśli jest używane istniejące konto magazynu, usługa skryptu usuwa udział plików, ale zachowuje konto magazynu.

    Wystąpienie kontenera i konto magazynu są usuwane zgodnie z .cleanupPreference Jeśli jednak skrypt zakończy się niepowodzeniem i cleanupPreference nie zostanie ustawiony na Zawsze, proces wdrażania automatycznie przechowuje kontener uruchomiony przez jedną godzinę lub do momentu wyczyszczenia kontenera. Aby rozwiązać problemy ze skryptem, możesz użyć czasu. Jeśli chcesz zachować działanie kontenera po pomyślnych wdrożeniach, dodaj krok uśpienia do skryptu. Na przykład dodaj pozycję Start-Sleep na końcu skryptu. Jeśli nie dodasz kroku uśpienia, kontener zostanie ustawiony na stan terminalu i nie będzie można uzyskać do niego dostępu, nawet jeśli nie został jeszcze usunięty.

  • retentionInterval: określ interwał czasu, który zostanie zachowany przez deploymentScript zasób, a następnie wygaśnie i zostanie usunięty.

Uwaga

Nie zaleca się używania konta magazynu i wystąpienia kontenera, które są generowane przez usługę skryptu w innych celach. Te dwa zasoby można usunąć w zależności od cyklu życia skryptu.

Nie można usunąć automatycznie utworzonego konta magazynu i wystąpienia kontenera, jeśli skrypt wdrożenia został wdrożony w grupie zasobów z blokadą CanNotDelete. Aby rozwiązać ten problem, możesz wdrożyć skrypt wdrażania w innej grupie zasobów bez blokad. Zobacz Przykładowe 4 i Przykład 5 w przykładowych szablonach.

Uruchamianie skryptu więcej niż raz

Wykonanie skryptu wdrażania jest operacją idempotentną. Jeśli żadna z deploymentScripts właściwości zasobu (w tym skrypt wbudowany) nie zostanie zmieniona, skrypt nie zostanie wykonany podczas ponownego wdrażania szablonu. Usługa skryptu wdrażania porównuje nazwy zasobów w szablonie z istniejącymi zasobami w tej samej grupie zasobów. Istnieją dwie opcje wielokrotnego wykonywania tego samego skryptu wdrażania:

  • Zmień nazwę deploymentScripts zasobu. Na przykład użyj funkcji szablonu utcNow jako nazwy zasobu lub jako części nazwy zasobu. Zmiana nazwy zasobu powoduje utworzenie nowego deploymentScripts zasobu. Dobrze jest zachować historię wykonywania skryptu.

    Uwaga

    Funkcja utcNow może być używana tylko w wartości domyślnej parametru.

  • Określ inną wartość we właściwości szablonu forceUpdateTag . Na przykład użyj utcNow wartości jako wartości.

Uwaga

Napisz skrypty wdrażania, które są idempotentne. Gwarantuje to, że jeśli zostaną uruchomione ponownie przypadkowo, nie spowoduje to zmian systemu. Jeśli na przykład skrypt wdrażania jest używany do tworzenia zasobu platformy Azure, sprawdź, czy zasób nie istnieje przed jego utworzeniem, więc skrypt zakończy się powodzeniem lub nie utworzysz zasobu ponownie.

Konfigurowanie środowiska programowania

Możesz użyć wstępnie skonfigurowanego obrazu kontenera jako środowiska deweloperskiego skryptu wdrażania. Aby uzyskać więcej informacji, zobacz Konfigurowanie środowiska deweloperskiego dla skryptów wdrażania w szablonach.

Po pomyślnym przetestowaniu skryptu możesz użyć go jako skryptu wdrażania w szablonach.

Kody błędów skryptu wdrażania

Kod błędu opis
DeploymentScriptInvalidOperation Definicja zasobu skryptu wdrożenia w szablonie zawiera nieprawidłowe nazwy właściwości.
DeploymentScriptResourceConflict Nie można usunąć zasobu skryptu wdrożenia, który jest w stanie nieokreślonym, a wykonanie nie przekroczyło 1 godziny. Lub nie można ponownie uruchomić tego samego skryptu wdrożenia o tym samym identyfikatorze zasobu (tej samej subskrypcji, nazwie grupy zasobów i nazwie zasobu), ale w tym samym czasie innej zawartości treści skryptu.
DeploymentScriptOperationFailed Operacja skryptu wdrażania nie powiodła się wewnętrznie. Skontaktuj się z pomocą techniczną firmy Microsoft.
DeploymentScriptStorageAccountAccessKeyNotSpecified Klucz dostępu nie został określony dla istniejącego konta magazynu.
DeploymentScriptContainerGroupContainsInvalidContainers Grupa kontenerów utworzona przez usługę skryptu wdrożenia została zmodyfikowana zewnętrznie i dodano nieprawidłowe kontenery.
DeploymentScriptContainerGroupInNonterminalState Co najmniej dwa zasoby skryptu wdrożenia używają tej samej nazwy wystąpienia kontenera platformy Azure w tej samej grupie zasobów, a jedna z nich jeszcze nie zakończyła wykonywania.
DeploymentScriptStorageAccountInvalidKind Istniejące konto magazynu typu BlobBlobStorage lub BlobStorage nie obsługuje udziałów plików i nie można ich używać.
DeploymentScriptStorageAccountInvalidKindAndSku Istniejące konto magazynu nie obsługuje udziałów plików. Aby uzyskać listę obsługiwanych rodzajów kont magazynu, zobacz Używanie istniejącego konta magazynu.
DeploymentScriptStorageAccountNotFound Konto magazynu nie istnieje lub zostało usunięte przez zewnętrzny proces lub narzędzie.
DeploymentScriptStorageAccountWithServiceEndpointEnabled Określone konto magazynu ma punkt końcowy usługi. Konto magazynu z punktem końcowym usługi nie jest obsługiwane.
DeploymentScriptStorageAccountInvalidAccessKey Nieprawidłowy klucz dostępu określony dla istniejącego konta magazynu.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Nieprawidłowy format klucza konta magazynu. Zobacz Zarządzanie kluczami dostępu do konta magazynu.
DeploymentScriptExceededMaxAllowedTime Czas wykonywania skryptu wdrożenia przekroczył wartość limitu czasu określoną w definicji zasobu skryptu wdrożenia.
DeploymentScriptInvalidOutputs Dane wyjściowe skryptu wdrażania nie są prawidłowym obiektem JSON.
DeploymentScriptContainerInstancesServiceLoginFailure Tożsamość zarządzana przypisana przez użytkownika nie mogła się zalogować po 10 próbach z 1-minutowym interwałem.
DeploymentScriptContainerGroupNotFound Grupa kontenerów utworzona przez usługę skryptu wdrażania została usunięta przez zewnętrzne narzędzie lub proces.
DeploymentScriptDownloadFailure Nie można pobrać skryptu pomocniczego. Zobacz Używanie skryptu pomocniczego.
DeploymentScriptError Skrypt użytkownika zgłosił błąd.
DeploymentScriptBootstrapScriptExecutionFailed Skrypt uruchamiania rzucił błąd. Skrypt bootstrap to skrypt systemowy, który organizuje wykonywanie skryptu wdrażania.
DeploymentScriptExecutionFailed Nieznany błąd podczas wykonywania skryptu wdrażania.
DeploymentScriptContainerInstancesServiceUnavailable Podczas tworzenia wystąpienia kontenera platformy Azure (ACI) usługa ACI zwróciła błąd niedostępności usługi.
DeploymentScriptContainerGroupInNonterminalState Podczas tworzenia wystąpienia kontenera platformy Azure (ACI) inny skrypt wdrażania używa tej samej nazwy ACI w tym samym zakresie (tej samej subskrypcji, nazwy grupy zasobów i nazwy zasobu).
DeploymentScriptContainerGroupNameInvalid Określona nazwa wystąpienia kontenera platformy Azure (ACI) nie spełnia wymagań usługi ACI. Zobacz Rozwiązywanie typowych problemów w usłudze Azure Container Instances.

Używanie programu Microsoft Graph w skrycie wdrażania

Skrypt wdrażania może używać programu Microsoft Graph do tworzenia obiektów i pracy z obiektami w identyfikatorze Entra firmy Microsoft.

Polecenia

Korzystając ze skryptów wdrażania interfejsu wiersza polecenia platformy Azure, możesz użyć poleceń w az ad grupie poleceń do pracy z aplikacjami, jednostkami usługi, grupami i użytkownikami. Interfejsy API programu Microsoft Graph można również wywoływać bezpośrednio za pomocą az rest polecenia .

Jeśli używasz skryptów wdrażania programu Azure PowerShell, możesz użyć Invoke-RestMethod polecenia cmdlet , aby bezpośrednio wywołać interfejsy API programu Microsoft Graph.

Uprawnienia

Tożsamość używana przez skrypt wdrażania musi być autoryzowana do pracy z interfejsem API programu Microsoft Graph z odpowiednimi uprawnieniami do wykonywanych operacji. Musisz autoryzować tożsamość poza wdrożeniem szablonu, na przykład przez wstępnie utworzenie tożsamości zarządzanej przypisanej przez użytkownika i przypisanie jej roli aplikacji dla programu Microsoft Graph. Aby uzyskać więcej informacji, zobacz ten przykład z przewodnika Szybki start.

Uzyskiwanie dostępu do prywatnej sieci wirtualnej

W przypadku biblioteki Microsoft.Resources/deploymentScripts w wersji 2023-08-01 można uruchamiać skrypty wdrażania w sieciach prywatnych z dodatkowymi konfiguracjami.

  • Utwórz tożsamość zarządzaną przypisaną przez użytkownika i określ ją we identity właściwości . Aby przypisać tożsamość, zobacz Tożsamość.

  • Utwórz konto magazynu z allowSharedKeyAccess ustawioną wartością true i określ skrypt wdrożenia, aby użyć istniejącego konta magazynu. Aby określić istniejące konto magazynu, zobacz Używanie istniejącego konta magazynu. Niektóre dodatkowe konfiguracje są wymagane dla konta magazynu.

    1. Otwórz konto magazynu w witrynie Azure Portal.

    2. W menu po lewej stronie wybierz pozycję Kontrola dostępu (zarządzanie dostępem i tożsamościami), a następnie wybierz kartę Przypisania ról.

    3. Storage File Data Privileged Contributor Dodaj rolę do tożsamości zarządzanej przypisania użytkownika.

    4. W menu po lewej stronie w obszarze Zabezpieczenia i sieć wybierz pozycję Sieć, a następnie wybierz pozycję Zapory i sieci wirtualne.

    5. Wybierz pozycję Włączone z wybranych sieci wirtualnych i adresów IP.

      Zrzut ekranu przedstawiający konfigurowanie konta magazynu na potrzeby uzyskiwania dostępu do sieci prywatnej.

    6. W obszarze Sieci wirtualne dodaj podsieć. Na zrzucie ekranu podsieć nosi nazwę dspvnVnet.

    7. W obszarze Wyjątki wybierz pozycję Zezwalaj usługom platformy Azure na liście zaufanych usług, aby uzyskać dostęp do tego konta magazynu.

Poniższy szablon usługi ARM pokazuje, jak skonfigurować środowisko do uruchamiania skryptu wdrażania:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "maxLength": 10
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "userAssignedIdentityName": {
      "type": "string",
      "defaultValue": "[format('{0}Identity', parameters('prefix'))]"
    },
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('{0}stg{1}', parameters('prefix'), uniqueString(resourceGroup().id))]"
    },
    "vnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Vnet', parameters('prefix'))]"
    },
    "subnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Subnet', parameters('prefix'))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2023-09-01",
      "name": "[parameters('vnetName')]",
      "location": "[parameters('location')]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "10.0.0.0/16"
          ]
        },
        "enableDdosProtection": false,
        "subnets": [
          {
            "name": "[parameters('subnetName')]",
            "properties": {
              "addressPrefix": "10.0.0.0/24",
              "serviceEndpoints": [
                {
                  "service": "Microsoft.Storage"
                }
              ],
              "delegations": [
                {
                  "name": "Microsoft.ContainerInstance.containerGroups",
                  "properties": {
                    "serviceName": "Microsoft.ContainerInstance/containerGroups"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-01-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "networkAcls": {
          "bypass": "AzureServices",
          "virtualNetworkRules": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]",
              "action": "Allow",
              "state": "Succeeded"
            }
          ],
          "defaultAction": "Deny"
        },
        "allowSharedKeyAccess": true
      },
      "dependsOn": [
        "[resourceId('Microsoft.Network/virtualNetworks', parameters('vnetName'))]"
      ]
    },
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "apiVersion": "2023-07-31-preview",
      "name": "[parameters('userAssignedIdentityName')]",
      "location": "[parameters('location')]"
    },
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "scope": "[format('Microsoft.Storage/storageAccounts/{0}', parameters('storageAccountName'))]",
      "name": "[guid(tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd'), resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName')))]",
      "properties": {
        "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2023-07-31-preview').principalId]",
        "roleDefinitionId": "[tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd')]",
        "principalType": "ServicePrincipal"
      },
      "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
      ]
    }
  ]
}

Do przetestowania wdrożenia można użyć następującego szablonu usługi ARM:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    },
    "storageAccountName": {
      "type": "string"
    },
    "vnetName": {
      "type": "string"
    },
    "subnetName": {
      "type": "string"
    },
    "userAssignedIdentityName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2023-08-01",
      "name": "[format('{0}DS', parameters('prefix'))]",
      "location": "[parameters('location')]",
      "identity": {
        "type": "userAssigned",
        "userAssignedIdentities": {
          "[format('{0}', resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')))]": {}
        }
      },
      "kind": "AzureCLI",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azCliVersion": "2.47.0",
        "storageAccountSettings": {
          "storageAccountName": "[parameters('storageAccountName')]"
        },
        "containerSettings": {
          "subnetIds": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]"
            }
          ]
        },
        "scriptContent": "echo \"Hello world!\"",
        "retentionInterval": "P1D",
        "cleanupPreference": "OnExpiration"
      }
    }
  ]
}

Następne kroki

W tym artykule przedstawiono sposób używania skryptów wdrażania. Aby zapoznać się z samouczkiem dotyczącym skryptu wdrażania:

Samouczek: używanie skryptów wdrażania w szablonach usługi Azure Resource Manager

Moduł szkoleniowy: rozszerzanie szablonów usługi ARM przy użyciu skryptów wdrażania