Azure 元数据服务:适用于 Windows VM 的计划事件Azure Metadata Service: Scheduled Events for Windows VMs

预定事件是一个 Azure 元数据服务,可提供应用程序时间用于准备虚拟机维护。Scheduled Events is an Azure Metadata Service that gives your application time to prepare for virtual machine maintenance. 它提供有关即将发生的维护事件的信息(例如重新启动),使应用程序可以为其准备并限制中断。It provides information about upcoming maintenance events (e.g. reboot) so your application can prepare for them and limit disruption. 它可用于 Windows 和 Linux 上的所有 Azure 虚拟机类型(包括 PaaS 和 IaaS)。It is available for all Azure Virtual Machine types including PaaS and IaaS on both Windows and Linux.

有关 Linux 上的计划事件的信息,请参阅适用于 Linux VM 的计划事件For information about Scheduled Events on Linux, see Scheduled Events for Linux VMs.

Note

计划事件在所有 Azure 区域中正式发布。Scheduled Events is generally available in all Azure Regions. 有关最新版本信息,请参阅版本和区域可用性See Version and Region Availability for latest release information.

为何使用计划事件?Why Scheduled Events?

许多应用程序都可以受益于时间来准备虚拟机维护。Many applications can benefit from time to prepare for virtual machine maintenance. 时间可以用于执行应用程序的特定任务的提高可用性、可靠性和可维护性,包括:The time can be used to perform application specific tasks that improve availability, reliability, and serviceability including:

  • 检查点和还原Checkpoint and restore
  • 连接清空Connection draining
  • 主要副本故障转移Primary replica failover
  • 从负载均衡器池删除Removal from load balancer pool
  • 事件日志记录Event logging
  • 正常关闭Graceful shutdown

使用计划事件,应用程序可以发现维护的发生,并触发任务以限制其影响。Using Scheduled Events your application can discover when maintenance will occur and trigger tasks to limit its impact. 启用计划事件可在执行维护活动之前为虚拟机提供最少的时间。Enabling scheduled events gives your virtual machine a minimum amount of time before the maintenance activity is performed. 有关详细信息,请参阅下面的“事件计划”部分。See the Event Scheduling section below for details.

预定事件提供以下用例中的事件:Scheduled Events provides events in the following use cases:

基础知识The Basics

Azure 元数据服务公开在 VM 中使用可访问的 REST 终结点运行虚拟机的相关信息。Azure Metadata service exposes information about running Virtual Machines using a REST Endpoint accessible from within the VM. 该信息通过不可路由的 IP 提供,因此不会在 VM 外部公开。The information is available via a non-routable IP so that it is not exposed outside the VM.

终结点发现Endpoint Discovery

对于启用了 VNET 的 VM,元数据服务可通过不可路由的静态 IP (169.254.169.254) 使用。For VNET enabled VMs, the metadata service is available from a static non-routable IP, 169.254.169.254. 最新版本的计划事件的完整终结点是:The full endpoint for the latest version of Scheduled Events is:

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

如果不是在虚拟网络中创建虚拟机(云服务和经典 VM 的默认情况),则需使用额外的逻辑以发现要使用的 IP 地址。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. 请参阅此示例,了解如何发现主机终结点Refer to this sample to learn how to discover the host endpoint.

版本和区域可用性Version and Region Availability

计划事件服务受版本控制。The Scheduled Events Service is versioned. 版本是必需的,当前版本为 2017-11-01Versions are mandatory and the current version is 2017-11-01.

版本Version 发布类型Release Type 区域Regions 发行说明Release Notes
2017-08-012017-08-01 正式版General Availability 全部All
  • 已从 IaaS VM 的资源名称中删除前置下划线Removed prepended underscore from resource names for IaaS VMs
  • 针对所有请求强制执行元数据标头要求Metadata Header requirement enforced for all requests
  • 2017-03-012017-03-01 预览Preview 全部All
  • 初始版本Initial release
  • Note

    支持的计划事件的前一预览版 {latest} 发布为 api-version。Previous preview releases of scheduled events supported {latest} as the api-version. 此格式不再受支持,并且将在未来弃用。This format is no longer supported and will be deprecated in the future.

    启用和禁用计划事件Enabling and Disabling Scheduled Events

    首次为事件发出请求时,为服务启用了计划事件。Scheduled Events is enabled for your service the first time you make a request for events. 首次调用时应该会延迟响应最多两分钟。You should expect a delayed response in your first call of up to two minutes. 你应定期查询终结点,以便检测到即将发生的维护事件以及正在执行的维护活动的状态。You should query the endpoint periodically to detect upcoming maintenance events as well as the status of maintenance activities that are being performed.

    如果 24 小时未发出请求,将为服务禁用计划事件。Scheduled Events is disabled for your service if it does not make a request for 24 hours.

    用户启动的维护User Initiated Maintenance

    用户通过 Azure 门户、API、CLI 或 PowerShell 启动的虚拟机维护会生成计划事件。User initiated virtual machine maintenance via the Azure portal, API, CLI, or PowerShell results in a scheduled event. 这样便可以在应用程序中测试维护准备逻辑,并可以通过应用程序准备用户启动的维护。This allows you to test the maintenance preparation logic in your application and allows your application to prepare for user initiated maintenance.

    重启虚拟机会计划 Reboot 类型的事件。Restarting a virtual machine schedules an event with type Reboot. 重新部署虚拟机会计划 Redeploy 类型的事件。Redeploying a virtual machine schedules an event with type Redeploy.

    使用 APIUsing the API

    标头Headers

    查询元数据服务时,必须提供标头 Metadata:true 以确保不会在无意中重定向该请求。When you query the Metadata Service, you must provide the header Metadata:true to ensure the request was not unintentionally redirected. Metadata:true 标头对于所有预定事件请求是必需的。The Metadata:true header is required for all scheduled events requests. 不在请求中包含标头会导致元数据服务发出的“错误的请求”响应。Failure to include the header in the request will result in a Bad Request response from the Metadata Service.

    查询事件Query for events

    只需进行以下调用即可查询计划事件: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"}
    

    响应包含计划事件的数组。A response contains an array of scheduled events. 数组为空意味着目前没有计划事件。An empty array means that there are currently no events scheduled. 如果有计划事件,响应会包含事件的数组: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 是一个 ETag,它提供了一种简单的方法来检查自上次查询以来事件有效负载是否已更改。The DocumentIncarnation is an ETag and provides an easy way to inspect if the Events payload has changed since the last query.

    事件属性Event Properties

    属性Property 说明Description
    EventIdEventId 此事件的全局唯一标识符。Globally unique identifier for this event.

    示例:Example:
    • 602d9444-d2cd-49c7-8624-8643e7171297602d9444-d2cd-49c7-8624-8643e7171297
    EventTypeEventType 此事件造成的影响。Impact this event causes.

    值:Values:
    • Freeze:虚拟机计划暂停数秒。Freeze: The Virtual Machine is scheduled to pause for a few seconds. CPU 和网络连接可能会暂停,但对内存或打开的文件没有影响。CPU and network connectivity may be suspended, but there is no impact on memory or open files.
    • Reboot:计划重启虚拟机(非永久性内存丢失)。Reboot: The Virtual Machine is scheduled for reboot (non-persistent memory is lost).
    • Redeploy:计划将虚拟机移到另一节点(临时磁盘将丢失)。Redeploy: The Virtual Machine is scheduled to move to another node (ephemeral disks are lost).
    ResourceTypeResourceType 此事件影响的资源的类型。Type of resource this event impacts.

    值:Values:
    • VirtualMachine
    资源Resources 此事件影响的资源的列表。List of resources this event impacts. 它保证最多只能包含一个更新域的计算机,但可能不包含该更新域中的所有计算机。This is guaranteed to contain machines from at most one Update Domain, but may not contain all machines in the UD.

    示例:Example:
    • ["FrontEnd_IN_0", "BackEnd_IN_0"]["FrontEnd_IN_0", "BackEnd_IN_0"]
    事件状态Event Status 此事件的状态。Status of this event.

    值:Values:
    • Scheduled:此事件计划在 NotBefore 属性指定的时间之后启动。Scheduled: This event is scheduled to start after the time specified in the NotBefore property.
    • Started:此事件已启动。Started: This event has started.
    不提供 Completed 或类似状态;事件完成后,将不再返回事件。No Completed or similar status is ever provided; the event will no longer be returned when the event is completed.
    NotBeforeNotBefore 此事件可能会在之后启动的时间。Time after which this event may start.

    示例:Example:
    • 2016 年 9 月 19 日星期一 18:29:47 GMTMon, 19 Sep 2016 18:29:47 GMT

    事件计划Event Scheduling

    将根据事件类型为每个事件计划将来的最小量时间。Each event is scheduled a minimum amount of time in the future based on event type. 此时间反映在某个事件的 NotBefore 属性上。This time is reflected in an event's NotBefore property.

    EventTypeEventType 最小值通知Minimum Notice
    冻结Freeze 15 分钟15 minutes
    重新启动Reboot 15 分钟15 minutes
    重新部署Redeploy 10 分钟10 minutes
    PreemptPreempt 30 秒30 seconds

    事件作用域Event Scope

    计划的事件传送到:Scheduled events are delivered to:

    • 独立虚拟机Standalone Virtual Machines
    • 云服务中的所有虚拟机All Virtual Machines in a Cloud Service
    • 可用性集中的所有虚拟机All Virtual Machines in an Availability Set
    • 规模集位置组中的所有虚拟机。All Virtual Machines in a Scale Set Placement Group.

    因此,应查看事件中的 Resources 字段以确定将受到影响的 VM。As a result, you should check the Resources field in the event to identify which VMs are going to be impacted.

    启动事件Starting an event

    了解即将发生的事件并完成正常关闭逻辑后,可以通过使用 EventId 对元数据服务进行 POST 调用来批准未完成的事件。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. 这指示 Azure 可以缩短最小通知时间(如可能)。This indicates to Azure that it can shorten the minimum notification time (when possible).

    下面是 POST 请求正文中所需的 json。The following is the json expected in the POST request body. 请求应包含 StartRequests 列表。The request should contain a list of StartRequests. 每个 StartRequest 包含想要加速的事件的 EventIdEach 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
    

    Note

    确认事件后,即可允许事件针对事件中所有的 Resources 继续进行,而不仅仅是确认该事件的虚拟机。Acknowledging an event allows the event to proceed for all Resources in the event, not just the virtual machine that acknowledges the event. 因此,可以选择一个指挥计算机来协调该确认,为简单起见,可选择 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 示例PowerShell sample

    下例将查询计划事件的元数据服务器并审核所有未完成的事件。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 
        }
    }
    

    后续步骤Next steps