Parametri di input dei runbookRunbook input parameters

I parametri di input dei runbook ne aumentano la flessibilità perché consentono di passare dati a un runbook al momento dell'avvio.Runbook input parameters increase the flexibility of runbooks by allowing you to pass data to it when it is started. I parametri consentono di eseguire azioni runbook mirate per ambienti e scenari specifici.The parameters allow the runbook actions to be targeted for specific scenarios and environments. Questo articolo illustra vari scenari in cui i parametri di input vengono usati nei runbook.In this article, we will walk you through different scenarios where input parameters are used in runbooks.

Configurare i parametri di inputConfigure input parameters

È possibile configurare i parametri di input nei runbook grafici e in quelli di PowerShell, di Python e del flusso di lavoro PowerShell.Input parameters can be configured in PowerShell, PowerShell Workflow, Python, and graphical runbooks. Un runbook può avere più parametri con tipi di dati diversi oppure non avere parametri.A runbook can have multiple parameters with different data types, or no parameters at all. I parametri di input possono essere obbligatori o facoltativi ed è possibile assegnare un valore predefinito per i parametri facoltativi.Input parameters can be mandatory or optional, and you can assign a default value for optional parameters. È possibile assegnare valori ai parametri di input per un runbook quando viene avviato tramite uno dei metodi disponibili.You can assign values to the input parameters for a runbook when you start it through one of the available methods. Questi metodi includono l'avvio di un runbook dal portale o da un servizio Web.These methods include starting a runbook from the portal or a web service. È inoltre possibile avviare un runbook come figlio, definito inline in un altro runbook.You can also start one as a child runbook that is called inline in another runbook.

Configurare i parametri di input nei runbook di PowerShell e nei runbook del flusso di lavoro PowerShellConfigure input parameters in PowerShell and PowerShell Workflow runbooks

I runbook del flusso di lavoro PowerShell e i runbook di PowerShell in Automazione di Azure supportano parametri di input definiti tramite gli attributi seguenti.PowerShell and PowerShell Workflow runbooks in Azure Automation support input parameters that are defined through the following attributes.

ProprietàProperty DescrizioneDescription
TypeType Obbligatoria.Required. Tipo di dati previsto per il valore del parametro.The data type expected for the parameter value. Qualsiasi tipo .NET è valido.Any .NET type is valid.
NomeName Obbligatoria.Required. Nome del parametro.The name of the parameter. Questo valore deve essere univoco all'interno del runbook e può contenere solo lettere, numeri o caratteri di sottolineatura.This must be unique within the runbook, and can contain only letters, numbers, or underscore characters. Deve iniziare con una lettera.It must start with a letter.
ObbligatorioMandatory Facoltativa.Optional. Specifica se è necessario specificare un valore per il parametro.Specifies whether a value must be provided for the parameter. Se la proprietà è impostata su $true, è necessario specificare un valore quando viene avviato il runbook.If you set this to $true, then a value must be provided when the runbook is started. Se la proprietà è impostata su $false, il valore è facoltativo.If you set this to $false, then a value is optional.
Default valueDefault value Facoltativa.Optional. Specifica un valore che verrà usato per il parametro se non viene passato un valore all'avvio del runbook.Specifies a value that will be used for the parameter if a value is not passed in when the runbook is started. È possibile impostare un valore predefinito per qualsiasi parametro, rendendolo automaticamente facoltativo indipendentemente dall'impostazione della proprietà Mandatory.A default value can be set for any parameter and will automatically make the parameter optional regardless of the Mandatory setting.

Windows PowerShell supporta più attributi dei parametri di input di quelli elencati di seguito, ad esempio la convalida, gli alias e i set di parametri.Windows PowerShell supports more attributes of input parameters than those listed here, like validation, aliases, and parameter sets. Tuttavia, Automazione di Azure attualmente supporta solo i parametri di input sopra elencati.However, Azure Automation currently supports only the input parameters listed above.

Una definizione di parametri nei runbook del flusso di lavoro PowerShell ha il formato generale seguente, in cui più parametri sono separati da virgole.A parameter definition in PowerShell Workflow runbooks has the following general form, where multiple parameters are separated by commas.

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

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

Nota

Quando si definiscono i parametri, se non si specifica l'attributo Mandatory , il parametro è considerato facoltativo per impostazione predefinita.When you're defining parameters, if you don’t specify the Mandatory attribute, then by default, the parameter is considered optional. Se si imposta un valore predefinito per un parametro nei runbook del flusso di lavoro PowerShell, il parametro verrà considerato come facoltativo da PowerShell, indipendentemente dal valore dell'attributo Mandatory.Also, if you set a default value for a parameter in PowerShell Workflow runbooks, it will be treated by PowerShell as an optional parameter, regardless of the Mandatory attribute value.

