Använda distributionsskript i Azure Resource Manager-mallar

Lär dig hur du använder distributionsskript i ARM-mallar (Azure Resource Manager). Med resursen deploymentScripts kan användare köra skript i ARM-distributioner och granska körningsresultat.

Dessa skript kan användas för att utföra anpassade steg, till exempel:

• Lägg till användare i en katalog.
• Utför dataplansåtgärder, till exempel kopiera blobar eller startdatabaser.
• Leta upp och verifiera en licensnyckel.
• Skapa ett självsignerat certifikat.
• Skapa ett objekt i Microsoft Entra-ID.
• Leta upp IP-adressblock från ett anpassat system.

Fördelarna med distributionsskriptet:

• Du kan utveckla distributionsskript i dina favoritmiljöer för utveckling. Skripten kan bäddas in i mallar eller i externa skriptfiler.
• Du kan ange skriptspråk och plattform. För närvarande stöds Azure PowerShell- och Azure CLI-distributionsskript i Linux-miljön.
• Tillåt att kommandoradsargument skickas till skriptet.
• Kan ange skriptutdata och skicka tillbaka dem till distributionen.

Distributionsskriptresursen är endast tillgänglig i de regioner där Azure Container Instance är tillgängligt. Se Resurstillgänglighet för Azure Container Instances i Azure-regioner. Distributionsskriptet använder för närvarande endast offentliga nätverk.

Utbildningsresurser

Om du hellre vill lära dig mer om distributionsskript via stegvis vägledning kan du läsa Utöka ARM-mallar med hjälp av distributionsskript.

Konfigurera de minsta behörigheterna

För distributionsskriptet API version 2020-10-01 eller senare finns det två huvudnamn som ingår i körningen av distributionsskriptet:

• Distributionshuvudnamn (det huvudnamn som används för att distribuera mallen): Det här huvudkontot används för att skapa underliggande resurser som krävs för att distributionsskriptresursen ska köras – ett lagringskonto och en Azure-containerinstans. Om du vill konfigurera behörigheter med minst behörighet tilldelar du en anpassad roll med följande egenskaper till distributionsobjektet:

  {
    "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/*"
        ],
       "dataActions": [
          "Microsoft.Storage/storageAccounts/fileServices/*"
        ]
      }
    ],
    "assignableScopes": [
      "[subscription().id]"
    ]
  }
  

  Om Resursprovidrar för Azure Storage och Azure Container Instance inte har registrerats måste du också lägga Microsoft.Storage/register/action till och Microsoft.ContainerInstance/register/action.

• Huvudnamn för distributionsskript: Det här huvudnamnet krävs bara om distributionsskriptet behöver autentiseras till Azure och anropa Azure CLI eller Azure PowerShell. Det finns två sätt att ange distributionsskriptets huvudnamn:

  • Ange en användartilldelad hanterad identitet i identity egenskapen (se Exempelmallar). När det anges anropar Connect-AzAccount -Identity skripttjänsten innan distributionsskriptet anropas. Den hanterade identiteten måste ha den åtkomst som krävs för att slutföra åtgärden i skriptet. För närvarande stöds endast användartilldelad hanterad identitet för egenskapen identity . Om du vill logga in med en annan identitet använder du den andra metoden i den här listan.
  • Skicka autentiseringsuppgifterna för tjänstens huvudnamn som säkra miljövariabler och anropa sedan Connect-AzAccount eller az login i distributionsskriptet.

  Om en hanterad identitet används behöver distributionsobjektet rollen Hanterad identitetsoperator (en inbyggd roll) som tilldelats den hanterade identitetsresursen.

Exempelmallar

Följande JSON är ett exempel. Mer information finns i det senaste mallschemat.

{
  "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/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {}
    }
  },
  "properties": {
    "forceUpdateTag": "1",
    "containerSettings": {
      "containerGroupName": "mycustomaci"
    },
    "storageAccountSettings": {
      "storageAccountName": "myStorageAccount",
      "storageAccountKey": "myKey"
    },
    "azPowerShellVersion": "14.0",  // 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"
  }
}

Information om egenskapsvärde:

