Runbookinvoerparameters configureren in Automation

Runbookinvoerparameters vergroten de flexibiliteit van een runbook doordat gegevens aan het runbook kunnen worden doorgegeven wanneer deze worden gestart. Met deze parameters kunnen runbookacties worden gericht op specifieke scenario's en omgevingen. In dit artikel worden de configuratie en het gebruik van invoerparameters in uw runbooks beschreven.

U kunt invoerparameters configureren voor PowerShell-, PowerShell Workflow-, grafische en Python-runbooks. Een runbook kan meerdere parameters hebben met verschillende gegevenstypen of geen parameters. Invoerparameters kunnen verplicht of optioneel zijn en u kunt standaardwaarden gebruiken voor optionele parameters.

U wijst waarden toe aan de invoerparameters voor een runbook wanneer u het start. U kunt een runbook starten vanuit Azure Portal, een webservice of PowerShell. U kunt er ook een starten als een onderliggend runbook dat inline wordt aangeroepen in een ander runbook.

Invoertypen

Azure Automation ondersteunt verschillende invoerparameterwaarden voor de verschillende runbooktypen. Ondersteunde invoertypen voor elk type runbook worden vermeld in de volgende tabel.

Runbooktype	Ondersteunde parameterinvoer
PowerShell	-Tekenreeks - Security.SecureString - INT32 -Booleaanse -Datetime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell Workflow	-Tekenreeks - Security.SecureString - INT32 -Booleaanse -Datetime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
Grafische PowerShell	-Tekenreeks - INT32 - INT64 -Booleaanse -Decimaal -Datetime -Object
Python	-Tekenreeks

Invoerparameters configureren in PowerShell-runbooks

PowerShell- en PowerShell Workflow-runbooks in Azure Automation ondersteunen invoerparameters die zijn gedefinieerd via de volgende eigenschappen.

Eigenschappen	Beschrijving
Type	Vereist. Het gegevenstype wordt verwacht voor de parameterwaarde. Elk .NET-type is geldig.
Naam	Vereist. De naam van de parameter. Deze naam moet uniek zijn binnen het runbook, moet beginnen met een letter en mag alleen letters, cijfers of onderstrepingstekens bevatten.
Verplicht	Optioneel. De Booleaanse waarde geeft aan of voor de parameter een waarde is vereist. Als u dit instelt op Waar, moet er een waarde worden opgegeven wanneer het runbook wordt gestart. Als u dit instelt op Onwaar, is een waarde optioneel. Als u geen waarde voor de Mandatory eigenschap opgeeft, wordt de invoerparameter standaard door PowerShell als optioneel beschouwd.
Default value	Optioneel. Een waarde die wordt gebruikt voor de parameter als er geen invoerwaarde wordt doorgegeven wanneer het runbook wordt gestart. Het runbook kan een standaardwaarde instellen voor elke parameter.

Windows PowerShell ondersteunt meer kenmerken van invoerparameters dan die hierboven worden vermeld, zoals validatie, aliassen en parametersets. Azure Automation ondersteunt momenteel echter alleen de eigenschappen van de vermelde invoerparameter.

Laten we eens kijken naar een parameterdefinitie in een PowerShell Workflow-runbook. Deze definitie heeft de volgende algemene vorm, waarbij meerdere parameters worden gescheiden door komma's.

Param
(
  [Parameter (Mandatory= $true/$false)]
  [Type] $Name1 = <Default value>,

  [Parameter (Mandatory= $true/$false)]
  [Type] $Name2 = <Default value>
)

Nu gaan we de invoerparameters configureren voor een PowerShell Workflow-runbook dat details uitvoert over virtuele machines, één VM of alle VM's in een resourcegroep. Dit runbook heeft twee parameters, zoals wordt weergegeven in de volgende schermopname: de naam van de virtuele machine (VMName) en de naam van de resourcegroep (resourceGroupName).

In deze parameterdefinitie zijn de invoerparameters eenvoudige parameters van het type tekenreeks.

