Microsoft Graph を使用して JavaScript アプリをビルドする
このチュートリアルでは、Microsoft Graph APIを使用してユーザーの代わりにデータにアクセスする JavaScript コンソール アプリを構築する方法について説明します。
注:
Microsoft Graph を使用してアプリ専用認証を使用してデータにアクセスする方法については、この アプリ専用認証チュートリアルを参照してください。
このチュートリアルの内容:
ヒント
このチュートリアルに従う代わりに、アプリの登録と構成を自動化する クイック スタート ツールを使用して、完成したコードをダウンロードできます。 ダウンロードしたコードは、変更を加えずに機能します。
GitHub リポジトリをダウンロードまたは複製し、README の指示に従ってアプリケーションを登録し、プロジェクトを構成することもできます。
前提条件
このチュートリアルを開始する前に、開発用コンピューター にNode.js がインストールされている必要があります。
また、Exchange Online メールボックスを持つ Microsoft の職場または学校アカウントも必要です。 Microsoft 365 テナントをお持ちでない場合は、 Microsoft 365 開発者プログラムを通じてテナントの資格を得る可能性があります。詳細については、 FAQ を参照してください。 または、 1 か月間の無料試用版にサインアップするか、Microsoft 365 プランを購入することもできます。
注:
このチュートリアルは、Node.js バージョン 16.14.2 で記述されました。 このガイドの手順は、他のバージョンで動作する可能性がありますが、テストされていません。
ポータルでアプリを登録する
この演習では、 ユーザー認証を有効にするために、Azure Active Directory に新しいアプリケーションを登録します。 アプリケーションは、Azure Active Directory 管理センターを使用するか、 Microsoft Graph PowerShell SDK を使用して登録できます。
ユーザー認証用にアプリケーションを登録する
このセクションでは、 デバイス コード フローを使用したユーザー認証をサポートするアプリケーションを登録します。
ブラウザーを開き、 Azure Active Directory 管理センター に移動し、 職場または学校アカウントを使用してログインします。
左側のナビゲーションで [Azure Active Directory] を選択し、それから [管理] で [アプリの登録] を選択します。
[新規登録] を選択します。 アプリケーションの名前を入力します (例:
Graph User Auth Tutorial
)。必要に応じて、[サポートされているアカウントの種類] を設定します。 以下のオプションがあります:
オプション サインインできるユーザー この組織のディレクトリ内のアカウントのみ Microsoft 365 organization内のユーザーのみ 組織のディレクトリ内のアカウント Microsoft 365 organization (職場または学校アカウント) のユーザー 任意の組織ディレクトリ ... のアカウント。個人の Microsoft アカウント Microsoft 365 organization (職場または学校アカウント) および個人用 Microsoft アカウントのユーザー [リダイレクト URI]を空のままにします。
[登録] を選択します。 アプリケーションの [概要 ] ページで、 アプリケーション (クライアント) ID の値をコピーして保存します。次の手順で必要になります。 [サポートされているアカウントの種類] に対してのみこの組織ディレクトリの [アカウント] を選択した場合は、ディレクトリ (テナント) ID もコピーして保存します。
[管理] の下の [認証] を選択します。 [ 詳細設定 ] セクションを見つけて、[ パブリック クライアント フローを許可する] トグルを [はい] に変更し、[保存] を選択 します。
注:
アプリの登録に対して Microsoft Graph のアクセス許可を構成していないことに注意してください。 これは、サンプルで 動的同意 を使用して、ユーザー認証の特定のアクセス許可を要求するためです。
JavaScript コンソール アプリを作成する
まず、新しい Node.js プロジェクトを作成します。 プロジェクトを作成するディレクトリでコマンド ライン インターフェイス (CLI) を開きます。 次のコマンドを実行します。
npm init
独自の値を指定するか、既定値をそのまま使用して、プロンプトに応答します。
依存関係のインストール
次に進む前に、後で使用するいくつかの依存関係を追加します。
- ユーザーを認証し、アクセス トークンを取得するための JavaScript 用の Azure Identity クライアント ライブラリ。
- Microsoft Graph JavaScript クライアント ライブラリ を使用して、Microsoft Graph を呼び出します。
- api を Node.js に追加
fetch
するための等形フェッチ。 これは、Microsoft Graph JavaScript クライアント ライブラリの依存関係です。 - ユーザーに入力を求める readline-sync。
CLI で次のコマンドを実行して、依存関係をインストールします。
npm install @azure/identity @microsoft/microsoft-graph-client isomorphic-fetch readline-sync
アプリケーション設定を読み込む
このセクションでは、アプリ登録の詳細をプロジェクトに追加します。
プロジェクトのルートに appSettings.js という名前のファイルを作成し、次のコードを追加します。
const settings = { 'clientId': 'YOUR_CLIENT_ID_HERE', 'tenantId': 'common', 'graphUserScopes': [ 'user.read', 'mail.read', 'mail.send' ] }; module.exports = settings;
の値を次の
settings
表に従って更新します。設定 値 clientId
アプリ登録のクライアント ID tenantId
organizationのユーザーのみがサインインできるようにするオプションを選択した場合は、この値をテナント ID に変更します。 それ以外の場合は、 のままに common
します。
アプリを設計する
このセクションでは、簡単なコンソール ベースのメニューを作成します。
プロジェクトのルートに graphHelper.js という名前のファイルを作成し、次のプレースホルダー コードを追加します。 このファイルには、後の手順でさらにコードを追加します。
module.exports = {};
プロジェクトのルートに index.js という名前のファイルを作成し、次のコードを追加します。
const readline = require('readline-sync'); const settings = require('./appSettings'); const graphHelper = require('./graphHelper'); async function main() { console.log('JavaScript Graph Tutorial'); let choice = 0; // Initialize Graph initializeGraph(settings); // Greet the user by name await greetUserAsync(); const choices = [ 'Display access token', 'List my inbox', 'Send mail', 'Make a Graph call' ]; while (choice != -1) { choice = readline.keyInSelect(choices, 'Select an option', { cancel: 'Exit' }); switch (choice) { case -1: // Exit console.log('Goodbye...'); break; case 0: // Display access token await displayAccessTokenAsync(); break; case 1: // List emails from user's inbox await listInboxAsync(); break; case 2: // Send an email message await sendMailAsync(); break; case 3: // Run any Graph code await makeGraphCallAsync(); break; default: console.log('Invalid choice! Please try again.'); } } } main();
ファイルの末尾に次のプレースホルダー メソッドを追加します。 後の手順で実装します。
function initializeGraph(settings) { // TODO } async function greetUserAsync() { // TODO } async function displayAccessTokenAsync() { // TODO } async function listInboxAsync() { // TODO } async function sendMailAsync() { // TODO } async function makeGraphCallAsync() { // TODO }
これにより、基本的なメニューが実装され、コマンド ラインからユーザーの選択が読み取ります。
ユーザー認証を追加する
このセクションでは、前の演習のアプリケーションを拡張して、Azure AD での認証をサポートします。 これは、Microsoft Graph を呼び出すために必要な OAuth アクセス トークンを取得するために必要です。 この手順では、 JavaScript 用の Azure Identity クライアント ライブラリ をアプリケーションに統合し、 Microsoft Graph JavaScript クライアント ライブラリの認証を構成します。
Azure Identity ライブラリには、OAuth2 トークン フローを実装する多数の TokenCredential
クラスが用意されています。 Microsoft Graph クライアント ライブラリでは、これらのクラスを使用して Microsoft Graph への呼び出しを認証します。
ユーザー認証用に Graph クライアントを構成する
このセクションでは、 クラスを DeviceCodeCredential
使用して、 デバイス コード フローを使用してアクセス トークンを要求します。
graphHelper.js を開き、その内容を次のように置き換えます。
require('isomorphic-fetch'); const azure = require('@azure/identity'); const graph = require('@microsoft/microsoft-graph-client'); const authProviders = require('@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials'); let _settings = undefined; let _deviceCodeCredential = undefined; let _userClient = undefined; function initializeGraphForUserAuth(settings, deviceCodePrompt) { // Ensure settings isn't null if (!settings) { throw new Error('Settings cannot be undefined'); } _settings = settings; _deviceCodeCredential = new azure.DeviceCodeCredential({ clientId: settings.clientId, tenantId: settings.tenantId, userPromptCallback: deviceCodePrompt }); const authProvider = new authProviders.TokenCredentialAuthenticationProvider( _deviceCodeCredential, { scopes: settings.graphUserScopes }); _userClient = graph.Client.initWithMiddleware({ authProvider: authProvider }); } module.exports.initializeGraphForUserAuth = initializeGraphForUserAuth;
index.js の空
initializeGraph
の関数を次のように置き換えます。function initializeGraph(settings) { graphHelper.initializeGraphForUserAuth(settings, (info) => { // Display the device code message to // the user. This tells them // where to go to sign in and provides the // code to use. console.log(info.message); }); }
このコードでは、 DeviceCodeCredential
オブジェクトとオブジェクトの 2 つのプライベート プロパティを Client
宣言します。 関数は initializeGraphForUserAuth
の新しいインスタンス DeviceCodeCredential
を作成し、そのインスタンスを使用して の Client
新しいインスタンスを作成します。 を介して _userClient
Microsoft Graph に API 呼び出しが行われるたびに、指定された資格情報を使用してアクセス トークンを取得します。
DeviceCodeCredential をテストする
次に、 からアクセス トークンを取得するコードを追加します DeviceCodeCredential
。
次の関数を graphHelper.jsに追加します。
async function getUserTokenAsync() { // Ensure credential isn't undefined if (!_deviceCodeCredential) { throw new Error('Graph has not been initialized for user auth'); } // Ensure scopes isn't undefined if (!_settings?.graphUserScopes) { throw new Error('Setting "scopes" cannot be undefined'); } // Request token with given scopes const response = await _deviceCodeCredential.getToken(_settings?.graphUserScopes); return response.token; } module.exports.getUserTokenAsync = getUserTokenAsync;
index.js の空
displayAccessTokenAsync
の関数を次のように置き換えます。async function displayAccessTokenAsync() { try { const userToken = await graphHelper.getUserTokenAsync(); console.log(`User token: ${userToken}`); } catch (err) { console.log(`Error getting user access token: ${err}`); } }
プロジェクトのルートで CLI で次のコマンドを実行します。
node index.js
オプションの入力を求められたら、「」と入力
1
します。 アプリケーションに URL とデバイス コードが表示されます。JavaScript Graph Tutorial [1] Display access token [2] List my inbox [3] Send mail [4] Make a Graph call [0] Exit Select an option [1...4 / 0]: 1 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code RK987NX32 to authenticate.
ブラウザーを開き、表示された URL を参照します。 指定したコードを入力し、サインインします。
重要
を
https://microsoft.com/devicelogin
参照するときにブラウザーにログインしている既存の Microsoft 365 アカウントに注意してください。 プロファイル、ゲスト モード、プライベート モードなどのブラウザー機能を使用して、テストに使用するアカウントとして認証することを確認します。完了したら、アプリケーションに戻り、アクセス トークンを表示します。
ヒント
検証とデバッグ のみを目的として、 で Microsoft のオンライン トークン パーサー https://jwt.msを使用してユーザー アクセス トークンをデコードできます (職場または学校アカウントの場合のみ)。 これは、Microsoft Graph を呼び出すときにトークン エラーが発生した場合に役立ちます。 たとえば、トークン内の要求に
scp
想定される Microsoft Graph アクセス許可スコープが含まれていることを確認します。
ユーザーを取得する
このセクションでは、Microsoft Graph をアプリケーションに組み込みます。 Microsoft Graph JavaScript クライアント ライブラリを使用して、Microsoft Graph を呼び出します。
graphHelper.js 開き、次の関数を追加します。
async function getUserAsync() { // Ensure client isn't undefined if (!_userClient) { throw new Error('Graph has not been initialized for user auth'); } return _userClient.api('/me') // Only request specific properties .select(['displayName', 'mail', 'userPrincipalName']) .get(); } module.exports.getUserAsync = getUserAsync;
index.js の空
greetUserAsync
の関数を次のように置き換えます。async function greetUserAsync() { try { const user = await graphHelper.getUserAsync(); console.log(`Hello, ${user?.displayName}!`); // For Work/school accounts, email is in mail property // Personal accounts, email is in userPrincipalName console.log(`Email: ${user?.mail ?? user?.userPrincipalName ?? ''}`); } catch (err) { console.log(`Error getting user: ${err}`); } }
今すぐアプリを実行すると、アプリにログインすると名前で歓迎されます。
Hello, Megan Bowen!
Email: MeganB@contoso.com
コードの説明
関数のコードを getUserAsync
考えてみましょう。 ほんの数行ですが、注意する必要がある重要な詳細がいくつかあります。
'me' へのアクセス
関数は要求ビルダーに渡 /me
され _userClient.api
、 Get user API に要求がビルドされます。 この API には、次の 2 つの方法でアクセスできます。
GET /me
GET /users/{user-id}
この場合、コードは API エンドポイントを GET /me
呼び出します。 これは、ユーザー ID を知らずに認証されたユーザーを取得するためのショートカット メソッドです。
注:
API エンドポイントは GET /me
認証されたユーザーを取得するため、ユーザー認証を使用するアプリでのみ使用できます。 アプリ専用認証アプリは、このエンドポイントにアクセスできません。
特定のプロパティの要求
関数は、要求で メソッドを使用 select
して、必要なプロパティのセットを指定します。 これにより、 $select クエリ パラメーター が API 呼び出しに追加されます。
厳密に型指定された戻り値の型
関数は、 User
API からの JSON 応答から逆シリアル化されたオブジェクトを返します。 コードでは を使用 select
するため、返される User
オブジェクトには、要求されたプロパティのみが値を持ちます。 その他のすべてのプロパティには既定値が設定されます。
受信トレイを一覧表示する
このセクションでは、ユーザーのメール 受信トレイにメッセージを一覧表示する機能を追加します。
graphHelper.js 開き、次の関数を追加します。
async function getInboxAsync() { // Ensure client isn't undefined if (!_userClient) { throw new Error('Graph has not been initialized for user auth'); } return _userClient.api('/me/mailFolders/inbox/messages') .select(['from', 'isRead', 'receivedDateTime', 'subject']) .top(25) .orderby('receivedDateTime DESC') .get(); } module.exports.getInboxAsync = getInboxAsync;
index.js の空
ListInboxAsync
の関数を次のように置き換えます。async function listInboxAsync() { try { const messagePage = await graphHelper.getInboxAsync(); const messages = messagePage.value; // Output each message's details for (const message of messages) { console.log(`Message: ${message.subject ?? 'NO SUBJECT'}`); console.log(` From: ${message.from?.emailAddress?.name ?? 'UNKNOWN'}`); console.log(` Status: ${message.isRead ? 'Read' : 'Unread'}`); console.log(` Received: ${message.receivedDateTime}`); } // If @odata.nextLink is not undefined, there are more messages // available on the server const moreAvailable = messagePage['@odata.nextLink'] != undefined; console.log(`\nMore messages available? ${moreAvailable}`); } catch (err) { console.log(`Error getting user's inbox: ${err}`); } }
アプリを実行し、サインインし、オプション 2 を選択して受信トレイを一覧表示します。
[1] Display access token [2] List my inbox [3] Send mail [4] Make a Graph call [0] Exit Select an option [1...4 / 0]: 2 Message: Updates from Ask HR and other communities From: Contoso Demo on Yammer Status: Read Received: 12/30/2021 4:54:54 AM -05:00 Message: Employee Initiative Thoughts From: Patti Fernandez Status: Read Received: 12/28/2021 5:01:10 PM -05:00 Message: Voice Mail (11 seconds) From: Alex Wilber Status: Unread Received: 12/28/2021 5:00:46 PM -05:00 Message: Our Spring Blog Update From: Alex Wilber Status: Unread Received: 12/28/2021 4:49:46 PM -05:00 Message: Atlanta Flight Reservation From: Alex Wilber Status: Unread Received: 12/28/2021 4:35:42 PM -05:00 Message: Atlanta Trip Itinerary - down time From: Alex Wilber Status: Unread Received: 12/28/2021 4:22:04 PM -05:00 ... More messages available? true
コードの説明
関数のコードを getInboxAsync
考えてみましょう。
既知のメール フォルダーへのアクセス
関数は要求ビルダーに渡 /me/mailFolders/inbox/messages
され _userClient.api
、 List メッセージ API に要求がビルドされます。 API エンドポイントの部分が /mailFolders/inbox
含まれているため、API は要求されたメール フォルダー内のメッセージのみを返します。 この場合、受信トレイはユーザーのメールボックス内の既定の既知のフォルダーであるため、既知の名前を使用してアクセスできます。 既知の名前をメール フォルダーの ID プロパティに置き換えることで、既定以外のフォルダーにも同じ方法でアクセスします。 使用可能な既知のフォルダー名の詳細については、「 mailFolder リソースの種類」を参照してください。
コレクションへのアクセス
1 つのオブジェクトを getUserAsync
返す前のセクションの関数とは異なり、このメソッドはメッセージのコレクションを返します。 コレクションを返す Microsoft Graph のほとんどの API では、使用可能なすべての結果が 1 つの応答で返されるわけではありません。 代わりに、 ページングを 使用して結果の一部を返しながら、クライアントが次の "ページ" を要求するメソッドを提供します。
既定のページ サイズ
ページングを使用する API では、既定のページ サイズが実装されます。 メッセージの場合、既定値は 10 です。 クライアントは、 $top クエリ パラメーターを使用して、より多く (またはそれ以下) を要求できます。 では getInboxAsync
、 メソッドを使用して .top(25)
これを実行します。
注:
に渡される .top()
値は、明示的な数値ではなく、上限です。 API は、指定した値までのメッセージ数 を 返します。
後続のページを取得する
サーバーで使用可能な結果が増える場合、コレクション応答には、次のページにアクセスするための API URL を持つプロパティが含まれます @odata.nextLink
。 JavaScript クライアント ライブラリは、オブジェクトに対してこのプロパティを PageCollection
公開します。 このプロパティが未定義でない場合は、使用可能な結果が増えます。
の @odata.nextLink
値を に _userClient.api
渡して、結果の次のページを取得できます。 または、クライアント ライブラリの オブジェクトを PageIterator
使用して、 使用可能なすべてのページを反復処理することもできます。
コレクションを並べ替える
関数は、要求で メソッドを orderby
使用して、メッセージが受信された時刻 (receivedDateTime
プロパティ) で並べ替えられた結果を要求します。 最近受信したメッセージがDESC
最初に一覧表示されるように、キーワード (keyword)が含まれます。 これにより、 $orderby クエリ パラメーター が API 呼び出しに追加されます。
メールを送信する
このセクションでは、認証されたユーザーとして電子メール メッセージを送信する機能を追加します。
graphHelper.js 開き、次の関数を追加します。
async function sendMailAsync(subject, body, recipient) { // Ensure client isn't undefined if (!_userClient) { throw new Error('Graph has not been initialized for user auth'); } // Create a new message const message = { subject: subject, body: { content: body, contentType: 'text' }, toRecipients: [ { emailAddress: { address: recipient } } ] }; // Send the message return _userClient.api('me/sendMail') .post({ message: message }); } module.exports.sendMailAsync = sendMailAsync;
index.js の空
sendMailAsync
の関数を次のように置き換えます。async function sendMailAsync() { try { // Send mail to the signed-in user // Get the user for their email address const user = await graphHelper.getUserAsync(); const userEmail = user?.mail ?? user?.userPrincipalName; if (!userEmail) { console.log('Couldn\'t get your email address, canceling...'); return; } await graphHelper.sendMailAsync('Testing Microsoft Graph', 'Hello world!', userEmail); console.log('Mail sent.'); } catch (err) { console.log(`Error sending mail: ${err}`); } }
アプリを実行し、サインインし、オプション 3 を選択して自分にメールを送信します。
[1] Display access token [2] List my inbox [3] Send mail [4] Make a Graph call [0] Exit Select an option [1...4 / 0]: 3 Mail sent.
注:
Microsoft 365 開発者プログラムの開発者テナントでテストしている場合は、送信したメールが配信されず、配信不能レポートが届く場合があります。 このような場合は、Microsoft 365 管理センターからサポートにお問い合わせください。
メッセージが受信されたことを確認するには、オプション 2 を選択して受信トレイを一覧表示します。
コードの説明
関数のコードを sendMailAsync
考えてみましょう。
メールの送信
関数は要求ビルダーに渡 /me/sendMail
され _userClient.api
、送信 メール API に要求がビルドされます。 要求ビルダーは、送信する Message
メッセージを表す オブジェクトを受け取ります。
オブジェクトの作成
データのみを読み取る Microsoft Graph の以前の呼び出しとは異なり、この呼び出しではデータが作成されます。 これをクライアント ライブラリで行うには、データを表す クラスのインスタンス (この場合は) を作成し、 Message
目的のプロパティを設定し、API 呼び出しで送信します。 呼び出しがデータを post
送信しているため、 メソッドは ではなく get
を使用します。
省略可能: 独自のコードを追加する
このセクションでは、独自の Microsoft Graph 機能をアプリケーションに追加します。 これは、Microsoft Graph ドキュメントまたは Graph エクスプローラーのコード スニペット、または作成したコードです。 このセクションは省略可能です。
アプリを更新する
graphHelper.js 開き、次の関数を追加します。
// This function serves as a playground for testing Graph snippets // or other code async function makeGraphCallAsync() { // INSERT YOUR CODE HERE } module.exports.makeGraphCallAsync = makeGraphCallAsync;
index.js の空
makeGraphCallAsync
の関数を次のように置き換えます。async function makeGraphCallAsync() { try { await graphHelper.makeGraphCallAsync(); } catch (err) { console.log(`Error making Graph call: ${err}`); } }
API を選択する
試したい API を Microsoft Graph で見つけます。 たとえば、 Create イベント API です。 API ドキュメントの例のいずれかを使用するか、Graph エクスプローラーで API 要求をカスタマイズし、生成されたスニペットを使用できます。
アクセス許可を構成する
選択した API のリファレンス ドキュメントの [アクセス許可] セクションを確認して、サポートされている認証方法を確認します。 たとえば、一部の API では、アプリ専用アカウントや個人用 Microsoft アカウントがサポートされていません。
- ユーザー認証を使用して API を呼び出すには (API でユーザー (委任された) 認証がサポートされている場合)、必要なアクセス許可スコープ をappSettings.jsに追加します。
- アプリ専用認証を使用して API を呼び出すには、 アプリのみの認証 に関するチュートリアルを参照してください。
コードを追加する
graphHelper.jsの makeGraphCallAsync
関数にコード を コピーします。 ドキュメントまたは Graph エクスプローラーからスニペットをコピーする場合は、 の名前を に_userClient
変更client
してください。
おめでとうございます。
JavaScript Microsoft Graph チュートリアルを完了しました。 Microsoft Graph を呼び出す作業アプリが作成されたので、新しい機能を試して追加できます。
- Microsoft Graph JavaScript SDK で アプリのみの認証 を使用する方法について説明します。
- Microsoft Graph でアクセスできるすべてのデータについては、 Microsoft Graph の概要 に関するページを参照してください。
Microsoft Graph ツールキット
UI を使用して JavaScript アプリをビルドする場合、 Microsoft Graph Toolkit には、開発を簡略化できるコンポーネントのコレクションが用意されています。
TypeScript/JavaScript のサンプル
このセクションに問題がある場合 このセクションを改善できるよう、フィードバックをお送りください。