使用 Exchange 中的 EWS 更新约会的时区Update the time zone for an appointment by using EWS in Exchange

了解如何使用 Exchange 中的 EWS 托管 API 或 EWS 更新现有约会或会议的时区。Learn how to update the time zone for an existing appointment or meeting by using the EWS Managed API or EWS in Exchange.

在 Exchange 日历上创建约会或会议时,用于指定开始和结束时间的时区将保存为约会的创建时区。When an appointment or meeting is created on an Exchange calendar, the time zone used to specify the start and end times is saved as the creation time zone for the appointment. 您可以使用 EWS 托管 API 或 EWS 更改该时区。You can change that time zone by using the EWS Managed API or EWS. 但是,更改约会上的时区会对约会的开始时间和结束时间产生其他影响。However, changing the time zone on an appointment has other effects on the start and end time of the appointment.

时间值以协调通用时间(UTC)的形式存储在 Exchange 服务器上。Time values are stored on the Exchange server in Coordinate Universal Time (UTC). 因此,如果约会设置为在东部时区(UTC-05:00)中以 1:00 PM (13:00)开始,则该值在服务器上存储为 6:00 PM (18:00),假定时区处于其标准时间阶段。So if an appointment is set to start at 1:00 PM (13:00) in the Eastern time zone (UTC-05:00), that value is stored as 6:00 PM (18:00) on the server, assuming that the time zone is in its standard time phase. 在其他时区中查看该约会时,将从 UTC 值中添加或减去相应的小时数,以确定特定时区的时间。When that appointment is viewed in other time zones, the appropriate number of hours is added or subtracted from the UTC value to determine the time zone-specific time. 例如,如果约会的开始时间为东部时间下午1:00 (6:00 PM UTC),并且在太平洋时区(UTC-08:00)中从客户端查看,则该客户端的时区特定开始时间为 10:00 AM (18:00-08:00)。For example, if an appointment has a start time at 1:00 PM Eastern (6:00 PM UTC), and is viewed from a client in the Pacific time zone (UTC-08:00), the time-zone specific start time for that client would be 10:00 AM (18:00 - 08:00).

当您更新约会的时区而不更新开始和结束时间时,服务器将更新存储在服务器上的 UTC 值,以使开始时间和结束时间与时区特定的时间相同。When you update the time zone of the appointment without updating the start and end time, the server updates the UTC values stored on the server to keep the start and end time as the same time zone-specific times. 例如,请考虑 "东部时间下午 1:00" 约会。For example, consider the 1:00 PM Eastern appointment. 时间存储为服务器上的 18:00 UTC。The time is stored as 18:00 UTC on the server. 如果约会的时区更改为 "太平洋时区",则服务器将开始时间更改为 "太平洋时间 1:00 PM (21:00 UTC)"。If the time zone of the appointment is changed to the Pacific time zone, the server shifts the start time to 1:00 PM Pacific (21:00 UTC).

您可以通过显式设置开始时间和结束时间来更改此行为。You can change this behavior by explicitly setting the start and end times.

使用 EWS 托管 API 更新现有约会上的时区Updating the time zone on an existing appointment by using the EWS Managed API

在下面的示例中,通过更新StartTimeZoneEndTimeZone属性,可以使用 EWS 托管 API 将现有约会上的时区更新为中央时区。In the following example, the EWS Managed API is used to update the time zone on an existing appointment to the Central time zone by updating the Appointment.StartTimeZone and Appointment.EndTimeZone properties. 如果将_shiftAppointnment_参数设置为true,则代码不会显式设置约会的开始时间和结束时间。If the shiftAppointnment parameter is set to true, the code does not explicitly set the start and end times on the appointment. 在这种情况下,服务器将移动开始和结束时间,以使其在新时区中的相对时区相同。In this case, the server will shift the start and end times to keep them at the same time zone-relative times in the new time zone. 如果设置为false,则代码将显式转换开始时间和结束时间,以在 UTC 时间内保持约会。If set to false, the code converts the start and end times explicitly to keep the appointment at the same time in UTC.

此示例假定已使用凭据Url属性中的有效值对ExchangeService对象进行了初始化。This example assumes that the ExchangeService object has been initialized with valid values in the Credentials and Url properties.