PowerShell- en PowerShell Workflow-runbooks ondersteunen alle eenvoudige typen en complexe typen, zoals Object of PSCredential voor invoerparameters. Als uw runbook een objectinvoerparameter heeft, moet u een PowerShell-hashtabel met naam-waardeparen gebruiken om een waarde door te geven. U hebt bijvoorbeeld de volgende parameter in een runbook.

[Parameter (Mandatory = $true)]
[object] $FullName

In dit geval kunt u de volgende waarde doorgeven aan de parameter.

@{"FirstName"="Joe";"MiddleName"="Bob";"LastName"="Smith"}

Geef voor PowerShell 7.1-runbooks matrixinvoerparameters op in de onderstaande indeling:

Naam	Value
TESTPARAMETER	doet, dit, zelfs, werk

Notitie

Wanneer u geen waarde doorgeeft aan een optionele tekenreeksparameter met een null-standaardwaarde, is de waarde van de parameter een lege tekenreeks in plaats van Null.

Invoerparameters configureren in grafische runbooks

Om de configuratie van invoerparameters voor een grafisch runbook te illustreren, gaan we een runbook maken dat details over virtuele machines uitvoert, ofwel één VIRTUELE machine of alle VM's in een resourcegroep. Zie Mijn eerste grafische runbook voor meer informatie.

Een grafisch runbook maakt gebruik van deze belangrijke runbookactiviteiten:

• Verifiëren met Azure met behulp van een beheerde identiteit die is geconfigureerd voor een Automation-account.
• Definitie van een Get-AzVM-cmdlet om VM-eigenschappen op te halen.
• Gebruik van de activiteit Write-Output om de namen van de VIRTUELE machines uit te voeren.

De Get-AzVM activiteit definieert twee invoerwaarden, de naam van de VM en de naam van de resourcegroep. Omdat deze namen kunnen verschillen telkens wanneer het runbook wordt gestart, moet u invoerparameters toevoegen aan uw runbook om deze invoer te accepteren. Raadpleeg Grafische creatie in Azure Automation.

Volg deze stappen om de invoerparameters te configureren.

1. Selecteer het grafische runbook op de pagina Runbooks en klik vervolgens op Bewerken.

2. Klik in de grafische editor op de knop Invoer en uitvoer en voeg vervolgens invoer toe om het deelvenster Invoerparameter runbook te openen.

   

3. In het besturingselement Invoer en Uitvoer wordt een lijst met invoerparameters weergegeven die zijn gedefinieerd voor het runbook. Hier kunt u een nieuwe invoerparameter toevoegen of de configuratie van een bestaande invoerparameter bewerken. Als u een nieuwe parameter voor het runbook wilt toevoegen, klikt u op Invoer toevoegen om de blade Invoerparameter runbook te openen. Hier kunt u parameters configureren met behulp van de eigenschappen die zijn gedefinieerd in Grafische creatie in Azure Automation.

   

4. Maak twee parameters met de volgende eigenschappen die door de Get-AzVM activiteit moeten worden gebruikt en klik vervolgens op OK.

   • Parameter 1:

     • Naam -- VAN VM-naam
     • Type -- Tekenreeks
     • Verplicht -- nee

   • Parameter 2:

     • Naam -- resourceGroupName
     • Type -- Tekenreeks
     • Verplicht -- nee
     • Standaardwaarde -- Aangepast
     • Aangepaste standaardwaarde: naam van de resourcegroep die de VM's bevat

5. Bekijk de parameters in het besturingselement Invoer en Uitvoer.

6. Klik nogmaals op OK en klik vervolgens op Opslaan.

7. Klik op Publiceren om uw runbook te publiceren.

Invoerparameters configureren in Python-runbooks

