Instance Metadata Service: Scheduled Events für Windows-VMsAzure Metadata Service: Scheduled Events for Windows VMs

Geplante Ereignisse ist ein Azure-Metadatendienst, der Ihren Anwendungen Zeit zur Vorbereitung auf die Wartung virtueller Computer gibt.Scheduled Events is an Azure Metadata Service that gives your application time to prepare for virtual machine maintenance. Er stellt Informationen zu geplanten Wartungsereignissen (z.B. Neustart) bereit, damit Ihre Anwendung sich darauf vorbereiten und Unterbrechungen begrenzen kann.It provides information about upcoming maintenance events (e.g. reboot) so your application can prepare for them and limit disruption. Der Dienst steht für sämtliche Arten virtueller Azure-Computer zur Verfügung, einschließlich PaaS und IaaS unter Windows und Linux.It is available for all Azure Virtual Machine types including PaaS and IaaS on both Windows and Linux.

Informationen zu geplanten Ereignissen unter Linux finden Sie unter Geplante Ereignisse für virtuelle Linux-Computer .For information about Scheduled Events on Linux, see Scheduled Events for Linux VMs.

Hinweis

Scheduled Events ist in allen Azure-Regionen allgemein verfügbar.Scheduled Events is generally available in all Azure Regions. Informationen zu aktuellen Releases finden Sie unter Version und regionale Verfügbarkeit.See Version and Region Availability for latest release information.

Warum geplante Ereignisse?Why Scheduled Events?

Viele Anwendungen können von der Vorbereitungszeit auf die Wartung virtueller Computer profitieren.Many applications can benefit from time to prepare for virtual machine maintenance. Die Zeit kann genutzt werden, um anwendungsspezifische Aufgaben durchzuführen, die die Verfügbarkeit, Zuverlässigkeit und Wartungsfreundlichkeit verbessern. Dazu gehören u.a.:The time can be used to perform application specific tasks that improve availability, reliability, and serviceability including:

  • Prüfpunkt und WiederherstellungCheckpoint and restore
  • VerbindungsausgleichConnection draining
  • Primäres ReplikatfailoverPrimary replica failover
  • Entfernung aus dem LastenausgleichspoolRemoval from load balancer pool
  • EreignisprotokollierungEvent logging
  • Ordnungsgemäßes HerunterfahrenGraceful shutdown

Mit Geplante Ereignisse kann Ihre Anwendung erkennen, wann eine Wartung erfolgt, und so Aufgaben auslösen, um die Auswirkungen zu beschränken.Using Scheduled Events your application can discover when maintenance will occur and trigger tasks to limit its impact. Mit geplanten Ereignissen erhält Ihr virtueller Computer ein Mindestmaß an Zeit, bevor die Wartungsaktivität ausgeführt wird.Enabling scheduled events gives your virtual machine a minimum amount of time before the maintenance activity is performed. Details dazu finden Sie weiter unten im Abschnitt „Ereigniszeitplanung“.See the Event Scheduling section below for details.

Geplante Ereignisse umfasst Ereignisse in den folgenden Anwendungsfällen:Scheduled Events provides events in the following use cases:

Die GrundlagenThe Basics

Der Azure-Metadatendienst macht Informationen zu ausgeführten virtuellen Computern mithilfe eines innerhalb einer VM zugänglichen REST-Endpunkts verfügbar.Azure Metadata service exposes information about running Virtual Machines using a REST Endpoint accessible from within the VM. Die Informationen stehen über eine nicht routbare IP-Adresse bereit, die außerhalb der VM nicht verfügbar gemacht wird.The information is available via a non-routable IP so that it is not exposed outside the VM.

EndpunktermittlungEndpoint Discovery

Für virtuelle Computer in VNETs ist der Metadatendienst über eine statische, nicht routingfähige IP-Adresse (169.254.169.254) verfügbar.For VNET enabled VMs, the metadata service is available from a static non-routable IP, 169.254.169.254. Der vollständige Endpunkt für die neueste Version von Scheduled Events ist wie folgt:The full endpoint for the latest version of Scheduled Events is:

http://169.254.169.254/metadata/scheduledevents?api-version=2017-11-01

Wenn der virtuelle Computer nicht innerhalb eines virtuellen Netzwerks erstellt wird (Standard für Clouddienste und klassische virtuelle Computer), ist zusätzliche Logik erforderlich, um die zu verwendende IP-Adresse zu ermitteln.If the Virtual Machine is not created within a Virtual Network, the default cases for cloud services and classic VMs, additional logic is required to discover the IP address to use. In diesem Beispiel erfahren Sie, wie Sie den Hostendpunkt ermitteln.Refer to this sample to learn how to discover the host endpoint.

Version und regionale VerfügbarkeitVersion and Region Availability

