Microsoft Graph と Outlook REST API のエンドポイントの比較
Outlook REST API は、 Microsoft Graph と Outlook API エンドポイント (https://outlook.office.com/api) の両方で使用できます。 API は通常同じ機能を提供し、同じ種類のリソース使用します。
注:
Outlook REST API が重複しています。
Outlook REST エンドポイントは、2024 年 3 月に完全に使用停止になります。 既存のアプリを移行して Microsoft Graph を使用します。 これには、「OAuth を 使用した IMAP、POP、または SMTP 接続の認証」の説明に従って OAuth2 トークン対象ユーザーは含まれません。
どちらのエンドポイントを使うべきですか?
Microsoft Graph を使用します。Outlook REST v2.0 は使用停止のパスにあります。 Microsoft Graph エンドポイントでは、Outlook に加えて、他の Office 365 サービス、Enterprise Mobility + Security、Windows 10 を含むその他のたくさんのサービスと機能にアクセスできます。 Microsoft Graph エンドポイントを選択すると、複数のトークンを要求することなく、アプリで Outlook データとその他のリソースの両方へのアクセスを許可するアクセス トークンを取得することができます。
機能の相違点
一部の機能については、現在、Outlook エンドポイントのみで使用できるものや、Microsoft Graph のベータ版にのみ存在するものがあります。
注:
Microsoft では、Outlook エンドポイントで現在使用できるすべての機能を Microsoft Graph に組み込むことに常に取り組んでいます。 このリストは更新されますので、定期的に確認してください。
| 機能 | エンドポイント間の相違点 |
|---|---|
| Outlook のタスク | To Do API を通して、Microsoft Graph でユーザーのタスクにアクセスできます。 |
| 多機能な通知 | Outlook API では、開発者は $select パラメーターを使用することにより、特定のフィールドを通知ペイロードに含めるよう要求することができます。 Microsoft Graph では現在、ベータ エンドポイントでのみこの機能がサポートされています。間もなく v1.0 にリリースする予定です。 |
| ストリーミング通知 | Outlook API では、ベータ エンドポイントのプレビューでのストリーミング通知がサポートされています。 Microsoft Graph はこの機能をサポートしていないため、ロードマップの一部ではありません。 |
Outlook エンドポイントから Microsoft Graph への移行
Microsoft Graph エンドポイントと Outlook エンドポイントの API はよく似ています。 しかしながら、特に Microsoft Graph に移行する場合や、同じアプリケーション内で両方のエンドポイントを使用する場合は知っておくべき相違点があります。
API バージョン
Microsoft Graph API には、v1.0 と beta の 2 つのバージョンが用意されています。一方、Outlook には v1.0、v2.0、beta が用意されています。 Microsoft Graph v1.0 は Outlook v2.0 に、Microsoft Graph beta は Outlook beta に相当します。
OAuth スコープ
Microsoft Graph エンドポイントと Outlook エンドポイントはどちらも Azure AD が発行するトークンに依存し、使用されるアクセス許可は同じですが、アプリケーションがこれらのアクセス許可を要求する方法は各エンドポイントで少し異なります。
Azure v2 OAuth2 エンドポイント
OAuth2 に Azure AD v2.0 エンドポイントを使用するアプリは、認証要求またはトークン要求内の scope パラメーターでアクセス許可のスコープを要求します。
- Microsoft Graph の場合、アプリはアクセス許可を
https://graph.microsoft.com/のプレフィックスを付けて指定します。 たとえば、アプリはhttps://graph.microsoft.com/Mail.Readをscopeパラメーターに含めることでMail.Readアクセス許可を要求できます。 - Outlook エンドポイントの場合、アプリはアクセス許可を
https://outlook.office.com/のプレフィックスを付けて指定します。 たとえば、アプリはhttps://outlook.office.com/Mail.Readをscopeパラメーターに含めることでMail.Readアクセス許可を要求できます。
注:
ドメインがスコープに含まれていない場合、Microsoft Graph であると見なされます。
1 つのエンドポイントに発行されるトークンは、もう一方に対しては無効です。 さらに、1 つの要求内で 1 つのエンドポイントへのアクセス許可ともう一方へのアクセス許可を混在させることはできません。
Azure AD v2.0 エンドポイントでは、Microsoft Graph エンドポイントのクライアント資格情報フローのみがサポートされています。 Outlook エンドポイントでアプリ専用トークンを使用する必要があるアプリは、Azure AD v1.0 エンドポイントを使用する必要があります。
Azure v1 OAuth2 エンドポイント
Azure AD v1.0 エンドポイントを使用するアプリは、Azure Portal でのアプリ登録の際に必要なアクセス許可を指定します。
- Microsoft Graph の場合、必要なアクセス許可を追加する際には Microsoft Graph API を選択します。
- Outlook エンドポイントの場合、必要なアクセス許可を追加する際には Office 365 Exchange Online API を選択します。
リソースのプロパティ名
リソースは、Microsoft Graph と Outlook の間でほぼ同じです。 ただし、プロパティ名の大文字小文字の扱い方が 2 つのエンドポイントで異なります。 Microsoft Graph では、プロパティ名に camelCase を使用しますが、Outlook は PascalCase を使用します。 両者の変換を行うには、大文字と小文字を変換します。 変更されたプロパティ名は、次の表で指定します。
たとえば、Microsoft Graph のメッセージ リソースでは、プロパティを subject、from、receivedDateTime のように定義します。 Outlook エンドポイントでは、これらのプロパティ名は、Subject、From、ReceivedDateTime になります。
変更済みのプロパティ名
次のプロパティ名は、Microsoft Graph と Outlook の間で異なります。
| リソースの種類 | Microsoft Graph プロパティ | Outlook プロパティ |
|---|---|---|
contact |
mobilePhone |
MobilePhone1 |
変更の追跡 (同期)
両方のエンドポイントは、同期状態に関連する変更のコレクションのクエリをサポートします。 機能は同じですが、メソッドは多少異なります。
Microsoft Graph エンドポイントでは、変更はデルタ クエリを使ってクエリされます。 これは、コレクションに対する delta 関数として実装されます。
Outlook のエンドポイントでは、標準リソース コレクションのクエリにヘッダーを追加することによって変更がクエリされます。
バッチ処理
両方のエンドポイントは、1 つの HTTP 要求に最大 20 の個別の要求をバッチ処理できます。
Microsoft Graph のバッチ処理は、複数の API 要求をコンテンツ タイプ application/json の JSON 本文の中にエンコードします。
また、JSON 本文の形式に加え、Outlook エンドポイントのバッチ処理は、コンテンツ タイプ multipart/mixed のマルチパート本文の形式もサポートします。
例: メッセージの取得
簡単な例を見てみましょう。 このシナリオでは、Web アプリがユーザーの受信トレイにあるメッセージのリストを要求します。
Microsoft Graph
まず、アプリではユーザーのサインインによって、アプリケーションを承認します。 アプリは、Microsoft Graph のスコープ Mail.Read を使用するため、認証 URL は次のようになります。
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+Mail.Read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>
アプリがアクセス トークンを入手すると、アプリから次の要求が送信されます。
GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject,from,receivedDateTime,isRead
Accept: application/json
Authorization: Bearer <token>
サーバーは次の応答を返します。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('b63d5fb9-4f43-44c4-8f9d-fd0727842876')/mailFolders('inbox')/messages(subject,from,receivedDateTime,isRead)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject%2cfrom%2creceivedDateTime%2cisRead&$skip=1",
"value": [
{
"@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
"id": "AAMkAGI2...",
"receivedDateTime": "2015-11-03T03:21:04Z",
"subject": "Scrum",
"isRead": false,
"from": {
"emailAddress": {
"name": "user0TestUser",
"address": "user0@contoso.com"
}
}
}
]
}
Outlook
まず、アプリではユーザーのサインインによって、アプリケーションを承認します。 アプリは、Outlook のスコープ https://outlook.office.com/Mail.Read を使用するため、認証 URL は次のようになります。
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+https%3A%2F%2Foutlook.office.com%2Fmail.read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>
アプリがアクセス トークンを入手すると、アプリから次の要求が送信されます。
GET https://outlook.office.com/api/v2.0/me/mailfolders/inbox/messages?$top=1&$select=Subject,From,ReceivedDateTime,IsRead
Accept: application/json
Authorization: Bearer <token>
サーバーは次の応答を返します。
{
"@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
"@odata.nextLink": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
"value": [
{
"@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
"Id": "AAMkAGI2...",
"ReceivedDateTime": "2015-11-03T03:21:04Z",
"Subject": "Scrum",
"IsRead": false,
"From": {
"EmailAddress": {
"Name": "user0TestUser",
"Address": "user0@contoso.com"
}
}
}
]
}