In this article

Microsoft Graph bindings for Azure Functions

In this article

This article explains how to configure and work with Microsoft Graph triggers and bindings in Azure Functions. With these, you can use Azure Functions to work with data, insights, and events from the Microsoft Graph.

To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

Setting up the extensions

Microsoft Graph bindings are available through binding extensions. Binding extensions are optional components to the Azure Functions runtime. This section shows how to set up the Microsoft Graph and auth token extensions.

Enabling Functions 2.0 preview

Binding extensions are available only for Azure Functions 2.0 preview.

Installing the extension

To install an extension from the Azure portal, navigate to either a template or binding that references it. Create a new function, and while in the template selection screen, choose the "Microsoft Graph" scenario. Select one of the templates from this scenario. Alternatively, you can navigate to the "Integrate" tab of an existing function and select one of the bindings covered in this article.

In both cases, a warning will appear which specifies the extension to be installed. Click Install to obtain the extension. Each extension only needs to be installed once per function app.

Note

The in-portal installation process can take up to 10 minutes on a consumption plan.

Configuring Authentication / Authorization

The bindings outlined in this article require an identity to be used. This allows the Microsoft Graph to enforce permissions and audit interactions. The identity can be a user accessing your application or the application itself. To configure this identity, set up App Service Authentication / Authorization with Azure Active Directory. You will also need to request any resource permissions your functions require.

Note

The Microsoft Graph extension only supports Azure AD authentication. Users need to log in with a work or school account.

If you're using the Azure portal, you'll see a warning below the prompt to install the extension. The warning prompts you to configure App Service Authentication / Authorization and request any permissions the template or binding requires. Click Configure Azure AD now or Add permissions now as appropriate.

Auth token

The auth token input binding gets an Azure AD token for a given resource and provides it to your code as a string. The resource can be any for which the application has permissions.

Required - The identity that will be used to perform the action. Can be one of the following values:

userFromRequest - Only valid with HTTP trigger. Uses the identity of the calling user.

userFromId - Uses the identity of a previously logged-in user with the specified ID. See the userId property.

userFromToken - Uses the identity represented by the specified token. See the userToken property.

clientCredentials - Uses the identity of the function app.

userId

UserId

Needed if and only if identity is set to userFromId. A user principal ID associated with a previously logged-in user.

userToken

UserToken

Needed if and only if identity is set to userFromToken. A token valid for the function app.

Resource

resource

Required - An Azure AD resource URL for which the token is being requested.

Auth token - usage

The binding itself does not require any Azure AD permissions, but depending on how the token is used, you may need to request additional permissions. Check the requirements of the resource you intend to access with the token.

The token is always presented to code as a string.

Note

When developing locally with either of userFromId, userFromToken or userFromRequest options, required token can be obtained manually and specified in X-MS-TOKEN-AAD-ID-TOKEN request header from a calling client application.

Excel input

The Excel table input binding reads the contents of an Excel table stored in OneDrive.

Required - The identity that will be used to perform the action. Can be one of the following values:

userFromRequest - Only valid with HTTP trigger. Uses the identity of the calling user.

userFromId - Uses the identity of a previously logged-in user with the specified ID. See the userId property.

userFromToken - Uses the identity represented by the specified token. See the userToken property.

clientCredentials - Uses the identity of the function app.

userId

UserId

Needed if and only if identity is set to userFromId. A user principal ID associated with a previously logged-in user.

userToken

UserToken

Needed if and only if identity is set to userFromToken. A token valid for the function app.

Outlook output - usage

This binding requires the following Azure AD permissions:

Resource

Permission

Microsoft Graph

Send mail as user

The binding exposes the following types to .NET functions:

Microsoft.Graph.Message

Newtonsoft.Json.Linq.JObject

string

Custom object types (using structural model binding)

Webhooks

Webhooks allow you to react to events in the Microsoft Graph. To support webhooks, functions are needed to create, refresh, and react to webhook subscriptions. A complete webhook solution requires a combination of the following bindings:

The bindings themselves do not require any Azure AD permissions, but you need to request permissions relevant to the resource type you wish to react to. For a list of which permissions are needed for each resource type, see subscription permissions.

Required - the graph resource for which this function should respond to webhooks. Can be one of the following values:

#Microsoft.Graph.Message - changes made to Outlook messages.

#Microsoft.Graph.DriveItem - changes made to OneDrive root items.

#Microsoft.Graph.Contact - changes made to personal contacts in Outlook.

#Microsoft.Graph.Event - changes made to Outlook calendar items.

Note

A function app can only have one function that is registered against a given resourceType value.

Webhook trigger - usage

The binding exposes the following types to .NET functions:

Microsoft Graph SDK types relevant to the resource type, such as Microsoft.Graph.Message or Microsoft.Graph.DriveItem.

Custom object types (using structural model binding)

Webhook input

The Microsoft Graph webhook input binding allows you to retrieve the list of subscriptions managed by this function app. The binding reads from function app storage, so it does not reflect other subscriptions created from outside the app.

Needed if and only if the action is set to create. Indicates the type of change in the subscribed resource that will raise a notification. The supported values are: created, updated, deleted. Multiple values can be combined using a comma-separated list.

Webhook output - usage

The binding exposes the following types to .NET functions:

string

Microsoft.Graph.Subscription

Webhook subscription refresh

There are two approaches to refreshing subscriptions:

Use the application identity to deal with all subscriptions. This will require consent from an Azure Active Directory admin. This can be used by all languages supported by Azure Functions.

Use the identity associated with each subscription by manually binding each user ID. This will require some custom code to perform the binding. This can only be used by .NET functions.