Der Dienst Geplante Ereignisse ist versionsspezifisch.The Scheduled Events Service is versioned. Versionen sind obligatorisch, und die aktuelle Version ist 2017-11-01.Versions are mandatory and the current version is 2017-11-01.

VersionVersion ReleasetypRelease Type RegionsRegions VersionsinformationenRelease Notes
2017-11-012017-11-01 Allgemeine VerfügbarkeitGeneral Availability AlleAll
  • Unterstützung für die Entfernung von VMs mit niedriger Priorität hinzugefügt (EventType 'Preempt')Added support for Low-priority VM eviction EventType 'Preempt'
  • 2017-08-012017-08-01 Allgemeine VerfügbarkeitGeneral Availability AlleAll
  • Ein vorangestellter Unterstrich wurde aus Ressourcennamen virtueller Iaas-Computer entfernt.Removed prepended underscore from resource names for IaaS VMs
  • Der Metadatenheader wird als Voraussetzung für alle Anforderungen erzwungen.Metadata Header requirement enforced for all requests
  • 2017-03-012017-03-01 VorschauPreview AlleAll
  • Erste VersionInitial release
  • Hinweis

    In früheren Vorschauversionen von geplanten Ereignissen wird {latest} als „api-version“ unterstützt.Previous preview releases of scheduled events supported {latest} as the api-version. Dieses Format wird nicht mehr unterstützt und wird zukünftig veraltet sein.This format is no longer supported and will be deprecated in the future.

    Aktivieren und Deaktivieren von Scheduled EventsEnabling and Disabling Scheduled Events

    Scheduled Events wird für Ihren Dienst aktiviert, wenn Sie zum ersten Mal Ereignisse anfordern.Scheduled Events is enabled for your service the first time you make a request for events. Beim ersten Aufruf ist eine um bis zu zwei Minuten verzögerte Antwort zu erwarten.You should expect a delayed response in your first call of up to two minutes. Sie sollten den Endpunkt regelmäßig abfragen, um anstehende Wartungsereignisse sowie den Status von gerade ausgeführten Wartungsaktivitäten zu ermitteln.You should query the endpoint periodically to detect upcoming maintenance events as well as the status of maintenance activities that are being performed.

    Scheduled Events wird für Ihren Dienst deaktiviert, wenn 24 Stunden lang keine Anforderung erfolgt.Scheduled Events is disabled for your service if it does not make a request for 24 hours.

    Vom Benutzer initiierte WartungUser Initiated Maintenance

    Eine vom Benutzer über das Azure-Portal, die API, die Befehlszeilenschnittstelle oder PowerShell initiierte Wartung eines virtuellen Computers führt zu einem geplanten Ereignis.User initiated virtual machine maintenance via the Azure portal, API, CLI, or PowerShell results in a scheduled event. So können Sie die Logik zur Vorbereitung auf Wartungsmaßnahmen in Ihrer Anwendung testen und Ihre Anwendung auf die vom Benutzer initiierte Wartung vorbereiten.This allows you to test the maintenance preparation logic in your application and allows your application to prepare for user initiated maintenance.

    Das Neustarten eines virtuellen Computers plant ein Ereignis vom Typ Reboot.Restarting a virtual machine schedules an event with type Reboot. Das erneute Bereitstellen eines virtuellen Computers plant ein Ereignis vom Typ Redeploy.Redeploying a virtual machine schedules an event with type Redeploy.

    Verwenden der APIUsing the API

    HeaderHeaders

    Beim Abfragen des Metadatendiensts müssen Sie den Header Metadata:true angeben, um sicherzustellen, dass die Anforderung nicht unbeabsichtigt umgeleitet wurde.When you query the Metadata Service, you must provide the header Metadata:true to ensure the request was not unintentionally redirected. Der Header Metadata:true ist für alle Anforderungen für Geplante Ereignisse erforderlich.The Metadata:true header is required for all scheduled events requests. Wird der Header nicht in die Anforderung eingefügt, erhalten Sie vom Metadatendienst die Antwort „Ungültige Anforderung“.Failure to include the header in the request will result in a Bad Request response from the Metadata Service.

    Abfragen von EreignissenQuery for events

    Sie können geplante Ereignisse abfragen, indem Sie einfach folgenden Aufruf ausführen:You can query for Scheduled Events simply by making the following call:

    PowerShellPowershell

    curl http://169.254.169.254/metadata/scheduledevents?api-version=2017-11-01 -H @{"Metadata"="true"}
    

    Eine Antwort enthält ein Array geplanter Ereignisse.A response contains an array of scheduled events. Ein leeres Array bedeutet, dass derzeit keine Ereignisse geplant sind.An empty array means that there are currently no events scheduled. Sofern geplante Ereignisse vorliegen, enthält die Antwort ein Array mit Ereignissen:In the case where there are scheduled events, the response contains an array of events:

    {
        "DocumentIncarnation": {IncarnationID},
        "Events": [
            {
                "EventId": {eventID},
                "EventType": "Reboot" | "Redeploy" | "Freeze" | "Preempt",
                "ResourceType": "VirtualMachine",
                "Resources": [{resourceName}],
                "EventStatus": "Scheduled" | "Started",
                "NotBefore": {timeInUTC},
            }
        ]
    }
    

    DocumentIncarnation ist ein ETag und bietet eine einfache Möglichkeit, um zu untersuchen, ob sich die Ereignisnutzlast seit der letzten Abfrage geändert hat.The DocumentIncarnation is an ETag and provides an easy way to inspect if the Events payload has changed since the last query.

    EreigniseigenschaftenEvent Properties

    EigenschaftProperty BESCHREIBUNGDescription
    EventIdEventId Global eindeutiger Bezeichner für dieses EreignisGlobally unique identifier for this event.

    Beispiel:Example:
    • 602d9444-d2cd-49c7-8624-8643e7171297602d9444-d2cd-49c7-8624-8643e7171297
    EventTypeEventType Auswirkungen dieses EreignissesImpact this event causes.

    Werte:Values:
    • Freeze: Das Anhalten des virtuellen Computers für einige Sekunden ist geplant.Freeze: The Virtual Machine is scheduled to pause for a few seconds. Der Prozessor und die Netzwerkverbindung werden möglicherweise angehalten, es gibt jedoch keine Auswirkungen auf den Arbeitsspeicher oder geöffnete Dateien.CPU and network connectivity may be suspended, but there is no impact on memory or open files.
    • Reboot: Der Neustart der VM ist geplant (der flüchtige Arbeitsspeicher geht verloren).Reboot: The Virtual Machine is scheduled for reboot (non-persistent memory is lost).
    • Redeploy: Das Verschieben der VM auf einen anderen Knoten ist geplant (kurzlebige Datenträger gehen verloren).Redeploy: The Virtual Machine is scheduled to move to another node (ephemeral disks are lost).
    • Preempt: Virtueller Computer mit niedriger Priorität wird gelöscht (kurzlebige Datenträger gehen verloren).Preempt: The Low-priority Virtual Machine is being deleted (ephemeral disks are lost).
    ResourceTypeResourceType Typ der Ressource, auf die sich dieses Ereignis auswirktType of resource this event impacts.

    Werte:Values:
    • VirtualMachine
    RessourcenResources Liste von Ressourcen, auf die sich dieses Ereignis auswirkt.List of resources this event impacts. Diese Liste enthält garantiert Computer aus maximal einer Updatedomäne, muss jedoch nicht alle Computer in dieser Domäne enthalten.This is guaranteed to contain machines from at most one Update Domain, but may not contain all machines in the UD.

    Beispiel:Example:
    • [„FrontEnd_IN_0“, „BackEnd_IN_0“]["FrontEnd_IN_0", "BackEnd_IN_0"]
    EreignisstatusEvent Status Status dieses EreignissesStatus of this event.

    Werte:Values:
    • Scheduled: Dieses Ereignis erfolgt nach dem in der NotBefore-Eigenschaft angegebenen Zeitpunkt.Scheduled: This event is scheduled to start after the time specified in the NotBefore property.
    • Started: Dieses Ereignis wurde gestartet.Started: This event has started.
    Completed oder ähnliche Statusangaben werden niemals bereitgestellt. Das Ereignis wird nicht mehr zurückgegeben, nachdem es abgeschlossen ist.No Completed or similar status is ever provided; the event will no longer be returned when the event is completed.
    NotBeforeNotBefore Zeit, nach der dieses Ereignis gestartet werden kannTime after which this event may start.

    Beispiel:Example:
    • Mo., 19. September 2016 18:29:47 GMTMon, 19 Sep 2016 18:29:47 GMT

    EreigniszeitplanungEvent Scheduling

    Jedes Ereignis erfolgt dem Zeitplan nach, basierend auf dem Ereignistyp, eine Mindestzeitspanne in der Zukunft.Each event is scheduled a minimum amount of time in the future based on event type. Diese Zeit ist in der NotBefore-Eigenschaft eines Ereignisses angegeben.This time is reflected in an event's NotBefore property.

    EventTypeEventType MindestzeitspanneMinimum Notice
    FreezeFreeze 15 Minuten15 minutes
    RebootReboot 15 Minuten15 minutes
    Erneute BereitstellungRedeploy 10 Minuten10 minutes
    PreemptPreempt 30 Sekunden30 seconds

    EreignisbereichEvent Scope

    Geplante Ereignisse werden übermittelt an:Scheduled events are delivered to:

    • Eigenständige virtuelle ComputerStandalone Virtual Machines
    • Alle virtuellen Computer in einem ClouddienstAll Virtual Machines in a Cloud Service
    • Alle virtuellen Computer in einer VerfügbarkeitsgruppeAll Virtual Machines in an Availability Set
    • Alle virtuellen Computer in einer Skalierungsgruppen-PlatzierungsgruppeAll Virtual Machines in a Scale Set Placement Group.

    Daher sollten Sie das Feld Resources in einem Ereignis überprüfen, um zu ermitteln, welche VMs betroffen sein werden.As a result, you should check the Resources field in the event to identify which VMs are going to be impacted.

    Starten eines EreignissesStarting an event

    Sobald Sie von einem anstehenden Ereignis erfahren und Ihre Logik für ein ordnungsgemäßes Herunterfahren vervollständigt haben, können Sie ein ausstehendes Ereignis genehmigen, indem Sie einen Aufruf des Typs POST an den Metadatendienst mit der EventId ausführen.Once you have learned of an upcoming event and completed your logic for graceful shutdown, you can approve the outstanding event by making a POST call to the metadata service with the EventId. Dies zeigt Azure an, dass die minimale Benachrichtigungszeit verkürzt werden kann (wenn möglich).This indicates to Azure that it can shorten the minimum notification time (when possible).

    Im Folgenden finden Sie den in der POST-Anforderung erwarteten JSON-Code.The following is the json expected in the POST request body. Die Anforderung sollte eine Liste mit StartRequests enthalten.The request should contain a list of StartRequests. Jede StartRequest enthält die EventId für das Ereignis, das Sie beschleunigen möchten:Each StartRequest contains the EventId for the event you want to expedite:

    {
        "StartRequests" : [
            {
                "EventId": {EventId}
            }
        ]
    }
    

    PowerShellPowershell

    curl -H @{"Metadata"="true"} -Method POST -Body '{"StartRequests": [{"EventId": "f020ba2e-3bc0-4c40-a10b-86575a9eabd5"}]}' -Uri http://169.254.169.254/metadata/scheduledevents?api-version=2017-11-01
    

    Hinweis

    Durch das Bestätigen eines Ereignisses kann dieses für alle Resources im Ereignis fortgesetzt werden, nicht nur für den virtuellen Computer, der das Ereignis bestätigt.Acknowledging an event allows the event to proceed for all Resources in the event, not just the virtual machine that acknowledges the event. Daher sollten Sie möglicherweise einen Leiter zur Koordinierung der Bestätigung auswählen, beispielsweise einfach den ersten Computer im Feld Resources.You may therefore choose to elect a leader to coordinate the acknowledgement, which may be as simple as the first machine in the Resources field.

    PowerShell-BeispielPowerShell sample

    Im folgenden Beispiel fragt der Metadatenserver geplante Ereignisse ab und genehmigt jedes ausstehende Ereignis.The following sample queries the metadata service for scheduled events and approves each outstanding event.

    # How to get scheduled events 
    function Get-ScheduledEvents($uri)
    {
        $scheduledEvents = Invoke-RestMethod -Headers @{"Metadata"="true"} -URI $uri -Method get
        $json = ConvertTo-Json $scheduledEvents
        Write-Host "Received following events: `n" $json
        return $scheduledEvents
    }
    
    # How to approve a scheduled event
    function Approve-ScheduledEvent($eventId, $uri)
    {
        # Create the Scheduled Events Approval Document
        $startRequests = [array]@{"EventId" = $eventId}
        $scheduledEventsApproval = @{"StartRequests" = $startRequests} 
        
        # Convert to JSON string
        $approvalString = ConvertTo-Json $scheduledEventsApproval
    
        Write-Host "Approving with the following: `n" $approvalString
    
        # Post approval string to scheduled events endpoint
        Invoke-RestMethod -Uri $uri -Headers @{"Metadata"="true"} -Method POST -Body $approvalString
    }
    
    function Handle-ScheduledEvents($scheduledEvents)
    {
        # Add logic for handling events here
    }
    
    ######### Sample Scheduled Events Interaction #########
    
    # Set up the scheduled events URI for a VNET-enabled VM
    $localHostIP = "169.254.169.254"
    $scheduledEventURI = 'http://{0}/metadata/scheduledevents?api-version=2017-11-01' -f $localHostIP 
    
    # Get events
    $scheduledEvents = Get-ScheduledEvents $scheduledEventURI
    
    # Handle events however is best for your service
    Handle-ScheduledEvents $scheduledEvents
    
    # Approve events when ready (optional)
    foreach($event in $scheduledEvents.Events)
    {
        Write-Host "Current Event: `n" $event
        $entry = Read-Host "`nApprove event? Y/N"
        if($entry -eq "Y" -or $entry -eq "y")
        {
            Approve-ScheduledEvent $event.EventId $scheduledEventURI 
        }
    }
    

    Nächste SchritteNext steps