Aracılığıyla paylaş

Web kancasından runbook başlatma

Web kancası, dış hizmetin tek bir HTTP isteği ile Azure Otomasyonu’nda belirli bir runbook'u başlatmasına olanak tanır. Dış hizmetler Azure DevOps Services, GitHub, Azure İzleyici günlükleri ve özel uygulamalardır. Azure Otomasyonu API'sini tamamen uygulamaya gerek kalmadan, böyle bir hizmet runbook'u başlatmak için bir webhook kullanabilir. Web kancalarını, runbook'u Azure Otomasyonu'da başlatma bölümünden diğer runbook başlatma yöntemleriyle karşılaştırabilirsiniz.

Webhook'lar Genel Bakış

TLS 1.2 veya üzeri sürümlere yönelik web kancaları istemci gereksinimlerini anlamak için Azure Otomasyonu için TLS sayfasına bakın.

Webhook özellikleri

Aşağıdaki tabloda, web kancası için yapılandırmanız gereken özellikler açıklanır.

Mülk Açıklama
Ad Webhook'un adı. İstemciye sunulmadığından istediğiniz adı sağlayabilirsiniz. Yalnızca Azure Otomasyonu'nda runbook'u tanımlamanız için kullanılır. Web kancasına onu kullanan istemciyle ilgili bir ad vermek iyi bir yöntemdir.
URL Web kancasının URL'si. Bu, istemcinin web kancasına bağlı runbook'u başlatmak için HTTP POST ile çağırdığı benzersiz adrestir. Web kancası oluşturduğunuzda otomatik olarak oluşturulur. Özel URL belirtemezsiniz.

URL, üçüncü taraf bir sistemin başka kimlik doğrulaması yapmadan runbook'u çağırmasına olanak tanıyan bir güvenlik belirteci içerir. Bu nedenle URL'ye parola gibi davranmanız gerekir. Güvenlik nedeniyle URL'yi yalnızca web kancasını oluştururken Azure portalında görüntüleyebilirsiniz. Url'yi daha sonra kullanmak üzere güvenli bir konumda not edin.
Son kullanma tarihi Web kancasının son kullanma tarihi (bundan sonra artık kullanılamaz). Web kancası oluşturulduktan sonra, süresi dolmadığı sürece son kullanma tarihini değiştirebilirsiniz.
Etkinleştirilmiş Web kancasının oluşturulduğunda varsayılan olarak etkinleştirilip etkinleştirilmediğini belirten ayar. Bu özelliği Devre Dışı olarak ayarlarsanız, hiçbir istemci web kancasını kullanamaz. Web kancasını oluştururken veya oluşturulduktan sonra başka bir zaman bu özelliği ayarlayabilirsiniz.

Webhook bir çalışma kitabını başlattığında kullanılan parametreler

Web kancası, runbook başlatıldığında kullanılan runbook parametreleri için değerler tanımlayabilir. Web kancası, zorunlu olan runbook parametreleri için değerler içermelidir ve isteğe bağlı parametreler için de değerler içerebilir. Web kancasına yapılandırılan parametre değeri, web kancası oluşturulduktan sonra bile değiştirilebilir. Tek bir runbook'a bağlı birden çok web kancasının her birinde farklı runbook parametre değerleri kullanılabilir. bir istemci web kancası kullanarak bir runbook başlattığında, web kancasında tanımlanan parametre değerlerini geçersiz kılamaz.

runbook, istemciden veri almak için adlı WebhookDatatek bir parametreyi destekler. Bu parametre, istemcinin post isteğine dahil olduğu verileri içeren bir nesneyi tanımlar.

WebhookData özellikleri

WebhookData parametresi aşağıdaki özelliklere sahiptir:

Mülk Açıklama
Webhook Adı Webhook'un adı.
İstek Başlığı Gelen POST isteğinin üst bilgilerini içeren PSCustomObject.
RequestBody Gelen POST isteğinin gövdesi. Bu yapı, dize, JSON, XML veya form kodlaması gibi her tür veri biçimlendirmesini korur. Runbook beklenen veri biçimiyle çalışacak şekilde yazılmalıdır.

