Adding custom app data to Microsoft Graph now in preview
Microsoft Graph provides a single API endpoint that gives you access to rich people-centric data and insights, via a number of resources like users and messages. Frequently, developers want to associate additional custom data of their own with these resource types, requiring significant additional infrastructure – until now.
We’re happy to announce that there’s now a way for you to extend Microsoft Graph with your own data. Extensions allow you to add custom properties to Microsoft Graph resources without requiring an external data store. For example, you can store app-specific user profile data in Microsoft Graph by extending the user resource, instead of needing to invest in dedicated data-store infrastructure for your app. Alternatively, you might want to retain your app’s existing user profile store and link its records to users in Microsoft Graph by adding an app-specific identifier to the user resource.
Microsoft Graph offers two types of extensions:
- Open extensions: A good way for developers to get started with extending resources with custom data.
- Schema extensions: A more versatile mechanism for developers who care about storing typed data, making their schema discoverable and shareable, being able to filter, and in the future being able to perform input data validation and authorization.
NOTE: Open extensions (formerly known as Office 365 data extensions) were already available for Outlook resource types like message and event. We’re now adding the same capability for directory resource types like user and group.
Let’s take a quick look at how you can add custom data with open and schema extensions.
Using open extensions
Let’s say you want to let users configure their UI experience so it’s consistent no matter which device they use to sign in to your app. Adding roaming profile information to an existing user resource can be done with a POST.
POST https://graph.microsoft.com/beta/me/extensions
{
"@odata.type":"microsoft.graph.openTypeExtension",
"extensionName":"com.contoso.roamingSettings",
"theme":"dark",
"color":"purple",
"lang":"Japanese"
}
When the user signs in to the app from another device, the app can retrieve the user’s profile details as well as their roaming settings:
GET https://graph.microsoft.com/beta/me?$select=id,displayName,mail,mobilePhone&$expand=extensions
HTTP/1.1 200 OK
{
"id": "84b80893-8749-40a3-97b7-68513b600544",
"displayName": "John Smith",
"mail": "john@contoso.com",
"mobilePhone": "1-555-6589",
"extensions": [
{
"@odata.type": "#microsoft.graph.openTypeExtension",
"extensionName": "com.contoso.roamingSettings",
"id": "com.contoso.roamingSettings",
"theme": "dark",
"color": "purple",
"lang": "Japanese"
}
]
}
Using schema extensions
Schema extensions allow you to define a schema you can use to extend a resource type. First, you create your schema extension definition and then use it to extend resources with strongly-typed custom data. In this example we’ll define a training course extension for groups which specifies new properties for a course ID (courseId) and a course name (courseName).
Create the schema extension definition
POST https://graph.microsoft.com/beta/schemaExtensions
Content-type: application/json
{
"id":"graphlearn_courses",
"description": "Graph Learn training courses extensions",
"targetTypes": [
"Group"
],
"properties": [
{
"name": "courseId",
"type": "Integer"
},
{
"name": "courseName",
"type": "String"
}
]
}
Now we have a schema definition, we can use it to describe our training course.
Add custom data by setting schema extension values
We can add custom data either when creating or when updating a group. When updating an existing group, add the graphlearn_courses schema extension value to the body of the PATCH request:
PATCH https://graph.microsoft.com/beta/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json
{
"graphlearn_courses":{
"courseId":"123",
"courseName":"New Managers"
}
}
After adding the extension to the group, we can get the custom data together with other group data by using a $select statement:
GET https://graph.microsoft.com/beta/groups/dfc8016f-db97-4c47-a582-49cb8f849355?$select=displayName,id,description,graphlearn_courses
HTTP/1.1 200 OK
{
"displayName": "New Managers March 2017",
"description": "New Managers training course for March 2017",
"graphlearn_courses": {
"@odata.type": "#microsoft.graph.ComplexExtensionValue",
"courseId":"123",
"courseName":"New Managers"
}
}
More information
Please take a look at our Extensions overview documentation and try it out using the updated Microsoft Graph UWP Snippets Sample (REST) or by using Microsoft Graph Explorer. Note that you cannot create or manage schema extension definitions through Graph Explorer – for that you’ll need to create your own application.
Please let us know what you think and what other things you’d like to see in open and schema extensions.
Light
Dark