Mengonfigurasi parameter input runbook di Automation

Parameter input runbook meningkatkan fleksibilitas runbook dengan memungkinkan data diteruskan ke dalamnya saat dimulai. Parameter ini memungkinkan tindakan runbook ditargetkan untuk skenario dan lingkungan tertentu. Artikel ini menjelaskan konfigurasi dan penggunaan parameter input dalam runbook Anda.

Anda dapat mengonfigurasi parameter input untuk runbook PowerShell, PowerShell Workflow, grafis, dan Python. Runbook dapat memiliki beberapa parameter dengan jenis data yang berbeda atau tanpa parameter. Parameter input dapat bersifat wajib atau opsional, dan Anda dapat menggunakan nilai default untuk parameter opsional.

Anda menetapkan nilai ke parameter input untuk runbook saat Anda memulainya. Anda dapat memulai runbook dari portal Microsoft Azure, layanan web, atau PowerShell. Anda juga dapat memulainya sebagai runbook turunan yang dipanggil inline di runbook lain.

Jenis input

Azure Automation mendukung berbagai nilai parameter input di berbagai jenis runbook. Jenis input yang didukung untuk setiap jenis runbook tercantum dalam tabel berikut.

Jenis runbook	Input parameter yang didukung
PowerShell	-String - Security.SecureString - INT32 -Boolean -Datetime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell Workflow	-String - Security.SecureString - INT32 -Boolean -Datetime -Array - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell Grafis	-String - INT32 - INT64 -Boolean -Desimal -Datetime -Objek
Python	-String

Mengonfigurasi parameter input dalam runbook PowerShell

Runbook PowerShell dan PowerShell Workflow di Azure Automation mendukung parameter input yang ditentukan melalui properti berikut ini.

Properti	Keterangan
Jenis	Harus diisi. Jenis data diharapkan untuk nilai parameter. Jenis .NET apa pun valid.
Nama	Harus diisi. Nama parameter. Nama ini harus unik dalam runbook, harus dimulai dengan huruf, dan hanya dapat berisi huruf, angka, atau karakter garis bawah.
Wajib	Opsional. Nilai Boolean menentukan apakah parameter memerlukan nilai. Jika Anda mengatur ini ke True, nilai harus disediakan saat runbook dimulai. Jika Anda mengatur ini ke False, nilai bersifat opsional. Jika Anda tidak menentukan nilai untuk properti Mandatory, PowerShell akan mempertimbangkan parameter input opsional secara default.
Nilai default	Opsional. Nilai yang digunakan untuk parameter jika tidak ada nilai input yang diteruskan saat runbook dimulai. Runbook dapat menetapkan nilai default untuk parameter apa pun.

Windows PowerShell mendukung lebih banyak atribut parameter input dibanding yang tercantum di atas, seperti validasi, alias, dan set parameter. Namun, Azure Automation saat ini hanya mendukung properti parameter input yang tercantum.

Sebagai contoh, mari kita lihat definisi parameter dalam runbook PowerShell Workflow. Definisi ini memiliki bentuk umum berikut, dengan beberapa parameter dipisahkan oleh koma.

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

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

Sekarang, mari kita konfigurasi parameter input untuk runbook PowerShell Workflow yang menghasilkan detail tentang komputer virtual, baik VM tunggal atau semua VM dalam grup sumber daya. Runbook ini memiliki dua parameter, seperti yang ditunjukkan pada cuplikan layar berikut: nama komputer virtual (VMName) dan nama grup sumber daya (resourceGroupName).

Dalam definisi parameter ini, parameter input adalah parameter sederhana dari string jenis.

Perhatikan bahwa runbook PowerShell dan PowerShell Workflow mendukung semua jenis sederhana dan jenis kompleks, seperti Object atau PSCredential untuk parameter input. Jika runbook Anda memiliki parameter input objek, Anda harus menggunakan hashtable PowerShell dengan pasangan nama-nilai untuk meneruskan nilai. Misalnya, Anda memiliki parameter berikut dalam runbook.

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

Dalam hal ini, Anda dapat meneruskan nilai berikut ke parameter.

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

Untuk runbook PowerShell 7.1, berikan parameter input array dalam format di bawah ini:

Nama	Nilai
TESTPARAMETER	apakah, ini, bahkan, bekerja

Catatan

Ketika Anda tidak meneruskan nilai ke parameter String opsional dengan nilai default null, nilai parameter adalah string kosong, bukan Null.

Mengonfigurasi parameter input dalam runbook grafis

Untuk mengilustrasikan konfigurasi parameter input untuk runbook grafis, mari kita buat runbook yang menghasilkan detail tentang komputer virtual, baik VM tunggal atau semua VM dalam grup sumber daya. Untuk detailnya, lihat Runbook grafis pertama saya.

Runbook grafis menggunakan aktivitas runbook utama ini:

• Autentikasi dengan Azure menggunakan identitas terkelola yang dikonfigurasi untuk akun otomatisasi.
• Definisi cmdlet Get-AzVM untuk mendapatkan properti VM.
• Penggunaan aktivitas Write-Output untuk menghasilkan nama VM.

Aktivitas Get-AzVM mendefinisikan dua input, nama VM dan nama grup sumber daya. Karena nama-nama ini dapat berbeda setiap kali runbook dimulai, Anda harus menambahkan parameter input ke runbook Anda untuk menerima input ini. Lihat Penulisan grafis di Azure Automation.

Ikuti langkah-langkah ini untuk mengonfigurasi parameter input.

1. Pilih runbook grafis dari halaman Runbooks lalu klik Edit.

2. Di editor grafis, klik tombol Input dan output lalu Tambahkan input untuk membuka panel Parameter Input Runbook.

   

3. Kontrol Input dan Output menampilkan daftar parameter input yang didefinisikan untuk runbook. Di sini, Anda dapat menambahkan parameter input baru atau mengedit konfigurasi parameter input yang ada. Untuk menambahkan parameter baru untuk runbook, klik Tambahkan input untuk membuka panel parameter input Runbook, tempat Anda dapat mengonfigurasi parameter menggunakan properti yang ditentukan dalam Penulisan grafis di Azure Automation.

   

4. Buat dua parameter dengan properti berikut yang akan digunakan oleh aktivitas Get-AzVM, lalu klik OK.

   • Parameter 1:

     • Nama -- VMName
     • Jenis -- String
     • Wajib -- No

   • Parameter 2:

     • Nama -- resourceGroupName
     • Jenis -- String
     • Wajib -- No
     • Nilai default -- Kustom
     • Nilai default kustom -- Nama grup sumber daya yang berisi VM

5. Lihat parameter dalam kontrol Input dan Output.

6. Klik OK lagi, lalu klik Simpan.

7. Klik Terbitkan untuk menerbitkan runbook Anda.

Mengonfigurasi parameter input dalam runbook Python

Tidak seperti runbook PowerShell, PowerShell Workflow, dan grafis, runbook Python tidak mengambil parameter bernama. Editor runbook menguraikan semua parameter input sebagai array nilai argumen. Anda dapat mengakses array dengan mengimpor modul sys ke dalam skrip Python Anda, lalu menggunakan array sys.argv. Penting untuk dicatat bahwa elemen pertama dari array, sys.argv[0], adalah nama skrip. Oleh karena itu, parameter input aktual pertama adalah sys.argv[1].

Untuk contoh cara menggunakan parameter input dalam runbook Python, lihat Runbook Python pertama saya di Azure Automation.

Catatan

Argumen dengan spasi saat ini tidak didukung. Sebagai solusinya, Anda dapat menggunakan \\t selain \\n.

Menetapkan nilai untuk parameter input dalam runbook

Bagian ini menjelaskan beberapa cara untuk meneruskan nilai ke parameter input dalam runbook. Anda dapat menetapkan nilai parameter saat Anda:

• Memulai runbook
• Menguji runbook
• Menautkan jadwal untuk runbook
• Membuat webhook untuk runbook

Memulai runbook dan menetapkan parameter

Runbook dapat dimulai dengan banyak cara: melalui portal Microsoft Azure, dengan webhook, dengan cmdlet PowerShell, dengan REST API, atau dengan SDK.

