Konfigurowanie parametrów wejściowych elementu Runbook w usłudze Automation

Parametry wejściowe elementu Runbook zwiększają elastyczność elementu Runbook, umożliwiając przekazywanie danych do niego po uruchomieniu. Te parametry umożliwiają ukierunkowanie akcji elementu Runbook na określone scenariusze i środowiska. W tym artykule opisano konfigurację i użycie parametrów wejściowych w elementach Runbook.

Parametry wejściowe można skonfigurować dla elementów Runbook programu PowerShell, Przepływ pracy programu PowerShell, graficznych i Python. Element Runbook może mieć wiele parametrów z różnymi typami danych lub bez parametrów. Parametry wejściowe mogą być obowiązkowe lub opcjonalne i można użyć wartości domyślnych dla parametrów opcjonalnych.

Wartości są przypisywane do parametrów wejściowych elementu Runbook podczas jego uruchamiania. Element Runbook można uruchomić w witrynie Azure Portal, usłudze internetowej lub programie PowerShell. Można również uruchomić jeden jako podrzędny element Runbook, który jest nazywany wbudowanym elementem Runbook.

Typy danych wejściowych

Usługa Azure Automation obsługuje różne wartości parametrów wejściowych w różnych typach elementów Runbook. Obsługiwane typy danych wejściowych dla każdego typu elementu Runbook są wymienione w poniższej tabeli.

Typ elementu Runbook	Obsługiwane dane wejściowe parametrów
PowerShell	-Ciąg - Security.SecureString - INT32 -Boolean -Datetime -Tablicy - Collections.Hashtable - Management.Automation.SwitchParameter
Przepływ pracy programu PowerShell	-Ciąg - Security.SecureString - INT32 -Boolean -Datetime -Tablicy - Collections.Hashtable - Management.Automation.SwitchParameter
Graficzny program PowerShell	-Ciąg - INT32 - INT64 -Boolean -Dziesiętnych -Datetime -Obiektu
Python	-Ciąg

Konfigurowanie parametrów wejściowych w elementach runbook programu PowerShell

Elementy Runbook przepływu pracy programu PowerShell i programu PowerShell w usłudze Azure Automation obsługują parametry wejściowe zdefiniowane za pomocą następujących właściwości.

Właściwości	Opis
Type	Wymagany. Typ danych jest oczekiwany dla wartości parametru. Dowolny typ platformy .NET jest prawidłowy.
Nazwisko	Wymagany. Nazwa parametru. Ta nazwa musi być unikatowa w elemecie Runbook, musi zaczynać się literą i może zawierać tylko litery, cyfry lub znaki podkreślenia.
Obowiązkowy	Opcjonalny. Wartość logiczna określa, czy parametr wymaga wartości. W przypadku ustawienia wartości True należy podać wartość po uruchomieniu elementu Runbook. Jeśli ustawisz wartość False, wartość jest opcjonalna. Jeśli nie określisz wartości dla Mandatory właściwości, program PowerShell domyślnie uzna parametr wejściowy za opcjonalny.
Domyślna wartość	Opcjonalny. Wartość używana dla parametru, jeśli podczas uruchamiania elementu Runbook nie jest przekazywana żadna wartość wejściowa. Element Runbook może ustawić wartość domyślną dla dowolnego parametru.

Program Windows PowerShell obsługuje więcej atrybutów parametrów wejściowych niż wymienione powyżej, takie jak walidacja, aliasy i zestawy parametrów. Jednak usługa Azure Automation obecnie obsługuje tylko wymienione właściwości parametru wejściowego.

Na przykład przyjrzyjmy się definicji parametrów w elemecie Runbook przepływu pracy programu PowerShell. Ta definicja ma następującą ogólną formę, w której wiele parametrów jest rozdzielonych przecinkami.

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

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

