Memulai runbook dari webhook

  • Artikel

Webhook memungkinkan layanan eksternal untuk memulai runbook tertentu di Azure Automation melalui satu permintaan HTTP. Layanan eksternal termasuk Layanan Azure DevOps, GitHub, log Azure Monitor, dan aplikasi kustom. Layanan semacam itu dapat menggunakan webhook untuk memulai runbook tanpa menerapkan Azure Automation API penuh. Anda dapat membandingkan webhook dengan metode lain memulai runbook dalam Memulai runbook di Azure Automation.

WebhooksOverview

Untuk memahami persyaratan klien untuk TLS 1.2 atau yang lebih tinggi dengan webhook, lihat TLS untuk Azure Automation.

Properti webhook

Tabel berikut ini menjelaskan properti yang harus Anda konfigurasi untuk webhook.

Properti Deskripsi
Nama Nama webhook. Anda dapat memberikan nama sesuai keinginan Anda, karena tidak terekspos ke klien. Ini hanya digunakan agar Anda dapat mengidentifikasi runbook di Azure Automation. Sebagai praktik terbaik, Anda harus memberikan webhook nama yang terkait dengan klien yang menggunakannya.
URL URL webhook. Ini adalah alamat unik yang disebut klien dengan HTTP POST untuk memulai runbook yang ditautkan ke webhook. Dihasilkan secara otomatis saat Anda membuat webhook. Anda tidak dapat menentukan URL kustom.

URL berisi token keamanan yang memungkinkan sistem pihak ketiga memanggil runbook tanpa autentikasi lebih lanjut. Karena alasan ini, Anda harus memperlakukan URL seperti kata sandi. Karena alasan keamanan, Anda hanya dapat melihat URL di portal Azure saat membuat webhook. Perhatikan URL di lokasi aman untuk digunakan di masa mendatang.
Tanggal kedaluwarsa Tanggal kedaluwarsa webhook, setelah itu tidak dapat digunakan lagi. Anda dapat mengubah kedaluwarsa setelah webhook dibuat, selama webhook belum kedaluwarsa.
Aktif Pengaturan menunjukkan apakah webhook diaktifkan secara default saat dibuat. Jika Anda mengatur properti ini ke Nonaktif, maka klien tidak dapat menggunakan webhook. Anda dapat mengatur properti ini saat membuat webhook atau waktu lain setelah pembuatannya.

Parameter yang digunakan saat webhook memulai runbook

Webhook dapat menentukan nilai untuk parameter runbook yang digunakan saat runbook dimulai. Webhook harus menyertakan nilai untuk parameter runbook wajib dan dapat menyertakan nilai untuk parameter opsional. Nilai parameter yang dikonfigurasi ke webhook dapat diubah bahkan setelah pembuatan webhook. Beberapa webhook yang ditautkan ke satu runbook masing-masing dapat menggunakan nilai parameter runbook yang berbeda. Saat klien memulai runbook menggunakan webhook, klien tidak dapat menimpa nilai parameter yang ditentukan dalam webhook.

Untuk menerima data dari klien, runbook mendukung satu parameter yang disebut WebhookData. Parameter ini menentukan objek yang berisi data yang disertakan klien dalam permintaan POST.

Properti WebhookData

Parameter WebhookData memiliki properti berikut:

Properti Deskripsi
WebhookName Nama webhook.
RequestHeader PSCustomObject yang berisi header permintaan POST masuk.
RequestBody Isi permintaan POST yang masuk. Isi ini menyimpan pemformatan data apa pun, seperti string, JSON, XML, atau yang dikodekan formulir. Runbook harus ditulis agar berfungsi dengan format data yang diharapkan.

Tidak ada konfigurasi webhook yang diperlukan untuk mendukung parameter WebhookData, dan tidak diperlukan runbook untuk menerimanya. Jika runbook tidak menentukan parameter, detail permintaan yang dikirim dari klien diabaikan.

Catatan

Saat memanggil webhook, klien harus selalu menyimpan nilai parameter apa pun jika panggilan gagal. Jika ada masalah pemadaman jaringan atau koneksi, aplikasi tidak dapat mengambil panggilan webhook yang gagal.

Jika Anda menentukan nilai untuk WebhookData di pembuatan webhook, nilai tersebut akan diganti saat webhook memulai runbook dengan data dari permintaan POST klien. Ini terjadi meski aplikasi tidak menyertakan data apa pun dalam isi permintaan.

Jika Anda memulai runbook yang menentukan WebhookData menggunakan mekanisme selain webhook, Anda dapat memberikan nilai untuk WebhookData yang dikenali runbook. Nilai ini harus menjadi objek dengan properti yang sama dengan parameter WebhookData sehingga runbook dapat berfungsi dengannya sama seperti berfungsi dengan WebhookData objek aktual yang diteruskan oleh webhook.