• identity: För distributionsskriptet API version 2020-10-01 eller senare är en användartilldelad hanterad identitet valfri om du inte behöver utföra några Azure-specifika åtgärder i skriptet. För API-versionen 2019-10-01-preview krävs en hanterad identitet eftersom distributionsskripttjänsten använder den för att köra skripten. När identitetsegenskapen har angetts anropar Connect-AzAccount -Identity skripttjänsten innan användarskriptet anropas. För närvarande stöds endast användartilldelad hanterad identitet. Om du vill logga in med en annan identitet kan du anropa Connect-AzAccount i skriptet.

• tags: Taggar för distributionsskript. Om distributionsskripttjänsten genererar ett lagringskonto och en containerinstans skickas taggarna till båda resurserna, som kan användas för att identifiera dem. Ett annat sätt att identifiera dessa resurser är genom deras suffix, som innehåller "azscripts". Mer information finns i Övervaka och felsöka distributionsskript.

• kind: Ange typ av skript. För närvarande stöds Azure PowerShell- och Azure CLI-skript. Värdena är AzurePowerShell och AzureCLI.

• forceUpdateTag: Om du ändrar det här värdet mellan malldistributioner tvingar du distributionsskriptet att köras igen. Om du använder newGuid() funktionerna eller utcNow() kan båda funktionerna endast användas i standardvärdet för en parameter. Mer information finns i Kör skript mer än en gång.

• containerSettings: Ange inställningarna för att anpassa Azure Container Instance. Distributionsskriptet kräver en ny Azure Container Instance. Du kan inte ange en befintlig Azure Container Instance. Du kan dock anpassa namnet på containergruppen med hjälp containerGroupNameav . Om det inte anges genereras gruppnamnet automatiskt.

• storageAccountSettings: Ange inställningarna för att använda ett befintligt lagringskonto. Om storageAccountName inte anges skapas ett lagringskonto automatiskt. Se Använda ett befintligt lagringskonto.

• azPowerShellVersion / azCliVersion: Ange den modulversion som ska användas. Se en lista över Azure PowerShell-versioner som stöds. Versionen avgör vilken containeravbildning som ska användas:

  • Az-versionen större än eller lika med 9 använder Ubuntu 22.04.
  • Az-versionen är större än eller lika med 6 men mindre än 9 använder Ubuntu 20.04.
  • Az-version mindre än 6 använder Ubuntu 18.04.

  Viktigt!

  Det är lämpligt att uppgradera till den senaste versionen av Ubuntu, eftersom Ubuntu 18.04 närmar sig sin livslängd och inte längre får säkerhetsuppdateringar efter den 31 maj 2023.

  Se en lista över Azure CLI-versioner som stöds.

  Viktigt!

  Distributionsskriptet använder tillgängliga CLI-avbildningar från Microsoft Container Registry (MCR). Det tar vanligtvis ungefär en månad att certifiera en CLI-avbildning för distributionsskript. Använd inte DE CLI-versioner som släpptes inom 30 dagar. Information om hur du hittar versionsdatum för avbildningarna finns i versionsinformationen för Azure CLI. Om en version som inte stöds används visas de versioner som stöds i felmeddelandet.

• arguments: Ange parametervärdena. Värdena avgränsas med mellanslag.

  Distributionsskript delar upp argumenten i en matris med strängar genom att anropa systemanropet CommandLineToArgvW . Det här steget är nödvändigt eftersom argumenten skickas som en kommandoegenskap till Azure Container Instance och kommandoegenskapen är en strängmatris.

  Om argumenten innehåller undantagna tecken använder du JsonEscaper för att dubbla undantagna tecken. Klistra in den ursprungliga escape-strängen i verktyget och välj sedan Escape. Verktyget matar ut en dubbel escapead sträng. I den tidigare exempelmallen är -name \"John Dole\"argumentet till exempel . Den undantagna strängen är -name \\\"John Dole\\\".

  Om du vill skicka en ARM-mallparameter av typen objekt som ett argument konverterar du objektet till en sträng med hjälp av funktionen string() och använder sedan funktionen replace() för att ersätta alla \" till \\\". Till exempel:

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

  Mer information finns i exempelmallen.

• environmentVariables: Ange de miljövariabler som ska skickas till skriptet. Mer information finns i Utveckla distributionsskript.