Teraz skonfigurujemy parametry wejściowe elementu Runbook przepływu pracy programu PowerShell, który generuje szczegółowe informacje o maszynach wirtualnych— jednej maszynie wirtualnej lub wszystkich maszynach wirtualnych w grupie zasobów. Ten element Runbook ma dwa parametry, jak pokazano na poniższym zrzucie ekranu: nazwa maszyny wirtualnej (VMName) i nazwa grupy zasobów (resourceGroupName).

W tej definicji parametrów parametry wejściowe są prostymi parametrami ciągu typu.

Należy pamiętać, że elementy Runbook przepływu pracy programu PowerShell i programu PowerShell obsługują wszystkie proste typy i typy złożone, takie jak Object lub PSCredential dla parametrów wejściowych. Jeśli element Runbook ma parametr wejściowy obiektu, należy użyć tabeli skrótowej programu PowerShell z parami name-value, aby przekazać wartość. Na przykład w elemecie Runbook jest następujący parametr.

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

W takim przypadku można przekazać następującą wartość do parametru .

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

W przypadku elementów Runbook programu PowerShell 7.1 podaj parametry wejściowe tablicy w poniższym formacie:

Nazwa/nazwisko	Wartość
PARAMETR TESTOWY	czy,to,parzysta,praca

Uwaga

Jeśli nie przekazujesz wartości do opcjonalnego parametru String z wartością domyślną o wartości null, wartość parametru jest pustym ciągiem zamiast wartości Null.

Konfigurowanie parametrów wejściowych w graficznych elementach Runbook

Aby zilustrować konfigurację parametrów wejściowych dla graficznego elementu Runbook, utwórzmy element Runbook, który generuje szczegółowe informacje o maszynach wirtualnych— jednej maszynie wirtualnej lub wszystkich maszynach wirtualnych w grupie zasobów. Aby uzyskać szczegółowe informacje, zobacz Mój pierwszy graficzny element Runbook.

Graficzny element Runbook używa następujących głównych działań elementu Runbook:

• Uwierzytelnianie za pomocą platformy Azure przy użyciu tożsamości zarządzanej skonfigurowanej dla konta usługi Automation.
• Definicja polecenia cmdlet Get-AzVM w celu pobrania właściwości maszyny wirtualnej.
• Użyj działania Write-Output w celu wyprowadzenia nazw maszyn wirtualnych.

Działanie Get-AzVM definiuje dwa dane wejściowe, nazwę maszyny wirtualnej i nazwę grupy zasobów. Ponieważ te nazwy mogą być różne przy każdym uruchomieniu elementu Runbook, należy dodać parametry wejściowe do elementu Runbook, aby zaakceptować te dane wejściowe. Zapoznaj się z tematem Graficzne tworzenie w usłudze Azure Automation.

Wykonaj następujące kroki, aby skonfigurować parametry wejściowe.

1. Wybierz graficzny element Runbook na stronie Elementy Runbook, a następnie kliknij przycisk Edytuj.

2. W edytorze graficznym kliknij przycisk Dane wejściowe i wyjściowe , a następnie dodaj dane wejściowe , aby otworzyć okienko Parametr wejściowy elementu Runbook.

   

3. Kontrolka Dane wejściowe i wyjściowe wyświetla listę parametrów wejściowych zdefiniowanych dla elementu Runbook. W tym miejscu możesz dodać nowy parametr wejściowy lub edytować konfigurację istniejącego parametru wejściowego. Aby dodać nowy parametr elementu Runbook, kliknij przycisk Dodaj dane wejściowe , aby otworzyć blok parametru wejściowego elementu Runbook, w którym można skonfigurować parametry przy użyciu właściwości zdefiniowanych w tworzeniu graficznym w usłudze Azure Automation.

   

4. Utwórz dwa parametry z następującymi właściwościami, które mają być używane przez Get-AzVM działanie, a następnie kliknij przycisk OK.

   • Parametr 1:

     • Nazwa maszyny -- wirtualnej
     • Typ — ciąg
     • -- Obowiązkowy nie

   • Parametr 2:

     • Nazwa -- grupy zasobów
     • Typ — ciąg
     • -- Obowiązkowy nie
     • Wartość -- domyślna Niestandardowa
     • Niestandardowa wartość domyślna — nazwa grupy zasobów, która zawiera maszyny wirtualne

