Configurare i parametri di input del runbook in Automazione

I parametri di input dei runbook aumentano la flessibilità di questi ultimi consentendo il passaggio dei dati al momento dell'avvio. Tali parametri consentono di eseguire azioni di runbook mirate per ambienti e scenari specifici. Questo articolo descrive la configurazione e l'uso dei parametri di input nei runbook in uso.

È possibile configurare i parametri di input per runbook grafici, di PowerShell, del flusso di lavoro PowerShell e di Python. Un runbook può avere più parametri con tipi di dati diversi o senza parametri. I parametri di input possono essere obbligatori o facoltativi ed è possibile usare un valore predefinito per i parametri facoltativi.

I valori dei parametri di input per un runbook vengono assegnati all'avvio del runbook stesso. È possibile avviare un runbook nel portale di Azure, in un servizio Web o in PowerShell. È inoltre possibile avviare un runbook come figlio, definito inline in un altro runbook.

Tipi di input

Automazione di Azure supporta vari valori dei parametri di input nei diversi tipi di runbook. I tipi di input supportati per ogni tipo di runbook sono elencati nella tabella seguente.

Tipo di runbook	Input dei parametri supportati
PowerShell	-Corda - Security.SecureString - INT32 -Booleano - DateTime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
Flusso di lavoro PowerShell	-Corda - Security.SecureString - INT32 -Booleano - DateTime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell grafico	-Corda - INT32 - INT64 -Booleano -Decimale - DateTime -Oggetto
Python	-Corda

Configurare i parametri di input in runbook di PowerShell

I runbook di PowerShell e del flusso di lavoro PowerShell in Automazione di Azure supportano parametri di input definiti tramite le proprietà seguenti.

Proprietà	Descrizione
Tipo	Obbligatorio. Il tipo di dati è previsto per il valore del parametro. Qualsiasi tipo .NET è valido.
Nome	Obbligatorio. Nome del parametro. Questo nome deve essere univoco all'interno del runbook, deve iniziare con una lettera e può contenere solo lettere, numeri o caratteri di sottolineatura.
Obbligatorio	Facoltativo. Il valore booleano specifica se il parametro richiede un valore. Se la proprietà è impostata su true, è necessario specificare un valore quando il runbook viene avviato. Se la proprietà è impostata su false, il valore è facoltativo. Se non si specifica un valore per la proprietà Mandatory, PowerShell considera il parametro di input facoltativo per impostazione predefinita.
Default value	Facoltativo. Valore utilizzato per il parametro se non viene passato alcun valore di input all'avvio del runbook. Il runbook può impostare un valore predefinito per qualsiasi parametro.

Windows PowerShell supporta più attributi dei parametri di input rispetto a quelli elencati di seguito, ad esempio convalida, alias e set di parametri. Automazione di Azure, tuttavia, supporta attualmente solo le proprietà dei parametri di input elencate.

Esaminiamo ad esempio una definizione di parametro in un runbook del flusso di lavoro PowerShell. Tale definizione presenta il formato generale seguente, in cui più parametri sono separati da virgole.

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

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

Configuriamo ora i parametri di input per un runbook del flusso di lavoro PowerShell che restituisce informazioni dettagliate su macchine virtuali, sia di una singola macchina virtuale che di tutte le macchine virtuali all'interno di un gruppo di risorse. Tale runbook ha due parametri, come illustrato nella schermata seguente: il nome della macchina virtuale (VMName) e il nome del gruppo di risorse (resourceGroupName).

In questa definizione i parametri di input sono semplici parametri di tipo stringa.

Si noti che i runbook di PowerShell e del flusso di lavoro PowerShell supportano tutti i tipi semplici e complessi, ad esempio Object o PSCredential per i parametri di input. Se il runbook include un parametro di input di tipo object, per passare un valore è necessario usare una tabella hash di PowerShell con coppie nome-valore. Si supponga ad esempio di avere un runbook con questo parametro.

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