• scriptContent: Ange skriptinnehållet. Om du vill köra ett externt skript använder du primaryScriptUri i stället. Exempel finns i Använda infogat skript och Använd externt skript.

• primaryScriptUri: Ange en offentligt tillgänglig URL till det primära distributionsskriptet med filtillägg som stöds. Mer information finns i Använda externa skript.

• supportingScriptUris: Ange en matris med offentligt tillgängliga URL:er för stödfiler som anropas i antingen scriptContent eller primaryScriptUri. Mer information finns i Använda externa skript.

• timeout: Ange den maximala tillåtna körningstiden för skriptet angivet i formatet ISO 8601. Standardvärdet är P1D.

• cleanupPreference. Ange inställningen för att rensa de två stöddistributionsresurserna, lagringskontot och containerinstansen, när skriptkörningen hamnar i ett terminaltillstånd. Standardinställningen är Always, vilket innebär att stödresurserna tas bort trots sluttillståndet (Lyckades, Misslyckades, Avbröts). Mer information finns i Rensa distributionsskriptresurser.

• retentionInterval: Ange det intervall för vilket tjänsten behåller distributionsskriptresursen när körningen av distributionsskriptet når ett terminaltillstånd. Distributionsskriptresursen tas bort när den här varaktigheten upphör att gälla. Varaktigheten baseras på ISO 8601-mönstret. Kvarhållningsintervallet är mellan 1 och 26 timmar (PT26H). Den här egenskapen används när cleanupPreference är inställd på OnExpiration. Mer information finns i Rensa distributionsskriptresurser.

Fler exempel

• Exempel 1: Skapa ett nyckelvalv och använd distributionsskriptet för att tilldela ett certifikat till nyckelvalvet.
• Exempel 2: Skapa en resursgrupp på prenumerationsnivå, skapa ett nyckelvalv i resursgruppen och använd sedan distributionsskriptet för att tilldela ett certifikat till nyckelvalvet.
• Exempel 3: Skapa en användartilldelad hanterad identitet, tilldela deltagarrollen till identiteten på resursgruppsnivå, skapa ett nyckelvalv och använd sedan distributionsskriptet för att tilldela ett certifikat till nyckelvalvet.
• Exempel 4: Det är samma scenario som exempel 1 i den här listan. En ny resursgrupp skapas för att köra distributionsskriptet. Den här mallen är en mall på prenumerationsnivå.
• Exempel 5: Det är samma scenario som exempel 4. Den här mallen är en mall på resursgruppsnivå.
• Exempel 6: Skapa en användartilldelad hanterad identitet manuellt och tilldela den behörighet att använda Microsoft Graph API för att skapa Microsoft Entra-program. I ARM-mallen använder du ett distributionsskript för att skapa ett Microsoft Entra-program och tjänstens huvudnamn och matar ut objekt-ID:t och klient-ID:t.

Använda infogade skript

Följande mall har en resurs som definierats med Microsoft.Resources/deploymentScripts typen:

{
  "$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"
    }
  }
}

Skriptet tar en parameter och matar ut parametervärdet. DeploymentScriptOutputs används för att lagra utdata. I avsnittet value utdata visar raden hur du kommer åt de lagrade värdena. Write-Output används för felsökning. Information om hur du kommer åt utdatafilen finns i Övervaka och felsöka distributionsskript. Egenskapsbeskrivningar finns i Exempelmallar.

Om du vill köra skriptet väljer du Prova för att öppna Cloud Shell och klistrar sedan in följande kod i gränssnittsfönstret:

$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 ..."

Utdata ser ut så här:

Använda externa skript

Förutom infogade skript kan du även använda externa skriptfiler. Endast primära PowerShell-skript med filtillägget ps1 stöds. För CLI-skript kan de primära skripten ha alla tillägg (eller utan tillägg) så länge skripten är giltiga bash-skript. Om du vill använda externa skriptfiler ersätter du scriptContent med primaryScriptUri. Till exempel:

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

Mer information finns i exempelmallen.

De externa skriptfilerna måste vara tillgängliga. Om du vill skydda dina skriptfiler som lagras i Azure Storage-konton genererar du en SAS-token och tar med den i URI:n för mallen. Ange förfallotiden för att ge tillräckligt med tid för att slutföra distributionen. Mer information finns i Distribuera en privat ARM-mall med SAS-token.