Come esempio, di seguito vengono configurati i parametri di input per un runbook del flusso di lavoro PowerShell che restituisce informazioni dettagliate su macchine virtuali, che si tratti di una singola VM o di tutte le VM all'interno di un gruppo di risorse.As an example, let’s configure the input parameters for a PowerShell Workflow runbook that outputs details about virtual machines, either a single VM or all VMs within a resource group. Questo runbook ha due parametri, come illustrato nella schermata seguente: il nome della macchina virtuale e il nome del gruppo di risorse.This runbook has two parameters as shown in the following screenshot: the name of virtual machine and the name of the resource group.

Flusso di lavoro PowerShell di Automazione

In questa definizione di parametro i parametri $VMName e $resourceGroupName sono semplici parametri di tipo stringa.In this parameter definition, the parameters $VMName and $resourceGroupName are simple parameters of type string. I runbook di PowerShell e del flusso di lavoro PowerShell supportano tuttavia tutti i tipi semplici e complessi, ad esempio object o PSCredential per i parametri di input.However, PowerShell and PowerShell Workflow runbooks support all simple types and complex types, such as object or PSCredential for input parameters.

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).If your runbook has an object type input parameter, then use a PowerShell hashtable with (name,value) pairs to pass in a value. Ad esempio, se si ha questo parametro in un runbook:For example, if you have the following parameter in a runbook:

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

è possibile passare il valore seguente al parametro:Then you can pass the following value to the parameter:

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

Configurare i parametri di input in runbook graficiConfigure input parameters in graphical runbooks

Per configurare un runbook grafico con parametri di input, verrà creato un runbook grafico che restituisce informazioni dettagliate su macchine virtuali, che si tratti di una singola macchina virtuale o di tutte le macchine virtuali all'interno di un gruppo di risorse.To configure a graphical runbook with input parameters, let’s create a graphical runbook that outputs details about virtual machines, either a single VM or all VMs within a resource group. La configurazione di un runbook è costituita da due attività principali, come descritto di seguito.Configuring a runbook consists of two major activities, as described below.

Autenticare runbook con account RunAs di Azure per l'autenticazione con Azure.Authenticate Runbooks with Azure Run As account to authenticate with Azure.

Get-AzureRmVm per leggere le proprietà di una macchina virtuale.Get-AzureRmVm to get the properties of a virtual machines.