static void UpdateAppointmentTimeZone(ExchangeService service, ItemId apptId, bool shiftAppointment)
{
    PropertySet includeTimeZones = new PropertySet(AppointmentSchema.Subject,
                                                   AppointmentSchema.Start,
                                                   AppointmentSchema.ReminderDueBy,
                                                   AppointmentSchema.End,
                                                   AppointmentSchema.StartTimeZone,
                                                   AppointmentSchema.EndTimeZone);
    Appointment apptToUpdate;
    // Load the existing appointment.
    // This will result in a call to EWS.
    try
    {
        apptToUpdate = Appointment.Bind(service, apptId, includeTimeZones);
    }
    catch (Exception ex)
    {
        Console.WriteLine("Error retrieving existing appointment: {0}", ex.Message);
        return;
    }
    Console.WriteLine("Before update:");
    // Output the current start, reminder, end, and time zones.
    Console.WriteLine("  Start: {0}", apptToUpdate.Start);
    Console.WriteLine("  Start time zone: {0}", apptToUpdate.StartTimeZone.DisplayName);
    Console.WriteLine("  Reminder: {0}", apptToUpdate.ReminderDueBy);
    Console.WriteLine("  End: {0}", apptToUpdate.End);
    Console.WriteLine("  End time zone: {0}", apptToUpdate.EndTimeZone.DisplayName);
    // Retrieve the Central time zone.
    TimeZoneInfo centralTZ = TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time");
    // Update the time zones on the appointment.
    apptToUpdate.StartTimeZone = centralTZ;
    apptToUpdate.EndTimeZone = centralTZ;
    if (!shiftAppointment)
    {
        // Set the start and end times explicitly so that the appointment
        // will start and end at the same UTC time.
        // Convert the times to then Central time zone. This
        // will keep them at the same time in UTC.
        // For example, 1:00 PM Eastern becomes 12:00 PM Central.
        DateTime newStartTime = TimeZoneInfo.ConvertTime(
            apptToUpdate.Start, centralTZ);
        DateTime newEndTime = TimeZoneInfo.ConvertTime(
            apptToUpdate.End, centralTZ);
        apptToUpdate.Start = newStartTime;
        apptToUpdate.End = newEndTime;
    }
    try
    {
        // Save the changes. This will result in a call to EWS.
        apptToUpdate.Update(ConflictResolutionMode.AlwaysOverwrite, 
            SendInvitationsOrCancellationsMode.SendToNone);
    }
    catch (Exception ex)
    {
        Console.WriteLine("Error updating appointment: {0}", ex.Message);
        return;
    }
    // Now rebind to the appointment to get the new values.
    Appointment apptAfterUpdate;
    
    try
    {
        // This will result in a call to EWS.
        apptAfterUpdate = Appointment.Bind(service, apptId, includeTimeZones);
    }
    catch (Exception ex)
    {
        Console.WriteLine("Error retrieving existing appointment: {0}", ex.Message);
        return;
    }
    Console.WriteLine("After update:");
    // Output the current start, reminder, end, and time zones.
    Console.WriteLine("  Start: {0}", apptAfterUpdate.Start);
    Console.WriteLine("  Start time zone: {0}", apptAfterUpdate.StartTimeZone.DisplayName);
    Console.WriteLine("  Reminder: {0}", apptAfterUpdate.ReminderDueBy);
    Console.WriteLine("  End: {0}", apptAfterUpdate.End);
    Console.WriteLine("  End time zone: {0}", apptAfterUpdate.EndTimeZone.DisplayName);
}

当使用此示例更新从美国东部时间下午1:00 点开始的约会,并在美国东部时间下午2:00 结束时,将_shiftAppointment_参数设置为 true,并将ExchangeService属性设置为东部时区,输出如下所示:When the example is used to update an appointment that starts at 1:00 PM Eastern and ends at 2:00 PM Eastern, with the shiftAppointment parameter set to true, and the ExchangeService.TimeZone property set to the Eastern time zone, the output looks like the following.

Before update:
  Start: 6/20/2014 1:00:00 PM
  Start time zone: (UTC-05:00) Eastern Time (US & Canada)
  Reminder: 6/20/2014 1:00:00 PM
  End: 6/20/2014 2:00:00 PM
  End time zone: (UTC-05:00) Eastern Time (US & Canada)
After update:
  Start: 6/20/2014 2:00:00 PM
  Start time zone: (UTC-06:00) Central Time (US & Canada)
  Reminder: 6/20/2014 2:00:00 PM
  End: 6/20/2014 3:00:00 PM
  End time zone: (UTC-06:00) Central Time (US & Canada)

当使用此示例将_shiftAppointment_参数设置为 false,并再次将时区属性设置为东部时区时,输出的外观略有不同。When the example is used to update the same appointment with the shiftAppointment parameter set to false, and with the TimeZone property again set to the Eastern time zone, the output looks a little different.

Before update:
  Start: 6/20/2014 1:00:00 PM
  Start time zone: (UTC-05:00) Eastern Time (US & Canada)
  Reminder: 6/20/2014 1:00:00 PM
  End: 6/20/2014 2:00:00 PM
  End time zone: (UTC-05:00) Eastern Time (US & Canada)
After update:
  Start: 6/20/2014 1:00:00 PM
  Start time zone: (UTC-06:00) Central Time (US & Canada)
  Reminder: 6/20/2014 1:00:00 PM
  End: 6/20/2014 2:00:00 PM
  End time zone: (UTC-06:00) Central Time (US & Canada)

请注意,开始时间和结束时间不会发生变化。Notice that the start and end times did not change. 这是因为时间是在东部时区进行解释(因为 "时区" 属性设置为 "东部时区"),并且时间值已更新,以防止约会发生变化。This is because the times are being interpreted in the Eastern time zone (because the TimeZone property is set to the Eastern time zone), and the time values were updated to prevent the appointment from shifting.

使用 EWS 更新现有约会上的时区Updating the time zone on an existing appointment by using EWS

下面的示例 EWS UpdateItem 操作请求更新约会上的时区。The following example EWS UpdateItem operation request updates the time zone on an appointment. 本示例仅更新StartTimeZoneEndTimeZone元素,因此服务器将移动约会的开始和结束时间,以使其在新时区中的时间与时区相对应。This example only updates the StartTimeZone and EndTimeZone elements, so the server will shift the start and end times of the appointment to keep it at the same time-zone-relative time in the new time zone. 为了提高可读性, ItemId元素的值被缩短。The value of the ItemId element is shortened for readability.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2010" />
  </soap:Header>
  <soap:Body>
    <m:UpdateItem ConflictResolution="AlwaysOverwrite" SendMeetingInvitationsOrCancellations="SendToNone">
      <m:ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="AAMkADA5..." ChangeKey="DwAAABYA..." />
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="calendar:StartTimeZone" />
              <t:CalendarItem>
                <t:StartTimeZone Id="Central Standard Time" />
              </t:CalendarItem>
            </t:SetItemField>
            <t:SetItemField>
              <t:FieldURI FieldURI="calendar:EndTimeZone" />
              <t:CalendarItem>
                <t:EndTimeZone Id="Central Standard Time" />
              </t:CalendarItem>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
      </m:ItemChanges>
    </m:UpdateItem>
  </soap:Body>
</soap:Envelope>

下面的示例请求更新约会的时区,并通过显式设置startend元素来更新开始和结束时间。The following example request updates the time zone of the appointment, and also updates the start and end times by explicitly setting the Start and End elements. 为了提高可读性, ItemId元素的值被缩短。The value of the ItemId element is shortened for readability.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2010" />
  </soap:Header>
  <soap:Body>
    <m:UpdateItem ConflictResolution="AlwaysOverwrite" SendMeetingInvitationsOrCancellations="SendToNone">
      <m:ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="AAMkADA5..." ChangeKey="DwAAABYA..." />
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="calendar:StartTimeZone" />
              <t:CalendarItem>
                <t:StartTimeZone Id="Central Standard Time" />
              </t:CalendarItem>
            </t:SetItemField>
            <t:SetItemField>
              <t:FieldURI FieldURI="calendar:EndTimeZone" />
              <t:CalendarItem>
                <t:EndTimeZone Id="Central Standard Time" />
              </t:CalendarItem>
            </t:SetItemField>
            <t:SetItemField>
              <t:FieldURI FieldURI="calendar:Start" />
              <t:CalendarItem>
                <t:Start>2014-06-20T17:00:00.000Z</t:Start>
              </t:CalendarItem>
            </t:SetItemField>
            <t:SetItemField>
              <t:FieldURI FieldURI="calendar:End" />
              <t:CalendarItem>
                <t:End>2014-06-20T18:00:00.000Z</t:End>
              </t:CalendarItem>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
      </m:ItemChanges>
    </m:UpdateItem>
  </soap:Body>
</soap:Envelope>

另请参阅See also