Misalnya, jika Anda memulai runbook berikut dari portal Azure dan ingin meneruskan beberapa contoh data webhook untuk pengujian, Anda harus meneruskan data dalam JSON di antarmuka pengguna.

Parameter WebhookData dari UI

Untuk contoh runbook berikutnya, mari kita tentukan properti berikut untuk WebhookData:

  • WebhookName: MyWebhook
  • RequestBody: *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*

Sekarang kita meneruskan objek JSON berikut di UI untuk parameter WebhookData. Contoh ini, dengan pengembalian pengangkutan dan karakter baru, cocok dengan format yang diteruskan dari webhook.

{"WebhookName":"mywebhook","RequestBody":"[\r\n {\r\n \"ResourceGroup\": \"vm01\",\r\n \"Name\": \"vm01\"\r\n },\r\n {\r\n \"ResourceGroup\": \"vm02\",\r\n \"Name\": \"vm02\"\r\n }\r\n]"}

Mulai parameter WebhookData dari UI

Catatan

Otomatisasi Azure mencatat nilai semua parameter input dengan pekerjaan runbook. Dengan demikian setiap input yang diberikan oleh klien dalam permintaan webhook dicatat dan tersedia bagi siapa saja yang memiliki akses ke pekerjaan otomatisasi. Karena alasan ini, Anda harus berhati-hati tentang memasukkan informasi sensitif dalam panggilan webhook.

Keamanan webhook

Keamanan webhook bergantung pada privasi URL-nya, yang berisi token keamanan yang memungkinkan webhook dipanggil. Azure Automation tidak melakukan autentikasi apa pun atas permintaan selama dibuat untuk URL yang benar. Karena alasan ini, klien Anda tidak boleh menggunakan webhook untuk runbook yang melakukan operasi yang sangat sensitif tanpa menggunakan cara alternatif dalam memvalidasi permintaan.

Pertimbangkan strategi berikut:

  • Anda dapat menyertakan logika dalam runbook untuk menentukan apakah webhook memanggilnya. Minta runbook memeriksa properti WebhookName parameter WebhookData. Runbook dapat melakukan validasi lebih lanjut dengan mencari informasi tertentu di properti RequestHeader dan RequestBody.

  • Minta runbook melakukan beberapa validasi kondisi eksternal ketika menerima permintaan webhook. Misalnya, pertimbangkan runbook yang dipanggil oleh GitHub setiap kali ada penerapan baru untuk repositori GitHub. Runbook mungkin terhubung ke GitHub untuk memvalidasi bahwa penerapan baru telah terjadi sebelum melanjutkan.

  • Azure Automation mendukung tag layanan jaringan virtual Azure, khususnya GuestAndHybridManagement. Anda dapat menggunakan tag layanan untuk menentukan kontrol akses jaringan pada grup keamanan jaringan atau Azure Firewall dan memicu webhook dari dalam jaringan virtual Anda. Anda dapat menggunakan tag layanan sebagai pengganti alamat IP tertentu saat membuat aturan keamanan. Dengan menentukan nama tag layanan GuestAndHybridManagement di bidang aturan sumber atau tujuan yang sesuai, Anda dapat mengizinkan atau menolak lalu lintas untuk layanan Automation. Tag layanan ini tidak mendukung diizinkannya kontrol yang lebih terperinci dengan membatasi rentang IP untuk wilayah tertentu.

Membuat webhook

Catatan

Saat Anda menggunakan webhook dengan runbook PowerShell 7, itu secara otomatis mengonversi parameter input webhook menjadi JSON yang tidak valid. Untuk informasi selengkapnya, lihat Masalah yang diketahui - PowerShell 7.1 (pratinjau). Kami menyarankan agar Anda menggunakan webhook dengan runbook PowerShell 5.

  1. Buat runbook PowerShell dengan kode berikut:

    param
(
    [Parameter(Mandatory=$false)]
    [object] $WebhookData
)

write-output "start"
write-output ("object type: {0}" -f $WebhookData.gettype())
write-output $WebhookData
write-output "`n`n"
write-output $WebhookData.WebhookName
write-output $WebhookData.RequestBody
write-output $WebhookData.RequestHeader
write-output "end"

