Accessing the current user ’s profile, the user ’s properties, and the assigned Office 365
licenses is a well-known use case. In fact, whenever you create an app or an external tool that leverages the Office 365 services, you probably will have to define the current user ’s context.
To access the current user, the entry point is https://graph.microsoft.com/v1.0/me/. You can consume that URL with an HTTP GET request, providing the proper authentication
information, which will be explained in Chapter 4. In response, you will get a JSON object that will define a bunch of useful information. Depending on the Accept HTTP header for controlling OData, you can request an object with three different behaviors:
Accept: application/json;odata.metadata=none; => The service should omit any metadata information. The only OData metadata attribute provided, if any, will be the
@odata.nextLink to provide the link to the next page of objects when browsing for an entity set.
Accept: application/json;odata.metadata=minimal; => The service should remove computable control information from the response payload. Only the attributes
@odata.context, @odata.nextLink (if any), @odata.id, and a few others will be provided in the response payload.
Accept: application/json;odata.metadata=full; => The service must include all the control information explicitly in the response payload.
Based on the odata.metadata attribute that you provide, the payload size can be very different. By default, if you omit the odata.metadata attribute, the Microsoft Graph API applies a minimal behavior for OData metadata.
In Listing 3-1, you can see an excerpt of such a JSON response, based on minimal metadata.
LISTING 3-1 An excerpt of a JSON response for the https://graph.microsoft.com/v1.0/me/ API request
Click he re to vie w code imag e
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity", "@odata.type": "#microsoft.graph.user",
"@odata.id": "users/bea7a848-0459-4bee-9034-5513ee7f66e0", "businessPhones": [
"030-22446688"
],
"displayName": "Paolo Pialorsi", "givenName": "Paolo",
"jobTitle": null,
"mail": "[email protected]", "mobilePhone": "+391234567890",
"officeLocation": null,
"preferredLanguage": "en-US", "surname": "Pialorsi",
"userPrincipalName": "[email protected]", "id": "bea7a848-0459-4bee-9034-5513ee7f66e0"
}
As you can see, there is information about the JSON object itself, which is an instance of a Microsoft.Graph.User type. There is information about the current user such as address, display name, telephone, email, and so on. Another set of information that deserves attention is the list of properties related to on-premises directory synchronization, if it is configured.
For example, you can see the on-premises user ’s SID (onPremisesImmutableId), when the last synchronization happened (onPremisesLastSyncDateTime), and so on. Last, you will find the proxy address and the fundamental UPN (User Principal Name), which will be a unique identifier for the current user.
You can use the UPN to access any specific user profile as long as you have the
permissions to consume the user ’s directory in Azure AD. Let’s say that you want to access the entire list of users for a specific tenant. You can make an HTTP GET request for the
following URL: https://graph.microsoft.com/v1.0/users. In this case, the result will be a JSON representation of an array of Microsoft.Graph.User objects.
If you want to access the profile properties of a specific user, you can make an HTTP GET request for the following URL: https://graph.microsoft.com/v1.0/users/UPN. For example, when the current user has a UPN value like [email protected], the following URL defines a direct entry point to the user ’s profile:
https://graph.microsoft.com/v1.0/users/[email protected].
It is also possible to read the values of single properties instead of getting the entire JSON object. Moreover, there are complex properties like the user ’s photo that can be accessed only through a direct request. To access a single property, you can append the property name to the URL path of the user ’s profile URL. You can see such a request in Listing 3-2, in which the HTTP request headers include the authentication information (the OAuth bearer token), which will be explained in Chapter 4.
LISTING 3-2 The HTTP GET request for the userPrincipalName property of the current user
Click he re to vie w code imag e
GET /v1.0/me/userPrincipalName HTTP/1.1 Authorization: Bearer eyJ0...
Host: graph.microsoft.com Content-Length: 0
In Listing 3-3, you can see the response that you should get back.
LISTING 3-3 The HTTP response for the current user ’s userPrincipalName property
Click he re to vie w code imag e
HTTP/1.1 200 OK
Cache-Control: private Content-Type:
application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatib le=false;charset=utf-8
Server: Microsoft-IIS/8.5
request-id: 0c2f199c-782e-4918-8bd0-91b0c246a9c8
client-request-id: 0c2f199c-782e-4918-8bd0-91b0c246a9c8 OData-Version: 4.0
OutBoundDuration: 71.2145 Duration: 113.3553
X-Powered-By: ASP.NET
Date: Sat, 05 Sep 2015 08:54:52 GMT Content-Length: 192
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('<UserID>')/userPrinci palName","value":"paolo@<tenant>.onmicrosoft.com"}
Notice that the response contains a bunch of useful information like the ID of the request, the target server version and engine, and the overall duration of the request processing. The response is in JSON format, and you should deserialize it. However, you can also directly access the bare property value as text by appending the $value path to the property URL. The final URL will look like the following:
https://graph.microsoft.com/v1.0/me/userPrincipalName/$value
This technique becomes increasingly useful when you want to retrieve binary properties like the user ’s photo. By providing the $value path at the end of the user ’s photo property, you will get back the binary image file directly, which is useful for creating great user
experiences in your applications. In Listing 3-4, you can see the user ’s photo request.
LISTING 3-4 The HTTP GET request for the photo binary property value of the current user
Click he re to vie w code imag e
GET /v1.0/me/photo/$value HTTP/1.1 Authorization: Bearer eyJ0...
Host: graph.microsoft.com Content-Length: 0
In Listing 3-5, you can see the response from an HTTP perspective.
LISTING 3-5 The HTTP response for the binary value of the current user ’s photo property
Click he re to vie w code imag e
HTTP/1.1 200 OK
Cache-Control: private Content-Type: image/jpeg Server: Microsoft-IIS/8.5
request-id: 528841c7-eda8-4eb7-99f7-b241be2b66f9
client-request-id: 528841c7-eda8-4eb7-99f7-b241be2b66f9 OutBoundDuration: 1080.2745
Duration: 1268.9802 X-Powered-By: ASP.NET
Date: Sat, 05 Sep 2015 08:26:09 GMT Content-Length: 31194
You can read information about yourself or other users, and you can update that
information if you have proper permissions. To change data or execute operations, you will have to switch from HTTP GET requests to other HTTP verbs like POST, PATCH, and so on.
For example, to update your current mobile phone number, you can make an HTTP PATCH request against your profile URL (https://graph.microsoft.com/v1.0/me). You will have to provide a JSON object that defines the profile properties that you want to patch. It is
fundamental in this case to set the Content Type header of the request according to the JSON.
For example, in Listing 3-6, you can see the sample request for updating your mobile phone number.
LISTING 3-6 The HTTP PATCH request to update the mobile phone number of the current user
Click he re to vie w code imag e
PATCH /v1.0/me HTTP/1.1
Authorization: Bearer eyJ0...
Host: graph.microsoft.com
Content-Type: application/json;
Content-Length: 31
{ "mobilePhone":"+39-123456789" }
In Listing 3-7, you can see the response that you should get back.
LISTING 3-7 The HTTP response for the current user ’s profile update request
Click he re to vie w code imag e
HTTP/1.1 204 No Content
Cache-Control: private Transfer-Encoding: chunked Content-Type: text/plain Server: Microsoft-IIS/8.5
request-id: fbb823c4-0de9-40e1-bba1-eb5b9101baac
client-request-id: fbb823c4-0de9-40e1-bba1-eb5b9101baac OutBoundDuration: 491.0361
Duration: 494.4198 X-Powered-By: ASP.NET
Date: Sat, 05 Sep 2015 07:07:27 GMT
From a content perspective, the response just confirms that the operation was successful (HTTP Status 204).