Microsoft Graph Python SDK

通过将Microsoft Graph API集成到您的Python应用程序中，开始使用Microsoft Graph Python SDK。

注意

• 此SDK允许您使用Microsoft Graph的v1.0版本构建应用程序。如果您想尝试最新的Microsoft Graph API，请尝试beta SDK。

1. 安装

pip install msgraph-sdk

注意

• Microsoft Graph Python SDK是一个相当大的包。初始安装可能需要几分钟。
• 如果您收到Could not install packages due to an OSError错误，请在您的环境中启用长路径。有关详细信息，请参阅在Windows 10版本1607及以后启用长路径。

2. 开始使用Microsoft Graph

2.1 注册您的应用程序

按照以下步骤注册您的应用程序：使用Microsoft身份平台注册您的应用程序。

2.2 选择并创建一个身份验证提供者

要开始编写代码并向Microsoft Graph服务发送请求，您需要设置一个身份验证提供者。此对象将验证您对Microsoft Graph的请求。对于身份验证，Microsoft Graph Python SDK支持来自Azure Identity的同步和异步凭证类。选择哪个库取决于您正在构建的应用程序类型。

注意：对于身份验证，我们支持来自azure.identity的sync和async凭证类。有关更多信息，请参阅azure identity 文档。

通过查看您将使用的权限集来过滤此决策是最简单的方法。Microsoft Graph支持两种不同类型的权限：委托权限和应用权限

• 当您不需要用户登录到您的应用程序时，但应用程序将在后台运行并执行任务时，将使用应用权限。
• 委托权限（也称为作用域）用于您的应用程序需要用户登录并会话中与相关用户数据交互的情况。

以下表格列出了按权限集列出的常见库。

您还可以使用EnvironmentCredential、DefaultAzureCredential、OnBehalfOfCredential或任何其他Azure Identity库。

一旦您选择了一个身份验证库，我们就可以在您的应用程序中启动身份验证提供者。以下示例使用带有应用权限的ClientSecretCredential。

import asyncio

from azure.identity.aio import ClientSecretCredential

credential = ClientSecretCredential("tenantID",
                                    "clientID",
                                    "clientSecret")
scopes = ['https://graph.microsoft.com/.default']

以下示例使用带有委托权限的DeviceCodeCredential。

import asyncio

from azure.identity import DeviceCodeCredential

credential = DeviceCodeCredential("client_id",
                                  "tenant_id")
scopes = ['https://graph.microsoft.com/.default']

2.3 初始化GraphServiceClient对象

您必须创建GraphServiceClient对象以向服务发送请求。要创建此类的实例，您需要提供凭证和作用域，这可以验证对Microsoft Graph的请求。

# Example using async credentials and application access.
from azure.identity.aio import ClientSecretCredential
from msgraph import GraphServiceClient

credentials = ClientSecretCredential(
    'TENANT_ID',
    'CLIENT_ID',
    'CLIENT_SECRET',
)
scopes = ['https://graph.microsoft.com/.default']
client = GraphServiceClient(credentials=credentials, scopes=scopes)

上述示例使用默认作用域进行仅应用访问。如果您使用委托访问，则可以提供自定义作用域

# Example using sync credentials and delegated access.
from azure.identity import DeviceCodeCredential
from msgraph import GraphServiceClient

credentials = DeviceCodeCredential(
    'CLIENT_ID',
    'TENANT_ID',
)
scopes = ['https://graph.microsoft.com/.default']
client = GraphServiceClient(credentials=credentials, scopes=scopes)

注意：如果您需要配置HTTP代理，请参阅以下文档页面。

3. 向服务发送请求

在您有一个经过身份验证的GraphServiceClient之后，您就可以开始对该服务进行调用。对服务的请求看起来像我们的REST API。

注意：此SDK默认提供异步API。异步是一种比多线程更高效的并发模型，可以提供显著的性能优势，并允许使用WebSocket等长连接。

以下是一个完整的示例，展示了如何从Microsoft Graph获取用户。

import asyncio
from azure.identity.aio import ClientSecretCredential
from msgraph import GraphServiceClient

credential = ClientSecretCredential(
    'tenant_id',
    'client_id',
    'client_secret'
)
scopes = ['https://graph.microsoft.com/.default']
client = GraphServiceClient(credentials=credential, scopes=scopes)

# GET /users/{id | userPrincipalName}
async def get_user():
    user = await client.users.by_user_id('userPrincipalName').get()
    if user:
        print(user.display_name)
asyncio.run(get_user())

请注意，调用me需要已登录的用户，因此需要委托权限。有关更多信息，请参阅用户认证。

import asyncio
from azure.identity import InteractiveBrowserCredential
from msgraph import GraphServiceClient

credential = InteractiveBrowserCredential(
    client_id=os.getenv('client_id'),
    tenant_id=os.getenv('tenant_id'),
)
scopes = ["User.Read"]
client = GraphServiceClient(credentials=credential, scopes=scopes,)

# GET /me
async def me():
    me = await client.me.get()
    if me:
        print(me.display_name)
asyncio.run(me())

3.1 错误处理

失败的请求会引发APIError异常。您可以使用try catch语句来处理这些异常。

from kiota_abstractions.api_error import APIError
async def get_user():
    try:
        user = await client.users.by_user_id('userID').get()
        print(user.user_principal_name, user.display_name, user.id)
    except APIError as e:
        print(f'Error: {e.error.message}')
asyncio.run(get_user())

3.2 分页

默认情况下，返回最多100行，但如果响应中存在odata_next_link，则可以使用它来获取最多100行的下一批数据。以下是一个示例，首先获取一个组中成员的初始行，然后使用odata_next_link遍历行页面。

        # get group members
        members = await client.groups.by_group_id(id).members.get()
        if members:
            print(f"########## Members:")
            for i in range(len(members.value)):
                print(f"display_name: {members.value[i].display_name}, mail: {members.value[i].mail}, id: {members.value[i].id}")

        # iterate over result batches > 100 rows
        while members is not None and members.odata_next_link is not None:
            members = await client.groups.by_group_id(id).members.with_url(members.odata_next_link).get()
            if members:
                print(f"########## Members:")
                for i in range(len(members.value)):
                    print(f"display_name: {members.value[i].display_name}, mail: {members.value[i].mail}, id: {members.value[i].id}")

文档和资源

• 概述

• Microsoft Graph网站

• 示例

升级

有关主要升级期间引入的破坏性更改、错误修复和新功能的具体信息，请参阅我们的升级指南。

问题

在仓库中的问题选项卡中查看或记录问题。

贡献

请仔细阅读我们的贡献指南，了解如何为此仓库做出贡献。

版权和许可

版权（c）微软公司。保留所有权利。在MIT 许可下发布。

本项目已采用微软开源行为准则。有关更多信息，请参阅行为准则常见问题解答或联系opencode@microsoft.com以获取任何额外的疑问或评论。

第三方声明

第三方声明