Information om en webhookDetails of a webhook

I följande tabell beskrivs de egenskaper som du måste konfigurera för en webhook.The following table describes the properties that you must configure for a webhook.

EgenskapProperty

BeskrivningDescription

NamnName

Du kan ange vilket namn som helst för en webhook eftersom detta inte är exponerad för klienten.You can provide any name you want for a webhook since this is not exposed to the client.Den används endast för dig för att identifiera runbook i Azure Automation.It is only used for you to identify the runbook in Azure Automation.Som bästa praxis, bör du ge webhooken ett namn som är relaterade till klienter som använder den.As a best practice, you should give the webhook a name related to the client that will use it.

URL: en innehåller en säkerhetstoken som gör att runbook anropas av en tredjeparts-system utan ytterligare autentisering.The URL contains a security token that allows the runbook to be invoked by a third party system with no further authentication.Det bör därför behandlas som ett lösenord.For this reason, it should be treated like a password.Av säkerhetsskäl bör visa du bara URL: en i Azure-portalen när webhook har skapats.For security reasons, you can only view the URL in the Azure portal at the time the webhook is created.Du bör anteckna URL-Adressen i en säker plats för framtida användning.You should note the URL in a secure location for future use.

FörfallodatumExpiration date

Varje webhook har ett sista giltighetsdatum som den kan inte längre användas som ett certifikat.Like a certificate, each webhook has an expiration date at which time it can no longer be used.Den här upphör att gälla kan ändras när du har skapat webhooken.This expiration date can be modified after the webhook is created.

EnabledEnabled

En webhook är aktiverad som standard när den skapas.A webhook is enabled by default when it is created.Om du den inaktiverad, kommer ingen klient att kunna använda den.If you set it to Disabled, then no client will be able to use it.Du kan ange den aktiverad egenskapen när du skapar webhooken eller när som helst när den skapas.You can set the Enabled property when you create the webhook or anytime once it is created.

Innehållet i den inkommande POST-begäranden.The body of the incoming POST request.Detta behåller all formatering, till exempel sträng, JSON, XML, eller formulär-kodade data.This will retain any formatting such as string, JSON, XML, or form encoded data.Runbook måste vara skriven för att arbeta med dataformatet som förväntas.The runbook must be written to work with the data format that is expected.

Det finns ingen konfiguration av webhooken krävs för att stödja den $WebhookData parametern och runbook inte krävs för att godkänna.There is no configuration of the webhook required to support the $WebhookData parameter, and the runbook is not required to accept it.Om runbook inte definierar parametern ignoreras någon information om den begäran som skickades från klienten.If the runbook does not define the parameter, then any details of the request sent from the client is ignored.

Om du anger ett värde för $WebhookData när du skapar webhooken, att värdet kommer att åsidosättas när webhooken startar runbook med data från klienten POST-begäran, även om klienten inte innehåller några data i begärandetexten.If you specify a value for $WebhookData when you create the webhook, that value will be overridden when the webhook starts the runbook with the data from the client POST request, even if the client does not include any data in the request body.Om du startar en runbook med hjälp av en annan metod än en webhook $WebhookData, kan du ange ett värde för $Webhookdata som identifieras av runbook.If you start a runbook that has $WebhookData using a method other than a webhook, you can provide a value for $Webhookdata that will be recognized by the runbook.Det här värdet ska vara ett objekt med samma egenskaper som $Webhookdata så att runbook fungerar korrekt med det som om den arbetade med faktiska WebhookData skickades av en webhook.This value should be an object with the same properties as $Webhookdata so that the runbook can properly work with it as if it was working with actual WebhookData passed by a webhook.

Till exempel om du startar följande runbook från Azure Portal och vill skicka vissa exempel WebhookData för att testa, eftersom WebhookData är ett objekt som ska den skickas som JSON i Användargränssnittet.For example, if you are starting the following runbook from the Azure Portal and want to pass some sample WebhookData for testing, since WebhookData is an object, it should be passed as JSON in the UI.

För ovan runbook, om du har följande egenskaper för parametern WebhookData:For the above runbook, if you have the following properties for the WebhookData parameter:

WebhookName: MyWebhookWebhookName: MyWebhook

RequestHeader: från = testanvändareRequestHeader: From=Test User

RequestBody: [”VM1”, ”VM2”]RequestBody: [“VM1”, “VM2”]

Du skulle sedan överföra följande JSON-värde i Användargränssnittet för WebhookData-parametern:Then you would pass the following JSON value in the UI for the WebhookData parameter:

Värdena för alla indataparametrar loggas med runbook-jobbet.The values of all input parameters are logged with the runbook job.Detta innebär att alla indata som angetts av klienten i webhook-begäran är inloggade och tillgänglig för alla med åtkomst till automation-jobb.This means that any input provided by the client in the webhook request will be logged and available to anyone with access to the automation job.Därför bör du vara försiktig om känslig information, inklusive i webhook-anrop.For this reason, you should be cautious about including sensitive information in webhook calls.

SäkerhetSecurity

Säkerheten för en webhook är beroende av säkerheten för URL: en som innehåller en säkerhetstoken som gör att de kan anropas.The security of a webhook relies on the privacy of its URL which contains a security token that allows it to be invoked.Azure Automation utför inte någon autentisering på begäran så länge det görs till rätt URL.Azure Automation does not perform any authentication on the request as long as it is made to the correct URL.Därför bör du inte använda webhooks för runbooks som utför mycket känsliga funktioner utan att använda ett annat sätt att verifiera begäran.For this reason, webhooks should not be used for runbooks that perform highly sensitive functions without using an alternate means of validating the request.

Du kan inkludera logik i runbook för att fastställa att den anropades av en webhook genom att kontrollera den WebhookName -egenskapen för parametern $WebhookData.You can include logic within the runbook to determine that it was called by a webhook by checking the WebhookName property of the $WebhookData parameter.Runbook kan utföra ytterligare verifiering genom att söka efter specifika informationen i den RequestHeader eller RequestBody egenskaper.The runbook could perform further validation by looking for particular information in the RequestHeader or RequestBody properties.

Med hjälp av en webhookUsing a webhook

Om du vill använda en webhook när den har skapats, måste klientprogrammet utfärda en HTTP POST med URL-Adressen för webhooken.To use a webhook after it has been created, your client application must issue an HTTP POST with the URL for the webhook.Syntaxen för webhooken har följande format.The syntax of the webhook will be in the following format.

http://<Webhook Server>/token?=<Token Value>

Klienten får ett av följande returkoder från POST-begäran.The client will receive one of the following return codes from the POST request.

KodCode

TextText

BeskrivningDescription

202202

AccepteradAccepted

Begäran accepterades och runbook placerades i kö.The request was accepted, and the runbook was successfully queued.

400400

Felaktig förfråganBad Request

Begäran accepterades inte av något av följande skäl.The request was not accepted for one of the following reasons.

Webhook har gått ut.The webhook has expired.

Webhook har inaktiverats.The webhook is disabled.

Token i URL-Adressen är ogiltig.The token in the URL is invalid.

404404

Kunde inte hittasNot Found

Begäran accepterades inte av något av följande skäl.The request was not accepted for one of the following reasons.

ExempelExample

I följande exempel använder Windows PowerShell för att starta en runbook med en webhook.The following example uses Windows PowerShell to start a runbook with a webhook.Observera att alla språk som kan göra en HTTP-begäran kan använda en webhook; Windows PowerShell används bara exempel.Note that any language that can make an HTTP request can use a webhook; Windows PowerShell is just used here as an example.

Runbook förväntar sig en lista över virtuella datorer som har formaterats i JSON i brödtexten i begäran.The runbook is expecting a list of virtual machines formatted in JSON in the body of the request.Vi också inklusive information om som startar runbook och datum och tid som startas i huvudet i begäran.We also are including information about who is starting the runbook and the date and time it is being started in the header of the request.

Följande bild visar brödtexten i begäran (med hjälp av en Fiddler trace) som är tillgängligt för runbook i den RequestBody -egenskapen för WebhookData.The following image shows the body of the request (using a Fiddler trace) that is available to the runbook in the RequestBody property of WebhookData.Detta formateras som JSON eftersom som har det format som ingick i brödtexten i begäran.This is formatted as JSON because that was the format that was included in the body of the request.

Följande exempel-runbook utlöses när varningsregeln aktiveras och samlar det in aviseringskontext-parametrar som krävs att identifiera den resurs där den kommer att åtgärda runbook.The following sample runbook is triggered when the alert rule becomes active and it collects the Alert context parameters which are required for the runbook to identify the resource on which it will be taking action.