Microsoft Graph Beta Python SDK

1.57.0 · active · verified Thu Apr 16

The `msgraph-beta-sdk` is the official Python SDK for interacting with the Microsoft Graph API's beta endpoint. It enables developers to build applications using the latest, often experimental, features of Microsoft Graph. As of its current version (1.57.0), it offers an asynchronous API by default and integrates with `azure.identity` for authentication. It's important to note that this SDK is intended for development and testing new features, not for production environments, due to potential breaking changes and the evolving nature of beta APIs.

Common errors

```
TypeError: 'coroutine' object is not awaitable
```
cause Attempting to call an asynchronous SDK method without `await` in an `async` function, or calling it outside an `asyncio` event loop.

fix Prepend asynchronous SDK calls with `await` (e.g., `await client.me.get()`). Ensure the function containing the `await` call is an `async` function and is executed within an `asyncio` event loop (e.g., `asyncio.run(main())`).
```
OSError: [WinError 206] The filename or extension is too long:
```
cause This error can occur on Windows systems during installation of the SDK due to the large number of files and long path names generated by the package.

fix Enable long paths in your Windows operating system. This is typically done through Group Policy Editor or by modifying the registry.
```
azure.identity.CredentialUnavailableError: EnvironmentCredential authentication failed. No tenant ID, client ID, or client secret found.
```
cause The `EnvironmentCredential` relies on specific environment variables (`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`) not being set or being incorrectly configured.

fix Set the required environment variables in your operating system or development environment. Alternatively, use a different `azure.identity` credential type that suits your authentication flow (e.g., `DeviceCodeCredential` for interactive login).
```
The type of the current segment is not expected, and it must be of type 'users'.
```
cause Attempting to access an endpoint (e.g., `client.me.users`) that is not valid or incorrectly chained. The `client.me` property already refers to the current user.

fix Review the Microsoft Graph API documentation for the correct endpoint paths. For example, to get information about the current user, use `client.me.get()`. To get a list of users, use `client.users.get()`.

Warnings

breaking The `msgraph-beta-sdk` operates against the Microsoft Graph beta endpoint. APIs in the beta endpoint are subject to change without notice and may introduce breaking changes at any time. Features available in beta are not guaranteed to be promoted to the v1.0 endpoint.
Fix: Do not use `msgraph-beta-sdk` for production applications. Develop with the understanding that code may break with new releases. For stable production applications, use the `msgraph-sdk` (v1.0 endpoint).
gotcha The SDK is asynchronous by default. Operations return awaitable objects, requiring the use of `async`/`await` and an asyncio event loop.
Fix: Ensure your code runs within an `asyncio` event loop. Prefix API calls with `await`. For example, `await client.me.get()` instead of `client.me.get()`.
gotcha Installation of the `msgraph-beta-sdk` can be lengthy due to its size. On Windows, an `OSError` related to long paths may occur.
Fix: Be patient during installation. On Windows, enable long paths in your environment. Refer to Microsoft documentation on 'Enable Long Paths in Windows 10, Version 1607, and Later' if you encounter `OSError`.
deprecated Older authentication providers (e.g., from `Microsoft.Graph.Auth` in .NET, though relevant concept for Python too) are being deprecated in favor of `azure.identity` for `TokenCredential` based authentication.
Fix: Always use credential classes from the `azure.identity` library (e.g., `EnvironmentCredential`, `DeviceCodeCredential`, `ClientSecretCredential`) to instantiate `GraphServiceClient`.

Install

pip install msgraph-beta-sdk Install stable version

Imports

GraphServiceClient

from msgraph_beta import GraphServiceClient

EnvironmentCredential
```
from azure.identity.aio import EnvironmentCredential
```
Used for asynchronous authentication from environment variables; other credential types exist in `azure.identity`.

Quickstart

This quickstart demonstrates how to initialize the `GraphServiceClient` using `EnvironmentCredential` from `azure.identity.aio` for asynchronous operations and fetch the current user's profile. Ensure your application is registered with Azure AD and the necessary environment variables (`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`) are set, along with appropriate API permissions (scopes).

import asyncio
import os
from azure.identity.aio import EnvironmentCredential
from msgraph_beta import GraphServiceClient

async def main():
    # It's recommended to set 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET'
    # environment variables for EnvironmentCredential.
    # Replace with your actual scopes based on the permissions required by your application.
    scopes = ['User.Read', 'Mail.Read'] 

    try:
        credential = EnvironmentCredential()
        client = GraphServiceClient(credential, scopes=scopes)

        # Example: Get the currently signed-in user's profile
        user = await client.me.get()
        print(f"Hello, {user.display_name}!")
        print(f"Your email: {user.mail}")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →