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. Böyle bir hizmet, tam Azure Otomasyonu API'sini uygulamadan runbook başlatmak için bir web kancası 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.

Web KancalarıGenel Bakış

Web kancalarıyla TLS 1.2 veya üzeri sürümlere yönelik istemci gereksinimlerini anlamak için bkz. Azure Otomasyonu için TLS.

Web kancası özellikleri

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

Özellik Açıklama
Ad Web kancasının adı. İstemciye sunulmadığından istediğiniz adı sağlayabilirsiniz. Yalnızca Azure Otomasyonu'nda sizin runbook'u belirleyebilmeniz 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. Siz web kancasını oluştururken 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.
Etkin 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.

Web kancası bir runbook başlatırken kullanılan parametreler

Web kancası, runbook başlatıldığında kullanılan runbook parametreleri için değerler tanımlayabilir. Web kancası, zorunlu runbook parametreleri için değerler içermelidir ve isteğe bağlı parametreler için 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:

Özellik Açıklama
Web KancasıAdı Web kancasının adı.
RequestHeader Gelen POST isteğinin üst bilgilerini içeren PSCustomObject.
RequestBody Gelen POST isteğinin gövdesi. Bu gövde dize, JSON, XML veya form kodlanmış gibi tüm veri biçimlendirmelerini korur. Runbook beklenen veri biçimiyle çalışacak şekilde yazılmalıdır.

Web kancasının parametresini desteklemek WebhookData için yapılandırılması gerekmez ve runbook bunu kabul etmek için gerekli değildir. 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ı alamaz.

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

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

Örneğin, aşağıdaki runbook'u Azure portalından başlatacak ve test için bazı örnek web kancası verilerini geçirmek istiyorsanız, verileri kullanıcı arabiriminde JSON'da geçirmeniz gerekir.

Kullanıcı arabiriminden WebhookData parametresi

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

  • Web KancasıAdı: 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 geçirilen biçimle eşleşir.

{"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 herkes tarafından kullanılabilir. Bu nedenle, hassas bilgileri web kancası çağrılarına ekleme konusunda dikkatli olmanız gerekir.

Web kancası 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 web kancası tarafından çağrılıp çağrılmadığını belirlemek için runbook'a mantık ekleyebilirsiniz. Runbook'un parametresinin WebhookName özelliğini denetlemesini WebhookData sağlayın. Runbook, ve RequestBody özelliklerinde RequestHeader 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 Azure sanal ağ hizmet etiketlerini desteklerGuestAndHybridManagement. Hizmet etiketlerini kullanarak ağ güvenlik gruplarında ağ erişim denetimlerini tanımlayabilir veya sanal ağınızın içinden web kancalarını Azure Güvenlik Duvarı ve 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.

Web kancası oluşturma

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.

  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. Web kancası yayımlanmış bir runbook gerektirir. Bu kılavuzda, Azure Otomasyonu runbook oluşturma bölümünden oluşturulan runbook'un değiştirilmiş bir sürümü kullanılır.

    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ğinin vurgulandığı 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 simgesine tıklayın 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ını oluştur.

      Önemli

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

    9. Web Kancası Ekle sayfasına dönmek için Tamam'ı seçin.

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

      Parametrelerin vurgulandığı web kancası sayfası ekleyin.

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

    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.


Web kancası kullanma

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

  1. Web kancası çağrısının gövdesi olarak runbook'a geçirmek için 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):

    Web kancası çağrısından çıktı.

    İ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 edildi:
    • Web kancasının süresi doldu.
    • Web kancası devre dışı bırakıldı.
    • URL'deki belirteç geçersiz.
    404 Bulunamadı İstek aşağıdaki nedenlerden biri nedeniyle kabul edildi:
    • Web kancası 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:

    Web kancası işinden çıktı.

Web kancasını güncelleştirme

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 yeniden 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. Web kancasını içeren runbook'a 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
    

    çıktısı StatusCode : 200 , başarılı bir silme anlamına gelir.

ARM şablonuyla runbook ve web kancası oluşturma

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

  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ür.

    $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