Microsoft 365 Community Microsoft Graph, 7 Oct 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Getting started on using Microsoft Graph subscriptions with Azure Functions

Description

In this 20-minute Developer-focused demo, Yannick Plenevaux starts with an architectural overview of Microsoft Graph subscriptions (aka webhooks) and proceeds to show subscribing to and subsequently receiving activity notifications from various Microsoft 365 services. Graph is the relay or intermediary between a Microsoft 365 service and an app’s webhook. See how to create a webhook (HTTP trigger) in Azure, receive a notification, query the Graph back-end for details and review webhook operational and maintenance considerations. This PnP Community demo is taken from the General Microsoft 365 Development Special Interest Group (SIG) - Bi-weekly sync call recorded on September 17, 2020.

Demo Presenter: Yannick Plenevaux (PVX Solutions) | @yp_code

Supporting materials:
• Doc - Create subscription | https://docs.microsoft.com/en-us/graph/api/subscription-post-subscriptions
• Blog - Announcing the public preview of Microsoft Graph change notifications delivery via Azure Event Hubs | https://developer.microsoft.com/en-us/graph/blogs/announcing-the-public-preview-of-microsoft-graph-change-notifications-delivery-via-azure-event-hubs/
• Graph Doc - Set up notifications for changes in user data | https://docs.microsoft.com/en-us/graph/webhooks?context=graph/api/1.0
• Graph Doc - Use the Microsoft Graph API to get change notifications | https://docs.microsoft.com/en-us/graph/api/resources/webhooks?view=graph-rest-1.0
• Blog - Explore Microsoft Graph Subscriptions - Part I | https://ypcode.io/posts/2020/01/explore-microsoft-graph-subscriptions-part-i/
• Blog - Explore Microsoft Graph Subscriptions - Part II: Azure Function'd like a Pro | https://ypcode.io/posts/2020/01/explore-microsoft-graph-subscriptions-part-ii/
• Blog - Explore Microsoft Graph Subscriptions – Part III: Handle subscription lifetime | https://ypcode.io/posts/2020/03/explore-microsoft-graph-subscriptions-part-iii/

Learn more:
• Learn more about the Microsoft 365 Patterns and Practices community at: http://aka.ms/m365pnp
• Visit the Microsoft 365 Patterns and Practices community YouTube channel: https://aka.ms/m365pnp-videos

A

My name is senior principal, I'm a solution architect, working with microsoft, five, I am an office development mvp and you can reach me through the the information, as you can see here so today we are going to talk about the microsoft graph subscription and how to get started with them with azure functions. So as an introduction, what are microsoft graph subscription they are. They are also known as web books. So if you know about web books and other system they're, basically the same in microsoft graph, they allow the subscribe and external system to receive notification.

A

That of activities that have happened in your microsoft, 365 tenant.

A

They are relayed through microsoft, graph with common schemes, a common notification pattern, but the notification come come from the events of hearing in many many services in microsoft, 65..

A

So what is it about? More concretely, you can see here that we have microsoft, physics back with all the services that it includes, and um let's say that you want to build a system, a solution. Then you want actually the information that you get in microsoft, 365.

A

You want to be notified that something has changed in one of the servers, so we will use graph that surface microsoft, 365 and then microsoft graph will notify the changes that has appeared uh that have occurred in one of these services. So, basically, here on the right, you can see mostly the resources that are supported now in microsoft, graph with v1, so it could be changes in exchange with mailbox with users and groups in azure the chat messages that are currently in beta.

A

It is one exception here you have the shop on this content and the files in one drive and also the security alerts, so it most likely it is what is covered and supported now in the in the v1.

A

So it has to be done in initialization step where you create the subscription, and after this you receive the notification. So, first of all, we want to create a notification, so our web book, if you don't really know what it is, it is a public url.

A

It is a url that you can reach in a case microsoft graph. The url must be public urls, so in our system have a public url that we will need to expose to create the subscription. We have the json that you can see here. It is we.

A

We specified the notification that uh the notification url sorry it is the url of our web server and it could be whatever we will see it.

A