In tegenstelling tot PowerShell, PowerShell Workflow en grafische runbooks, nemen Python-runbooks geen benoemde parameters. De runbook-editor parseert alle invoerparameters als een matrix met argumentwaarden. U hebt toegang tot de matrix door de sys module te importeren in uw Python-script en vervolgens de sys.argv matrix te gebruiken. Het is belangrijk om te weten dat het eerste element van de matrix, sys.argv[0]de naam van het script is. Daarom is sys.argv[1]de eerste werkelijke invoerparameter .

Zie Mijn eerste Python-runbook in Azure Automation voor een voorbeeld van het gebruik van invoerparameters in een Python-runbook.

Notitie

Argumenten met spaties worden momenteel niet ondersteund. Als tijdelijke oplossing kunt u \\t naast \\n gebruiken.

Waarden toewijzen aan invoerparameters in runbooks

In deze sectie worden verschillende manieren beschreven om waarden door te geven aan invoerparameters in runbooks. U kunt parameterwaarden toewijzen wanneer u:

• Een runbook starten
• Een runbook testen
• Een planning voor het runbook koppelen
• Een webhook maken voor het runbook

Een runbook starten en parameters toewijzen

Een runbook kan op veel manieren worden gestart: via Azure Portal, met een webhook, met PowerShell-cmdlets, met de REST API of met de SDK.

Een gepubliceerd runbook starten met behulp van Azure Portal en parameters toewijzen

Wanneer u het runbook start in Azure Portal, wordt de blade Runbook starten geopend en kunt u waarden invoeren voor de parameters die u hebt gemaakt.

In het label onder het invoervak ziet u de eigenschappen die zijn ingesteld om parameterkenmerken te definiëren, bijvoorbeeld verplicht of optioneel, type, standaardwaarde. De Help-ballon naast de parameternaam definieert ook de belangrijkste informatie die nodig is om beslissingen te nemen over parameterinvoerwaarden.

Notitie

Tekenreeksparameters ondersteunen lege waarden van het type Tekenreeks. Als u in het invoerparametervak invoert [EmptyString] , wordt een lege tekenreeks doorgegeven aan de parameter. Tekenreeksparameters bieden ook geen ondersteuning voor Null. Als u geen waarde doorgeeft aan een tekenreeksparameter, interpreteert PowerShell deze als Null.

Een gepubliceerd runbook starten met behulp van PowerShell-cmdlets en parameters toewijzen

• Azure Resource Manager-cmdlets: u kunt een Automation-runbook starten dat is gemaakt in een resourcegroep met behulp van Start-AzAutomationRunbook.

     $params = @{"VMName"="WSVMClassic";"resourceGroupeName"="WSVMClassicSG"}
  
     Start-AzAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" –ResourceGroupName $resourceGroupName -Parameters $params
  

• Cmdlets voor het klassieke Azure-implementatiemodel: u kunt een automation-runbook starten dat is gemaakt in een standaardresourcegroep met behulp van Start-AzureAutomationRunbook.

     $params = @{"VMName"="WSVMClassic"; "ServiceName"="WSVMClassicSG"}
  
     Start-AzureAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" -Parameters $params
  

Notitie

Wanneer u een runbook start met behulp van PowerShell-cmdlets, wordt er een standaardparameter gemaakt MicrosoftApplicationManagementStartedBymet de waarde PowerShell. U kunt deze parameter weergeven in het deelvenster Taakdetails.

Een runbook starten met behulp van een SDK en parameters toewijzen

• Azure Resource Manager-methode: u kunt een runbook starten met behulp van de SDK van een programmeertaal. Hieronder ziet u een C#-codefragment voor het starten van een runbook in uw Automation-account. U kunt alle code bekijken in onze GitHub-opslagplaats.

  public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
  {
    var response = AutomationClient.Jobs.Create(resourceGroupName, automationAccount, new JobCreateParameters
    {
      Properties = new JobCreateProperties
      {
        Runbook = new RunbookAssociationProperty
        {
          Name = runbookName
        },
        Parameters = parameters
      }
    });
    return response.Job;
  }
  