Du ansvarar för att säkerställa integriteten för skripten som refereras till av distributionsskriptet, antingen primaryScriptUri eller supportingScriptUris. Referera endast till skript som du litar på.

Använda stödskript

Du kan dela in komplicerade logik i en eller flera stödskriptfiler. Med supportingScriptUris egenskapen kan du ange en matris med URI:er till stödskriptfilerna om det behövs:

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

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

Stödskriptfiler kan anropas från både infogade skript och primära skriptfiler. Stöd för skriptfiler har inga begränsningar för filtillägget.

Stödfilerna kopieras till azscripts/azscriptinput under körning. Använd relativ sökväg för att referera till stödfilerna från infogade skript och primära skriptfiler.

Arbeta med utdata från PowerShell-skript

Följande mall visar hur du skickar värden mellan två deploymentScripts resurser:

{
  "$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"
    }
  }
}

I den första resursen definierar du en variabel med namnet $DeploymentScriptOutputsoch använder den för att lagra utdatavärdena. Om du vill komma åt utdatavärdet från en annan resurs i mallen använder du:

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

Arbeta med utdata från CLI-skript

Till skillnad från Azure PowerShell-distributionsskripten exponerar CLI/bash inte någon vanlig variabel för lagring av skriptutdata. I stället använder den en miljövariabel med namnet AZ_SCRIPTS_OUTPUT_PATH för att ange platsen för skriptets utdatafil. När du kör ett distributionsskript i en ARM-mall konfigurerar Bash-gränssnittet automatiskt den här miljövariabeln åt dig. Dess fördefinierade värde anges som /mnt/azscripts/azscriptoutput/scriptoutputs.json. Utdata krävs för att överensstämma med en giltig JSON-strängobjektstruktur. Filens innehåll ska formateras som ett nyckel/värde-par. Till exempel ska en matris med strängar sparas som { "MyResult": [ "foo", "bar"] }. Lagring av endast matrisresultat, till exempel [ "foo", "bar" ], anses vara ogiltigt.

{
  "$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"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('runBashWithOutputs').outputs]",
      "type": "object"
    }
  }
}

jq används i föregående exempel. Den levereras med containeravbildningarna. Se Konfigurera utvecklingsmiljö.

Använda ett befintligt lagringskonto

Ett lagringskonto och en containerinstans behövs för skriptkörning och felsökning. Du har alternativ för att ange ett befintligt lagringskonto, annars skapas lagringskontot tillsammans med containerinstansen automatiskt av skripttjänsten. Kraven för att använda ett befintligt lagringskonto:

• Lagringskontotyper som stöds är:

  Artikelnummer	Typ som stöds
  Premium_LRS	Filförvaring
  Premium_ZRS	Filförvaring
  Standard_GRS	Lagring, StorageV2
  Standard_GZRS	StorageV2
  Standard_LRS	Lagring, StorageV2
  Standard_RAGRS	Lagring, StorageV2
  Standard_RAGZRS	StorageV2
  Standard_ZRS	StorageV2

  Dessa kombinationer stöder fildelningar. Mer information finns i Skapa en Azure-filresurs och typer av lagringskonton.

• Brandväggsregler för lagringskonto stöds inte än. Mer information finns i Konfigurera Azure Storage-brandväggar och virtuella nätverk.

• Distributionsansvarig måste ha behörighet att hantera lagringskontot, vilket omfattar läsning, skapande och borttagning av fildelningar.

• Egenskapen allowSharedKeyAccess för lagringskontot måste vara inställd på true. Det enda sättet att montera ett lagringskonto i Azure Container Instance (ACI) är via en åtkomstnyckel.

Om du vill ange ett befintligt lagringskonto lägger du till följande JSON i egenskapselementet Microsoft.Resources/deploymentScriptsi :

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

• storageAccountName: ange namnet på lagringskontot.

• storageAccountKey: ange en av lagringskontonycklarna. Du kan använda funktionen listKeys() för att hämta nyckeln. Till exempel:

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

Se Exempelmallar för ett fullständigt Microsoft.Resources/deploymentScripts definitionsexempel.