Webhook'un WebhookData parametresini desteklemek için yapılandırılması gerekmez ve runbook'un bunu kabul etmesine gerek yoktur. Runbook parametresini tanımlamıyorsa, istemciden gönderilen isteğin tüm ayrıntıları yoksayılır.

Not

Web kancasını çağırırken, çağrının başarısız olması durumunda istemcinin her zaman parametre değerlerini depolaması gerekir. Ağ kesintisi veya bağlantı sorunu varsa, uygulama başarısız web kancası çağrılarını geri getiremez.

Webhook oluşturma sırasında WebhookData için bir değer belirtirseniz, webhook runbook'u istemci POST isteğindeki verilerle başlattığında bu değer geçersiz kılınır. Uygulama istek gövdesine veri eklemese bile bu durum ortaya çıkar.

Web kancası dışında bir mekanizma kullanarak WebhookData tanımlayan bir runbook başlatırsanız, runbook'un tanıdığı bir değeri WebhookData için sağlayabilirsiniz. Runbook'un bir web kancası tarafından geçirilen gerçek nesnelerle çalıştığı gibi çalışabilmesi için bu değer parametresiyle aynı WebhookDataWebhookData sahip bir nesne olmalıdır.

Örneğin, Azure portalından aşağıdaki runbook'u başlatıyorsanız ve test için bazı örnek web kancası verilerini göndermek istiyorsanız, verileri kullanıcı arabiriminde JSON formatında iletmeniz gerekir.

Kullanıcı arabiriminden WebhookData parametresi

Sonraki runbook örneği için WebhookDataaşağıdaki özelliklerini tanımlayalım:

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

Şimdi parametresi için WebhookData kullanıcı arabiriminde aşağıdaki JSON nesnesini geçiriyoruz. Bu örnek, satır başı ve yeni satır karakterleriyle, bir web kancasından gönderilen biçime uyar.

{"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]"}

Kullanıcı arabiriminden WebhookData parametresini başlatma

Not

Azure Otomasyonu, Runbook işiyle tüm giriş parametrelerinin değerlerini günlüğe kaydeder. Bu nedenle, web kancası isteğinde istemci tarafından sağlanan tüm girişler günlüğe kaydedilir ve otomasyon işine erişimi olan herkesin erişimine açık olur. Bu nedenle, hassas bilgileri webhook çağrılarında ekleme konusunda dikkatli olmanız gerekir.

Webhook güvenliği

Web kancasının güvenliği, web kancasının çağrılmasını sağlayan bir güvenlik belirtecinin bulunduğu URL'sinin gizliliğine bağlıdır. Azure Otomasyonu, doğru URL'ye yapıldığı sürece istekte herhangi bir kimlik doğrulaması gerçekleştirmez. Bu nedenle istemcileriniz, isteği doğrulamaya yönelik alternatif bir araç kullanmadan son derece hassas işlemler gerçekleştiren runbook'lar için web kancalarını kullanmamalıdır.

Aşağıdaki stratejileri dikkate alın:

  • Bir webhook tarafından çağrılıp çağrılmadığını belirlemek için runbook'a mantık ekleyebilirsiniz. Runbook, WebhookName parametresinin WebhookData özelliğini denetlesin. Runbook, RequestHeader ve RequestBody özelliklerinde belirli bilgileri arayarak daha fazla doğrulama gerçekleştirebilir.

  • Runbook'un bir web kancası isteği aldığında dış koşulun bazı doğrulamalarını gerçekleştirmesini sağlayın. Örneğin, GitHub deposuna yeni bir işleme olduğunda GitHub tarafından çağrılan bir runbook düşünün. Runbook devam etmeden önce yeni bir işlemenin gerçekleştiğini doğrulamak için GitHub'a bağlanabilir.

  • Azure Otomasyonu, özellikle GuestAndHybridManagement olmak üzere Azure sanal ağ hizmet etiketlerini destekler. Azure Güvenlik Duvarı veya ağ güvenlik gruplarında hizmet etiketlerini kullanarak ağ erişim denetimlerini tanımlayabilir ve sanal ağınızın içinden web kancalarını tetikleyebilirsiniz. Güvenlik kuralları oluştururken belirli IP adreslerinin yerine hizmet etiketleri kullanılabilir. Bir kuralın uygun kaynak veya hedef alanında, GuestAndHybridManagement hizmet etiketi adını belirterek Otomasyon hizmeti için trafiğe izin verebilir veya trafiği reddedebilirsiniz. Bu hizmet etiketi, IP aralıklarını belirli bir bölgeyle kısıtlayarak daha ayrıntılı denetime izin vermenizi desteklemez.

Webhook oluştur

Not

  • Web kancasını PowerShell 7 runbook ile kullandığınızda, web kancası giriş parametresini geçersiz bir JSON'a otomatik olarak dönüştürür. Daha fazla bilgi için bkz . Bilinen sorunlar - PowerShell 7.1 (önizleme). Web kancasını PowerShell 5 runbook ile kullanmanızı öneririz.
  • Python runbook'u başlatmak için web kancası kullanılması desteklenmez.

Web kancası oluşturmak için şu adımları izleyin:

  1. Aşağıdaki kodla PowerShell runbook'u oluşturun:

    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. Azure portalını veya PowerShell veya REST API'yi kullanarak bir web kancası oluşturun. Bir web kancası, yayımlanmış bir çalışma kitabı talep eder. Bu adım adım kılavuz, Azure Otomasyonu Runbook oluşturma bölümünden oluşturulan runbook'un değiştirilmiş bir sürümünü kullanır.

    Azure portalını kullanarak web kancası oluşturmak için aşağıdakileri yapın:

    1. Azure Portal’ında oturum açın.

    2. Azure portalında Otomasyon hesabınıza gidin.

    3. İşlem Otomasyonu altında Runbook'lar'ı seçerek Runbook'lar sayfasını açın.

    4. Runbook'a Genel Bakış sayfasını açmak için listeden runbook'unuzu seçin.

    5. Web Kancası Ekle sayfasını açmak için Web Kancası Ekle'yi seçin.

      Web kancası ekle seçeneğinin vurgulandığı Runbook'a genel bakış sayfası.

    6. Web Kancası Ekle sayfasında Yeni web kancası oluştur'u seçin.

      Oluştur seçeneği vurgulanmış olarak web kancası sayfası ekleyin.

    7. Web kancasının Adı alanına girin. Süre sonu alanının son kullanma tarihi varsayılan olarak geçerli tarihten itibaren bir yıl olur.

    8. Kopyala simgesini seçin veya Ctrl + C tuşlarına basarak web kancasının URL'sini kopyalayın. Ardından URL'yi güvenli bir konuma kaydedin.

      URL'nin vurgulandığı web kancası sayfası oluşturma.

      Önemli

      Web kancasını oluşturduktan sonra URL'yi yeniden alamazsınız. Yukarıdaki gibi kopyalayıp kaydettiğinizden emin olun.

    9. Tamam'ı seçerek Web Kancası Ekle sayfasına dönün.

    10. Web Kancası Ekle sayfasında, Parametreleri yapılandır ve ayarları çalıştır'ı seçerek Parametreler sayfasını açın.

      Parametrelerin vurgulandığı webhook sayfasını ekleyin.

    11. Parametreler sayfasını gözden geçirin. Bu makalede kullanılan örnek çalışma kitabı için değişiklik gerekmez. Tamam'ı seçerek Web Kancası Ekle sayfasına dönün.

    12. Web Kancası Ekle sayfasında Oluştur'u seçin. Web kancası oluşturulur ve Runbook'a Genel Bakış sayfasına geri dönersiniz.

Webhook kullan

Bu örnekte, POST isteğini yeni web kancanıza göndermek için Invoke-WebRequest PowerShell cmdlet'i kullanılır.

Web kancası kullanmak için şu adımları izleyin:

  1. Webhook çağrısının gövdesi için runbook'a geçirmek üzere değerleri hazırlayın. Nispeten basit değerler için, değerleri aşağıdaki gibi betik olarak yazabilirsiniz:

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