Memulai runbook yang diterbitkan menggunakan portal Microsoft Azure dan menetapkan parameter

Saat Anda memulai runbook di portal Microsoft Azure, bilah Mulai Runbook terbuka dan Anda dapat memasukkan nilai untuk parameter yang telah Anda buat.

Dalam label di bawah kotak input, Anda dapat melihat properti yang telah diatur untuk menentukan atribut parameter, misalnya, wajib atau opsional, jenis, nilai default. Balon bantuan di samping nama parameter juga menentukan informasi utama yang diperlukan untuk membuat keputusan tentang nilai input parameter.

Catatan

Parameter string mendukung nilai kosong dari jenis String. Memasukkan [EmptyString] dalam kotak parameter input akan meneruskan string kosong ke parameter. Selain itu, parameter string tidak mendukung Null. Jika Anda tidak meneruskan nilai apa pun ke parameter string, PowerShell akan menginterpretasikannya sebagai Null.

Memulai runbook yang diterbitkan menggunakan cmdlet PowerShell dan menetapkan parameter

• cmdlet Azure Resource Manager: Anda dapat memulai runbook Automation yang dibuat dalam grup sumber daya menggunakan Start-AzAutomationRunbook.

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

• cmdlet model penyebaran klasik Azure: Anda dapat memulai runbook Automation yang dibuat di grup sumber daya default menggunakan Start-AzureAutomationRunbook.

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

Catatan

Saat Anda memulai runbook menggunakan cmdlet PowerShell, parameter default, MicrosoftApplicationManagementStartedBy, dibuat dengan nilai PowerShell. Anda dapat menampilkan parameter ini pada panel Detail pekerjaan.

Memulai runbook menggunakan SDK dan menetapkan parameter

• Metode Azure Resource Manager: Anda dapat memulai runbook menggunakan SDK bahasa pemrograman. Di bawah ini adalah cuplikan kode C# untuk memulai runbook di akun Automation Anda. Anda dapat melihat semua kode di repositori GitHub kami.

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

• Metode model penerapan klasik Azure: Anda dapat memulai runbook menggunakan SDK bahasa pemrograman. Di bawah ini adalah cuplikan kode C# untuk memulai runbook di akun Automation Anda. Anda dapat melihat semua kode di repositori GitHub kami.

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

  Untuk memulai metode ini, buat kamus VMName untuk menyimpan parameter runbook dan resourceGroupName nilainya. Lalu, mulai runbook. Di bawah ini adalah cuplikan kode C# untuk memanggil metode yang ditentukan di atas.

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

Memulai runbook menggunakan REST API dan menetapkan parameter

Anda dapat membuat dan memulai pekerjaan runbook dengan Azure Automation REST API menggunakan metode PUT dengan permintaan URI berikut: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

Dalam permintaan URI, ganti parameter berikut:

• subscriptionId: ID langganan Azure Anda.
• resourceGroupName: Nama grup sumber daya untuk akun Automation.
• automationAccountName: Nama akun Automation yang di-host dalam layanan cloud yang ditentukan.
• jobName: GUID untuk pekerjaan tersebut. GUID di PowerShell dapat dibuat menggunakan [GUID]::NewGuid().ToString()*.

Untuk meneruskan parameter ke pekerjaan runbook, gunakan isi permintaan. Ini membutuhkan informasi berikut, yang disediakan dalam format JSON:

• Nama runbook: Wajib diisi. Nama runbook untuk memulai pekerjaan.
• Parameter runbook: Opsional. Dictionary daftar parameter dalam format (nama, nilai), saat nama adalah dari jenis String dan nilai dapat menjadi nilai JSON yang valid.

Jika Anda ingin memulai runbook Get-AzureVMTextual yang dibuat sebelumnya dengan VMName dan resourceGroupName sebagai parameter, gunakan format JSON berikut untuk badan permintaan.

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

Kode status HTTP 201 dikembalikan jika pekerjaan berhasil dibuat. Untuk informasi selengkapnya tentang header respons dan isi respons, lihat membuat pekerjaan runbook menggunakan REST API.

