Category Archives: Microsoft Graph

Microsoft Graph / OneDrive : The resource could not be found

Microsoft Graph gives you access to a large range of features and data (Outlook, Delve, Azure AD…) using its REST API.

Among these features, you are able to retrieve content from the “OneDrive for Business” service associated to your Office 365 account.

To do this, you just have to call the following URL that will return all the items stored in the root folder of your personal document library.

GET https://graph.microsoft.com/v1.0/me/drive/root/children

By calling that URL, the server will return a JSON response such as the following (the response shown here was truncated for brevity) :

{
  value = ({
    @odata.id = "users/31950312-e7dd-44de-bfaa-4d8274e4d6a0/drive/root/children/01ZWNXWXJYRUGTTJRMQZB2L2YE4NQK4CIF",
    createdBy = { ... },
    createdDateTime = "...",
    eTag = "...",
    folder = { ... },
    id = "01ZWNXWXJYRUGTTJRMQZB2L2YE4NQK4CIF",
    lastModifiedBy = { ... },
    lastModifiedDateTime = "...",
    name = "...",
    parentReference = { ... },
    size = 0,
    webUrl = "..."
  },
  {
    @odata.id = "users/31950312-e7dd-44de-bfaa-4d8274e4d6a0/drive/root/children/01ZWNXWXJ3G5EOS6XJRRCJ54PQZQAJIM3H",
    createdBy = { ... },
    createdDateTime = "...",
    eTag = "...",
    folder = { ... },
    id = "01ZWNXWXJ3G5EOS6XJRRCJ54PQZQAJIM3H",
    lastModifiedBy = { ... },
    lastModifiedDateTime = "...",
    name = "...",
    parentReference = { ... },
    size = 0,
    webUrl = "..."
  })
}

This sample has 2 folders with their respective properties. One of the important parts in the response is the parameter named “@odata.id” which is the URL associated to the object, and used by the API to uniquely identify an item.

In the case of a folder, it could have children (folders and files). If you want to retrieve these children, you have to concatenate “/children” to the unique identifier of the item.

With the first folder of the previous JSON response, it should look like this :

GET https://graph.microsoft.com/v1.0/users/.../drive/root/children/01ZWNXWXJYRUGTTJRMQZB2L2YE4NQK4CIF/children

But if you call that URL, you get the following error message :

The resource could not be found.

This message means that Microsoft Graph is unable to process your request. It’s weird because the URL was generated by the server and returned in the JSON response.

So how can you get to access the children of this item ?

Now that we have retrieved the ID for the item (see the ID value in the JSON response), we are able to build our own URL to retrieve its children.

In Microsoft Graph / OneDrive API, each item is accessible through an URL such as “…/v1.0/users/{user_id}/drive/items/{item_id}”. So if we build our URL by respecting that schema, it works without errors.

In our previous example, the URL to call will be :

GET https://graph.microsoft.com/v1.0/users/.../drive/items/01ZWNXWXJYRUGTTJRMQZB2L2YE4NQK4CIF/children

If you want to play with Microsoft Graph APIs with data stored on your tenant, you can use this site created and hosted by Microsoft : https://graphexplorer2.azurewebsites.net

Set the timezone used for the events in Outlook and Microsoft Graph REST APIs

When you’ve been working for a while like me, you know that when a developer has to work with dates, he faces problems with timezones.

Outlook REST API allows you to get the events for a user by calling the following URL :

GET https://outlook.office365.com/api/v2.0/Me/Events

In the version 2.0 of the API and as you can see in the JSON response below for an event (the response shown here was truncated for brevity), the Start and End items contain two distinct properties for the date and timezone.

By default, all dates and times returned by the server are based on the UTC timezone.

{
  Attendees = (),
  Body = { ... },
  BodyPreview = "...",
  Categories = (),
  ChangeKey = "...",
  CreatedDateTime = "2015-12-02T16:21:57.91403Z";
  End = {
    DateTime = "2012-02-09T19:00:00.0000000",
    TimeZone = "UTC"
  },
  HasAttachments = false,
  Id = "...",
  Importance = "Normal",
  IsAllDay = false,
  IsCancelled = false,
  IsOrganizer = true,
  IsReminderOn = false,
  LastModifiedDateTime = "2015-12-02T16:21:58.7734204Z";
  Location = { ... },
  Organizer = { ... },
  OriginalEndTimeZone = "Pacific Standard Time",
  OriginalStartTimeZone = "Pacific Standard Time",
  Recurrence = { ... },
  ReminderMinutesBeforeStart = 0,
  ResponseRequested = true,
  ResponseStatus = { ... },
  Sensitivity = "Normal",
  SeriesMasterId = <null>,
  ShowAs = "Tentative",
  Start = {
    DateTime = "2012-02-09T18:00:00.0000000",
    TimeZone = "UTC"
  },
  Subject = "...",
  Type = "SeriesMaster"
  WebLink = "...",
  iCalUId = "..."
}

