Konfigurera runbook-indataparametrar i Automation

Artikel
11/28/2023

Runbook-indataparametrar ökar flexibiliteten för en runbook genom att tillåta att data skickas till den när den startas. Med de här parametrarna kan runbook-åtgärder riktas mot specifika scenarier och miljöer. I den här artikeln beskrivs konfiguration och användning av indataparametrar i dina runbooks.

Du kan konfigurera indataparametrar för PowerShell, PowerShell Workflow, grafiska runbooks och Python-runbooks. En runbook kan ha flera parametrar med olika datatyper eller inga parametrar. Indataparametrar kan vara obligatoriska eller valfria och du kan använda standardvärden för valfria parametrar.

Du tilldelar värden till indataparametrarna för en runbook när du startar den. Du kan starta en runbook från Azure-portalen, en webbtjänst eller PowerShell. Du kan också starta en som en underordnad runbook som kallas infogad i en annan runbook.

Indatatyper

Azure Automation stöder olika indataparametervärden för de olika runbook-typerna. Indatatyper som stöds för varje typ av runbook visas i följande tabell.

Typ av runbook	Parameterindata som stöds
PowerShell	-Sträng – Security.SecureString - INT32 -Boolean -Datetime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell-arbetsflöde	-Sträng – Security.SecureString - INT32 -Boolean -Datetime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
Grafisk PowerShell	-Sträng - INT32 - INT64 -Boolean -Decimal -Datetime -Objekt
Python	-Sträng

Konfigurera indataparametrar i PowerShell-runbooks

PowerShell- och PowerShell-arbetsflödesrunbooks i Azure Automation stöder indataparametrar som definieras via följande egenskaper.

Property	Beskrivning
Typ	Obligatoriska. Datatypen förväntas för parametervärdet. Alla .NET-typer är giltiga.
Namn	Obligatoriska. Namnet på parametern. Det här namnet måste vara unikt i runbooken, måste börja med en bokstav och får endast innehålla bokstäver, siffror eller understreck.
Obligatorisk	Valfritt. Det booleska värdet anger om parametern kräver ett värde. Om du anger sant måste ett värde anges när runbooken startas. Om du ställer in detta på False är ett värde valfritt. Om du inte anger något värde för `Mandatory` egenskapen anser PowerShell att indataparametern är valfri som standard.
Default value	Valfritt. Ett värde som används för parametern om inget indatavärde skickas när runbooken startar. Runbooken kan ange ett standardvärde för valfri parameter.

Windows PowerShell stöder fler attribut för indataparametrar än de som anges ovan, till exempel validering, alias och parameteruppsättningar. Azure Automation stöder dock för närvarande endast de angivna indataparameteregenskaperna.

Låt oss till exempel titta på en parameterdefinition i en PowerShell Workflow-runbook. Den här definitionen har följande allmänna formulär, där flera parametrar avgränsas med kommatecken.

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

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

Nu ska vi konfigurera indataparametrarna för en PowerShell Workflow-runbook som matar ut information om virtuella datorer, antingen en enskild virtuell dator eller alla virtuella datorer i en resursgrupp. Den här runbooken har två parametrar, enligt följande skärmbild: namnet på den virtuella datorn (VMName) och namnet på resursgruppen (resourceGroupName).

Automation PowerShell Workflow

I den här parameterdefinitionen är indataparametrarna enkla parametrar av typen sträng.

Observera att PowerShell- och PowerShell Workflow-runbooks stöder alla enkla typer och komplexa typer, till exempel Object eller PSCredential för indataparametrar. Om din runbook har en indataparameter för objekt måste du använda en PowerShell-hashtable med namn/värde-par för att skicka in ett värde. Du har till exempel följande parameter i en runbook.

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

I det här fallet kan du skicka följande värde till parametern.

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

För PowerShell 7.1-runbooks anger du parametrar för matrisindata i följande format:

Namn	Värde
TESTPARAMETER	does,this,even,work

Kommentar

När du inte skickar ett värde till en valfri Strängparameter med ett null-standardvärde är värdet för parametern en tom sträng i stället för Null.

Konfigurera indataparametrar i grafiska runbooks