Menguji runbook dan menetapkan parameter

Saat Anda menguji versi draf runbook menggunakan opsi uji, halaman Pengujian terbuka. Gunakan halaman ini untuk mengonfigurasi nilai untuk parameter yang telah Anda buat.

Menautkan jadwal ke runbook dan menetapkan parameter

Anda dapat menautkan jadwal ke runbook Anda sehingga runbook dimulai pada waktu tertentu. Anda menetapkan parameter input saat Membuat jadwal, dan runbook menggunakan nilai-nilai ini ketika jadwal dimulai. Anda tidak dapat menyimpan jadwal hingga semua nilai parameter wajib disediakan.

Membuat webhook untuk runbook dan menetapkan parameter

Anda dapat membuat webhook untuk runbook Anda dan mengonfigurasi parameter input runbook. Anda tidak dapat menyimpan webhook hingga semua nilai parameter wajib disediakan.

Saat Anda menjalankan runbook menggunakan webhook, parameter input yang telah ditentukan [WebhookData](automation-webhooks.md) dikirim bersama parameter input yang Anda tentukan.

Meneruskan objek JSON ke runbook

Ini dapat digunakan untuk menyimpan data yang ingin Anda berikan ke runbook dalam file JSON. Misalnya, Anda dapat membuat file JSON yang berisi semua parameter yang ingin Anda teruskan ke runbook. Untuk melakukan ini, Anda harus mengonversi kode JSON ke string lalu mengonversi string ke objek PowerShell sebelum meneruskannya ke runbook.

Bagian ini menggunakan contoh saat skrip PowerShell memanggil Start-AzAutomationRunbook untuk memulai runbook PowerShell, meneruskan konten file JSON ke runbook. Runbook PowerShell memulai Azure VM dengan mengambil parameter untuk VM dari objek JSON.

Membuat file JSON

Ketik kode berikut dalam file teks, dan simpan sebagai test.js di suatu tempat di komputer lokal Anda.

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

Membuat runbook

Buat runbook PowerShell baru bernama Test-Json di Azure Automation.

Untuk menerima data JSON, runbook harus mengambil objek sebagai parameter input. Runbook kemudian dapat menggunakan properti yang ditentukan dalam 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

Jika Anda ingin runbook dijalankan dengan identitas terkelola yang ditetapkan sistem, jangan ubah kodenya. Jika Anda lebih suka menggunakan identitas terkelola yang ditetapkan pengguna:

1. Dari baris 10, hapus $AzureContext = (Connect-AzAccount -Identity).context,
2. Ganti dengan $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, dan
3. Masukkan ID klien.

Simpan dan terbitkan runbook ini di akun Automation Anda.

Memanggil runbook dari PowerShell

Sekarang, Anda dapat memanggil runbook dari komputer lokal menggunakan Azure PowerShell.

1. Masuk ke Azure sesuai gambar. Setelah itu, Anda diminta untuk memasukkan kredensial Azure Anda.

   Connect-AzAccount
   

   Catatan

   Untuk runbook PowerShell, Add-AzAccount dan Add-AzureRMAccount merupakan alias untuk Connect-AzAccount. Perhatikan bahwa alias ini tidak tersedia untuk runbook grafis. Sebuah runbook grafis hanya dapat menggunakan Connect-AzAccount sendiri.

2. Dapatkan konten file JSON yang disimpan dan konversi ke string. JsonPath menunjukkan jalur tempat Anda menyimpan file JSON.

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

3. Mengonversi konten string $json menjadi objek PowerShell.

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

4. Buat hashtable untuk parameter untuk Start-AzAutomationRunbook.

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

   Perhatikan bahwa Anda mengatur nilai Parameters ke objek PowerShell yang berisi nilai dari file JSON.

5. Mulai runbook.

   $job = Start-AzAutomationRunbook @RBParams
   

Langkah berikutnya

• Untuk menyiapkan runbook tekstual, lihat Mengedit runbook tekstual di Azure Automation.
• Untuk menyiapkan runbook grafis, lihat Menulis runbook grafis di Azure Automation.