Microsoft Graph を使用して Python アプリをビルドする
このチュートリアルでは、Microsoft Graph API を使用してユーザーの代わりにデータにアクセスする Python コンソール アプリを構築する方法について説明します。
注意
Microsoft Graph を使用してアプリ専用認証を使用してデータにアクセスする方法については、この アプリ専用認証チュートリアルを参照してください。
このチュートリアルの内容:
ヒント
このチュートリアルに従う代わりに、アプリの登録と構成を自動化する クイック スタート ツールを使用して、完成したコードをダウンロードできます。 ダウンロードしたコードは、変更を加えずに機能します。
GitHub リポジトリをダウンロードまたは複製し、README の指示に従ってアプリケーションを登録し、プロジェクトを構成することもできます。
前提条件
このチュートリアルを開始する前に、開発用コンピューターに Python と pip がインストールされている必要があります。
また、Exchange Online メールボックスを持つ Microsoft の職場または学校アカウントも必要です。 Microsoft 365 テナントをお持ちでない場合は、 Microsoft 365 開発者プログラムを通じてテナントの資格を得る可能性があります。詳細については、 FAQ を参照してください。 または、 1 か月間の無料試用版にサインアップするか、Microsoft 365 プランを購入することもできます。
注意
このチュートリアルは、Python バージョン 3.10.4 と pip バージョン 20.0.2 で記述されました。 このガイドの手順は、他のバージョンで動作する可能性がありますが、テストされていません。
ポータルでアプリを登録する
この演習では、 ユーザー認証を有効にするために、Azure Active Directory に新しいアプリケーションを登録します。 アプリケーションは、Microsoft Entra 管理センターを使用するか、 Microsoft Graph PowerShell SDK を使用して登録できます。
ユーザー認証用にアプリケーションを登録する
このセクションでは、 デバイス コード フローを使用したユーザー認証をサポートするアプリケーションを登録します。
ブラウザーを開き、 Microsoft Entra 管理センター に移動し、グローバル管理者アカウントを使用してログインします。
左側のナビゲーションで [Microsoft Entra ID] を 選択し、[ ID] を展開し、[ アプリケーション] を展開して、[ アプリの登録] を選択します。
[新規登録] を選択します。 アプリケーションの名前 (例:
Graph User Auth Tutorial
) を入力します。必要に応じて、[サポートされているアカウントの種類] を設定します。 以下のオプションがあります:
オプション サインインできるユーザー この組織のディレクトリ内のアカウントのみ Microsoft 365 組織内のユーザーのみ 組織のディレクトリ内のアカウント Microsoft 365 組織内のユーザー (職場または学校アカウント) 任意の組織ディレクトリ ... のアカウント。個人の Microsoft アカウント Microsoft 365 組織内のユーザー (職場または学校アカウント) と個人の Microsoft アカウント [リダイレクト URI]を空のままにします。
[登録] を選択します。 アプリケーションの [概要 ] ページで、 アプリケーション (クライアント) ID の値をコピーして保存します。次の手順で必要になります。 [サポートされているアカウントの種類] に対してのみこの組織ディレクトリの [アカウント] を選択した場合は、ディレクトリ (テナント) ID もコピーして保存します。
[管理] の下の [認証] を選択します。 [ 詳細設定 ] セクションを見つけて、[ パブリック クライアント フローを許可する] トグルを [はい] に変更し、[保存] を選択 します。
注意
アプリの登録に対して Microsoft Graph のアクセス許可を構成していないことに注意してください。 これは、サンプルで 動的同意 を使用して、ユーザー認証の特定のアクセス許可を要求するためです。
Python コンソール アプリを作成する
まず、新しい Python ファイルを作成します。
main.py という名前の新しいファイル を 作成し、次のコードを追加します。
print ('Hello world!')
ファイルを保存し、次のコマンドを使用してファイルを実行します。
python3 main.py
動作する場合、アプリは
Hello world!
を出力する必要があります。
依存関係のインストール
次に進む前に、後で使用するいくつかの依存関係を追加します。
- ユーザーを認証し、アクセス トークンを取得するための Python 用の Azure Identity クライアント ライブラリ。
- Microsoft Graph SDK for Python (プレビュー) を使用して Microsoft Graph を呼び出します。
CLI で次のコマンドを実行して、依存関係をインストールします。
python3 -m pip install azure-identity
python3 -m pip install msgraph-sdk
アプリケーション設定を読み込む
このセクションでは、アプリ登録の詳細をプロジェクトに追加します。
config.cfg という名前 main.py 同じディレクトリにファイルを作成し、次のコードを追加します。
[azure] clientId = YOUR_CLIENT_ID_HERE tenantId = common graphUserScopes = User.Read Mail.Read Mail.Send
次の表に従って値を更新します。
設定 値 clientId
アプリ登録のクライアント ID tenantId
組織内のユーザーのみがサインインできるようにするオプションを選択した場合は、この値をテナント ID に変更します。 それ以外の場合は、 common
のままにします。ヒント
必要に応じて、 config.dev.cfg という名前の別のファイルでこれらの値を設定できます。
アプリを設計する
このセクションでは、簡単なコンソール ベースのメニューを作成します。
graph.py という名前 の 新しいファイルを作成し、そのファイルに次のコードを追加します。
# Temporary placeholder class Graph: def __init__(self, config): self.settings = config
このコードはプレースホルダーです。 次のセクションでは、
Graph
クラスを実装します。main.py を開き、その内容全体を次のコードに置き換えます。
import asyncio import configparser from msgraph.generated.models.o_data_errors.o_data_error import ODataError from graph import Graph async def main(): print('Python Graph Tutorial\n') # Load settings config = configparser.ConfigParser() config.read(['config.cfg', 'config.dev.cfg']) azure_settings = config['azure'] graph: Graph = Graph(azure_settings) await greet_user(graph) choice = -1 while choice != 0: print('Please choose one of the following options:') print('0. Exit') print('1. Display access token') print('2. List my inbox') print('3. Send mail') print('4. Make a Graph call') try: choice = int(input()) except ValueError: choice = -1 try: if choice == 0: print('Goodbye...') elif choice == 1: await display_access_token(graph) elif choice == 2: await list_inbox(graph) elif choice == 3: await send_mail(graph) elif choice == 4: await make_graph_call(graph) else: print('Invalid choice!\n') except ODataError as odata_error: print('Error:') if odata_error.error: print(odata_error.error.code, odata_error.error.message)
ファイルの末尾に次のプレースホルダー メソッドを追加します。 後の手順で実装します。
async def greet_user(graph: Graph): # TODO return async def display_access_token(graph: Graph): # TODO return async def list_inbox(graph: Graph): # TODO return async def send_mail(graph: Graph): # TODO return async def make_graph_call(graph: Graph): # TODO return
次の行を追加して、ファイルの末尾に
main
を呼び出します。# Run main asyncio.run(main())
これにより、基本的なメニューが実装され、コマンド ラインからユーザーの選択が読み取ります。
ユーザー認証を追加する
このセクションでは、前の演習のアプリケーションを拡張して、Azure AD での認証をサポートします。 これは、Microsoft Graph を呼び出すために必要な OAuth アクセス トークンを取得するために必要です。 この手順では、 Python 用 Azure Identity クライアント ライブラリ をアプリケーションに統合し、 Microsoft Graph SDK for Python (プレビュー) の認証を構成します。
Azure Identity ライブラリには、OAuth2 トークン フローを実装する多数の TokenCredential
クラスが用意されています。 Microsoft Graph SDK では、これらのクラスを使用して Microsoft Graph への呼び出しを認証します。
ユーザー認証用に Graph クライアントを構成する
このセクションでは、 DeviceCodeCredential
クラスを使用して、 デバイス コード フローを使用してアクセス トークンを要求します。
graph.py を開き、その内容全体を次のコードに置き換えます。
from configparser import SectionProxy from azure.identity import DeviceCodeCredential from msgraph import GraphServiceClient from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder from msgraph.generated.users.item.mail_folders.item.messages.messages_request_builder import ( MessagesRequestBuilder) from msgraph.generated.users.item.send_mail.send_mail_post_request_body import ( SendMailPostRequestBody) from msgraph.generated.models.message import Message from msgraph.generated.models.item_body import ItemBody from msgraph.generated.models.body_type import BodyType from msgraph.generated.models.recipient import Recipient from msgraph.generated.models.email_address import EmailAddress class Graph: settings: SectionProxy device_code_credential: DeviceCodeCredential user_client: GraphServiceClient def __init__(self, config: SectionProxy): self.settings = config client_id = self.settings['clientId'] tenant_id = self.settings['tenantId'] graph_scopes = self.settings['graphUserScopes'].split(' ') self.device_code_credential = DeviceCodeCredential(client_id, tenant_id = tenant_id) self.user_client = GraphServiceClient(self.device_code_credential, graph_scopes)
このコードでは、
DeviceCodeCredential
オブジェクトとGraphServiceClient
オブジェクトの 2 つのプライベート プロパティを宣言します。__init__
関数は、DeviceCodeCredential
の新しいインスタンスを作成し、そのインスタンスを使用してGraphServiceClient
の新しいインスタンスを作成します。user_client
を介して Microsoft Graph に API 呼び出しが行われるたびに、提供された資格情報を使用してアクセス トークンを取得します。次の関数を graph.py に追加します。
async def get_user_token(self): graph_scopes = self.settings['graphUserScopes'] access_token = self.device_code_credential.get_token(graph_scopes) return access_token.token
main.py の空の
display_access_token
関数 を 次のように置き換えます。async def display_access_token(graph: Graph): token = await graph.get_user_token() print('User token:', token, '\n')
アプリをビルドして実行します。 オプションの入力を求められたら、「
1
」と入力します。 アプリケーションに URL とデバイス コードが表示されます。Python Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. Make a Graph call 1 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code RB2RUD56D to authenticate.
ブラウザーを開き、表示された URL を参照します。 指定したコードを入力し、サインインします。
重要
https://microsoft.com/devicelogin
を参照するときにブラウザーにログインしている既存の Microsoft 365 アカウントに注意してください。 プロファイル、ゲスト モード、プライベート モードなどのブラウザー機能を使用して、テストに使用するアカウントとして認証することを確認します。完了したら、アプリケーションに戻り、アクセス トークンを表示します。
ヒント
検証とデバッグ のみを目的として、 https://jwt.msで Microsoft のオンライン トークン パーサーを使用してユーザー アクセス トークンをデコードできます (職場または学校アカウントの場合のみ)。 これは、Microsoft Graph を呼び出すときにトークン エラーが発生した場合に役立ちます。 たとえば、トークン内の
scp
要求に、想定される Microsoft Graph アクセス許可スコープが含まれていることを確認します。
ユーザーを取得する
このセクションでは、Microsoft Graph をアプリケーションに組み込みます。 このアプリケーションでは、 Microsoft Graph SDK for Python (プレビュー) を使用して Microsoft Graph を呼び出します。
次の関数を graph.py に追加します。
async def get_user(self): # Only request specific properties using $select query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters( select=['displayName', 'mail', 'userPrincipalName'] ) request_config = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration( query_parameters=query_params ) user = await self.user_client.me.get(request_configuration=request_config) return user
main.py の空の
greet_user
関数 を 次のように置き換えます。async def greet_user(graph: Graph): user = await graph.get_user() if user: print('Hello,', user.display_name) # For Work/school accounts, email is in mail property # Personal accounts, email is in userPrincipalName print('Email:', user.mail or user.user_principal_name, '\n')
今すぐアプリを実行すると、アプリにログインすると名前で歓迎されます。
Hello, Megan Bowen!
Email: MeganB@contoso.com
コードの説明
get_user
関数のコードについて考えてみましょう。 ほんの数行ですが、注意する必要がある重要な詳細がいくつかあります。
'me' へのアクセス
関数は 、Get ユーザー API に対する要求を作成します。 この API には、次の 2 つの方法でアクセスできます。
GET /me
GET /users/{user-id}
この場合、コードは GET /me
API エンドポイントを呼び出します。 これは、ユーザー ID を知らずに認証されたユーザーを取得するためのショートカット メソッドです。
注意
GET /me
API エンドポイントは認証されたユーザーを取得するため、ユーザー認証を使用するアプリでのみ使用できます。 アプリ専用認証アプリは、このエンドポイントにアクセスできません。
特定のプロパティの要求
関数は 、$select クエリ パラメーター を使用して、必要なプロパティのセットを指定します。 Microsoft Graph は、応答で要求されたプロパティのみを返します。
get_user
では、これは MeRequestBuilderGetQueryParameters
オブジェクトの select
パラメーターを使用して実現されます。
受信トレイを一覧表示する
このセクションでは、ユーザーのメール 受信トレイにメッセージを一覧表示する機能を追加します。
次の関数を graph.py に追加します。
async def get_inbox(self): query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters( # Only request specific properties select=['from', 'isRead', 'receivedDateTime', 'subject'], # Get at most 25 results top=25, # Sort by received time, newest first orderby=['receivedDateTime DESC'] ) request_config = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration( query_parameters= query_params ) messages = await self.user_client.me.mail_folders.by_mail_folder_id('inbox').messages.get( request_configuration=request_config) return messages
main.py の空の
list_inbox
関数 を 次のように置き換えます。async def list_inbox(graph: Graph): message_page = await graph.get_inbox() if message_page and message_page.value: # Output each message's details for message in message_page.value: print('Message:', message.subject) if ( message.from_ and message.from_.email_address ): print(' From:', message.from_.email_address.name or 'NONE') else: print(' From: NONE') print(' Status:', 'Read' if message.is_read else 'Unread') print(' Received:', message.received_date_time) # If @odata.nextLink is present more_available = message_page.odata_next_link is not None print('\nMore messages available?', more_available, '\n')
アプリを実行し、サインインし、オプション 2 を選択して受信トレイを一覧表示します。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. Make a Graph call 2 Message: Updates from Ask HR and other communities From: Contoso Demo on Yammer Status: Read Received: 2022-04-26T19:19:05Z Message: Employee Initiative Thoughts From: Patti Fernandez Status: Read Received: 2022-04-25T19:43:57Z Message: Voice Mail (11 seconds) From: Alex Wilber Status: Unread Received: 2022-04-22T19:43:23Z Message: Our Spring Blog Update From: Alex Wilber Status: Unread Received: 2022-04-19T22:19:02Z Message: Atlanta Flight Reservation From: Alex Wilber Status: Unread Received: 2022-04-19T15:15:56Z Message: Atlanta Trip Itinerary - down time From: Alex Wilber Status: Unread Received: 2022-04-18T14:24:16Z ... More messages available? True
コードの説明
get_inbox
関数のコードについて考えてみましょう。
既知のメール フォルダーへのアクセス
関数は、 List messages API への要求を作成します。
mail_folders.by_mail_folder_id('inbox')
要求ビルダーが含まれているため、API は要求されたメール フォルダー内のメッセージのみを返します。 この場合、受信トレイはユーザーのメールボックス内の既定の既知のフォルダーであるため、既知の名前を使用してアクセスできます。 既知の名前をメール フォルダーの ID プロパティに置き換えることで、既定以外のフォルダーにも同じ方法でアクセスします。 使用可能な既知のフォルダー名の詳細については、「 mailFolder リソースの種類」を参照してください。
コレクションへのアクセス
1 つのオブジェクトを返す前のセクションの get_user
関数とは異なり、このメソッドはメッセージのコレクションを返します。 コレクションを返す Microsoft Graph のほとんどの API では、使用可能なすべての結果が 1 つの応答で返されるわけではありません。 代わりに、 ページングを 使用して結果の一部を返しながら、クライアントが次の "ページ" を要求するメソッドを提供します。
既定のページ サイズ
ページングを使用する API では、既定のページ サイズが実装されます。 メッセージの場合、既定値は 10 です。 クライアントは、 $top クエリ パラメーターを使用して、より多く (またはそれ以下) を要求できます。
get_inbox
では、これは MessagesRequestBuilderGetQueryParameters
オブジェクトの top
パラメーターを使用して実現されます。
注意
$top
で渡される値は、明示的な数値ではなく、上限です。 API は、指定した値までのメッセージ数 を 返します。
後続のページを取得する
サーバーで使用可能な結果が増える場合、コレクション応答には、次のページにアクセスするための API URL を含む @odata.nextLink
プロパティが含まれます。 Python SDK では、コレクション ページ オブジェクトの odata_next_link
プロパティとしてこれを公開します。 このプロパティが存在する場合は、使用可能な結果が増えます。
コレクションを並べ替える
関数は 、$orderby クエリ パラメーター を使用して、メッセージの受信時刻 (receivedDateTime
プロパティ) で並べ替えられた結果を要求します。
DESC
キーワードが含まれているため、最近受信したメッセージが最初に一覧表示されます。
get_inbox
では、これは MessagesRequestBuilderGetQueryParameters
オブジェクトの orderby
パラメーターを使用して実現されます。
メールを送信する
このセクションでは、認証されたユーザーとして電子メール メッセージを送信する機能を追加します。
次の関数を graph.py に追加します。
async def send_mail(self, subject: str, body: str, recipient: str): message = Message() message.subject = subject message.body = ItemBody() message.body.content_type = BodyType.Text message.body.content = body to_recipient = Recipient() to_recipient.email_address = EmailAddress() to_recipient.email_address.address = recipient message.to_recipients = [] message.to_recipients.append(to_recipient) request_body = SendMailPostRequestBody() request_body.message = message await self.user_client.me.send_mail.post(body=request_body)
main.py の空の
send_mail
関数 を 次のように置き換えます。async def send_mail(graph: Graph): # Send mail to the signed-in user # Get the user for their email address user = await graph.get_user() if user: user_email = user.mail or user.user_principal_name await graph.send_mail('Testing Microsoft Graph', 'Hello world!', user_email or '') print('Mail sent.\n')
アプリを実行し、サインインし、オプション 3 を選択して自分にメールを送信します。
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. Make a Graph call 3 Mail sent.
注意
Microsoft 365 開発者プログラムの開発者テナントでテストしている場合は、送信したメールが配信されず、配信不能レポートが届く場合があります。 このような場合は、 Microsoft 365 管理センターからサポートにお問い合わせください。
メッセージが受信されたことを確認するには、オプション 2 を選択して受信トレイを一覧表示します。
コードの説明
send_mail
関数のコードについて考えてみましょう。
メールの送信
関数は、メール送信 API への要求をビルドするuser_client.me.send_mail
要求ビルダーを使用します。
オブジェクトの作成
データのみを読み取る Microsoft Graph の以前の呼び出しとは異なり、この呼び出しではデータが作成されます。 クライアント ライブラリでこれを行うには、要求ペイロードを表すディクショナリを作成し、目的のプロパティを設定してから、API 呼び出しで送信します。 呼び出しはデータを送信しているため、get
の代わりに post
メソッドが使用されます。
省略可能: 独自のコードを追加する
このセクションでは、独自の Microsoft Graph 機能をアプリケーションに追加します。 これは、Microsoft Graph ドキュメント または Graph エクスプローラーのコード スニペット、または作成したコードです。 このセクションは省略可能です。
アプリを更新する
次の関数を graph.py に追加します。
async def make_graph_call(self): # INSERT YOUR CODE HERE return
main.py の空の
make_graph_call
関数 を 次のように置き換えます。async def make_graph_call(graph: Graph): await graph.make_graph_call()
API を選択する
試したい API を Microsoft Graph で見つけます。 たとえば、 Create イベント API です。 API ドキュメントの例のいずれかを使用するか、独自の API 要求を作成できます。
アクセス許可を構成する
選択した API のリファレンス ドキュメントの [アクセス許可] セクションを確認して、サポートされている認証方法を確認します。 たとえば、一部の API では、アプリ専用アカウントや個人用 Microsoft アカウントがサポートされていません。
- ユーザー認証を使用して API を呼び出すには (API がユーザー (委任された) 認証をサポートしている場合)、 config.cfg に必要なアクセス許可スコープを追加します。
- アプリ専用認証を使用して API を呼び出すには、 アプリのみの認証 に関するチュートリアルを参照してください。
コードを追加する
コードを graph.py の make_graph_call
関数にコピーします。 ドキュメントまたは Graph Explorer からスニペットをコピーする場合は、必ず GraphServiceClient
の名前を self.user_client
に変更してください。
おめでとうございます。
Python Microsoft Graph チュートリアルを完了しました。 Microsoft Graph を呼び出す作業アプリが作成されたので、新しい機能を試して追加できます。
- Microsoft Graph SDK for Python で アプリのみの認証 を使用する方法について説明します。
- Microsoft Graph でアクセスできるすべてのデータについては、 Microsoft Graph の概要 に関するページを参照してください。
Python サンプル
このセクションに問題がある場合 このセクションを改善できるよう、フィードバックをお送りください。