È possibile usare l'attività Write-Output per restituire i nomi delle macchine virtuali.You can use the Write-Output activity to output the names of virtual machines. L'attività Get-AzureRmVm accetta due parametri: il nome della macchina virtuale and the nome del gruppo di risorse.The activity Get-AzureRmVm accepts two parameters, the virtual machine name and the resource group name. Dal momento che questi parametri potrebbero richiedere valori diversi ogni volta che si avvia il runbook, è possibile aggiungere parametri di input al runbook.Since these parameters could require different values each time you start the runbook, you can add input parameters to your runbook. Per aggiungere parametri di input, seguire questa procedura:Here are the steps to add input parameters:

  1. Selezionare il runbook grafico nel pannello Runbook e fare clic su Modifica.Select the graphical runbook from the Runbooks blade and then click Edit it.
  2. Nell'editor dei runbook fare clic su Input e output per aprire il pannello Input e output.From the runbook editor, click Input and output to open the Input and output blade.

    Runbook grafico di Automazione

  3. Il pannello Input e output mostra un elenco di parametri di input definiti per il runbook.The Input and output blade displays a list of input parameters that are defined for the runbook. In questo pannello è possibile aggiungere un nuovo parametro di input o modificare la configurazione di un parametro di input esistente.On this blade, you can either add a new input parameter or edit the configuration of an existing input parameter. Per aggiungere un nuovo parametro per il runbook, fare clic su Aggiungi input per aprire il pannello Parametro di input runbook,To add a new parameter for the runbook, click Add input to open the Runbook input parameter blade. in cui è possibile configurare i parametri seguenti:There, you can configure the following parameters:

    ProprietàProperty DescrizioneDescription
    NomeName Obbligatoria.Required. Nome del parametro.The name of the parameter. Questo valore deve essere univoco all'interno del runbook e può contenere solo lettere, numeri o caratteri di sottolineatura.This must be unique within the runbook, and can contain only letters, numbers, or underscore characters. Deve iniziare con una lettera.It must start with a letter.
    DescrizioneDescription Facoltativa.Optional. Descrizione dello scopo del parametro di input.Description about the purpose of input parameter.
    TypeType Facoltativa.Optional. Tipo di dati previsto per il valore del parametro.The data type that's expected for the parameter value. I tipi di parametro supportati sono String, Int32, Int64, Decimal, Boolean, DateTime e Object.Supported parameter types are String, Int32, Int64, Decimal, Boolean, DateTime, and Object. Se non è selezionato un tipo di dati, l'impostazione predefinita è String.If a data type is not selected, it defaults to String.
    ObbligatorioMandatory Facoltativa.Optional. Specifica se è necessario specificare un valore per il parametro.Specifies whether a value must be provided for the parameter. Se si sceglie , è necessario specificare un valore quando viene avviato il runbook.If you choose yes, then a value must be provided when the runbook is started. Se si sceglie No, non è necessario specificare un valore all'avvio del runbook ed è possibile impostare un valore predefinito.If you choose no, then a value is not required when the runbook is started, and a default value may be set.
    Default valueDefault Value Facoltativa.Optional. Specifica un valore che verrà usato per il parametro se non viene passato un valore all'avvio del runbook.Specifies a value that will be used for the parameter if a value is not passed in when the runbook is started. È possibile impostare un valore predefinito per un parametro non obbligatorio.A default value can be set for a parameter that's not mandatory. Per impostare un valore predefinito, scegliere Personalizzato.To set a default value, choose Custom. Questo valore viene usato a meno che non venga specificato un altro valore all'avvio del runbook.This value is used unless another value is provided when the runbook is started. Scegliere Nessuno se non si vuole specificare alcun valore predefinito.Choose None if you don’t want to provide any default value.

    Aggiunta di nuovo input

  4. Creare due parametri con le proprietà seguenti che verranno usate dall'attività Get-AzureRmVm:Create two parameters with the following properties that will be used by the Get-AzureRmVm activity:

    • Parametro 1:Parameter1:

      • Nome: VMNameName - VMName
      • Tipo: StringType - String
      • Obbligatorio: noMandatory - No
    • Parametro2:Parameter2:

      • Nome: resourceGroupNameName - resourceGroupName
      • Tipo: StringType - String
      • Obbligatorio: noMandatory - No
      • Valore predefinito: personalizzatoDefault value - Custom
      • Valore predefinito personalizzato: < nome del gruppo di risorse che contiene le macchine virtuali>.Custom default value - <Name of the resource group that contains the virtual machines>
  5. Dopo aver aggiunto i parametri, fare clic su OK.Once you add the parameters, click OK. Ora è possibile visualizzarli nel pannello Input e output.You can now view them in the Input and output blade. Fare nuovamente clic su OK, quindi su Salva e pubblicare il runbook.Click OK again, and then click Save and Publish your runbook.

Configurare i parametri di input in runbook di PythonConfigure input parameters in Python runbooks

A differenza dei runbook grafici, di PowerShell e del flusso di lavoro di PowerShell, i runbook di Python non accettano parametri denominati.Unlike PowerShell, PowerShell Workflow, and Graphical runbooks, Python runbooks do not take named parameters. Tutti i parametri di input vengono analizzati come matrice di valori di argomento.All input parameters are parsed as an array of argument values. Accedere alla matrice importando il sys modulo nelle script Python e quindi usando la matrice sys.argv.You access the array by importing the sys module into your Python script, and then using the sys.argv array. È importante notare che il primo elemento della matrice, sys.argv[0], è il nome dello script, pertanto il primo parametro di input effettivo è sys.argv[1].It is important to note that the first element of the array, sys.argv[0], is the name of the script, so the first actual input parameter is 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.For an example of how to use input parameters in a Python runbook, see My first Python runbook in Azure Automation.

Assegnare valori ai parametri di input nei runbookAssign values to input parameters in runbooks

È possibile passare valori ai parametri di input nei runbook negli scenari illustrati di seguito.You can pass values to input parameters in runbooks in the following scenarios.

Avviare un runbook e assegnare parametriStart a runbook and assign parameters

Ci sono diversi modi per avviare un runbook: dal portale di Azure, con un webhook, con i cmdlet di PowerShell, con l'API REST o con l'SDK.A runbook can be started many ways: through the Azure portal, with a webhook, with PowerShell cmdlets, with the REST API, or with the SDK. Di seguito vengono illustrati vari metodi per avviare un runbook e assegnare parametri.Below we discuss different methods for starting a runbook and assigning parameters.

Avviare un runbook pubblicato usando il portale di Azure e assegnare parametriStart a published runbook by using the Azure portal and assign parameters