• Methode voor het klassieke Azure-implementatiemodel: u kunt een runbook starten met behulp van de SDK van een programmeertaal. Hieronder ziet u een C#-codefragment voor het starten van een runbook in uw Automation-account. U kunt alle code bekijken in onze GitHub-opslagplaats.

  public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
  {
    var response = AutomationClient.Jobs.Create(automationAccount, new JobCreateParameters
    {
      Properties = new JobCreateProperties
      {
        Runbook = new RunbookAssociationProperty
        {
          Name = runbookName
        },
        Parameters = parameters
      }
    });
    return response.Job;
  }
  

  Als u deze methode wilt starten, maakt u een woordenlijst om de runbookparameters VMName en resourceGroupName de bijbehorende waarden op te slaan. Start vervolgens het runbook. Hieronder ziet u het C#-codefragment voor het aanroepen van de hierboven gedefinieerde methode.

  IDictionary<string, string> RunbookParameters = new Dictionary<string, string>();
  
  // Add parameters to the dictionary.
  RunbookParameters.Add("VMName", "WSVMClassic");
  RunbookParameters.Add("resourceGroupName", "WSSC1");
  
  //Call the StartRunbook method with parameters
  StartRunbook("Get-AzureVMGraphical", RunbookParameters);
  

Een runbook starten met behulp van de REST API en parameters toewijzen

U kunt een runbooktaak maken en starten met de Azure Automation REST API met behulp van de PUT methode met de volgende aanvraag-URI: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

Vervang in de aanvraag-URI de volgende parameters:

• subscriptionId: uw Azure-abonnements-id.
• resourceGroupName: De naam van de resourcegroep voor het Automation-account.
• automationAccountName: De naam van het Automation-account dat wordt gehost in de opgegeven cloudservice.
• jobName: de GUID voor de taak. GUID's in PowerShell kunnen worden gemaakt met behulp van [GUID]::NewGuid().ToString()*.

Gebruik de hoofdtekst van de aanvraag om parameters door te geven aan de runbooktaak. Hiervoor worden de volgende gegevens gebruikt, opgegeven in JSON-indeling:

• Runbooknaam: vereist. De naam van het runbook voor de taak die moet worden gestart.
• Runbookparameters: Optioneel. Een woordenlijst van de parameterlijst in indeling (naam, waarde), waarbij de naam van het type Tekenreeks en waarde elke geldige JSON-waarde kan zijn.

Als u het Get-AzureVMTextual-runbook wilt starten dat u eerder hebt gemaakt met VMName en resourceGroupName als parameters, gebruikt u de volgende JSON-indeling voor de aanvraagbody.

    {
      "properties":{
        "runbook":{
        "name":"Get-AzureVMTextual"},
      "parameters":{
         "VMName":"WindowsVM",
         "resourceGroupName":"ContosoSales"}
        }
    }

Er wordt een HTTP-statuscode 201 geretourneerd als de taak is gemaakt. Zie Een runbooktaak maken met behulp van de REST API voor meer informatie over antwoordheaders en de hoofdtekst van het antwoord.

Een runbook testen en parameters toewijzen

Wanneer u de conceptversie van uw runbook test met behulp van de testoptie, wordt de pagina Testen geopend. Op deze pagina kunt u waarden configureren voor de parameters die u hebt gemaakt.

Een planning koppelen aan een runbook en parameters toewijzen

U kunt een planning koppelen aan uw runbook, zodat het runbook op een bepaald tijdstip begint. U wijst invoerparameters toe wanneer u het schema maakt en het runbook gebruikt deze waarden wanneer het wordt gestart door de planning. U kunt de planning pas opslaan als alle verplichte parameterwaarden zijn opgegeven.

Een webhook maken voor een runbook en parameters toewijzen

U kunt een webhook maken voor uw runbook en runbookinvoerparameters configureren. U kunt de webhook pas opslaan als alle verplichte parameterwaarden zijn opgegeven.

Wanneer u een runbook uitvoert met behulp van een webhook, wordt de vooraf gedefinieerde invoerparameter [WebhookData](automation-webhooks.md) verzonden, samen met de invoerparameters die u definieert.

Een JSON-object doorgeven aan een runbook

Het kan handig zijn om gegevens op te slaan die u wilt doorgeven aan een runbook in een JSON-bestand. U kunt bijvoorbeeld een JSON-bestand maken dat alle parameters bevat die u wilt doorgeven aan een runbook. Hiervoor moet u de JSON-code converteren naar een tekenreeks en vervolgens de tekenreeks converteren naar een PowerShell-object voordat u deze doorgeeft aan het runbook.

In deze sectie wordt een voorbeeld gebruikt waarin een PowerShell-script Start-AzAutomationRunbook aanroept om een PowerShell-runbook te starten, waarbij de inhoud van het JSON-bestand wordt doorgegeven aan het runbook. Het PowerShell-runbook start een Azure-VM door de parameters voor de VIRTUELE machine op te halen vanuit het JSON-object.

Het JSON-bestand maken

Typ de volgende code in een tekstbestand en sla deze op als test.json ergens op uw lokale computer.

{
   "VmName" : "TestVM",
   "ResourceGroup" : "AzureAutomationTest"
}

Het runbook maken

Maak een nieuw PowerShell-runbook met de naam Test-Json in Azure Automation.

Als u de JSON-gegevens wilt accepteren, moet het runbook een object als invoerparameter gebruiken. Het runbook kan vervolgens de eigenschappen gebruiken die zijn gedefinieerd in het JSON-bestand.

Param(
     [parameter(Mandatory=$true)]
     [object]$json
)

# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

# Convert object to actual JSON
$json = $json | ConvertFrom-Json

# Use the values from the JSON object as the parameters for your command
Start-AzVM -Name $json.VMName -ResourceGroupName $json.ResourceGroup -DefaultProfile $AzureContext

Als u wilt dat het runbook wordt uitgevoerd met de door het systeem toegewezen beheerde identiteit, laat u de code staan. Als u liever een door de gebruiker toegewezen beheerde identiteit gebruikt, gaat u als volgende te werk:

1. Uit regel 10, verwijder $AzureContext = (Connect-AzAccount -Identity).context,
2. Vervang het door $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, en
3. Voer de client-id in.

Sla dit runbook op en publiceer dit in uw Automation-account.

Het runbook aanroepen vanuit PowerShell

U kunt het runbook nu aanroepen vanaf uw lokale computer met behulp van Azure PowerShell.

1. Meld u aan bij Azure zoals wordt weergegeven. Daarna wordt u gevraagd uw Azure-referenties in te voeren.

   Connect-AzAccount
   

   Notitie

   Voor PowerShell-runbooks zijn Add-AzAccount en Add-AzureRMAccount aliassen voor Connect-AzAccount. Houd er rekening mee dat deze aliassen niet beschikbaar zijn voor grafische runbooks. Een grafisch runbook kan zichzelf alleen gebruiken Connect-AzAccount .

2. Haal de inhoud van het opgeslagen JSON-bestand op en converteer het naar een tekenreeks. JsonPath geeft het pad aan waar u het JSON-bestand hebt opgeslagen.

   $json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
   

3. Converteer de tekenreeksinhoud naar $json een PowerShell-object.

   $JsonParams = @{"json"=$json}
   

4. Maak een hashtabel voor de parameters voor Start-AzAutomationRunbook.

   $RBParams = @{
        AutomationAccountName = 'AATest'
        ResourceGroupName = 'RGTest'
        Name = 'Test-Json'
        Parameters = $JsonParams
   }
   

   U ziet dat u de waarde instelt van Parameters het PowerShell-object dat de waarden uit het JSON-bestand bevat.

5. Start het runbook.

   $job = Start-AzAutomationRunbook @RBParams
   

Volgende stappen

• Zie Tekstrunbooks bewerken in Azure Automation om een tekstueel runbook voor te bereiden.
• Zie Grafische runbooks maken in Azure Automation om een grafisch runbook voor te bereiden.