It’s now easier to know what timezone is used for the dates and times. But that’s not all.

If you want the server automatically convert the dates and times of the events into a different timezone, you are able to do so and it’s very easy.

You just have to specify a HTTP header like in the example below to change the timezone. The server will then use this new parameter to return the dates and times in the desired timezone.

Prefer: outlook.timezone="Central Standard Time"

Specifying this HTTP header and calling the previously mentioned URL, you will retrieve a new JSON response like this one :

{
  Attendees = (),
  Body = { ... },
  BodyPreview = "...",
  Categories = (),
  ChangeKey = "...",
  CreatedDateTime = "2015-12-02T16:21:57.91403Z";
  End = {
    DateTime = "2012-02-09T13:00:00.0000000",
    TimeZone = "Central Standard Time"
  },
  HasAttachments = false,
  Id = "...",
  Importance = "Normal",
  IsAllDay = false,
  IsCancelled = false,
  IsOrganizer = true,
  IsReminderOn = false,
  LastModifiedDateTime = "2015-12-02T16:21:58.7734204Z";
  Location = { ... },
  Organizer = { ... },
  OriginalEndTimeZone = "Pacific Standard Time",
  OriginalStartTimeZone = "Pacific Standard Time",
  Recurrence = { ... },
  ReminderMinutesBeforeStart = 0,
  ResponseRequested = true,
  ResponseStatus = { ... },
  Sensitivity = "Normal",
  SeriesMasterId = <null>,
  ShowAs = "Tentative",
  Start = {
    DateTime = "2012-02-09T12:00:00.0000000",
    TimeZone = "Central Standard Time"
  },
  Subject = "...",
  Type = "SeriesMaster"
  WebLink = "...",
  iCalUId = "..."
}

If you want more information about the names of supported timezones, you can find a list on the official documentation on MSDN.

It’s also good to know that even if it’s not mentioned (for now) on the official documentation, this HTTP header also works with Microsoft Graph.

Be careful to case sensitivity in Microsoft Graph REST API

Last week during Connect(); // 2015, Microsoft announced the general availability (GA) of Microsoft Graph (formerly known as Unified API).

In association with the announcement, a brand new website with a full documentation that explains what’s Microsoft Graph and how to use the REST API was launched here : http://graph.microsoft.io/docs

Since few days, I’m working with Microsoft Graph and I found few issues. Today, I want to talk about one of them which is common with a lot of APIs but frustrating when you encounter it.

During my investigations, I was trying to send a mail and by refering the documentation, it’s noted that you just have to send a JSON message like this one…

["message": {
  body = {
    content = "This message was sent with Microsoft Graph",
    contentType = "text"
  },
  importance = "high",
  subject = "Microsoft Graph REST API",
  toRecipients = ({
    emailAddress = {
      address = "john@doe.com",
      name = "John Doe"
    }
  })
},
"saveToSentItems": false]

… to the following URL.

https://graph.microsoft.com/v1.0/me/microsoft.graph.sendMail

Very easy in theory but when I execute the request with these values, I receive the following error message.

One or more parameters of the operation 'SendMail' are missing from the request payload. The missing parameters are: Message.

To understand what’s the problem, I looked at the metadata generated for the REST API (based on OData 4.0) by accessing the following URL.

https://graph.microsoft.com/v1.0/$metadata

In the metadata returned by the server, you can see this.

<Action Name="sendMail" IsBound="true" EntitySetPath="bindingParameter">
<Parameter Name="bindingParameter" Type="microsoft.graph.user" />
<Parameter Name="Message" Type="microsoft.graph.message" Nullable="false" />
<Parameter Name="SaveToSentItems" Type="Edm.Boolean" />
</Action>

As you can see, the parameters used by this method are named “Message” and “SaveToSendItems” (in PascalCase) and not “message” and “saveToSendItems” (in lowerCamelCase) as written in the documentation.

When you pay attention to metadata generated by OData, you will see that some methods, especially those existing in other parts of Office 365 REST APIs (e.g. sendMail is used in Outlook REST API), still use PascalCase for their parameter names.

So if you follow the documentation to implement Microsoft Graph but you receive an error message indicating that a parameter is missing, take a look at metadata generated by OData to validate that the method is not expected to use PascalCase instead of lowerCamelCase for its parameters.

Introducing the new Office 365 unified API

Build conference was held in San Francisco this week (from April 29th to May 1st) and it was the place to be because Microsoft made a lot of announcements around its ecosystem (Windows 10, Azure, HoloLens, Office 365…).