När ett befintligt lagringskonto används skapar skripttjänsten en filresurs med ett unikt namn. Se Rensa distributionsskriptresurser för hur skripttjänsten rensar filresursen.

Utveckla distributionsskript

Hantera icke-avslutande fel

Du kan styra hur PowerShell svarar på icke-utrotande fel med hjälp av variabeln $ErrorActionPreference i distributionsskriptet. Om variabeln inte anges i distributionsskriptet använder skripttjänsten standardvärdet Fortsätt.

Skripttjänsten anger resursetableringstillståndet till Misslyckades när skriptet påträffar ett fel trots inställningen $ErrorActionPreference.

Använda miljövariabler

Distributionsskriptet använder följande miljövariabler:

Mer information om hur du använder AZ_SCRIPTS_OUTPUT_PATHfinns i Arbeta med utdata från CLI-skript.

Skicka skyddade strängar till distributionsskriptet

Om du anger miljövariabler (EnvironmentVariable) i containerinstanserna kan du ange dynamisk konfiguration av programmet eller skriptet som körs av containern. Distributionsskriptet hanterar icke-skyddade miljövariabler på samma sätt som Azure Container Instance. Mer information finns i Ange miljövariabler i containerinstanser. Ett exempel finns i Exempelmallar.

Den maximala tillåtna storleken för miljövariabler är 64 KB.

Övervaka och felsöka distributionsskript

Skripttjänsten skapar ett lagringskonto (om du inte anger ett befintligt lagringskonto) och en containerinstans för skriptkörning. Om dessa resurser skapas automatiskt av skripttjänsten har båda resurserna suffixet azscripts i resursnamnen.

Användarskriptet, körningsresultatet och stdout-filen lagras i lagringskontots filresurser. Det finns en mapp med namnet azscripts. I mappen finns det ytterligare två mappar för indata- och utdatafilerna: azscriptinput och azscriptoutput.

Utdatamappen innehåller en executionresult.json och skriptets utdatafil. Du kan se felmeddelandet för skriptkörning i executionresult.json. Utdatafilen skapas bara när skriptet körs. Indatamappen innehåller en PowerShell-systemskriptfil och skriptfilerna för användardistribution. Du kan ersätta skriptfilen för användardistribution med en reviderad och köra distributionsskriptet igen från Azure-containerinstansen.

Använda Azure Portal

När du har distribuerat en distributionsskriptresurs visas resursen under resursgruppen i Azure Portal. Följande skärmbild visar sidan Översikt för en resurs med distributionsskript:

Översiktssidan visar viktig information om resursen, till exempel etableringstillstånd, lagringskonto, containerinstans och loggar.

På den vänstra menyn kan du visa innehållet i distributionsskriptet, argumenten som skickas till skriptet och utdata. Du kan också exportera en mall för distributionsskriptet, inklusive distributionsskriptet.

Använda PowerShell

Med Azure PowerShell kan du hantera distributionsskript i prenumerations- eller resursgruppsomfång:

• Get-AzDeploymentScript: Hämtar eller listar distributionsskript.
• Get-AzDeploymentScriptLog: Hämtar loggen för en distributionsskriptkörning.
• Remove-AzDeploymentScript: Tar bort ett distributionsskript och dess associerade resurser.
• Save-AzDeploymentScriptLog: Sparar loggen för en distributionsskriptkörning till disk.

Utdata Get-AzDeploymentScript ser ut som:

Name                : runPowerShellInlineWithOutput
Id                  : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput
ResourceGroupName   : myds0618rg
Location            : centralus
SubscriptionId      : aaaabbbb-0000-cccc-1111-dddd2222eeee
ProvisioningState   : Succeeded
Identity            : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mydentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 14.0
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/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Storage/storageAccounts/ftnlvo6rlrvo2azscripts
ContainerInstanceId : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.ContainerInstance/containerGroups/ftnlvo6rlrvo2azscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole

RetentionInterval   : P1D
Timeout             : PT1H

Använda Azure CLI

Med Azure CLI kan du hantera distributionsskript i prenumerations- eller resursgruppsomfång:

• az deployment-scripts delete: Ta bort ett distributionsskript.
• az deployment-scripts list: Lista alla distributionsskript.
• az deployment-scripts show: Hämta ett distributionsskript.
• az deployment-scripts show-log: Visa distributionsskriptloggar.

Utdata från listkommandot liknar:

[
  {
    "arguments": "'foo' 'bar'",
    "azCliVersion": "2.40.0",
    "cleanupPreference": "OnExpiration",
    "containerSettings": {
      "containerGroupName": null
    },
    "environmentVariables": null,
    "forceUpdateTag": "20231101T163748Z",
    "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runBashWithOutputs",
    "identity": {
      "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
      "type": "userAssigned",
      "userAssignedIdentities": {
        "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myidentity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
          "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
        }
      }
    },
    "kind": "AzureCLI",
    "location": "centralus",
    "name": "runBashWithOutputs",
    "outputs": {
      "Result": [
        {
          "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/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/aaaabbbb-0000-cccc-1111-dddd2222eeee/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"
  }
]

Använda REST-API

Du kan hämta distributionsskriptets resursdistributionsinformation på resursgruppsnivå och prenumerationsnivå med hjälp av REST API:

/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

I följande exempel används ARMClient:

armclient login
armclient get /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

Resultatet liknar följande:

{
  "kind": "AzurePowerShell",
  "identity": {
    "type": "userAssigned",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myidentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
        "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
      }
    }
  },
  "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": "14.0",
    "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/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.ContainerInstance/containerGroups/64lxews2qfa5uazscripts",
      "storageAccountId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/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/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "runPowerShellInlineWithOutput"
}

Följande REST API returnerar loggen:

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

Det fungerar bara innan resurserna för distributionsskriptet tas bort.

Om du vill se deploymentScripts-resursen i portalen väljer du Visa dolda typer:

Rensa distributionsskriptresurser

De två automatiskt skapade stödresurserna kan aldrig överleva resursen deploymentScript , såvida det inte uppstår fel när de tas bort. Livscykeln för de stödande resurserna styrs av cleanupPreference egenskapen. Resursens deploymentScript livscykel styrs av egenskapen retentionInterval :

• cleanupPreference: Ange rensningsinställningen för de två stödresurserna när skriptkörningen hamnar i ett terminaltillstånd. De värden som stöds är:

  • Alltid: Ta bort de två stödresurserna när skriptkörningen har ett terminaltillstånd. Om ett befintligt lagringskonto används, tar skripttjänsten bort fildelningen som har skapats av tjänsten. Eftersom resursen deploymentScripts fortfarande kan finnas kvar när de stödjande resurserna har rensats, bevarar skripttjänsten resultatet av skriptkörningen, till exempel stdout, utdata och returvärde innan resurserna tas bort.

  • OnSuccess: Ta bara bort de två stödresurserna när skriptkörningen lyckas. Om ett befintligt lagringskonto används tar skripttjänsten bara bort filresursen när skriptkörningen lyckas.

    Om skriptkörningen inte lyckas väntar skripttjänsten tills den retentionInterval upphör att gälla innan den rensar de resurser som stöds och sedan resursen för distributionsskriptet.

  • OnExpiration: Ta bara bort de två stödresurserna när inställningen retentionInterval har upphört att gälla. Om ett befintligt lagringskonto används tar skripttjänsten bort filresursen, men behåller lagringskontot.

  Containerinstansen och lagringskontot tas bort enligt cleanupPreference. Men om skriptet misslyckas och cleanupPreference inte är inställt på Alltid, håller distributionsprocessen automatiskt containern igång i en timme eller tills containern rensas. Du kan använda tiden för att felsöka skriptet. Om du vill att containern ska köras efter lyckade distributioner lägger du till ett vilosteg i skriptet. Du kan till exempel lägga till Start-Sleep i slutet av skriptet. Om du inte lägger till vilolägessteget är containern inställd på ett terminaltillstånd och kan inte nås även om den inte har tagits bort ännu.

• retentionInterval: Ange tidsintervallet som en deploymentScript resurs ska behållas och varefter den upphör att gälla och tas bort.

Det automatiskt skapade lagringskontot och containerinstansen kan inte tas bort om distributionsskriptet distribueras till en resursgrupp med ett CanNotDelete-lås. Du kan lösa det här problemet genom att distribuera distributionsskriptet till en annan resursgrupp utan lås. Se Exempel 4 och Exempel 5 i exempelmallar.