In questo caso, è possibile passare al parametro il valore seguente.

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

Per i runbook di PowerShell 7.1, specificare i parametri di input della matrice nel formato seguente:

Nome	valore
TESTPARAMETER	fa, questo, anche, lavoro

Nota

Quando a un parametro stringa facoltativo non si passa un valore predefinito Null, il valore del parametro è una stringa vuota anziché Null.

Configurare i parametri di input in runbook grafici

Per illustrare la configurazione dei parametri di input per un runbook grafico, è possibile creare un runbook che restituisca informazioni dettagliate sulle macchine virtuali, una singola o tutte, all'interno di un gruppo di risorse. Per informazioni dettagliate, vedere Il primo runbook grafico.

Un runbook grafico usa queste principali attività del runbook:

• Eseguire l'autenticazione con Azure usando l'identità gestita configurata per l'account di automazione.
• Definizione di un cmdlet Get-AzVM per ottenere le proprietà della macchina virtuale.
• Usare l'attività Write-Output per restituire i nomi delle macchine virtuali.

L'attività Get-AzVM definisce due input, ovvero il nome della macchina virtuale e quello del gruppo di risorse. Poiché questi nomi possono essere diversi ogni volta che il runbook viene avviato, è necessario aggiungere parametri di input al runbook per accettare tali input. Vedere Creazione grafica in Automazione di Azure.

Per configurare i parametri di input, eseguire queste operazioni.

1. Selezionare il runbook grafico nella pagina Runbook e quindi fare clic su Modifica.

2. Nell'editor grafico fare clic sul pulsante Input e output, quindi fare clic su Aggiungi input per aprire il riquadro dei parametri di input del runbook.

   

3. Il pannello Input e output mostra un elenco di parametri di input definiti per il runbook. Qui è possibile aggiungere un nuovo parametro di input o modificare la configurazione di un parametro di input esistente. Per aggiungere un nuovo parametro per il runbook, fare clic su Aggiungi input per aprire il riquadro Parametro di input del runbook in cui è possibile configurare i parametri usando le proprietà definite in Creare runbook grafici in Automazione di Azure.

   

4. Creare due parametri con le proprietà seguenti che verranno usate dall'attività Get-AzVM e quindi fare clic su OK.

   • Parametro 1

     • Nome -- VMName
     • Tipo: string
     • Obbligatoria -- No

   • Parametro 2

     • Nome -- resourceGroupName
     • Tipo: string
     • Obbligatoria -- No
     • Valore predefinito -- Custom
     • Valore predefinito personalizzato: nome del gruppo di risorse che contengono le macchine virtuali

5. Visualizzare i parametri nel controllo Input e output.

6. Fare clic di nuovo su OK e quindi fare clic Salva.

7. Fare clic su Pubblica per pubblicare il runbook.

Configurare i parametri di input in runbook di Python

A differenza dei runbook grafici, di PowerShell e del flusso di lavoro di PowerShell, i runbook di Python non accettano parametri denominati. L'editor di runbook analizza tutti i parametri di input come una matrice di valori di argomento. Accedere alla matrice importando il modulo sys nello script Python e quindi usando la matrice sys.argv. È importante notare che il primo elemento della matrice, sys.argv[0], è il nome dello script. Il primo parametro di input effettivo è pertanto sys.argv[1].

Per un esempio su come usare i parametri di input in un runbook di Python, vedere Il primo runbook Python in Automazione di Azure.

Nota

Gli argomenti con spazi non sono attualmente supportati. Come soluzione alternativa, è possibile usare \\t oltre a \\n.

Assegnare valori ai parametri di input nei runbook

Questa sezione descrive diversi modi per passare i valori ai parametri di input nei runbook. È possibile assegnare i valori dei parametri nei casi seguenti:

• Avviare un runbook
• Testare un runbook
• Collegamento di una pianificazione per il runbook
• Creazione di un webhook per il runbook

Avviare un runbook e assegnare parametri

Sono disponibili diversi modi per avviare un runbook, ovvero nel portale di Azure, con un webhook, con i cmdlet di PowerShell, con l'API REST o con il componente SDK.

Avviare un runbook pubblicato usando il portale di Azure e assegnare parametri

Quando si avvia il runbook nel portale di Azure, viene aperto il pannello Avvia Runbook dove è possibile immettere i valori per i parametri creati.

Nell'etichetta sotto la casella di input è possibile visualizzare le proprietà impostate per definire gli attributi dei parametri, ad esempio obbligatorio o facoltativo, tipo, valore predefinito. Il fumetto della guida accanto al nome del parametro definisce anche le informazioni chiave necessarie per prendere decisioni relative ai valori di input dei parametri.

Nota

I parametri di tipo stringa supportano valori vuoti dello stesso tipo. Se si immette [EmptyString] nella casella del parametro di input, viene passata una stringa vuota al parametro. I parametri di tipo stringa, inoltre, non supportano il valore Null. Se non viene passato alcun valore al parametro di tipo stringa, PowerShell lo interpreta come Null.

Avviare un runbook pubblicato usando i cmdlet di PowerShell e assegnare parametri

• Cmdlet di Azure Resource Manager: è possibile avviare un runbook di Automazione creato in un gruppo di risorse usando Start-AzAutomationRunbook.

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

• Cmdlet del modello di distribuzione classica di Azure: è possibile avviare un runbook di automazione creato in un gruppo di risorse predefinito usando Start-AzureAutomationRunbook.

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

Nota

Quando si avvia un runbook usando i cmdlet di PowerShell, viene creato un parametro predefinito, MicrosoftApplicationManagementStartedBy, con valore PowerShell. Questo parametro può essere visualizzato nel riquadro Dettagli processo.

Avviare un runbook usando un SDK e assegnare parametri

• Metodo di Azure Resource Manager: è possibile avviare un runbook usando l'SDK di un linguaggio di programmazione. Di seguito è riportato un frammento di codice C# per l'avvio di un runbook nell'account di automazione. È possibile visualizzare tutto il codice nel repository GitHub.

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

• Metodo del modello di distribuzione classica di Azure: è possibile avviare un runbook usando l'SDK di un linguaggio di programmazione. Di seguito è riportato un frammento di codice C# per l'avvio di un runbook nell'account di automazione. È possibile visualizzare tutto il codice nel repository GitHub.

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

  Per avviare questo metodo, creare un dizionario per archiviare i VMName parametri del runbook e resourceGroupName i relativi valori. Avviare quindi il runbook. Di seguito è riportato un frammento di codice C# per chiamare il metodo definito in precedenza.

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

Avviare un runbook usando l'API REST e assegnare parametri

È possibile creare e avviare un processo del runbook con l'API REST di Automazione di Azure usando il metodo PUT con l'URI della richiesta seguente: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

Nell'URI della richiesta sostituire i parametri seguenti:

• subscriptionId: ID sottoscrizione di Azure.
• resourceGroupName: nome del gruppo di risorse per l'account di Automazione.
• automationAccountName: nome dell'account di Automazione ospitato nel servizio cloud specificato.
• jobName: GUID per il processo. I GUID in PowerShell possono essere creati usando [GUID]::NewGuid().ToString()*.

Per passare parametri al processo del runbook, usare il corpo della richiesta. Vengono accettate le informazioni seguenti in formato JSON.

• Nome del runbook: obbligatorio. Nome del runbook per il processo da avviare.
• Parametri del runbook: facoltativi. Dizionario dell'elenco dei parametri in formato (nome, valore) in cui il nome deve essere di tipo stringa e il valore può essere qualsiasi valore JSON valido.

Se si intende avviare il runbook Get-AzureVMTextual creato in precedenza con VMName e resourceGroupName come parametri, usare il formato JSON seguente per il corpo della richiesta.

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

Se il processo è stato creato, viene restituito un codice di stato HTTP 201. Per altre informazioni sulle intestazioni di risposta e sul corpo della risposta, vedere Creare un processo del runbook usando l'API REST.

Eseguire il test di un runbook e assegnare parametri

Quando si esegue il test della versione bozza del runbook in uso tramite l'opzione di test, viene visualizzata la pagina Test. Usare questa pagina per configurare i valori per i parametri creati.

Collegare una pianificazione a un runbook e assegnare parametri

È possibile collegare una pianificazione al runbook in modo che venga avviato in un momento specifico. Assegnare i parametri di input durante la creazione della pianificazione. Il runbook usa questi valori quando viene avviato dalla pianificazione. Fino a quando non vengono specificati tutti i valori dei parametri obbligatori, non è possibile salvare la pianificazione.

Creare un webhook per un runbook e assegnare parametri

È possibile creare un webhook per il runbook e configurare i parametri di input del runbook. Fino a quando non vengono specificati tutti i valori dei parametri obbligatori, non è possibile salvare il webhook.

Quando si esegue un runbook con un webhook, insieme ai parametri di input definiti viene inviato il parametro di input predefinito [WebhookData](automation-webhooks.md).

Passare un oggetto JSON a un runbook

Può essere utile archiviare i dati che si desidera passare a un runbook in un file JSON. È possibile ad esempio creare un file JSON che contiene tutti i parametri da passare a un runbook. A tale scopo, è necessario convertire il codice JSON in una stringa e quindi convertire la stringa in un oggetto di PowerShell prima di passarla al runbook.

Questa sezione usa un esempio in cui uno script di PowerShell chiama Start-AzAutomationRunbook per avviare un runbook di PowerShell, passando il contenuto del file JSON al runbook. Il runbook di PowerShell avvia una macchina virtuale di Azure recuperando i parametri per la macchina dall'oggetto JSON.

Creare il file JSON

Digitare il codice seguente in un file di testo e salvarlo come test.json in un punto qualsiasi del computer locale.

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

Creare il runbook

Creare un nuovo runbook di PowerShell denominato Test-Json in Automazione di Azure.

Per accettare i dati JSON, il runbook deve accettare un oggetto come parametro di input. Il runbook può quindi usare le proprietà definite nel file JSON.

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

Se si vuole che il runbook venga eseguito con l'identità gestita assegnata dal sistema, lasciare invariato il codice. Se si preferisce usare un'identità gestita assegnata dall'utente, procedere come illustrato di seguito:

1. Dalla riga 10 rimuovere $AzureContext = (Connect-AzAccount -Identity).context,
2. Sostituirlo con $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context e
3. Immettere l'ID client.

Salvare e pubblicare il runbook nell'account di automazione.

Chiamare il runbook da PowerShell

Ora è possibile chiamare il runbook dal computer locale tramite Azure PowerShell.

1. Accedere ad Azure nel modo illustrato. Viene richiesto di immettere le credenziali di Azure.

   Connect-AzAccount
   

   Nota

   Per i runbook PowerShell, Add-AzAccount e Add-AzureRMAccount sono alias per Connect-AzAccount. Si noti che questi alias non sono disponibili per i runbook grafici. Un runbook grafico può usare solo Connect-AzAccount.

2. Ottenere il contenuto del file JSON salvato e convertirlo in una stringa. JsonPath indica il percorso in cui è stato salvato il file JSON.

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

3. Convertire i contenuti stringa di $json in un oggetto di PowerShell.

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

4. Creare una tabella hash per i parametri per Start-AzAutomationRunbook.

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

   Si noti che si imposta il valore di Parameters sull'oggetto PowerShell che contiene i valori dal file JSON.

5. Avviare il runbook.

   $job = Start-AzAutomationRunbook @RBParams
   

Passaggi successivi

• Per preparare un runbook testuale, vedere Modificare runbook testuali in Automazione di Azure.
• Per preparare un runbook grafico, vedere Creare runbook grafici in Automazione di Azure.