Quando si avvia il runbook, viene aperto il pannello Avvia runbook ed è possibile immettere i valori per i parametri appena creati.When you start the runbook, the Start Runbook blade opens and you can enter values for the parameters that you just created.

Attività iniziali con il portale

Nell'etichetta sotto la casella di input è possibile visualizzare gli attributi impostati per il parametro.In the label beneath the input box, you can see the attributes that have been set for the parameter. Gli attributi includono obbligatorio o facoltativo, tipo e valore predefinito.Attributes include mandatory or optional, type, and default value. Nel fumetto della Guida accanto al nome del parametro sono disponibili tutte le informazioni chiave necessarie per scegliere i valori dei parametri di input,In the help balloon next to the parameter name, you can see all the key information you need to make decisions about parameter input values. Queste informazioni indicano se un parametro è obbligatorio o facoltativo.This information includes whether a parameter is mandatory or optional. Includono inoltre il tipo e il valore predefinito (se presente) e altre note utili.It also includes the type and default value (if any), and other helpful notes.

Fumetto della Guida

Nota

I parametri di tipo String supportano valori di stringa vuoti .String type parameters support Empty String values. Immettendo [EmptyString] nella casella del parametro di input viene passata una stringa vuota al parametro.Entering [EmptyString] in the input parameter box will pass an empty string to the parameter. I parametri di tipo String non supportano il passaggio di valori Null .Also, String type parameters don’t support Null values being passed. Se non viene passato alcun valore al parametro String, PowerShell lo interpreterà come Null.If you don’t pass any value to the String parameter, then PowerShell will interpret it as null.

Avviare un runbook pubblicato usando i cmdlet di PowerShell e assegnare parametriStart a published runbook by using PowerShell cmdlets and assign parameters

  • Cmdlet di Azure Resource Manager: è possibile avviare un runbook di Automazione creato in un gruppo di risorse usando Start-AzureRmAutomationRunbook.Azure Resource Manager cmdlets: You can start an Automation runbook that was created in a resource group by using Start-AzureRmAutomationRunbook.

    Esempio:Example:

    $params = @{“VMName”=”WSVMClassic”;”resourceGroupeName”=”WSVMClassicSG”}
    
    Start-AzureRmAutomationRunbook -AutomationAccountName “TestAutomation” -Name “Get-AzureVMGraphical” –ResourceGroupName $resourceGroupName -Parameters $params
    
  • Cmdlet di Gestione dei servizi di Azure: è possibile avviare un runbook di automazione creato in un gruppo di risorse predefinito usando Start-AzureAutomationRunbook.Azure Service Management cmdlets: You can start an automation runbook that was created in a default resource group by using Start-AzureAutomationRunbook.

    Esempio:Example:

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

Nota

Quando si avvia un runbook con i cmdlet di PowerShell viene creato un parametro predefinito, MicrosoftApplicationManagementStartedBy, con il valore PowerShell.When you start a runbook by using PowerShell cmdlets, a default parameter, MicrosoftApplicationManagementStartedBy is created with the value PowerShell. Questo parametro può essere visualizzato nel pannello Dettagli processo .You can view this parameter in the Job details blade.

Avviare un runbook usando un SDK e assegnare parametriStart a runbook by using an SDK and assign parameters

  • Metodo di Azure Resource Manager: è possibile avviare un runbook usando l'SDK di un linguaggio di programmazione.Azure Resource Manager method: You can start a runbook by using the SDK of a programming language. Di seguito è riportato un frammento di codice C# per l'avvio di un runbook nell'account di automazione.Below is a C# code snippet for starting a runbook in your Automation account. È possibile visualizzare tutto il codice nel repository GitHub.You can view all the code at our GitHub repository.

     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 di gestione del servizio Azure: è possibile avviare un runbook usando l'SDK di un linguaggio di programmazione.Azure Service Management method: You can start a runbook by using the SDK of a programming language. Di seguito è riportato un frammento di codice C# per l'avvio di un runbook nell'account di automazione.Below is a C# code snippet for starting a runbook in your Automation account. È possibile visualizzare tutto il codice nel repository GitHub.You can view all the code at our GitHub repository.

    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 parametri del runbook, VMName e resourceGroupName, e i relativi valori.To start this method, create a dictionary to store the runbook parameters, VMName and resourceGroupName, and their values. Avviare quindi il runbook.Then start the runbook. Di seguito è riportato un frammento di codice C# per chiamare il metodo definito in precedenza.Below is the C# code snippet for calling the method that's defined above.

    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 parametriStart a runbook by using the REST API and assign parameters