För att illustrera konfigurationen av indataparametrar för en grafisk runbook ska vi skapa en runbook som matar ut information om virtuella datorer, antingen en enskild virtuell dator eller alla virtuella datorer i en resursgrupp. Mer information finns i Min första grafiska runbook.

En grafisk runbook använder de här stora runbook-aktiviteterna:

Autentisera med Azure med hjälp av en hanterad identitet som konfigurerats för automationskontot.
Definition av en Get-AzVM-cmdlet för att hämta VM-egenskaper.
Använd aktiviteten Write-Output för att mata ut namnen på den virtuella datorn.

Aktiviteten Get-AzVM definierar två indata, namnet på den virtuella datorn och resursgruppens namn. Eftersom dessa namn kan vara olika varje gång runbooken startar måste du lägga till indataparametrar i din runbook för att acceptera dessa indata. Se Grafisk redigering i Azure Automation.

Följ dessa steg för att konfigurera indataparametrarna.

Välj den grafiska runbooken på sidan Runbooks och klicka sedan på Redigera.
I den grafiska redigeraren klickar du på knappen Indata och utdata och sedan på Lägg till indata för att öppna fönstret Indataparameter för Runbook.
Kontrollen Indata och utdata visar en lista över indataparametrar som har definierats för runbooken. Här kan du antingen lägga till en ny indataparameter eller redigera konfigurationen av en befintlig indataparameter. Om du vill lägga till en ny parameter för runbooken klickar du på Lägg till indata för att öppna bladet Runbook-indataparameter , där du kan konfigurera parametrar med de egenskaper som definierats i Grafisk redigering i Azure Automation.
Skapa två parametrar med följande egenskaper som ska användas av Get-AzVM aktiviteten och klicka sedan på OK.
- Parameter 1:
  - Namnge -- VMName
  - Typ – sträng
  - Obligatoriskt -- nej
- Parameter 2:
  - Namnge -- resourceGroupName
  - Typ – sträng
  - Obligatoriskt -- nej
  - Anpassat standardvärde --
  - Anpassat standardvärde – Namnet på resursgruppen som innehåller de virtuella datorerna
Visa parametrarna i indata- och utdatakontrollen.
Klicka på OK igen och klicka sedan på Spara.
Klicka på Publicera för att publicera din runbook.

Konfigurera indataparametrar i Python-runbooks

Till skillnad från PowerShell, PowerShell Workflow och grafiska runbooks tar Python-runbooks inte namngivna parametrar. Runbook-redigeraren parsar alla indataparametrar som en matris med argumentvärden. Du kan komma åt matrisen genom att importera modulen sys till python-skriptet och sedan använda matrisen sys.argv . Observera att det första elementet i matrisen, , sys.argv[0]är namnet på skriptet. Därför är sys.argv[1]den första faktiska indataparametern .

Ett exempel på hur du använder indataparametrar i en Python-runbook finns i Min första Python-runbook i Azure Automation.

Kommentar

Argument med blanksteg stöds för närvarande inte. Som en lösning kan du använda \\t utöver \\n.

Tilldela värden till indataparametrar i runbooks

I det här avsnittet beskrivs flera sätt att skicka värden till indataparametrar i runbooks. Du kan tilldela parametervärden när du:

Starta en Runbook
Testa en Runbook
Länka ett schema för runbooken
Skapa en webhook för runbooken

Starta en runbook och tilldela parametrar

En runbook kan startas på många sätt: via Azure-portalen, med en webhook, med PowerShell-cmdletar, med REST-API:et eller med SDK:n.

Starta en publicerad runbook med hjälp av Azure-portalen och tilldela parametrar

När du startar runbooken i Azure-portalen öppnas bladet Start Runbook och du kan ange värden för de parametrar som du har skapat.

Start using the portal

I etiketten under indatarutan kan du se de egenskaper som har angetts för att definiera parameterattribut, till exempel obligatoriska eller valfria, typ, standardvärde. Hjälpballongen bredvid parameternamnet definierar också den viktiga information som behövs för att fatta beslut om parameterindatavärden.

Kommentar

Strängparametrar stöder tomma värden av typen Sträng. När du anger [EmptyString] i rutan för indataparameter skickas en tom sträng till parametern. Dessutom stöder inte strängparametrar Null. Om du inte skickar något värde till en strängparameter tolkar PowerShell det som Null.

Starta en publicerad runbook med PowerShell-cmdletar och tilldela parametrar

Azure Resource Manager-cmdletar: Du kan starta en Automation-runbook som skapades i en resursgrupp med hjälp av Start-AzAutomationRunbook.

   $params = @{"VMName"="WSVMClassic";"resourceGroupeName"="WSVMClassicSG"}

   Start-AzAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" –ResourceGroupName $resourceGroupName -Parameters $params

Cmdletar för den klassiska Azure-distributionsmodellen: Du kan starta en Automation-runbook som skapades i en standardresursgrupp med hjälp av Start-AzureAutomationRunbook.

   $params = @{"VMName"="WSVMClassic"; "ServiceName"="WSVMClassicSG"}

   Start-AzureAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" -Parameters $params

Kommentar

När du startar en runbook med PowerShell-cmdletar skapas en standardparameter, MicrosoftApplicationManagementStartedBy, med värdet PowerShell. Du kan visa den här parametern i fönstret Jobbinformation.

Starta en runbook med hjälp av ett SDK och tilldela parametrar

Azure Resource Manager-metod: Du kan starta en runbook med hjälp av SDK för ett programmeringsspråk. Nedan visas ett C#-kodfragment för att starta en runbook i ditt Automation-konto. Du kan visa all kod på vår GitHub-lagringsplats.

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;
}

Klassisk Azure-distributionsmodellmetod: Du kan starta en runbook med hjälp av SDK för ett programmeringsspråk. Nedan visas ett C#-kodfragment för att starta en runbook i ditt Automation-konto. Du kan visa all kod på vår GitHub-lagringsplats.

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;
}

Om du vill starta den här metoden skapar du en ordlista för att lagra runbookparametrarna VMName och resourceGroupName deras värden. Starta sedan runbooken. Nedan visas kodfragmentet C# för att anropa metoden som definieras ovan.

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);

Starta en runbook med hjälp av REST-API:et och tilldela parametrar

Du kan skapa och starta ett runbook-jobb med Azure Automation REST API med hjälp PUT av metoden med följande URI för begäran: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

Ersätt följande parametrar i begärande-URI:n:

subscriptionId: Ditt Azure-prenumerations-ID.
resourceGroupName: Namnet på resursgruppen för Automation-kontot.
automationAccountName: Namnet på automationskontot som finns i den angivna molntjänsten.
jobName: GUID för jobbet. GUID:er i PowerShell kan skapas med hjälp [GUID]::NewGuid().ToString()*av .

Om du vill skicka parametrar till runbook-jobbet använder du begärandetexten. Den innehåller följande information, som anges i JSON-format:

Runbook-namn: Krävs. Namnet på runbooken som jobbet ska starta.
Runbook-parametrar: Valfritt. En ordlista för parameterlistan i (namn, värde) format, där namnet är av typen Sträng och värde kan vara valfritt giltigt JSON-värde.

Om du vill starta runbooken Get-AzureVMTextual som skapades tidigare med VMName och resourceGroupName som parametrar använder du följande JSON-format för begärandetexten.

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

En HTTP-statuskod 201 returneras om jobbet har skapats. Mer information om svarshuvuden och svarstexten finns i skapa ett runbook-jobb med hjälp av REST-API:et.

Testa en runbook och tilldela parametrar

När du testar utkastversionen av runbooken med hjälp av testalternativet öppnas testsidan. Använd den här sidan om du vill konfigurera värden för de parametrar som du har skapat.

Test and assign parameters

Länka ett schema till en runbook och tilldela parametrar

Du kan länka ett schema till din runbook så att runbooken startar vid en viss tidpunkt. Du tilldelar indataparametrar när du skapar schemat, och runbooken använder dessa värden när det startas av schemat. Du kan inte spara schemat förrän alla obligatoriska parametervärden har angetts.

Schedule and assign parameters

Skapa en webhook för en runbook och tilldela parametrar

Du kan skapa en webhook för din runbook och konfigurera runbook-indataparametrar. Du kan inte spara webhooken förrän alla obligatoriska parametervärden har angetts.

Create webhook and assign parameters

När du kör en runbook med hjälp av en webhook skickas den fördefinierade indataparametern [WebhookData](automation-webhooks.md) tillsammans med de indataparametrar som du definierar.

WebhookData parameter

Skicka ett JSON-objekt till en runbook

Det kan vara användbart att lagra data som du vill skicka till en runbook i en JSON-fil. Du kan till exempel skapa en JSON-fil som innehåller alla parametrar som du vill skicka till en runbook. För att göra detta måste du konvertera JSON-koden till en sträng och sedan konvertera strängen till ett PowerShell-objekt innan du skickar den till runbooken.

Det här avsnittet använder ett exempel där ett PowerShell-skript anropar Start-AzAutomationRunbook för att starta en PowerShell-runbook och skickar innehållet i JSON-filen till runbooken. PowerShell-runbooken startar en virtuell Azure-dator genom att hämta parametrarna för den virtuella datorn från JSON-objektet.

Skapa JSON-filen

Skriv följande kod i en textfil och spara den som test.json någonstans på den lokala datorn.

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

Skapa runbooken

Skapa en ny PowerShell-runbook med namnet Test-Json i Azure Automation.

För att acceptera JSON-data måste runbooken ta ett objekt som indataparameter. Runbooken kan sedan använda de egenskaper som definierats i JSON-filen.

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

Om du vill att runbooken ska köras med den systemtilldelade hanterade identiteten lämnar du koden som den är. Om du föredrar att använda en användartilldelad hanterad identitet:

Från rad 10 tar du bort $AzureContext = (Connect-AzAccount -Identity).context,
Ersätt den med $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, och
Ange klient-ID:t.

Spara och publicera den här runbooken i ditt Automation-konto.

Anropa runbooken från PowerShell

Nu kan du anropa runbooken från den lokala datorn med hjälp av Azure PowerShell.

Logga in på Azure som du ser. Efteråt uppmanas du att ange dina Azure-autentiseringsuppgifter.
```
Connect-AzAccount
```
Kommentar

För PowerShell-runbooks Add-AzAccount och Add-AzureRMAccount är alias för Connect-AzAccount. Observera att dessa alias inte är tillgängliga för grafiska runbooks. En grafisk runbook kan bara använda Connect-AzAccount sig själv.
Hämta innehållet i den sparade JSON-filen och konvertera den till en sträng. JsonPath anger sökvägen där du sparade JSON-filen.
```
$json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
```
Konvertera stränginnehållet i $json till ett PowerShell-objekt.
```
$JsonParams = @{"json"=$json}
```
Skapa en hashtable för parametrarna för Start-AzAutomationRunbook.
```
$RBParams = @{
     AutomationAccountName = 'AATest'
     ResourceGroupName = 'RGTest'
     Name = 'Test-Json'
     Parameters = $JsonParams
}
```
Observera att du ställer in värdet Parameters för det PowerShell-objekt som innehåller värdena från JSON-filen.

Starta runbooken.

$job = Start-AzAutomationRunbook @RBParams

Nästa steg

Information om hur du förbereder en text runbook finns i Redigera text runbooks i Azure Automation.
Information om hur du förbereder en grafisk runbook finns i Skapa grafiska runbooks i Azure Automation.

Konfigurera runbook-indataparametrar i Automation

Indatatyper

Konfigurera indataparametrar i PowerShell-runbooks

Konfigurera indataparametrar i grafiska runbooks

Konfigurera indataparametrar i Python-runbooks

Tilldela värden till indataparametrar i runbooks

Starta en runbook och tilldela parametrar

Starta en publicerad runbook med hjälp av Azure-portalen och tilldela parametrar

Starta en publicerad runbook med PowerShell-cmdletar och tilldela parametrar

Starta en runbook med hjälp av ett SDK och tilldela parametrar

Starta en runbook med hjälp av REST-API:et och tilldela parametrar

Testa en runbook och tilldela parametrar

Länka ett schema till en runbook och tilldela parametrar

Skapa en webhook för en runbook och tilldela parametrar

Skicka ett JSON-objekt till en runbook

Skapa JSON-filen

Skapa runbooken

Anropa runbooken från PowerShell

Nästa steg

Ytterligare resurser