5. Wyświetl parametry w kontrolce Dane wejściowe i wyjściowe.

6. Kliknij ponownie przycisk OK , a następnie kliknij przycisk Zapisz.

7. Kliknij pozycję Publikuj, aby opublikować element Runbook.

Konfigurowanie parametrów wejściowych w elementach Runbook języka Python

W przeciwieństwie do programu PowerShell, przepływu pracy programu PowerShell i graficznych elementów runbook, elementy Runbook języka Python nie przyjmują nazwanych parametrów. Edytor elementu Runbook analizuje wszystkie parametry wejściowe jako tablicę wartości argumentów. Dostęp do tablicy można uzyskać, importując sys moduł do skryptu języka Python, a następnie używając tablicy sys.argv . Należy pamiętać, że pierwszy element tablicy , sys.argv[0]to nazwa skryptu. Dlatego pierwszym rzeczywistym parametrem wejściowym jest sys.argv[1].

Przykład użycia parametrów wejściowych w elemecie Runbook języka Python można znaleźć w temacie My first Python runbook in Azure Automation (Mój pierwszy element Runbook języka Python w usłudze Azure Automation).

Uwaga

Argumenty ze spacjami nie są obecnie obsługiwane. Aby obejść ten problem, można użyć \\t oprócz \\n.

Przypisywanie wartości do parametrów wejściowych w elementach Runbook

W tej sekcji opisano kilka sposobów przekazywania wartości do parametrów wejściowych w elementach Runbook. Wartości parametrów można przypisać w następujących przypadkach:

• Uruchamianie elementu Runbook
• Testowanie elementu Runbook
• Łączenie harmonogramu elementu Runbook
• Tworzenie elementu webhook dla elementu Runbook

Uruchamianie elementu Runbook i przypisywanie parametrów

Element Runbook można uruchomić na wiele sposobów: za pośrednictwem witryny Azure Portal, z elementem webhook, poleceniami cmdlet programu PowerShell, interfejsem API REST lub zestawem SDK.

Uruchamianie opublikowanego elementu Runbook przy użyciu witryny Azure Portal i przypisywanie parametrów

Po uruchomieniu elementu Runbook w witrynie Azure Portal zostanie otwarty blok Uruchom element Runbook i możesz wprowadzić wartości dla utworzonych parametrów.

W etykiecie pod polem wejściowym można zobaczyć właściwości, które zostały ustawione do definiowania atrybutów parametrów, na przykład obowiązkowych lub opcjonalnych, typ, wartość domyślna. Dymek pomocy obok nazwy parametru definiuje również kluczowe informacje potrzebne do podejmowania decyzji dotyczących wartości wejściowych parametrów.

Uwaga

Parametry ciągu obsługują puste wartości typu Ciąg. Wprowadzenie [EmptyString] w polu parametru wejściowego przekazuje pusty ciąg do parametru. Ponadto parametry ciągu nie obsługują wartości Null. Jeśli nie przekażesz żadnej wartości do parametru ciągu, program PowerShell interpretuje ją jako null.

Uruchamianie opublikowanego elementu Runbook przy użyciu poleceń cmdlet programu PowerShell i przypisywanie parametrów

• Polecenia cmdlet usługi Azure Resource Manager: możesz uruchomić element runbook usługi Automation utworzony w grupie zasobów przy użyciu polecenia Start-AzAutomationRunbook.

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

• Polecenia cmdlet klasycznego modelu wdrażania platformy Azure: możesz uruchomić element Runbook automatyzacji, który został utworzony w domyślnej grupie zasobów przy użyciu elementu Start-AzureAutomationRunbook.

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

Uwaga