È 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.A runbook job can be created and started with the Azure Automation REST API by using the PUT method with the following request URI.

https://management.core.windows.net/<subscription-id>/cloudServices/<cloud-service-name>/resources/automation/~/automationAccounts/<automation-account-name>/jobs/<job-id>?api-version=2014-12-08`

Nell'URI della richiesta sostituire i parametri seguenti:In the request URI, replace the following parameters:

  • subscription-id: ID della sottoscrizione di Azure.subscription-id: Your Azure subscription ID.
  • cloud-service-name: nome del servizio cloud a cui deve essere inviata la richiesta.cloud-service-name: The name of the cloud service to which the request should be sent.
  • automation-account-name: nome dell'account di Automazione ospitato nel servizio cloud specificato.automation-account-name: The name of your automation account that's hosted within the specified cloud service.
  • job-id: GUID del processo.job-id: The GUID for the job. Per creare GUID in PowerShell è possibile usare il comando [GUID]::NewGuid().ToString() .GUIDs in PowerShell can be created by using the [GUID]::NewGuid().ToString() command.

Per passare parametri al processo del runbook, usare il corpo della richiesta.In order to pass parameters to the runbook job, use the request body. Vengono usate le due proprietà seguenti, specificate in formato JSON:It takes the following two properties provided in JSON format:

  • Nome del runbook: obbligatorio.Runbook name: Required. Nome del runbook per il processo da avviare.The name of the runbook for the job to start.
  • Parametri del runbook: facoltativi.Runbook parameters: Optional. Dizionario dell'elenco dei parametri in formato (nome, valore) in cui il nome deve essere di tipo String e il valore può essere qualsiasi valore JSON valido.A dictionary of the parameter list in (name, value) format where name should be of String type and value can be any valid JSON value.

Per avviare il runbook Get-AzureVMTextual creato in precedenza con VMName e resourceGroupName come parametri, usare il formato JSON seguente per il corpo della richiesta.If you want to start the Get-AzureVMTextual runbook that was created earlier with VMName and resourceGroupName as parameters, use the following JSON format for the request body.

 {
   "properties":{
     "runbook":{
     "name":"Get-AzureVMTextual"},
   "parameters":{
      "VMName":"WSVMClassic",
      "resourceGroupName":”WSCS1”}
     }
 }

Se il processo è stato creato, viene restituito un codice di stato HTTP 201.A HTTP status code 201 is returned if the job is successfully created. Per altre informazioni su intestazioni di risposta e sul corpo della risposta, vedere l'articolo relativo alla creazione di un processo del runbook tramite l'API REST.For more information on response headers and the response body, refer to the article about how to create a runbook job by using the REST API.

Eseguire il test di un runbook e assegnare parametriTest a runbook and assign parameters

Quando si esegue il test della versione bozza del runbook con l'opzione di test, viene visualizzato il pannello Test in cui è possibile configurare i valori per i parametri appena creati.When you test the draft version of your runbook by using the test option, the Test blade opens and you can configure values for the parameters that you just created.

Esecuzione di test e assegnazione di parametri

È possibile collegare una pianificazione al runbook in modo che venga avviato in un momento specifico.You can link a schedule to your runbook so that the runbook starts at a specific time. Assegnare i parametri di input durante la creazione della pianificazione. Il runbook usa questi valori quando viene avviato dalla pianificazione.You assign input parameters when you create the schedule, and the runbook will use these values when it is started by the schedule. Fino a quando non vengono forniti tutti i valori dei parametri obbligatori non è possibile salvare la pianificazione.You can’t save the schedule until all mandatory parameter values are provided.

Pianificazione e assegnazione di parametri

Creare un webhook per un runbook e assegnare parametriCreate a webhook for a runbook and assign parameters

È possibile creare un webhook per il runbook e configurare i parametri di input del runbook.You can create a webhook for your runbook and configure runbook input parameters. Fino a quando non vengono forniti tutti i valori dei parametri obbligatori non è possibile salvare il webhook.You can’t save the webhook until all mandatory parameter values are provided.

Creazione di webhook e assegnazione di parametri

Quando si esegue un runbook con un webhook, insieme ai parametri di input definiti viene inviato il parametro di input predefinito Webhookdata .When you execute a runbook by using a webhook, the predefined input parameter Webhookdata is sent, along with the input parameters that you defined. È possibile fare clic per espandere il parametro WebhookData e visualizzarne i dettagli.You can click to expand the WebhookData parameter for more details.

Parametro WebhookData

Passaggi successiviNext steps