if ($WebhookData.RequestBody) { 
    $names = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

        foreach ($x in $names)
        {
            $name = $x.Name
            Write-Output "Hello $name"
        }
}
else {
    Write-Output "Hello World!"
}

  2. Buat webhook menggunakan portal Azure, atau PowerShell atau REST API. Webhook memerlukan runbook yang diterbitkan. Panduan ini menggunakan runbook versi modifikasi yang dibuat dari Buat runbook Azure Automation.

    1. Masuk ke portal Azure.

    2. Di portal Microsoft Azure, buka akun Automation Anda.

    3. Pada Proses Automation, pilih Runbook untuk membuka halaman Runbook.

    4. Pilih runbook dari daftar untuk membuka halaman Ringkasan Runbook.

    5. Pilih Tambahkan webhook untuk membuka halaman Tambahkan Webhook.

      Halaman ringkasan Runbook dengan Tambahkan webhook disorot.

    6. Di halaman Tambahkan Webhook, pilih Buat webhook baru.

      Halaman Tambahkan webhook dengan Buat disorot.

    7. Masukkan di Nama untuk webhook. Tanggal kedaluwarsa untuk bidang Kedaluwarsa diatur default ke satu tahun sejak tanggal saat ini.

    8. Klik ikon salin atau tekan Ctrl + C untuk menyalin URL webhook. Kemudian, simpan URL ke lokasi yang aman.

      Halaman Buat webhook dengan URL disorot.

      Penting

      Setelah Anda membuat webhook, Anda tidak dapat mengambil URL lagi. Pastikan Anda menyalin dan merekamnya seperti di atas.

    9. Pilih OK untuk kembali ke halaman Tambahkan Webhook.

    10. Dari halaman Tambahkan Webhook, pilih Konfigurasi parameter dan jalankan pengaturan untuk membuka halaman Parameter.

      Halaman Tambahkan webhook dengan parameter disorot.

    11. Tinjau halaman Parameter. Untuk contoh runbook yang digunakan dalam artikel ini, perubahan tidak diperlukan. Pilih OK untuk kembali ke halaman Tambahkan Webhook.

    12. Dari halaman Tambahkan Webhook, pilih Buat. Webhook dibuat dan Anda dialihkan kembali ke halaman Ringkasan Runbook.

Gunakan webhook

Contoh ini menggunakan cmdlet PowerShell Invoke-WebRequest untuk mengirim permintaan POST ke webhook baru Anda.

  1. Siapkan nilai untuk diteruskan ke runbook sebagai isi untuk panggilan webhook. Untuk nilai yang relatif mudah, Anda dapat menulis skrip nilai sebagai berikut:

    $Names  = @(
            @{ Name="Hawaii"},
            @{ Name="Seattle"},
            @{ Name="Florida"}
        )

$body = ConvertTo-Json -InputObject $Names

  2. Untuk set yang lebih besar, sebaiknya gunakan file. Buat file bernama names.json dan tempelkan kode berikut:

    [
    { "Name": "Hawaii" },
    { "Name": "Florida" },
    { "Name": "Seattle" }
]

    Ubah nilai untuk variabel $file dengan jalur aktual ke file json sebelum menjalankan perintah PowerShell berikut.

    # Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file

  3. Jalankan perintah PowerShell berikut untuk memanggil webhook menggunakan REST API.

    $response = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $body -UseBasicParsing
$response

$responseFile = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $bodyFile -UseBasicParsing
$responseFile

    Sebagai ilustrasi, dua panggilan dibuat untuk dua metode yang berbeda dalam membuat isi. Untuk produksi, gunakan satu metode saja. Output harus tampak seperti berikut (hanya satu output yang ditampilkan):

    Output dari panggilan webhook.

    Klien menerima salah satu kode pengembalian berikut dari permintaan POST.

    Kode Teks Deskripsi
    202 Diterima Permintaan diterima, dan runbook berhasil diantrekan.
    400 Permintaan Buruk Permintaan tidak diterima karena salah satu alasan berikut:
    • Webhook telah kedaluwarsa.
    • Webhook dinonaktifkan.
    • Token dalam URL tidak valid.
    404 Tidak Ditemukan Permintaan tidak diterima karena salah satu alasan berikut:
    • Webhook tidak ditemukan.
    • Runbook tidak ditemukan.
    • Akun tidak ditemukan.
    500 Kesalahan Server Internal URL ini valid, tetapi terjadi kesalahan. Kirim ulang permintaan.

    Dengan asumsi permintaan berhasil, respons webhook berisi ID pekerjaan dalam format JSON seperti yang ditunjukkan di bawah ini. Ini berisi ID pekerjaan tunggal, tetapi format JSON memungkinkan potensi penyempurnaan di masa mendatang.

    {"JobIds":["<JobId>"]}

  4. Cmdlet PowerShell Get-AzAutomationJobOutput akan digunakan untuk mendapatkan output. Azure Automation API juga dapat digunakan.

    #isolate job ID
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

