\n This week, we\u2019ll focus on the Microsoft Graph, specifically:\n<\/p>\n
- \n
- \n The basics of MS Graph\n <\/li>\n
- \n Exploring the MS Graph API with Graph Explorer\n <\/li>\n
- \n Adding MS Graph API permissions to your app registration\n <\/li>\n<\/ul>\n
\n Next week, after you have a better understanding of the Microsoft Graph and how to add permissions to your app registration, we\u2019ll show you how to call the MS Graph API from an Android app!\n<\/p>\n
Microsoft Graph Overview<\/h2>\n
\n The Microsoft Graph<\/a> is a common set of APIs that allows developers to get user data from a common Microsoft tenant<\/a>. Depending on the tenant, you can access different kinds of information. For example, you can access your own data in a personal Microsoft tenant, and access data and analytics across your company in a work-based Microsoft tenant.\n<\/p>\n
\n With MS Graph, you can access a wide range of information from M365, Windows, and Enterprise Mobility + Security services, like calendar events, user profile information, Teams meeting data, and Viva Insights analytics. These APIs can be accessed from a variety of platforms, including Android, to enhance a user’s experience with personalized data. To learn more, check out the full list of MS Graph services and features<\/a>.\n<\/p>\n
\n
![\"\"](\"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-content\/uploads\/sites\/53\/2023\/03\/diagram-description-automatically-generated.png\")
\n<\/p>\nFigure 1. Visualization of the Microsoft Graph and the information it exposes.<\/em>\n<\/p>\n
\n Data from the M365 platform can be accessed in three main ways: with the Microsoft Graph API, connectors<\/a>, or Data Connect<\/a>. Today, we\u2019ll be focusing on the MS Graph API, which uses REST APIs and SDKs to access the
https:\/\/graph.microsoft.com<\/code> endpoint.\n<\/p>\nGraph Explorer<\/h2>\n
\n The best way to start familiarizing yourself with the MS Graph API is to check out the Graph Explorer<\/a>! This online tool helps you visualize and test out different API calls, inspect request\/response bodies, and see what permissions are required.\n<\/p>\n
\n To use the Graph Explorer, you must follow a few simple steps:\n<\/p>\n
- \n
- \n Sign in\n<\/li>\n
- \n Select a query\n<\/li>\n
- \n Consent to permissions\n<\/li>\n
- \n Run a query\n<\/li>\n<\/ol>\n
Sign in<\/h3>\n
\n The first step is to sign in your Microsoft account! We would recommend using a personal account, if possible, because work\/school accounts may have stricter restrictions on how users can use MS Graph.\n<\/p>\n
\n
![\"\"](\"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-content\/uploads\/sites\/53\/2023\/03\/graphical-user-interface-text-application-email-1.png\")
\n<\/p>\nFigure 2. Before making calls with the Graph Explorer, you need to sign in with a Microsoft account.<\/em>\n<\/p>\n
Select a query<\/h3>\n
\n The next step is to select a query to run, which you can do by searching through the Sample queries<\/em> pane on the lefthand side of the screen. As you can see, the queries are sorted by which resources they access, and they help give you an idea of what can be accomplished with the MS Graph API. You can check out the Microsoft Graph REST API v1.0 documentation<\/a> for the full list of possible queries.\n<\/p>\n
\n The pre-generated sample queries provide a great starting point for building requests, since they already fill out the target resource URL and provide sample request bodies. You can then start to customize requests by modifying the endpoint or request body \u2013 in some cases, such as a POST request to create a new OneNote page (Figure 3), this may even be necessary for the request to succeed.\n<\/p>\n
\n
![\"\"](\"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-content\/uploads\/sites\/53\/2023\/03\/graphical-user-interface-text-application-email-2.png\")
\n<\/p>\nFigure 3. In Graph Explorer, you can start out with a sample query and then modify the endpoint or request body to customize the request. For example, when trying to create a new page in OneNote, you can customize the page HTML in the request body, and you need to change the highlighted \u201csection-id\u201d placeholder to a specific section ID from one of your notebooks.<\/em>\n<\/p>\n
Consent to permissions<\/h3>\n
\n In order to run the query you\u2019ve selected, you will also need to grant MS Graph the permissions to read\/write to different resources. Otherwise, you\u2019ll run into a
Forbidden -\u00a0403. Access denied<\/code> error when trying to make a request. \n<\/p>\n\n There are two ways you can grant the proper permission(s):\n<\/p>\n
- \n
- \n If you already know what calls you\u2019ll be making, then you can click on your profile photo, click on Consent to permissions<\/em>, and then search for and consent to the permissions you need (Figure 4).\n <\/li>\n<\/ul>\n
![](\"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-content\/uploads\/sites\/53\/2023\/03\/word-image-3099-4.png\")
<\/em>\n<\/p>\nFigure 4. In the \u201cConsent to permissions\u201d view, you can search for and grant various MS Graph permissions.<\/em>\n<\/p>\n
- \n
- \n If you don\u2019t know ahead of time which calls you\u2019ll make, you can grant permissions as you go. If you prepare a query and then switch to the Modify permissions<\/em> tab, you can view and consent to all the permissions required for the request (Figure 5). \n <\/li>\n<\/ul>\n
\n
![\"Graphical](\"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-content\/uploads\/sites\/53\/2023\/03\/graphical-user-interface-text-application-email-3.png\")
\n<\/p>\nFigure 5. Before running a query, you can also check the \u201cModify permissions\u201d tab for the permissions you need to grant.<\/em>\n<\/p>\n
Run a query<\/h3>\n
\n Finally, once you\u2019re logged in and have granted the proper permissions, you just have to click \u201cRun query\u201d!\n<\/p>\n
\n
![\"Graphical](\"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-content\/uploads\/sites\/53\/2023\/03\/graphical-user-interface-text-application-email-4.png\")
\n<\/p>\nFigure 6. Once your query has run, you can inspect the request body\/headers, as well as the response preview and code snippets for how to perform the same call with different MS Graph SDKs.<\/em>\n<\/p>\n
\n You can inspect both the request and response details, view code snippets for how to make the same request with SDKs, and find links to API documentation. This really comes in handy when you need to know how to format request bodies\/headers and how to parse response information.\n<\/p>\n
Adding permissions to your app registration<\/h2>\n
\n Now that you know that basics of the Microsoft Graph API and the kinds of requests you can make (thanks Graph Explorer \ud83d\ude01), we\u2019ll move on to how you can start using MS Graph in an Android app.\n<\/p>\n
\n The first step is related to an MSAL topic we covered last week: registering an app in the Azure Portal<\/a>. In Graph Explorer, we had to consent to permissions to make sure we could read\/write to different resources. We have to do the same thing now in our app registration to let our app make requests to the MS Graph API.\n<\/p>\n
\n You can use the Graph Explorer or the Microsoft Graph permissions reference<\/a> to figure out what permissions your app will need, then in Azure Portal, you can add these under the API permissions<\/em> section (Figure 6). In most cases, you will need to add delegated permissions<\/em>, which mean you\u2019re accessing the API as the signed-in user. Application permissions<\/em> are for the cases when your app is running as a background service without a signed-in user.\n<\/p>\n
\n
![\"\"](\"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-content\/uploads\/sites\/53\/2023\/03\/graphical-user-interface-text-email-description.png\")
\n
Figure 7. In the API permissions section in Azure Portal, you can add the necessary permissions for MS Graph requests to your app registration. This example app contains the permissions for reading and writing OneNote information.<\/em>\n<\/p>\n\n Once you\u2019ve updated your app registration, users will be prompted the first time they sign in to consent to the permissions you added to your app.\n<\/p>\n
\n So, to review, in this post we learned the basics of the Microsoft Graph, how to build and test requests with Graph Explorer, and how to add MS Graph API permissions to an app registration in Azure Portal. Stay tuned for next week\u2019s post, where we\u2019ll combine today\u2019s learnings with our MSAL lessons from last week to show you how to call the Microsoft Graph API in an Android app!\n<\/p>\n
Resources and feedback<\/h2>\n
\n To learn more about using MS Graph in Android apps, check out:\n<\/p>\n
- \n
- Microsoft Graph DevBlog<\/a>\n <\/li>\n
- Tutorial: Sign in users and call the Microsoft Graph from an Android application<\/a>\n <\/li>\n
- Quickstart: Sign in users and call the Microsoft Graph API from a mobile application<\/a>\n <\/li>\n
- Quickstart sample repo<\/a> \n <\/li>\n<\/ul>\n
\n If you have any questions, or would like to tell us about your apps, use the feedback forum<\/a> or message us on Twitter @surfaceduodev<\/a>.\n<\/p>\n
- Tutorial: Sign in users and call the Microsoft Graph from an Android application<\/a>\n <\/li>\n
- Microsoft Graph DevBlog<\/a>\n <\/li>\n
- \n If you don\u2019t know ahead of time which calls you\u2019ll make, you can grant permissions as you go. If you prepare a query and then switch to the Modify permissions<\/em> tab, you can view and consent to all the permissions required for the request (Figure 5). \n <\/li>\n<\/ul>\n
- \n If you already know what calls you\u2019ll be making, then you can click on your profile photo, click on Consent to permissions<\/em>, and then search for and consent to the permissions you need (Figure 4).\n <\/li>\n<\/ul>\n