This week we’re happy to announce two new Microsoft Graph features for OneDrive files: webhook notifications and large file uploads. This functionality is available on the Microsoft Graph beta endpoint, https://graph.microsoft.com/beta.
Webhook Notifications
By creating a subscription on a drive’s root item, your app will receive a webhook notification whenever files within that drive are created, deleted, or modified. To create a subscription, your app needs to specify the Files.ReadWrite permission scope and request a subscription type of ‘updated’. We’ve included an example create request, response, and notification below. Make sure to visit our documentation for more details on using webhooks with the Microsoft Graph.
Subscription Create Request
To create a new Webhook notification subscription, your application sends a POST request to the subscriptions collection:
POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json
{
“changeType”: “updated”,
“notificationUrl”: “https://webhookapp12345.azurewebsites.net/api/notifications“,
“clientState”: “My client state”,
“resource”: “me/drive/root”,
“expirationDateTime”: “2016-08-26T23:08:37Z”
}
Note: In the subscription create request it is important to use the “updated” change type as it is the only supported type for the drive resource.
Subscription Create Response
HTTP/1.1 200 OK
Content-Type: application/json
{
“id”: “aa269f87-2a92-4cff-a43e-2771878c3727”,
“resource”: “me/drive/root”,
“changeType”: “updated”,
“clientState”: “My client state”,
“notificationUrl”: “https://webhookapp12345.azurewebsites.net/api/notifications“,
“expirationDateTime”: “2016-08-26T23:08:37Z”
}
Your app should track the resulting subscription ID and the user who subscribed, so that when a notification is received you can connect the notification to the user/drive to request the changes to the drive.
Notification
When a notification is triggered, the Graph API will POST a request to your registered notification URL, similar to the following:
POST https://webhookapp12345.azurewebsites.net/api/notification
Content-Type: application/json
{
“subscriptionId”: “aa269f87-2a92-4cff-a43e-2771878c3727”,
“clientState”: “My client state”,
“changeType”: “updated”,
“resource”: “me/drive/root”,
“subscriptionExpirationDateTime”: “2016-08-26T23:08:37.00+00:00”,
“resourceData”: null
}
As you can see in the notification example, the resource data returned is null – you will need to use the delta functionality (/me/drive/root/delta) on the target drive’s root object to track state and find what changed. This ensures that a dropped notification does not result in any loss of state.
Large File Uploads
This week we’re also adding the createUploadSession method to driveItem. This allows your application to request an upload session which allows uploading files larger than 4 MB through Graph API. To upload larger files, your application POSTs a request to createUploadSession to create a new upload session for a file.
POST https://graph.microsoft.com/beta/me/drive/root:/file.mp4:/createUploadSession
This returns a URL which your application can use to upload the contents of the file.
{
“uploadUrl”: “https://contoso.sharepoint.com/_api/v2.0/uploadsessions123191”,
“expirationDateTime”: “20160916T21:00:12Z”
}
Next your app logically breaks the file into fragments, each of which must be a multiple of 320KiB. For example, you could choose a fragment size of 4,259,840 bytes (approximately 4 MB) for good performance. Then, your application sequentially makes a PUT request to the uploadUrl and writes the uploads the contents of the next fragment. Your app must use the Content-Range header to specify which part of the file you are uploading, and must upload the file’s contents sequentially.
If the upload of one part of the file is unable to complete (say the connection is dropped), your app can resume the upload by remembering the uploadUrl. Your app can query for the current status of the upload URL by performing a GET request on the uploadUrl, which will return the expirationDateTime and nextExpectedRanges values, which indicate which parts of the file should be uploaded next.
When the last part of the file is uploaded, the session is committed and the file appears inside the user’s drive.
We’re excited to be rolling out this functionality to make it easier to use Microsoft Graph API for all scenarios where your app interacts with OneDrive content. Happy coding!
Ryan Gregg, Principal Program Manager, OneDrive/SharePoint and Matt Geimer, Program Manager II, Microsoft Graph