# Get output
Get-AzAutomationJobOutput `
    -AutomationAccountName $automationAccount `
    -Id $jobid `
    -ResourceGroupName $resourceGroup `
    -Stream Output

    Saat Anda memicu runbook yang dibuat pada langkah sebelumnya, runbook akan membuat pekerjaan dan outputnya akan terlihat mirip dengan yang berikut ini:

    Output dari tugas webhook.

Memperbarui webhook

Saat dibuat, webhook memiliki masa berlaku 10 tahun, setelah itu akan otomatis kedaluwarsa. Setelah webhook kedaluwarsa, Anda tidak dapat mengaktifkannya kembali. Anda hanya dapat menghapus lalu membuatnya kembali. Anda dapat memperpanjang webhook yang belum mencapai waktu kedaluwarsanya. Untuk memperpanjang webhook, lakukan langkah-langkah berikut.

  1. Navigasi ke runbook yang berisi webhook.
  2. Di bagian Sumber daya, pilih Webhook, lalu webhook yang ingin diperpanjang.
  3. Dari halaman Webhook, pilih tanggal dan waktu kedaluwarsa baru dan klik Simpan.

Tinjau panggilan API Webhook - Update dan cmdlet PowerShell Set-AzAutomationWebhook untuk kemungkinan modifikasi lainnya.

Membersihkan sumber daya

Berikut contoh menghapus webhook dari runbook Automation.

  • Dengan PowerShell, cmdlet Remove-AzAutomationWebhook akan digunakan seperti yang ditunjukkan di bawah. Tidak ada output yang ditampilkan.

    Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook

  • Dengan REST, API Webhook - Delete REST dapat digunakan seperti yang ditunjukkan di bawah.

    Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader

    Output StatusCode : 200 berarti penghapusan berhasil.

Membuat runbook dan webhook dengan template ARM

Webhook Automation juga dapat dibuat menggunakan template Azure Resource Manager. Contoh template ini membuat akun Automation, empat runbook, dan webhook untuk runbook bernama.

  1. Buat file bernama webhook_deploy.json dan tempelkan kode berikut:

    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "automationAccountName": {
            "type": "String",
            "metadata": {
                "description": "Automation account name"
            }
        },
        "webhookName": {
            "type": "String",
            "metadata": {
                "description": "Webhook Name"
            }
        },
        "runbookName": {
            "type": "String",
            "metadata": {
                "description": "Runbook Name for which webhook will be created"
            }
        },
        "WebhookExpiryTime": {
            "type": "String",
            "metadata": {
                "description": "Webhook Expiry time"
            }
        },
        "_artifactsLocation": {
            "defaultValue": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.automation/101-automation/",
            "type": "String",
            "metadata": {
                "description": "URI to artifacts location"
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Automation/automationAccounts",
            "apiVersion": "2020-01-13-preview",
            "name": "[parameters('automationAccountName')]",
            "location": "[resourceGroup().location]",
            "properties": {
                "sku": {
                    "name": "Free"
                }
            },
            "resources": [
                {
                    "type": "runbooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('runbookName')]",
                    "location": "[resourceGroup().location]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]"
                    ],
                    "properties": {
                        "runbookType": "Python2",
                        "logProgress": "false",
                        "logVerbose": "false",
                        "description": "Sample Runbook",
                        "publishContentLink": {
                            "uri": "[uri(parameters('_artifactsLocation'), 'scripts/AzureAutomationTutorialPython2.py')]",
                            "version": "1.0.0.0"
                        }
                    }
                },
                {
                    "type": "webhooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('webhookName')]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]",
                        "[parameters('runbookName')]"
                    ],
                    "properties": {
                        "isEnabled": true,
                        "expiryTime": "[parameters('WebhookExpiryTime')]",
                        "runbook": {
                            "name": "[parameters('runbookName')]"
                        }
                    }
                }
            ]
        }
    ],
    "outputs": {
        "webhookUri": {
            "type": "String",
            "value": "[reference(parameters('webhookName')).uri]"
        }
    }
}

  2. Sampel kode PowerShell berikut menyebarkan template dari komputer Anda. Masukkan nilai yang tepat untuk variabel, lalu jalankan skrip.

    $resourceGroup = "resourceGroup"
$templateFile = "path\webhook_deploy.json"
$armAutomationAccount = "automationAccount"
$armRunbook = "ARMrunbookName"
$armWebhook = "webhookName"
$webhookExpiryTime = "12-31-2022"

New-AzResourceGroupDeployment `
    -Name "testDeployment" `
    -ResourceGroupName $resourceGroup `
    -TemplateFile $templateFile `
    -automationAccountName $armAutomationAccount `
    -runbookName $armRunbook `
    -webhookName $armWebhook `
    -WebhookExpiryTime $webhookExpiryTime

    Catatan

    Karena alasan keamanan, URI hanya dikembalikan saat pertama kali templat digunakan.

Langkah berikutnya