It could be an azure function that could be also an app service in asia or it could be a web server in your local premises and then we will say we want to subscribe to changes that occurs to that resource here, and we have to specify also the exploration of the subscription, we'll see that in a minute, so with this subscription that we want to create, we put this this data and send it through a post request, a post, http request to the delegated and pointed microsoft graph. So basically it is slash subscript subscriptions.

A

When microsoft graph received this. It will immediately try to validate that the url that we subscribed is valid.

A

It is a valid web book, so it will immediately contact it by sending uh um a query, um a request with a parameter in the query thing, that's called validation token, and we need to respond within 10 seconds with a success code and just pass it the validation token as it is and when it is done, then the subscription is created in microsoft, graph, the notification once it is created, we will have to handle the notification, so we have still our service. We are still.

A

We have still microsoft, 365 and microsoft graph and let's say, for instance, that in our case we will focus on when an email arrives in the user's mailbox. So the um the activity occurs in exchange online exchange will relay its change through microsoft, graph and microsoft. Graph will send a notification through an http plus request to our web book.

A

Typically, we don't want the web to do complex stuff. We want it to respond right away, and so, if it receives the notification, then pass it to a back-end process, whatever we want to do with it, but it responds within maximum 30 seconds, with a success http code to microsoft, graph, what if it if it does not respond within 30 seconds, microsoft graph will consider the notification never arrived so later on. It will try resending it and it will do until there is a successful call.

A

It will do it several time during the during about four hours. After four hours, notification will be forever lost.

A

So let's try it with a demo here.

A

So I will use really basic tools here. Just for the experiment, uh I will use graph explorer to create a subscription and I will use the in portal azure function.

A

So, first of all, I will create my web book. I already have one here, but just to let you see how it is done. I create in my function app here. I create a new http trigger and I will call it webook pnp and I want to make it anonymous because the the url, the url, must be accessible by anyone without any authentication scheme.

A

I created, and hopefully it will be quite fast.

A

Okay, so what I have to make sure is uh that it accept post uh http request, okay, so by default it does and that's basically it here. Okay, I can switch the code and I will just take my cheat sheet here with the code that I prepared and copy it.

A

And so what do I do in the code here? It's really simple. I handle the validation step. So if I see in the query a validation token parameter, I just resend it as the body as plain text.

A

If not, I just display in the console the the notification that I received, but here it is where you're supposed to pass along the notification to every back-end process and to do whatever you want to do with it.

A

So I just checked that I'm saved okay and just to make sure that it is running I will test it here.

A

It is, should be running okay. I do that because if I don't uh the the the azure function in consumption plan won't be warmed up yet, and so remember in my slide, that in the validation step, you have to respond within 10 seconds, and so microsoft graph won't accept it if it is not already running so it is saved okay and then now I have to go to graph explorer and you see that currently, if I type subscription and get I have already a subscription which I think I cleaned before.

A

Let me quickly do it.

A

Daily, okay, so now not delete get okay. So now I have a clean set of subscription and I will create a new one so to create a new one. I send a first http request with not this one, this one here, and so it's basically the same json, except that that you saw in the slide, except that I will have to get the url of my new web book.

A

Okay- and I will want to uh subscribe to my messages so web books will be smart enough to convert this to the appropriate user, slash and my id, and I need to specify an expiration date time that will be not later than three days from now about three days.

A

So it's tomorrow, so we should be good. So if I run it okay, it is created. So you see that I have an id here so 30 30 69. So something like this.

A

If I check here in the log- and I did not- uh I didn't know the planet too bad, but you would have seen that it. uh It would have locked the validation token and then we returned it. uh But, okay! So now I have a subscription to my messages of my emails in exchange.

A

If I check here me, not a mess.

A

What is going on.

B

A

Thank you heather, so, yes, I see some messages that I have in my various folders and so on. uh Let me open up outlook and I will send a message to myself: okay, test.

A

A

Okay, so I received it- and you see here that I have received a notification- okay- and I will just paste this in my vs code uh to make it more clear and you see that it is well my subscription so 30 30 69 and it it tells me that I have a something that changed that has been updated on that resource and that resource, so user. Slash id, slash message that slash the id of the message is: if all went well.

A

My message indeed so, basically with that in place, I can then uh query graph on in my backend system and do whatever I I need to do with the data, let's change in microsoft, 365., and it is basically it for the demo, so I will switch back for a next couple of slides, so some important considerations that the subscription maximum lifetime is quite short for almost every resource resources types in v1. It is a bit less than three days a bit less than 72 hours.

A

Actually, so what you will have to do in your system is that you will be responsible for updating the lifetime of the subscription before it expires, because when it is, it is expired. It is simply deleted and notification won't be sent anymore.

B

A

30, second time also, it is what I said uh just before after 30 second timeout microsoft will reconsider notification are not received and resend it later. So you have to make sure that your web responds as fast as possible and rather do the the less possible task in the web itself, but rather pass along the notification to a backend system, a background job or something.

A

The notifications are not immediate. It's important to consider because you should not expect them to err to arrive immediately, because it really depends on the type of the resources you are subscribing to here for the mails and the events in outlook. It is quite immediate for, um based on my experience for notification on users and groups, and so on, it might take a few minutes according to documentation.

A

It is. It should be maximum 15 minutes for receiving the notification, so you should not use web books expecting real time. Notification for critical uh stuff web must have https public reachable url. So it means that if your web book is on your local premises, for instance, you will have to deal with the firewall dns and so on so forth.

A

Web books are public and have no authentication. It means that anyone could try to to to spoof you and to to say that something happened. So you should be really careful of the code that you are writing in the web book itself.

A

So what you can do as one step towards security is that in the in the subscription you can specify the client secret, uh not the current secretary, a client state that is secret, and this one should be known only by graph and your endpoint, and if it sends the secret, it means that it should be graph, but it is one step ahead in security, but still not.

A

If someone gets to know your secret, it can stop the the notification as well, and uh so you have to make sure that you won't cause any risk to your system or to your microsoft, 365 tenant. By directly in this. um In the code of this web book, you will have to make sure that you put everything that you can to validate, that it has to be secure enough um and last thing. Notification do not contain data.

A

It is not true in the beta version of microsoft graph, because in beta version you have some endpoint that accept what is called rich notification that contains some content, but it has to be uh sight for it with a certificate and so on. It's a bit more tricky in my opinion to to to set up, but it also allows more complex scenarios so, but for v1, your system in turn needs to call microsoft graph with the identifier of the resources.

B

We need to, unfortunately, move forward and just few pointers um just to call out uh things as well. So obviously, the the the subscriptions and web hooks in the graph are super super powerful, there's a massive amount of different options related on that I'll add a list of different uh resources um which you can actually subscribe to, just as an example for all of the incoming messages in the teams or events which are getting created or any single sharepoint list or library is getting created in a tenant.

B

You can subscribe to that event and then modify that list based on your business requirements. So super super super powerful, also one thing, but I wanted to call out because vincent is in the call, so we we paul was already helpful and updated to think that you don't actually have to be necessarily anonymous with the endpoint so vincent. Can you actually quickly explain that winston being an ex-mvp nowadays in the craft team implementing some of their stuff so sure.

C

Hi everyone, so thank you, yannick for a great demo to begin with. um I don't want to take too much time because I know there is another demonstration right after that. um So you do have a couple of ways you can authenticate and authenticate with uh web hooks. You mentioned the client secret to begin with, so that's a shared secret between graph and your service that has to stay secret by a sense right. Another way is to make sure if you're, using rich notifications, they can come with certificate, authentication and certificate.

C

uh Signing of a payload, so you're sure that the payload comes from microsoft graph and it's secured, and it cannot be decrypted by anybody else and so on and so forth, and the third thing that we're previewing is the ability to receive change notifications not for webhooks, so not through an http post but through um azure even hubs instead.

C

So that's really great for cases where you are behind a firewall or you are already using some azure services or you want high performance, and one of the great things about even hubs is that it is authenticated by default. So the whole uh string of notifications will be secured and authenticated by default and feel free to reach out to me. If you have any uh questions and with that, I don't want to take more time from birch, because I know bert has a great demonstrations to to follow with.

C

So thank you everyone and have a great day. Everyone thanks vincent.