$body = ConvertTo-Json -InputObject $Names

  2. Daha büyük kümeler için bir dosya kullanmak isteyebilirsiniz. adlı names.json bir dosya oluşturun ve aşağıdaki kodu yapıştırın:

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

    Aşağıdaki PowerShell komutlarını çalıştırmadan önce değişkenin $file değerini json dosyasının gerçek yoluyla değiştirin.

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

  3. REST API kullanarak web kancasını çağırmak için aşağıdaki PowerShell komutlarını çalıştırın.

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

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

    Açıklayıcı amaçlarla, vücudu üretmenin iki farklı yöntemi için iki çağrı yapıldı. Üretim için yalnızca bir yöntem kullanın. Çıkış aşağıdaki gibi görünmelidir (yalnızca bir çıkış gösterilir):

    Webhook çağrısının çıktısı.

    İstemci, istekten aşağıdaki dönüş kodlarından POST birini alır.

    Kod Metin Açıklama
    202 Kabul edildi İstek kabul edildi ve runbook başarıyla kuyruğa alındı.
    400 Hatalı İstek İstek aşağıdaki nedenlerden biri nedeniyle kabul edilmedi:
    • Webhook'un süresi doldu.
    • Webhook devre dışı bırakıldı.
    • URL'deki belirteç geçersiz.
    404 Bulunamadı İstek aşağıdaki nedenlerden biri nedeniyle kabul edilmedi:
    • Webhook bulunamadı.
    • Runbook bulunamadı.
    • Hesap bulunamadı.
    500 İç Sunucu Hatası URL geçerliydi, ancak bir hata oluştu. İsteği yeniden gönderin.

    İsteğin başarılı olduğu varsayıldığında, web kancası yanıtı aşağıda gösterildiği gibi iş kimliğini JSON biçiminde içerir. Tek bir iş kimliği içerir, ancak JSON biçimi gelecekteki olası iyileştirmelere olanak tanır.

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

  4. Çıkışı almak için Get-AzAutomationJobOutput PowerShell cmdlet'i kullanılır. Azure Otomasyonu API de kullanılabilir.

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

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

    Önceki adımda oluşturulan bir runbook'u tetiklediğinizde bir iş oluşturulur ve çıktı aşağıdakine benzer olmalıdır:

    Webhook işinin çıktısı.

Webhook'u güncelleme

Web kancası oluşturulduğunda, geçerlilik süresi 10 yıl olur ve bu sürenin sonunda otomatik olarak süresi dolar. Bir web kancasının süresi dolduktan sonra tekrar etkinleştiremezsiniz. Yalnızca kaldırabilir ve sonra yeniden oluşturabilirsiniz. Son kullanma tarihine ulaşmamış bir web kancasının süresini uzatabilirsiniz. Web kancasını genişletmek için aşağıdaki adımları uygulayın:

  1. Webhook içeren çalışma kitabına gidin.
  2. Kaynaklar'ın altında Web Kancaları'nı ve ardından genişletmek istediğiniz web kancasını seçin.
  3. Web kancası sayfasında yeni bir son kullanma tarihi ve saati seçin ve ardından Kaydet'i seçin.

Diğer olası değişiklikler için Api çağrısı Web Kancası - Güncelleştirme ve PowerShell cmdlet'ini Set-AzAutomationWebhook gözden geçirin.

Kaynakları temizleme

Otomasyon runbook'undan web kancasını kaldırma örnekleri aşağıda verilmiştir.

  • PowerShell kullanarak Remove-AzAutomationWebhook cmdlet'i aşağıda gösterildiği gibi kullanılabilir. Çıkış döndürülmedi.

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

  • REST kullanarak REST Web Kancası - Silme API'sini aşağıda gösterildiği gibi kullanabilirsiniz.

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

    Çıkışın StatusCode : 200 olması, başarılı bir silme anlamına gelir.

ARM şablonuyla runbook ve webhook oluşturma

Otomasyon web kancaları, Azure Resource Manager şablonları kullanılarak da oluşturulabilir. Bu örnek şablon, adlandırılmış bir runbook için bir Otomasyon hesabı, dört adet runbook ve bir web kancası oluşturur.

ARM şablonu kullanarak web kancası oluşturmak için şu adımları izleyin:

  1. adlı webhook_deploy.json bir dosya oluşturun ve aşağıdaki kodu yapıştırın:

    {
    "$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. Aşağıdaki PowerShell kod örneği, şablonu makinenizden dağıtır. Değişkenler için uygun bir değer sağlayın ve betiği yürütün.

    $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

    Not

    Güvenlik nedeniyle, URI yalnızca ilk kez bir şablon dağıtıldığında döndürülür.

Sonraki adımlar

  • Last updated on