Po uruchomieniu elementu Runbook przy użyciu poleceń cmdlet programu PowerShell domyślny parametr MicrosoftApplicationManagementStartedBy, jest tworzony z wartością PowerShell. Ten parametr można wyświetlić w okienku Szczegóły zadania.

Uruchamianie elementu Runbook przy użyciu zestawu SDK i przypisywanie parametrów

• Metoda usługi Azure Resource Manager: element Runbook można uruchomić przy użyciu zestawu SDK języka programowania. Poniżej znajduje się fragment kodu języka C# umożliwiający uruchamianie elementu Runbook na koncie usługi Automation. Cały kod można wyświetlić w naszym repozytorium 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;
  }
  

• Klasyczna metoda modelu wdrażania platformy Azure: element Runbook można uruchomić przy użyciu zestawu SDK języka programowania. Poniżej znajduje się fragment kodu języka C# umożliwiający uruchamianie elementu Runbook na koncie usługi Automation. Cały kod można wyświetlić w naszym repozytorium 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;
  }
  

  Aby uruchomić tę metodę, utwórz słownik do przechowywania parametrów VMName elementu Runbook i resourceGroupName ich wartości. Następnie uruchom element Runbook. Poniżej znajduje się fragment kodu języka C# do wywoływania metody zdefiniowanej powyżej.

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

Uruchamianie elementu Runbook przy użyciu interfejsu API REST i przypisywanie parametrów

Zadanie elementu Runbook można utworzyć i uruchomić za pomocą interfejsu API REST usługi Azure Automation przy użyciu PUT metody z następującym identyfikatorem URI żądania: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

W identyfikatorze URI żądania zastąp następujące parametry:

• subscriptionId: Identyfikator subskrypcji platformy Azure.
• resourceGroupName: nazwa grupy zasobów dla konta usługi Automation.
• automationAccountName: nazwa konta usługi Automation hostowanego w określonej usłudze w chmurze.
• jobName: identyfikator GUID zadania. Identyfikatory GUID w programie PowerShell można utworzyć przy użyciu polecenia [GUID]::NewGuid().ToString()*.

Aby przekazać parametry do zadania elementu Runbook, użyj treści żądania. Przyjmuje następujące informacje podane w formacie JSON:

• Nazwa elementu Runbook: wymagane. Nazwa elementu Runbook, który ma zostać uruchomiony.
• Parametry elementu Runbook: opcjonalne. Słownik listy parametrów w formacie (nazwa, wartość), gdzie nazwa jest typu Ciąg i wartość może być dowolną prawidłową wartością JSON.

Jeśli chcesz uruchomić utworzony wcześniej element Runbook Get-AzureVMTextual z parametrami VMName i resourceGroupName jako, użyj następującego formatu JSON dla treści żądania.

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

Jeśli zadanie zostało pomyślnie utworzone, zostanie zwrócony kod stanu HTTP 201. Aby uzyskać więcej informacji na temat nagłówków odpowiedzi i treści odpowiedzi, zobacz tworzenie zadania elementu Runbook przy użyciu interfejsu API REST.

Testowanie elementu Runbook i przypisywanie parametrów

Po przetestowaniu wersji roboczej elementu Runbook przy użyciu opcji testu zostanie otwarta strona Test. Ta strona służy do konfigurowania wartości utworzonych parametrów.

Łączenie harmonogramu z elementem Runbook i przypisywanie parametrów

Możesz połączyć harmonogram z elementem Runbook, aby element Runbook był uruchamiany w określonym czasie. Parametry wejściowe są przypisywane podczas tworzenia harmonogramu, a element Runbook używa tych wartości podczas jego uruchamiania zgodnie z harmonogramem. Nie można zapisać harmonogramu, dopóki nie zostaną podane wszystkie obowiązkowe wartości parametrów.

Tworzenie elementu webhook dla elementu Runbook i przypisywanie parametrów

Możesz utworzyć element webhook dla elementu Runbook i skonfigurować parametry wejściowe elementu Runbook. Nie można zapisać elementu webhook, dopóki nie zostaną podane wszystkie obowiązkowe wartości parametrów.

Podczas wykonywania elementu Runbook przy użyciu elementu webhook jest wysyłany wstępnie zdefiniowany parametr [WebhookData](automation-webhooks.md) wejściowy wraz z zdefiniowanymi parametrami wejściowymi.

Przekazywanie obiektu JSON do elementu runbook

Przydatne może być przechowywanie danych, które chcesz przekazać do elementu Runbook w pliku JSON. Możesz na przykład utworzyć plik JSON zawierający wszystkie parametry, które chcesz przekazać do elementu Runbook. W tym celu należy przekonwertować kod JSON na ciąg, a następnie przekonwertować ciąg na obiekt programu PowerShell przed przekazaniem go do elementu Runbook.

W tej sekcji użyto przykładu, w którym skrypt programu PowerShell wywołuje element Start-AzAutomationRunbook w celu uruchomienia elementu Runbook programu PowerShell, przekazując zawartość pliku JSON do elementu Runbook. Element Runbook programu PowerShell uruchamia maszynę wirtualną platformy Azure, pobierając parametry maszyny wirtualnej z obiektu JSON.

Tworzenie pliku JSON

Wpisz następujący kod w pliku tekstowym i zapisz go jako plik test.json gdzieś na komputerze lokalnym.

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

Tworzenie elementu Runbook

Utwórz nowy element Runbook programu PowerShell o nazwie Test-Json w usłudze Azure Automation.

Aby zaakceptować dane JSON, element Runbook musi przyjąć obiekt jako parametr wejściowy. Element Runbook może następnie używać właściwości zdefiniowanych w pliku 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

Jeśli chcesz, aby element Runbook był wykonywany przy użyciu tożsamości zarządzanej przypisanej przez system, pozostaw kod w stanie rzeczywistym. Jeśli wolisz użyć tożsamości zarządzanej przypisanej przez użytkownika, wykonaj:

1. Z wiersza 10 usuń element $AzureContext = (Connect-AzAccount -Identity).context,
2. Zastąp go ciągiem $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, i
3. Wprowadź identyfikator klienta.

Zapisz i opublikuj ten element Runbook na koncie usługi Automation.

Wywoływanie elementu Runbook z poziomu programu PowerShell

Teraz możesz wywołać element Runbook z komputera lokalnego przy użyciu programu Azure PowerShell.

1. Zaloguj się do platformy Azure, jak pokazano poniżej. Następnie zostanie wyświetlony monit o wprowadzenie poświadczeń platformy Azure.

   Connect-AzAccount
   

   Uwaga

   W przypadku elementów Runbook Add-AzAccount programu PowerShell i Add-AzureRMAccount są aliasami dla programu Connect-AzAccount. Należy pamiętać, że te aliasy nie są dostępne dla graficznych elementów Runbook. Graficzny element Runbook może używać Connect-AzAccount tylko samego siebie.

2. Pobierz zawartość zapisanego pliku JSON i przekonwertuj go na ciąg. JsonPath wskazuje ścieżkę, w której zapisano plik JSON.

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

3. Przekonwertuj zawartość ciągu na $json obiekt programu PowerShell.

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

4. Utwórz tabelę skrótu dla parametrów dla elementu Start-AzAutomationRunbook.

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

   Zwróć uwagę, że ustawiasz wartość Parameters dla obiektu programu PowerShell, który zawiera wartości z pliku JSON.

5. Uruchom element Runbook.

   $job = Start-AzAutomationRunbook @RBParams
   

Następne kroki

• Aby przygotować tekstowy element Runbook, zobacz Edytowanie tekstowych elementów Runbook w usłudze Azure Automation.
• Aby przygotować graficzny element Runbook, zobacz Tworzenie graficznych elementów Runbook w usłudze Azure Automation.