Köra skript mer än en gång

Exekvering av distributionsskript är en idempotent åtgärd. Om ingen av resursegenskaperna deploymentScripts (inklusive det infogade skriptet) ändras körs inte skriptet när du distribuerar om mallen. Distributionsskripttjänsten jämför resursnamnen i mallen med befintliga resurser i samma resursgrupp. Det finns två alternativ om du vill köra samma distributionsskript flera gånger:

• Ändra namnet på resursen deploymentScripts . Använd till exempel utcNow-mallfunktionen som resursnamn eller som en del av resursnamnet. Om du ändrar resursnamnet skapas en ny deploymentScripts resurs. Det är bra för att hålla en historik över körning av skript.

  Kommentar

  Funktionen utcNow kan bara användas i standardvärdet för en parameter.

• Ange ett annat värde i mallegenskapen forceUpdateTag . Använd till exempel utcNow som värde.

Konfigurera utvecklingsmiljön

Du kan använda en förkonfigurerad containeravbildning som utvecklingsmiljö för distributionsskript. Mer information finns i Konfigurera utvecklingsmiljö för distributionsskript i mallar.

När skriptet har testats kan du använda det som ett distributionsskript i dina mallar.

Felkoder för distributionsskript

Använda Microsoft Graph i ett distributionsskript

Ett distributionsskript kan använda Microsoft Graph för att skapa och arbeta med objekt i Microsoft Entra-ID.

Kommandon

När du använder Azure CLI-distributionsskript kan du använda kommandon i az ad kommandogruppen för att arbeta med program, tjänstens huvudnamn, grupper och användare. Du kan också anropa Microsoft Graph-API:er direkt med hjälp az rest av kommandot .

När du använder Azure PowerShell-distributionsskript kan du använda cmdleten Invoke-RestMethod för att direkt anropa Microsoft Graph-API:erna.

Behörigheter

Den identitet som distributionsskriptet använder måste ha behörighet att arbeta med Microsoft Graph-API:et, med rätt behörigheter för de åtgärder som utförs. Du måste auktorisera identiteten utanför malldistributionen, till exempel genom att skapa en användartilldelad hanterad identitet och tilldela den en approll för Microsoft Graph. Mer information finns i det här snabbstartsexemplet.

Åtkomst till privat virtuellt nätverk

Med Microsoft.Resources/deploymentScripts version 2023-08-01 kan du köra distributionsskript i privata nätverk med några ytterligare konfigurationer.

• Skapa en användartilldelad hanterad identitet och ange den i egenskapen identity . Information om hur du tilldelar identiteten finns i Identitet.

• Skapa ett lagringskonto med allowSharedKeyAccess inställt på true och ange distributionsskriptet för att använda det befintliga lagringskontot. Information om hur du anger ett befintligt lagringskonto finns i Använda ett befintligt lagringskonto. Det krävs ytterligare konfiguration för lagringskontot.

  1. Öppna lagringskontot i Azure Portal.

  2. Välj Åtkomstkontroll (IAM) på den vänstra menyn och välj sedan fliken Rolltilldelningar .

  3. Lägg till rollen Storage File Data Privileged Contributor i den hanterade identiteten för användartilldelning.

  4. På den vänstra menyn går du till Säkerhet + nätverk, väljer Nätverk och sedan Brandväggar och virtuella nätverk.

  5. Välj Aktiverad från valda virtuella nätverk och IP-adresser.

     

  6. Under Virtuella nätverk lägger du till ett undernät. På skärmbilden kallas undernätet dspvnVnet.

  7. Under Undantag väljer du Tillåt Att Azure-tjänster i listan över betrodda tjänster får åtkomst till det här lagringskontot.

Följande ARM-mall visar hur du konfigurerar miljön för att köra ett distributionsskript:

{
  "$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'))]"
      ]
    }
  ]
}

Du kan använda följande ARM-mall för att testa distributionen:

{
  "$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"
      }
    }
  ]
}

Nästa steg

I den här artikeln har du lärt dig hur du använder distributionsskript. Så här följer du en handledning om distributionsskript: