Upcoming change to Event schema in the Outlook REST API beta endpoint

Artikkeli
06/01/2017

We wanted to give you a heads-up on upcoming changes to how locations are exposed for events in the Outlook REST API. Outlook recently introduced the option to use multiple locations to schedule meetings and appointments. The feature is designed for meetings scheduled for persons and teams spanning different regions, for example, some people attending in a conference room in Seattle, another person joining from a coffee shop in Paris, and others from the New York office, with all the locations connected via Skype for Business.

To support multiple locations in the Event schema, we are adding:

A Locations property as part of the Event resource
A LocationType property to the Location complex type, with an enumeration of possible locations types

This change is currently available on the https://outlook.office.com/api/beta endpoint.

Note: These are schema additions and the existing Location property that represents a single location for an event has not been removed, to allow for an easier transition. If your REST client is already using Location, your client doesn't break. However, be aware that in the future, the Location property will be removed, and apps will need to be updated.

Here are the updated portions of the schema, with the changes highlighted.

 <EntityType Name="Event" BaseType="Microsoft.OutlookServices.Item">
    ...
    <Property Name="Start" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    <Property Name="OriginalStart" Type="Edm.DateTimeOffset" />
    <Property Name="End" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    <Property Name="Location" Type="Microsoft.OutlookServices.Location" />
    <Property Name="Locations" Type="Collection(Microsoft.OutlookServices.Location)" />
    <Property Name="Start" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    <Property Name="OriginalStart" Type="Edm.DateTimeOffset" />
    <Property Name="End" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    ...
</EntityType>

<ComplexType Name="Location">
    <Property Name="DisplayName" Type="Edm.String" />
    <Property Name="LocationEmailAddress" Type="Edm.String" />
    <Property Name="Address" Type="Microsoft.OutlookServices.PhysicalAddress" />
    <Property Name="Coordinates" Type="Microsoft.OutlookServices.GeoCoordinates" />
    <Property Name="LocationUri" Type="Edm.String" />
    <Property Name="LocationType" Type="Microsoft.OutlookServices.LocationType" />
</ComplexType>

<EnumType Name="LocationType">
    <Member Name="Default" Value="0" />
    <Member Name="ConferenceRoom" Value="1" />
    <Member Name="HomeAddress" Value="2" />
    <Member Name="BusinessAddress" Value="3" />
    <Member Name="GeoCoordinates" Value="4" />
    <Member Name="StreetAddress" Value="5" />
    <Member Name="Hotel" Value="6" />
    <Member Name="Restaurant" Value="7" />
    <Member Name="LocalBusiness" Value="8" />
    <Member Name="PostalAddress" Value="9" />
</EnumType>

Using multiple locations and location types in the Outlook Rest API

Get events

You can use the GET /me/events API to get a collection of calendar events:

 GET https://outlook.office.com/api/beta/me/events?$select=Subject,Organizer,Start,End,Locations,Location

With this schema addition, the GET /me/events command will return, for each Event, the collection of Locations.

Example of a response:

 {
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer,Start,End,Locations,Location)",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI28tEyDAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAA/LpDWw==\"",
      "Id": "AAMkAGI28tEyDAAA=",
      "Subject": "Scrum",
      "Start": {
        "DateTime": "2017-11-28T08:00:00",
        "TimeZone": "Pacific Standard Time"
      },
      "End": {
        "DateTime": "2017-11-28T09:00:00",
        "TimeZone": "Pacific Standard Time"
      },
      "Organizer": {
        "EmailAddress": {
          "Name": "Adele Vance",
          "Address": "adelev@contoso.onmicrosoft.com"
        }
      },
      "Location": {
        "DisplayName": "Conf Room 3; Fourth Coffee; Home Office",
        "LocationType": "Default"
      },
      "Locations": [
        {
          "DisplayName": "Conf Room 3",
          "LocationType": "ConferenceRoom"
        },
        {
          "DisplayName": "Fourth Coffee",
          "Address": {
            "Street": "4567 Main St",
            "City": "Redmond",
            "State": "WA",
            "CountryOrRegion": "US",
            "PostalCode": "32008"
          },
          "Coordinates": {
            "Latitude": 47.672,
            "Longitude": -102.103
          },
          "LocationType": "LocalBusiness"
        },
        {
          "DisplayName": "Home Office",
          "LocationType": "Default"
        }
      ]
    }
  ]
}

Create an event with multiple locations

The following example creates a new event on the user's default calendar with multiple locations.

 POST https://outlook.office.com/api/beta/me/events
Content-Type: application/json

{
  "Subject": "Discuss the Event in Multiple Locations REST API",
  "Start": {
    "DateTime": "2017-06-06T08:00:00",
    "TimeZone": "Pacific Standard Time"
  },
  "End": {
    "DateTime": "2017-06-06T09:00:00",
    "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "janets@contoso.onmicrosoft.com",
        "Name": "Janet Schorr"
      },
      "Type": "Required"
    }
  ],
  "Locations": [
    {
      "DisplayName": "Conf Room 3",
      "LocationType": "ConferenceRoom"
    },
    {
      "DisplayName": "Fourth Coffee",
      "Address": {
        "Street": "4567 Main St",
        "City": "Redmond",
        "State": "WA",
        "CountryOrRegion": "US",
        "PostalCode": "32008"
      },
      "Coordinates": {
        "Latitude": 47.672,
        "Longitude": -102.103
      },
      "LocationType": "LocalBusiness"
    }
  ]
}

Update an event with multiple locations

To update locations of an event, apps include the Locations property in the PATCH payload. The existing value of the Locations property is overwritten, so in order to add a location to an existing event, apps should get the current value of the Locations property, then add the new location, and PATCH the resulting value.

For example, the following example would add the Conf Room 2 (New York) location to the existing locations of the event created in the previous example.

 PATCH https://outlook.office.com/api/beta/me/events/{event-id}
Content-Type: application/json

{
  "Locations": [
    {
      "DisplayName": "Conf Room 3",
      "LocationType": "ConferenceRoom"
    },
    {
      "DisplayName": "Fourth Coffee",
      "Address": {
        "Street": "4567 Main St",
        "City": "Redmond",
        "State": "WA",
        "CountryOrRegion": "US",
        "PostalCode": "32008"
      },
      "Coordinates": {
        "Latitude": 47.672,
        "Longitude": -102.103
      },
      "LocationType": "LocalBusiness"
    },
    {
      "DisplayName": "Conf Room 2 (New York)",
      "LocationType": "ConferenceRoom"
    }
  ]
}

Behavior with Location property

Apps should update to use the Locations property. However, if an app continues to use the Location property, the property will behave in the following ways:

Read

When reading the Location property, the value will include a Location entity with just the DisplayName and LocationType properties. The DisplayName property will be a semi-colon delimited list of the display names of each location in the Locations property, and the LocationType will be Default.

Write

If an app updates the Location property via POST or PATCH, the Locations property will be updated to have the same Location entity as the one and only location in the collection. So, if an event already has multiple locations, and an app updates the Location property, all existing locations will be removed from the Locations property and replaced with the single location set in the Location property.

Jaa