Among all the news annouced this week, we particularly appreciated the launch (in preview version for now) of the Office 365 unified API. Let’s take a look to this new API.

Why a new API ?

As you probably know, Office 365 offers a lot of features for companies who needs a directory, emails, instant messaging, collaboration, videos, search, social network…

Each of these features are offered by a dedicated product (Azure AD, Exchange, Lync, SharePoint, Yammer, OneDrive for Business…) and it was pretty complicated to develop solutions which are connected with all of them.

Indeed, each product has its own API, accessible through a dedicated endpoint :

It’s to simplify all of this, that the new Office 365 Unified API was created. It allows developers to create solutions which are able to reach the content of each product from a single endpoint.

Office365 Unified API

A single endpoint is more easy to use and it simplifies a lot of tasks such as managing authentication tokens (you need one access token for each endpoint when you use the actual Office 365 APIs).

This new API works like the actual APIs so to use it, you need to :

  • Register you app in Azure AD
  • Define permission scopes and security
  • Authenticate through OAuth 2.0

Office365 Unified API - Registration in Azure

To retrieve data from your tenant and after successful completion of the authentication process, you can send requests to the endpoint as you can see in the following examples.

Me (or other users)

Get information about the current user (the authenticated user) :

https://graph.microsoft.com/beta/me

Get the picture (of given dimensions) for the current user :

https://graph.microsoft.com/beta/me/userphotos/96X77

Get the manager, the subordinates or the groups for the current user :

https://graph.microsoft.com/beta/me/manager
https://graph.microsoft.com/beta/me/directReports
https://graph.microsoft.com/beta/me/memberOf

Get information about another user in your company’s directory  :

https://graph.microsoft.com/beta/contoso.com/users/demo@contoso.com
https://graph.microsoft.com/beta/contoso.com/users/demo@contoso.com/manager
https://graph.microsoft.com/beta/contoso.com/users/demo@contoso.com/memberOf

Messages

Get the email messages for the current user :

https://graph.microsoft.com/beta/me/messages

Get the last 5 message for the current user :

https://graph.microsoft.com/beta/me/messages?$top=5

Get the next 5 messages ordered by creation date :

https://graph.microsoft.com/beta/me/messages?$top=5&$skip=5&$orderby=DateTimeCreated

Calendar / Events

Get the events for the current user :

https://graph.microsoft.com/beta/me/events

Get the events for the current user between the start date and the end date:

https://graph.microsoft.com/beta/me/calendarview?startdatetime=2015-04-01t01:00:00z&enddatetime=2015-04-16t23:00:00z

SharePoint Files / OneDrive Files

Get OneDrive’s for Business files for the current user and get a specific file by using its ID :

https://graph.microsoft.com/beta/me/files
https://graph.microsoft.com/beta/me/files/<id>

Get OneDrive’s for Business files for a given user :

https://graph.microsoft.com/beta/demo@contoso.com/files

Groups

Get the groups (collaboration and not security/distribution) for your company :

https://graph.microsoft.com/beta/contoso.com/groups?$filter=groupType+eq+'Unified'

Get the members, the files, and the conversations for a group by using its ID :

https://graph.microsoft.com/beta/contoso.com/groups/<id>/members
https://graph.microsoft.com/beta/contoso.com/groups/<id>/files
https://graph.microsoft.com/beta/contoso.com/groups/<id>/conversations

Office Graph / Delve

Get the people with whom the current user work with :

https://graph.microsoft.com/beta/me/workingWith

Get the data (documents, email attachments…) which are trending around the current user :

https://graph.microsoft.com/beta/me/trendingAround

What’s coming next ?

In the examples presented in this article, we only saw how to get data but you are already able to perform CRUD operations as you can do it today with other dedicated endpoints.

It’s also good to note that Microsoft has updated its client libraries for .NET, iOS and Android to support the new unified API.

The Office 365 Unified API available today is just the first version (a preview version) and a lot of improvements will be available in the future. New data types will be added in the next few months.

Among some of the improvements already announced by Microsoft during the conference :

  • Tasks
  • Notes
  • Skype
  • Personal Contacts
  • Notifications
  • And much more…

Want to learn more and want to try it ?

The first thing to see if you want to discover the new API (this article was based on it) is the webcast of the session named “Supercharging Your Custom Solutions with the Office 365 Unified API Endpoint” which has been recorded during the Build conference. It’s available on Channel 9 : http://channel9.msdn.com/Events/Build/2015/3-641

If you want to learn more about the new Office 365 Unified API, you can also refer to the official documentation available at http://dev.office.com/unifiedAPIs.

Microsoft has also created/updated some websites if you want to try the new API directly from your web browser: