Delen via

Implementatiescripts gebruiken in ARM-sjablonen

  • Artikel

Meer informatie over het gebruik van implementatiescripts in ARM-sjablonen (Azure Resource Manager). Met de deploymentScripts resource kunnen gebruikers scripts uitvoeren in ARM-implementaties en uitvoeringsresultaten bekijken.

Tip

We raden Bicep aan omdat het dezelfde mogelijkheden biedt als ARM-sjablonen en de syntaxis gemakkelijker te gebruiken is. Zie Implementatiescript voor meer informatie.

Deze scripts kunnen worden gebruikt voor het uitvoeren van aangepaste stappen, zoals:

  • Gebruikers toevoegen aan een directory.
  • Voer gegevensvlakbewerkingen uit, bijvoorbeeld blobs of seed-database kopiëren.
  • Zoek en valideer een licentiesleutel.
  • Maak een zelfondertekend certificaat.
  • Maak een object in Microsoft Entra ID.
  • Zoek IP-adresblokken van aangepast systeem op.

De voordelen van implementatiescript:

  • Eenvoudig te coden, te gebruiken en fouten op te sporen. U kunt implementatiescripts ontwikkelen in uw favoriete ontwikkelomgevingen. De scripts kunnen worden ingesloten in sjablonen of in externe scriptbestanden.
  • U kunt de scripttaal en het platform opgeven. Momenteel worden Azure PowerShell- en Azure CLI-implementatiescripts in de Linux-omgeving ondersteund.
  • Geef opdrachtregelargumenten door aan het script.
  • Kan scriptuitvoer opgeven en deze doorgeven aan de implementatie.

De implementatiescriptresource is alleen beschikbaar in de regio's waar Azure Container Instance beschikbaar is. Bekijk de beschikbaarheid van resources voor Azure Container Instances in Azure-regio's. Op dit moment maakt het implementatiescript alleen gebruik van openbare netwerken.

Belangrijk

De implementatiescriptservice vereist twee ondersteunende resources voor het uitvoeren en oplossen van problemen: een opslagaccount en een containerinstantie. U kunt een bestaand opslagaccount opgeven, anders maakt de scriptservice er een voor u. De twee automatisch gemaakte ondersteunende resources worden meestal verwijderd door de scriptservice wanneer de uitvoering van het implementatiescript een terminalstatus krijgt. U wordt gefactureerd voor de ondersteunende resources totdat ze worden verwijderd. Zie Prijzen voor Container Instances en Prijzen voor Azure Storage voor de prijsinformatie. Zie Resources voor het opschonen van implementatiescripts voor meer informatie.

Notitie

Pogingslogica voor Aanmelden bij Azure is nu ingebouwd in het wrapper-script. Als u machtigingen verleent in dezelfde sjabloon als uw implementatiescripts, meldt de implementatiescriptservice zich 10 minuten opnieuw aan met een interval van 10 seconden totdat de toewijzing van de rol van de beheerde identiteit wordt gerepliceerd.

Trainingsmateriaal

Als u liever meer wilt weten over implementatiescripts via stapsgewijze richtlijnen, raadpleegt u ARM-sjablonen uitbreiden met behulp van implementatiescripts.

De minimale machtigingen configureren

Voor implementatiescript-API-versie 2020-10-01 of hoger zijn er twee principals betrokken bij het uitvoeren van implementatiescripts:

  • Implementatie-principal (de principal die wordt gebruikt om de sjabloon te implementeren): deze principal wordt gebruikt om onderliggende resources te maken die nodig zijn voor de implementatiescriptresource die moet worden uitgevoerd: een opslagaccount en een Azure-containerinstantie. Als u de machtigingen met minimale bevoegdheden wilt configureren, wijst u een aangepaste rol toe met de volgende eigenschappen aan de implementatie-principal:

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

    Als de Azure Storage- en azure Container Instance-resourceproviders niet zijn geregistreerd, moet u ook toevoegen Microsoft.Storage/register/action en Microsoft.ContainerInstance/register/action.

  • Implementatiescript-principal: deze principal is alleen vereist als het implementatiescript moet worden geverifieerd bij Azure en Azure CLI/PowerShell moet aanroepen. Er zijn twee manieren om de principal voor het implementatiescript op te geven:

    • Geef een door de gebruiker toegewezen beheerde identiteit op in de identity eigenschap (zie voorbeeldsjablonen). Wanneer dit is opgegeven, roept Connect-AzAccount -Identity de scriptservice het implementatiescript aan voordat u het implementatiescript aanroept. De beheerde identiteit moet de vereiste toegang hebben om de bewerking in het script te voltooien. Momenteel wordt alleen door de gebruiker toegewezen beheerde identiteit ondersteund voor de identity eigenschap. Als u zich wilt aanmelden met een andere identiteit, gebruikt u de tweede methode in deze lijst.
    • Geef de referenties van de service-principal door als veilige omgevingsvariabelen en roep vervolgens Connect-AzAccount of az login aan in het implementatiescript.

    Als een beheerde identiteit wordt gebruikt, heeft de implementatie-principal de rol Managed Identity Operator (een ingebouwde rol) nodig die is toegewezen aan de beheerde identiteitsresource.

Voorbeeldsjablonen

De volgende JSON is een voorbeeld. Zie het meest recente sjabloonschema voor meer informatie.

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

Notitie

Het voorbeeld is bedoeld voor demonstratiedoeleinden. De eigenschappen scriptContent en primaryScriptUri kunnen niet naast elkaar bestaan in een sjabloon.

Notitie

De scriptContent toont een script met meerdere regels. De Azure-portal en de Azure DevOps-pijplijn kunnen een implementatiescript met meerdere regels niet parseren. U kunt de PowerShell-opdrachten koppelen (met puntkomma's of \r\n of \n) in één regel, of de primaryScriptUri eigenschap gebruiken met een extern scriptbestand. Er zijn veel gratis escape-/unescape-hulpprogramma's voor JSON-tekenreeksen beschikbaar. Bijvoorbeeld: https://www.freeformatter.com/json-escape.html.

Details van eigenschapswaarde:

  • identity: Voor implementatiescript-API-versie 2020-10-01 of hoger is een door de gebruiker toegewezen beheerde identiteit optioneel, tenzij u Azure-specifieke acties in het script moet uitvoeren. Voor de API-versie 2019-10-01-preview is een beheerde identiteit vereist omdat de implementatiescriptservice deze gebruikt om de scripts uit te voeren. Wanneer de id-eigenschap is opgegeven, roept Connect-AzAccount -Identity de scriptservice aan voordat het gebruikersscript wordt aanroepen. Op dit moment wordt alleen door de gebruiker toegewezen beheerde identiteit ondersteund. Als u zich wilt aanmelden met een andere identiteit, kunt u Connect-AzAccount aanroepen in het script.

  • tags: scripttags voor implementatie. Als de implementatiescriptservice een opslagaccount en een containerinstantie genereert, worden de tags doorgegeven aan beide resources, die kunnen worden gebruikt om ze te identificeren. Een andere manier om deze resources te identificeren, is via hun achtervoegsels, die 'azscripts' bevatten. Zie Implementatiescripts bewaken en problemen oplossen voor meer informatie.

  • kind: Geef het type script op. Momenteel worden Azure PowerShell- en Azure CLI-scripts ondersteund. De waarden zijn AzurePowerShell en AzureCLI.

  • forceUpdateTag: Als u deze waarde tussen sjabloonimplementaties wijzigt, wordt het implementatiescript opnieuw uitgevoerd. Als u de newGuid() of de utcNow() functies gebruikt, kunnen beide functies alleen worden gebruikt in de standaardwaarde voor een parameter. Zie Script meerdere keren uitvoeren voor meer informatie.

  • containerSettings: Geef de instellingen op om Azure Container Instance aan te passen. Voor het implementatiescript is een nieuw Azure Container Instance vereist. U kunt geen bestaande Azure Container Instance opgeven. U kunt de naam van de containergroep echter aanpassen met behulp van containerGroupName. Als dit niet is opgegeven, wordt de groepsnaam automatisch gegenereerd.

  • storageAccountSettings: Geef de instellingen op voor het gebruik van een bestaand opslagaccount. Als storageAccountName dit niet is opgegeven, wordt automatisch een opslagaccount gemaakt. Zie Een bestaand opslagaccount gebruiken.

  • azPowerShellVersion/azCliVersion: Geef de moduleversie op die moet worden gebruikt. Bekijk een lijst met ondersteunde Azure PowerShell-versies. De versie bepaalt welke containerinstallatiekopieën moeten worden gebruikt:

    • Az-versie groter dan of gelijk aan 9 maakt gebruik van Ubuntu 22.04.
    • Az-versie groter dan of gelijk aan 6, maar minder dan 9 maakt gebruik van Ubuntu 20.04.
    • Az-versie kleiner dan 6 maakt gebruik van Ubuntu 18.04.

    Belangrijk

    Het is raadzaam om een upgrade uit te voeren naar de nieuwste versie van Ubuntu, omdat Ubuntu 18.04 het einde van de levensduur nadert en geen beveiligingsupdates meer ontvangt dan 31 mei 2023.

    Bekijk een lijst met ondersteunde Azure CLI-versies.

    Belangrijk

    Implementatiescript maakt gebruik van de beschikbare CLI-installatiekopieën van Microsoft Container Registry (MCR). Het duurt doorgaans ongeveer één maand om een CLI-installatiekopieën te certificeren voor het implementatiescript. Gebruik niet de CLI-versies die binnen 30 dagen zijn uitgebracht. Raadpleeg de releaseopmerkingen van Azure CLI om de releasedatums voor de installatiekopieën te vinden. Als er een niet-ondersteunde versie wordt gebruikt, worden in het foutbericht de ondersteunde versies vermeld.

  • arguments: Geef de parameterwaarden op. De waarden worden gescheiden door een spatie.

    Met implementatiescripts worden de argumenten gesplitst in een matrix met tekenreeksen door de aanroep van het CommandLineToArgvW-systeem aan te roepen. Deze stap is nodig omdat de argumenten worden doorgegeven als een opdrachteigenschap aan Azure Container Instance en de opdrachteigenschap een matrix met tekenreeksen is.

    Als de argumenten escape-tekens bevatten, gebruikt u JsonEscaper om de tekens te dubbel escapen. Plak de oorspronkelijke escape-tekenreeks in het hulpmiddel en selecteer Vervolgens Escape. Het hulpprogramma voert een dubbele escape-tekenreeks uit. In de vorige voorbeeldsjabloon is -name \"John Dole\"het argument bijvoorbeeld . De escape-tekenreeks is -name \\\"John Dole\\\".

    Als u een ARM-sjabloonparameter van het typeobject als argument wilt doorgeven, converteert u het object naar een tekenreeks met behulp van de functie string() en gebruikt u vervolgens de functie replace() om een \" waarde te vervangen in \\\". Voorbeeld:

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

    Zie de voorbeeldsjabloon voor meer informatie.

  • environmentVariables: Geef de omgevingsvariabelen op die moeten worden doorgegeven aan het script. Zie Implementatiescripts ontwikkelen voor meer informatie.

  • scriptContent: Geef de scriptinhoud op. Als u een extern script wilt uitvoeren, gebruikt primaryScriptUri u in plaats daarvan. Zie Inlinescript gebruiken en Extern script gebruiken voor voorbeelden.

  • primaryScriptUri: Geef een openbaar toegankelijke URL op naar het primaire implementatiescript met ondersteunde bestandsextensies. Zie Externe scripts gebruiken voor meer informatie.

  • supportingScriptUris: Geef een matrix van openbaar toegankelijke URL's op voor ondersteunende bestanden die worden aangeroepen in of scriptContent primaryScriptUri. Zie Externe scripts gebruiken voor meer informatie.

  • timeout: Geef de maximale toegestane uitvoeringstijd voor scripts op die is opgegeven in de ISO 8601-indeling. Standaardwaarde is P1D.

  • cleanupPreference. Geef de voorkeur op voor het opschonen van de twee ondersteunende implementatieresources, het opslagaccount en de containerinstantie, wanneer de uitvoering van het script in een terminalstatus terechtkomt. De standaardinstelling is Altijd, wat betekent dat u de ondersteunende resources verwijdert ondanks de terminalstatus (geslaagd, mislukt, geannuleerd). Zie Resources van implementatiescripts opschonen voor meer informatie.

  • retentionInterval: Geef het interval op waarvoor de service de implementatiescriptresource behoudt nadat de uitvoering van het implementatiescript een terminalstatus heeft bereikt. De implementatiescriptresource wordt verwijderd wanneer deze duur verloopt. De duur is gebaseerd op het ISO 8601-patroon. Het bewaarinterval ligt tussen 1 en 26 uur (PT26H). Deze eigenschap wordt gebruikt wanneer cleanupPreference deze is ingesteld op OnExpiration. Zie Resources van implementatiescripts opschonen voor meer informatie.

Meer voorbeelden

  • Voorbeeld 1: een sleutelkluis maken en het implementatiescript gebruiken om een certificaat toe te wijzen aan de sleutelkluis.
  • Voorbeeld 2: maak een resourcegroep op abonnementsniveau, maak een sleutelkluis in de resourcegroep en gebruik vervolgens het implementatiescript om een certificaat toe te wijzen aan de sleutelkluis.
  • Voorbeeld 3: maak een door de gebruiker toegewezen beheerde identiteit, wijs de rol inzender toe aan de identiteit op het niveau van de resourcegroep, maak een sleutelkluis en gebruik vervolgens een implementatiescript om een certificaat toe te wijzen aan de sleutelkluis.
  • Voorbeeld 4: dit is hetzelfde scenario als voorbeeld 1 in deze lijst. Er wordt een nieuwe resourcegroep gemaakt om het implementatiescript uit te voeren. Deze sjabloon is een sjabloon op abonnementsniveau.
  • Voorbeeld 5: het is hetzelfde scenario als voorbeeld 4. Deze sjabloon is een sjabloon op resourcegroepniveau.
  • Voorbeeld 6: maak handmatig een door de gebruiker toegewezen beheerde identiteit en wijs deze machtiging toe om de Microsoft Graph API te gebruiken om Microsoft Entra-toepassingen te maken. Gebruik in de ARM-sjabloon een implementatiescript om een Microsoft Entra-toepassing en service-principal te maken en voer de object-id's en client-id uit.

Inlinescripts gebruiken

De volgende sjabloon heeft één resource die is gedefinieerd met het Microsoft.Resources/deploymentScripts type. Het gemarkeerde gedeelte is het inlinescript.

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

Notitie

Omdat de inline-implementatiescripts tussen dubbele aanhalingstekens staan, moeten de tekenreeksen in de implementatiescripts worden ontsnapt met behulp van een backslash (\) of tussen enkele aanhalingstekens. U kunt ook overwegen om tekenreeksvervanging te gebruiken, omdat deze wordt weergegeven in het vorige JSON-voorbeeld.

Het script heeft één parameter en voert de parameterwaarde uit. DeploymentScriptOutputs wordt gebruikt voor het opslaan van uitvoer. In de uitvoersectie laat de value regel zien hoe u toegang hebt tot de opgeslagen waarden. Write-Output wordt gebruikt voor foutopsporing. Zie Implementatiescripts bewaken en problemen oplossen voor meer informatie over het openen van het uitvoerbestand. Zie Voorbeeldsjablonen voor de beschrijvingen van eigenschappen.

Als u het script wilt uitvoeren, selecteert u Proberen om de Cloud Shell te openen en plakt u de volgende code in het shell-deelvenster.

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

De uitvoer ziet er als volgt uit:

Schermopname van implementatiescript van Resource Manager-sjabloon hello world-uitvoer.

Externe scripts gebruiken

Naast inlinescripts kunt u ook externe scriptbestanden gebruiken. Alleen primaire PowerShell-scripts met de ps1-bestandsextensie worden ondersteund. Voor CLI-scripts kunnen de primaire scripts extensies hebben (of zonder extensie), zolang de scripts geldige bash-scripts zijn. Als u externe scriptbestanden wilt gebruiken, vervangt u door scriptContent primaryScriptUri. Voorbeeld:

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

Zie de voorbeeldsjabloon voor meer informatie.

De externe scriptbestanden moeten toegankelijk zijn. Als u uw scriptbestanden wilt beveiligen die zijn opgeslagen in Azure-opslagaccounts, genereert u een SAS-token en neemt u het op in de URI voor de sjabloon. Stel de vervaltijd zo in, dat er genoeg tijd is om de implementatie te voltooien. Zie Privé-ARM-sjabloon implementeren met SAS-token voor meer informatie.

U bent verantwoordelijk voor het waarborgen van de integriteit van de scripts waarnaar wordt verwezen door een implementatiescript of primaryScriptUri supportingScriptUris. Verwijs alleen naar scripts die u vertrouwt.

Ondersteunende scripts gebruiken

U kunt ingewikkelde logica scheiden in een of meer ondersteunende scriptbestanden. Met supportingScriptUris de eigenschap kunt u zo nodig een matrix met URI's opgeven voor de ondersteunende scriptbestanden:

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

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

Ondersteunende scriptbestanden kunnen worden aangeroepen vanuit zowel inlinescripts als primaire scriptbestanden. Ondersteunende scriptbestanden hebben geen beperkingen voor de bestandsextensie.

De ondersteunende bestanden worden tijdens de runtime gekopieerd azscripts/azscriptinput . Gebruik relatief pad om te verwijzen naar de ondersteunende bestanden van inlinescripts en primaire scriptbestanden.

Werken met uitvoer van PowerShell-scripts

In de volgende sjabloon ziet u hoe u waarden tussen twee deploymentScripts resources doorgeeft:

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

In de eerste resource definieert u een variabele met de naam $DeploymentScriptOutputsen gebruikt u deze om de uitvoerwaarden op te slaan. Als u toegang wilt krijgen tot de uitvoerwaarde van een andere resource in de sjabloon, gebruikt u:

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

Werken met uitvoer van CLI-scripts

In tegenstelling tot de Azure PowerShell-implementatiescripts biedt CLI/bash geen algemene variabele voor het opslaan van scriptuitvoer. In plaats daarvan wordt een omgevingsvariabele met de naam gebruikt AZ_SCRIPTS_OUTPUT_PATH om de locatie van het scriptuitvoerbestand aan te geven. Bij het uitvoeren van een implementatiescript in een ARM-sjabloon configureert de Bash-shell deze omgevingsvariabele automatisch voor u. De vooraf gedefinieerde waarde wordt ingesteld als /mnt/azscripts/azscriptoutput/scriptoutputs.json. De uitvoer is vereist om te voldoen aan een geldige JSON-tekenreeksobjectstructuur. De inhoud van het bestand moet worden opgemaakt als een sleutel-waardepaar. Een matrix met tekenreeksen moet bijvoorbeeld worden opgeslagen als { "MyResult": [ "foo", "bar"] }. Alleen de matrixresultaten, zoals [ "foo", "bar" ], worden als ongeldig beschouwd.

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

jq wordt gebruikt in het vorige voorbeeld. Deze wordt geleverd met de containerinstallatiekopieën. Zie Ontwikkelomgeving configureren.

Bestaand opslagaccount gebruiken

Er zijn een opslagaccount en een containerinstantie nodig voor het uitvoeren en oplossen van problemen met scripts. U hebt de opties om een bestaand opslagaccount op te geven, anders wordt het opslagaccount samen met de containerinstantie automatisch gemaakt door de scriptservice. De vereisten voor het gebruik van een bestaand opslagaccount:

  • Ondersteunde opslagaccounttypen zijn:

    SKU Ondersteund type
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Opslag, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Opslag, StorageV2
    Standard_RAGRS Opslag, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

    Deze combinaties ondersteunen bestandsshares. Zie Een Azure-bestandsshare en typen opslagaccounts maken voor meer informatie.

  • Firewallregels voor opslagaccounts worden nog niet ondersteund. Raadpleeg Firewalls en virtuele netwerken voor Azure Storage configureren voor meer informatie.

  • De implementatie-principal moet machtigingen hebben voor het beheren van het opslagaccount, waaronder lezen, maken, verwijderen van bestandsshares.

  • De allowSharedKeyAccess eigenschap van het opslagaccount moet worden ingesteld op true. De enige manier om een opslagaccount te koppelen in Azure Container Instance (ACI) is via een toegangssleutel.

Als u een bestaand opslagaccount wilt opgeven, voegt u de volgende JSON toe aan het eigenschapselement van Microsoft.Resources/deploymentScripts:

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

  • storageAccountName: geef de naam van het opslagaccount op.

  • storageAccountKey: geef een van de opslagaccountsleutels op. U kunt de functie listKeys() gebruiken om de sleutel op te halen. Voorbeeld:

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

Zie Voorbeeldsjablonen voor een volledig Microsoft.Resources/deploymentScripts definitievoorbeeld.

Wanneer een bestaand opslagaccount wordt gebruikt, maakt de scriptservice een bestandsshare met een unieke naam. Zie Resources voor implementatiescripts opschonen voor de wijze waarop de scriptservice de bestandsshare opschoont.

Implementatiescripts ontwikkelen

Niet-bepalende fouten afhandelen

U kunt bepalen hoe PowerShell reageert op niet-bepalende fouten met behulp van de $ErrorActionPreference variabele in uw implementatiescript. Als de variabele niet is ingesteld in uw implementatiescript, gebruikt de scriptservice de standaardwaarde Doorgaan.

De scriptservice stelt de inrichtingsstatus van de resource in op Mislukt wanneer er een fout optreedt ondanks de instelling van $ErrorActionPreference.

Omgevingsvariabelen gebruiken

Implementatiescript maakt gebruik van deze omgevingsvariabelen:

Omgevingsvariabele Default value Systeem gereserveerd
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> J
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput J
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput J
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME Azure PowerShell: userscript.ps1; Azure CLI: userscript.sh J
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config J
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config J
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json J
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json J
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY /abonnementen/ N

Zie Werken met uitvoer van CLI-script voor meer informatie over het gebruikAZ_SCRIPTS_OUTPUT_PATH.

Beveiligde tekenreeksen doorgeven aan implementatiescript

Als u omgevingsvariabelen (EnvironmentVariable) instelt in uw containerinstanties, kunt u dynamische configuratie bieden van de toepassing of het script dat door de container wordt uitgevoerd. Het implementatiescript verwerkt niet-beveiligde en beveiligde omgevingsvariabelen op dezelfde manier als Azure Container Instance. Zie Omgevingsvariabelen instellen in containerinstanties voor meer informatie. Zie Voorbeeldsjablonen voor een voorbeeld.

De maximale toegestane grootte voor omgevingsvariabelen is 64 kB.

Implementatiescripts bewaken en problemen oplossen

De scriptservice maakt een opslagaccount (tenzij u een bestaand opslagaccount opgeeft) en een containerinstantie voor het uitvoeren van scripts. Als deze resources automatisch door de scriptservice worden gemaakt, hebben beide resources het azscripts achtervoegsel in de resourcenamen.

Schermopname van resourcenamen van Resource Manager-sjabloonimplementatiescripts.

Het gebruikersscript, de uitvoeringsresultaten en het stdout-bestand worden opgeslagen in de bestandsshares van het opslagaccount. Er is een map met de naam azscripts. In de map zijn er nog twee mappen voor de invoer en de uitvoerbestanden: azscriptinput en azscriptoutput.

De output-map bevat een executionresult.json en het uitvoerbestand van het script. U ziet het foutbericht over de uitvoering van het script in executionresult.json. Het uitvoerbestand wordt alleen gemaakt wanneer het script is uitgevoerd. De input-map bevat een scriptbestand voor het PowerShell-systeem en de scriptbestanden voor de gebruikersimplementatie. U kunt het scriptbestand voor gebruikersimplementatie vervangen door een herzien script en het implementatiescript opnieuw uitvoeren vanuit de Azure-containerinstantie.

De Azure-portal gebruiken

Nadat u een implementatiescriptresource hebt geïmplementeerd, wordt de resource vermeld onder de resourcegroep in Azure Portal. In de volgende schermopname ziet u de pagina Overzicht van een implementatiescriptresource:

Schermopname van het overzicht van de implementatiescriptportal voor Resource Manager-sjablonen.

Op de overzichtspagina worden enkele belangrijke informatie van de resource weergegeven, zoals de inrichtingsstatus, het opslagaccount, het containerexemplaren en de logboeken.

In het linkermenu kunt u de inhoud van het implementatiescript, de argumenten die zijn doorgegeven aan het script en de uitvoer bekijken. U kunt ook een sjabloon exporteren voor het implementatiescript, inclusief het implementatiescript.

PowerShell gebruiken

Met Behulp van Azure PowerShell kunt u implementatiescripts beheren op abonnements- of resourcegroepbereik:

De Get-AzDeploymentScript uitvoer is vergelijkbaar met:

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

Azure CLI gebruiken

Met behulp van Azure CLI kunt u implementatiescripts beheren op abonnements- of resourcegroepbereik:

De uitvoer van de lijstopdracht is vergelijkbaar met:

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

REST API gebruiken

U kunt de implementatiegegevens van de implementatiescriptresource ophalen op het niveau van de resourcegroep en het abonnementsniveau met behulp van 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

In het volgende voorbeeld wordt ARMClient gebruikt:

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

De uitvoer is vergelijkbaar met:

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

De volgende REST API retourneert het logboek:

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

Het werkt alleen voordat de resources van het implementatiescript worden verwijderd.

Als u de deploymentScripts-resource in de portal wilt zien, selecteert u Verborgen typen weergeven:

Schermopname van het Resource Manager-sjabloonimplementatiescript met de optie Verborgen typen weergeven in de portal.

Resources voor implementatiescripts opschonen

De twee automatisch gemaakte ondersteunende resources kunnen de deploymentScript resource nooit overleven, tenzij er fouten zijn opgetreden bij het verwijderen ervan. De levenscyclus van de ondersteunende resources wordt beheerd door de cleanupPreference eigenschap, de levenscyclus van de deploymentScript resource wordt beheerd door de retentionInterval eigenschap:

  • cleanupPreference: Geef de opschoningsvoorkeur op van de twee ondersteunende resources wanneer de uitvoering van het script een terminalstatus krijgt. De ondersteunde waarden zijn:

    • Altijd: verwijder de twee ondersteunende resources zodra de uitvoering van het script in een terminalstatus is. Als een bestaand opslagaccount wordt gebruikt, verwijdert de scriptservice de bestandsshare die door de service is gemaakt. Omdat de deploymentScripts resource nog steeds aanwezig is nadat de ondersteunende resources zijn opgeschoond, blijft de scriptservice de resultaten van de uitvoering van het script behouden, bijvoorbeeld stdout, uitvoer en retourwaarde voordat de resources worden verwijderd.

    • OnSuccess: verwijder de twee ondersteunende resources alleen wanneer de uitvoering van het script is geslaagd. Als een bestaand opslagaccount wordt gebruikt, verwijdert de scriptservice de bestandsshare alleen wanneer de uitvoering van het script is geslaagd.

      Als de uitvoering van het script niet lukt, wacht de scriptservice totdat het retentionInterval verloopt voordat de ondersteunende resources worden opgeschoond en vervolgens de implementatiescriptresource.

    • OnExpiration: verwijder de twee ondersteunende resources alleen wanneer de retentionInterval instelling is verlopen. Als een bestaand opslagaccount wordt gebruikt, verwijdert de scriptservice de bestandsshare, maar behoudt het opslagaccount.

    Het containerexemplaren en het opslagaccount worden verwijderd volgens de cleanupPreference. Als het script echter mislukt en cleanupPreference niet is ingesteld op Altijd, houdt het implementatieproces de container automatisch één uur actief of totdat de container is opgeschoond. U kunt de tijd gebruiken om problemen met het script op te lossen. Als u de container na geslaagde implementaties actief wilt houden, voegt u een slaapstandstap toe aan uw script. Voeg bijvoorbeeld Start-Sleep toe aan het einde van uw script. Als u de slaapstandstap niet toevoegt, wordt de container ingesteld op een terminalstatus en kan deze nog niet worden geopend, zelfs niet als deze nog niet is verwijderd.

  • retentionInterval: Geef het tijdsinterval op dat een deploymentScript resource wordt bewaard en waarna deze is verlopen en verwijderd.

Notitie

Het wordt niet aanbevolen om het opslagaccount en de containerinstantie te gebruiken die voor andere doeleinden door de scriptservice worden gegenereerd. De twee resources kunnen worden verwijderd, afhankelijk van de levenscyclus van het script.

Het automatisch gemaakte opslagaccount en het containerexemplaren kunnen niet worden verwijderd als het implementatiescript wordt geïmplementeerd in een resourcegroep met een CanNotDelete-vergrendeling. U kunt dit probleem oplossen door het implementatiescript te implementeren in een andere resourcegroep zonder vergrendelingen. Zie voorbeeld 4 en voorbeeld 5 in voorbeeldsjablonen.

Script meer dan één keer uitvoeren

De uitvoering van het implementatiescript is een idempotente bewerking. Als geen van de deploymentScripts resource-eigenschappen (inclusief het inlinescript) wordt gewijzigd, wordt het script niet uitgevoerd wanneer u de sjabloon opnieuw implementeert. De implementatiescriptservice vergelijkt de resourcenamen in de sjabloon met de bestaande resources in dezelfde resourcegroep. Er zijn twee opties als u hetzelfde implementatiescript meerdere keren wilt uitvoeren:

  • Wijzig de naam van uw deploymentScripts resource. Gebruik bijvoorbeeld de functie utcNow-sjabloon als de resourcenaam of als onderdeel van de resourcenaam. Als u de resourcenaam wijzigt, wordt er een nieuwe deploymentScripts resource gemaakt. Het is goed om een geschiedenis van het uitvoeren van scripts bij te houden.

    Notitie

    De utcNow functie kan alleen worden gebruikt in de standaardwaarde voor een parameter.

  • Geef een andere waarde op in de forceUpdateTag sjablooneigenschap. Gebruik bijvoorbeeld utcNow als waarde.

Notitie

Schrijf de implementatiescripts die idempotent zijn. Dit zorgt ervoor dat als ze per ongeluk opnieuw worden uitgevoerd, dit geen systeemwijzigingen veroorzaakt. Als het implementatiescript bijvoorbeeld wordt gebruikt om een Azure-resource te maken, controleert u of de resource niet bestaat voordat u deze maakt, zodat het script slaagt of u de resource niet opnieuw maakt.

De ontwikkelomgeving configureren

U kunt een vooraf geconfigureerde containerinstallatiekopieën gebruiken als uw ontwikkelomgeving voor implementatiescripts. Zie Ontwikkelomgeving configureren voor implementatiescripts in sjablonen voor meer informatie.

Nadat het script is getest, kunt u het gebruiken als een implementatiescript in uw sjablonen.

Foutcodes voor implementatiescripts

Foutcode Beschrijving
DeploymentScriptInvalidOperation De resourcedefinitie van het implementatiescript in de sjabloon bevat ongeldige eigenschapsnamen.
DeploymentScriptResourceConflict Kan een implementatiescriptresource die niet-terminal is niet verwijderen en de uitvoering niet langer is dan 1 uur. Of kan hetzelfde implementatiescript niet opnieuw uitvoeren met dezelfde resource-id (hetzelfde abonnement, de naam van de resourcegroep en de resourcenaam), maar tegelijkertijd andere inhoud van de scripttekst.
DeploymentScriptOperationFailed De implementatiescriptbewerking is intern mislukt. Neem contact op met Microsoft Ondersteuning.
DeploymentScriptStorageAccountAccessKeyNotSpecified De toegangssleutel is niet opgegeven voor het bestaande opslagaccount.
DeploymentScriptContainerGroupContainsInvalidContainers Een containergroep die door de implementatiescriptservice is gemaakt, is extern gewijzigd en ongeldige containers zijn toegevoegd.
DeploymentScriptContainerGroupInNonterminalState Twee of meer implementatiescriptresources gebruiken dezelfde Naam van het Azure-containerexemplaren in dezelfde resourcegroep en een van deze resources heeft de uitvoering nog niet voltooid.
DeploymentScriptStorageAccountInvalidKind Het bestaande opslagaccount van het type BlobBlobStorage of BlobStorage biedt geen ondersteuning voor bestandsshares en kan niet worden gebruikt.
DeploymentScriptStorageAccountInvalidKindAndSku Het bestaande opslagaccount biedt geen ondersteuning voor bestandsshares. Zie Bestaand opslagaccount gebruiken voor een lijst met ondersteunde opslagaccounttypen.
DeploymentScriptStorageAccountNotFound Het opslagaccount bestaat niet of is verwijderd door een extern proces of hulpprogramma.
DeploymentScriptStorageAccountWithServiceEndpointEnabled Het opgegeven opslagaccount heeft een service-eindpunt. Een opslagaccount met een service-eindpunt wordt niet ondersteund.
DeploymentScriptStorageAccountInvalidAccessKey Ongeldige toegangssleutel die is opgegeven voor het bestaande opslagaccount.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Ongeldige indeling van opslagaccountsleutel. Zie Toegangssleutels voor opslagaccounts beheren.
DeploymentScriptExceededMaxAllowedTime De uitvoeringstijd van het implementatiescript heeft de time-outwaarde overschreden die is opgegeven in de definitie van de implementatiescriptresource.
DeploymentScriptInvalidOutputs De uitvoer van het implementatiescript is geen geldig JSON-object.
DeploymentScriptContainerInstancesServiceLoginFailure De door de gebruiker toegewezen beheerde identiteit kon zich niet aanmelden na tien pogingen met een interval van 1 minuut.
DeploymentScriptContainerGroupNotFound Een containergroep die is gemaakt door de implementatiescriptservice, is verwijderd door een extern hulpprogramma of proces.
DeploymentScriptDownloadFailure Kan een ondersteunend script niet downloaden. Zie Ondersteuningsscript gebruiken.
DeploymentScriptError Er is een fout opgetreden in het gebruikersscript.
DeploymentScriptBootstrapScriptExecutionFailed Er is een fout opgetreden in het bootstrap-script. Bootstrap-script is het systeemscript waarmee de uitvoering van het implementatiescript wordt ingedeeld.
DeploymentScriptExecutionFailed Onbekende fout tijdens de uitvoering van het implementatiescript.
DeploymentScriptContainerInstancesServiceUnavailable Bij het maken van de Azure Container Instance (ACI) heeft ACI een service niet beschikbaar gemaakt.
DeploymentScriptContainerGroupInNonterminalState Bij het maken van de Azure Container Instance (ACI) gebruikt een ander implementatiescript dezelfde ACI-naam in hetzelfde bereik (hetzelfde abonnement, de naam van de resourcegroep en de resourcenaam).
DeploymentScriptContainerGroupNameInvalid De opgegeven ACI-naam (Azure Container Instance) voldoet niet aan de ACI-vereisten. Zie Veelvoorkomende problemen in Azure Container Instances oplossen.

Microsoft Graph gebruiken binnen een implementatiescript

Een implementatiescript kan Microsoft Graph gebruiken om objecten in Microsoft Entra-id te maken en ermee te werken.

Opdracht

Wanneer u Azure CLI-implementatiescripts gebruikt, kunt u opdrachten in de az ad opdrachtgroep gebruiken om te werken met toepassingen, service-principals, groepen en gebruikers. U kunt ook rechtstreeks Microsoft Graph API's aanroepen met behulp van de az rest opdracht.

Wanneer u Azure PowerShell-implementatiescripts gebruikt, kunt u de Invoke-RestMethod cmdlet gebruiken om de Microsoft Graph-API's rechtstreeks aan te roepen.

Machtigingen

De identiteit die door uw implementatiescript wordt gebruikt, moet worden geautoriseerd om te werken met de Microsoft Graph API, met de juiste machtigingen voor de bewerkingen die worden uitgevoerd. U moet de identiteit buiten uw sjabloonimplementatie autoriseren, bijvoorbeeld door een door de gebruiker toegewezen beheerde identiteit vooraf te maken en deze toe te wijzen aan een app-rol voor Microsoft Graph. Zie dit snelstartvoorbeeld voor meer informatie.

Toegang tot een virtueel particulier netwerk

Met Microsoft.Resources/deploymentScripts versie 2023-08-01 kunt u implementatiescripts uitvoeren in privénetwerken met enkele extra configuraties.

  • Maak een door de gebruiker toegewezen beheerde identiteit en geef deze op in de identity eigenschap. Zie Identiteit om de identiteit toe te wijzen.

  • Maak een opslagaccount met allowSharedKeyAccess de waarde ingesteld op true en geef het implementatiescript op om het bestaande opslagaccount te gebruiken. Zie Bestaand opslagaccount gebruiken om een bestaand opslagaccount op te geven. Er is een extra configuratie vereist voor het opslagaccount.

    1. Open het opslagaccount in Azure Portal.

    2. Selecteer in het linkermenu Toegangsbeheer (IAM) en selecteer vervolgens het tabblad Roltoewijzingen .

    3. Voeg de Storage File Data Privileged Contributor rol toe aan de door de gebruiker toegewezen beheerde identiteit.

    4. Selecteer in het linkermenu onder Beveiliging en netwerken de optie Netwerken en selecteer vervolgens Firewalls en virtuele netwerken.

    5. Selecteer Ingeschakeld in geselecteerde virtuele netwerken en IP-adressen.

      Schermopname van het configureren van het opslagaccount voor toegang tot het privénetwerk.

    6. Voeg onder Virtuele netwerken een subnet toe. In de schermopname heet het subnet dspvnVnet.

    7. Selecteer onder Uitzonderingen Azure-services toestaan in de lijst met vertrouwde services voor toegang tot dit opslagaccount.

De volgende ARM-sjabloon laat zien hoe u de omgeving configureert voor het uitvoeren van een implementatiescript:

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

U kunt de volgende ARM-sjabloon gebruiken om de implementatie te testen:

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

Volgende stappen

In dit artikel hebt u geleerd hoe u implementatiescripts gebruikt. Een zelfstudie voor een implementatiescript doorlopen:

Zelfstudie: Implementatiescripts gebruiken in Azure Resource Manager-sjablonen

Learn-module: ARM-sjablonen uitbreiden met behulp van implementatiescripts