Outlook REST API (ベータ版) を使用する

  • [アーティクル]

適用対象: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

注意

Microsoft Graph を使用して Outlook を含む Microsoft 365 サービス に、より豊富なシナリオをビルドします。 「Microsoft Graph をベースとした Outlook REST API へ移行する」ための方法を確認します。

Outlook REST API には、Office 365、Hotmail.com、Live.com、MSN.com、Outlook.com、および Passport.com でユーザーのメールボックス データにアクセスするための次のサブセットが含まれています。

以下の表は、各サブセットのコア機能が使用可能となった最初のバージョンを一覧表示しています。 サブセット内では、新機能と API は、それ以降のバージョンに後で追加できることに注意してください。

API サブセット 使用可能なバージョン
複数の API 呼び出しのバッチ処理 v2.0、ベータ版
予定表 API v2.0、v1.0、ベータ版
連絡先 API v2.0、v1.0、ベータ版
データ拡張機能 API v2.0、ベータ版
拡張プロパティ API v2.0、ベータ版
メール API v2.0、v1.0、ベータ版
プッシュ通知 API v2.0、ベータ版
ストリーミング通知 API (プレビュー) ベータ版
People API ベータ版
タスク API v2.0、ベータ版
ユーザー写真 API v2.0、ベータ版

注意

この記事の残りの部分では、Outlook REST API のすべてのサブセットに適用される一般的な情報について説明します。 リファレンスをわかりやすくするため、この記事の残りの部分では Outlook.com を、Hotmail.com、Live.com、MSN.com、Outlook.com、Passport.com などのドメインのアカウントを含めるものとして使用しています。

アプリの登録および認証

Outlook の REST API を使用して、ユーザーのメールボックス データにアクセスするには、アプリの登録とユーザー認証を次のように実行する必要があります。

  1. 最初に、Outlook REST API にアクセスするアプリを登録します。これで、アプリに API 呼び出しを実装することができます。

  2. 実行時に、ユーザーからの承認を取得し、ユーザーのメールボックスにアクセスするための REST API 要求を実行します。

現在、アプリの登録とユーザー認証を処理する方法には次の 2 つがあります。

Azure AD v2 認証エンドポイント

Azure AD v2 認証エンドポイントにより、Microsoft の組織アカウントと個人アカウントの両方で動作するアプリの構築が簡単になります。これを使用すると、職場、教育機関、および個人のアカウント ユーザーは、ボタン 1 つでサインインできるようになります。

この集中型プログラミング モデルは最新の方法で、次の内容で構成されています。

この方法では、シームレスなアプリ登録とユーザー認証エクスペリエンスにより、Office 365 や Outlook.com でユーザーのメールボックスのデータにアクセスするための適切なトークンを取得します。Outlook.com のアプリを開発する場合は、この方法を使用する必要があります。

v2 認証エンドポイントでは、アプリの登録時にアクセス許可を要求する代わりに、実行時に対応するユーザーの操作に基づいて、動的にダイアログを表示し、必要なアクセス許可を要求することができます。

この集中型プログラミング モデルは、いくつかのコンポーネントで構成されているため、1 つのコンポーネントを使用すると、他のものも使用する必要があります。

詳細については、「作業開始の例」および「v2 認証エンドポイントを使用して Office 365 と Outlook.com API を認証する」を参照してください。

重要

アプリを作成または更新する場合、有効になっている Outlook.com のメールボックスをそのアプリが処理できることと、有効になるのを待機しているそれらのメールボックスに Outlook REST API を使用してアクセスできることを確認します。詳しくは、「このような Outlook.com シナリオのテストおよび処理方法」を参照してください。

Azure AD および OAuth を使用した登録と認証

これは、Office 365 のメールボックス データにのみアクセスする場合の以前の方法です。Outlook.com でのデータへのアクセスや、Office 365 向けの新しいアプリの作成を計画している場合、代わりに v2 認証エンドポイントを使用してください。

しばらくの間は、Office 365 のメールボックス データにアクセスする場合、以前のように Azure AD でアプリを登録し、アプリが必要とする適切なスコープのアクセス許可を指定することができます。実行時に、アプリは Azure AD および OAuth を使用して、アプリケーションの要求を引き続き認証することができます。詳細については、「Office 365 アプリ認証の概念」を参照してください。アップグレード パスの計画を立てる必要があります。

この手法を使用すると、Office 365 アプリで直接呼び出すことによって、または Office 365 クライアント ライブラリを使用して、Outlook REST API にアクセスすることができます。

アップグレード パス

v2 認証エンドポイントは、プレビューから Outlook および Outlook.com 開発者向けの一般提供 (GA) 状態に格上げされています。

Office 365 メールボックスのデータにアクセスする運用環境アプリがある場合、または Office 365 または Outlook.com 向けの_新しい_アプリを作成する場合は、v2 認証エンドポイントを最新の Outlook エンドポイント (https://outlook.office.com/、詳細については以下を参照) と一緒に使用して、組織の Office 365 ユーザーと個人の Outlook.com ユーザーの両方に対して 1 つのコード セットだけを利用することを検討してください。

Windows Live API を使用して Outlook.com のメールボックス データにアクセスする運用環境アプリがある場合、v2 認証エンドポイントと Outlook REST API を使用するにはアプリを書き換える必要があります。 Windows Live API は Outlook.com では廃止されており、Outlook.com ユーザーは Outlook REST API 向けにメールボックスを有効にするため、ユーザーがこのような Windows Live API アプリを実行しようとすると HTTP 404 エラーが表示されます。

一方で、Outlook REST API を使用することで、新たな機会がもたらされます。— ユーザーは、Node、Python、Swift、Java などの一般的な言語の一覧から選択し、アプリを 1 回だけで作成でき、Outlook.com と Office 365 の両方のユーザーを Web、iOS、Android、または Windows デバイスでキャプチャすることができます。

注意

運用環境アプリで引き続き Outlook.com メールボックスのデータに_のみ_アクセスする場合は、同じ Windows Live のスコープをそのまま使用して、Outlook REST API のほとんどにアクセスすることができます。 詳細については、「Windows Live のスコープと Outlook REST API を使用して Outlook.com メールボックスのデータにアクセスする」を参照してください。

アプリの登録とユーザー認証で使用する方法や、アプリが Office 365 または Outlook.com メールボックス データのどちらをターゲットにしているかにかかわらず、最新の Outlook REST エンドポイントは運用環境にあるため、REST API 呼び出しでいつでも使用を開始できます。

https://outlook.office.com/api/{version}/{user_context}

次の Outlook REST エンドポイントは、しばらくの間は Office 365 メールボックス データでのみ動作します。

https://outlook.office365.com/api/{version}/{user_context}

サポートされている REST 操作、エンドポイント、バージョンの詳細については、以下を参照してください。

重要

  • Outlook REST API エンドポイント https://outlook.office.com では、基本認証はサポートされなくなりました。新しい Outlook REST API エンドポイントを使用するアプリの認証および承認を行う場合は、v2 認証エンドポイントまたは Azure AD を使用してください。
  • 新しい Outlook REST エンドポイントを使用する場合に最適なパフォーマンスを得るには、要求ごとに x-AnchorMailbox ヘッダーを追加し、それをユーザーの電子メール アドレスに設定します。例: x-AnchorMailbox:john@contoso.com
  • Outlook REST API での Outlook.com のメールボックスの有効化は一定期間行われるため、既存の Outlook.com アカウントを有効にするには時間がかかる場合があります。 既に有効になっている Outlook.com メールボックスのデータにアクセスするアプリをテストする場合、outlookdev@microsoft.com に電子メールを送信することによって、新しい有効な Outlook.com 開発者プレビュー アカウントを要求できます。
  • アプリが Outlook.com メールボックス データにアクセスする場合は、ユーザーのメールボックスが Outlook REST API でまだ有効になっていないシナリオを処理する必要があります。このような状況で REST 要求を行うと、次のようなエラーが発生します。
    • HTTP エラー:404
    • エラー コード:MailboxNotEnabledForRESTAPI または MailboxNotSupportedForRESTAPI
    • エラー メッセージ:"REST API はこのメールボックスでまだサポートされていません。
  • v2 認証エンドポイントを使用するコード サンプルについては、dev.outlook.com を参照してください。

Windows Live のスコープと Outlook REST API を使用して Outlook.com メールボックスのデータにアクセスする

Outlook.com の運用環境アプリで Windows Live のスコープを使用し、Office 365 メールボックスのデータを対象にしない場合は、ほとんどの Outlook REST API でこれらの Windows Live のスコープをそのまま使用することができます。次の表は、Windows Live のスコープが Outlook REST API スコープをマップする方法を示しています。Mail.Read 用の Windows Live のスコープの直接マッピングは存在しないことに注意してください。アプリは wl.imap を使用して、Mail.Read を必要とするこれらの Outlook REST API 操作にアクセスすることができます。

Windows Live のスコープ Outlook REST API のスコープ
wl.basic User.Read, Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.ReadWrite, Mail.Send

サポートされている REST 処理およびエンドポイント

Outlook REST API を操作するには、サポートされているメソッド (GET、POST、PATCH、または DELETE) を使用する HTTP 要求を送信します。POST と PATCH 要求の本文とサーバー応答は、JSON ペイロードで送信されます。

パス URL リソース名とクエリ パラメーターは、大文字と小文字が区別されません。ただし、割り当てた値、エンティティ ID、その他の base64 でエンコードされた値では大文字と小文字を区別します。

すべての Outlook REST API 要求で次の新しいルート URL 形式を使用します。

https://outlook.office.com/api/{version}/{user_context}

適切なユーザー認証を使用した場合、このルート URL の REST API は、Office 365 および Outlook.com のメールボックス データへのアクセスを提供します。この記事の残りの部分では、このエンドポイントの REST API について説明します。

既存のルート URL https://outlook.office365.com/api/{version}/{user_context} を使用するコードがある場合、コードはしばらくの間は Office 365 でそのまま機能しますが、新しいルート URL への切り替えを検討する必要があります。

重要

最適なパフォーマンスを得るために、新しいルート URL を使用して REST 要求を行う場合は、x-AnchorMailbox ヘッダーを追加し、それをユーザーの電子メール アドレスに設定します。 また、Outlook.com ユーザーのメールボックスが Outlook REST API でまだ有効になっていない状況であれば、対応します。エラー コード MailboxNotEnabledForRESTAPI と MailboxNotSupportedForRESTAPI を確認してください。 詳細については、こちらを参照してください。

中国の開発者用のメモ

サポートされる API のバージョン

{version} は、指定したルート URL の Outlook REST API のバージョンを表します。次のいずれかの値を指定できます。

  • v1.0。 これは、一般提供 (GA) の状態で最も初期のバージョンであり、運用コードで使用できます。 URL の例は、http://outlook.office.com/api/v1.0/me/events です。

  • v2.0。 このバージョンも一般提供 (GA) 状態で、運用コードで使用できます。 URL の例は、http://outlook.office.com/api/v2.0/me/events です。 このバージョンには、v1.0 がそのまま使用できなくなる可能性のある変更と、完成してプレビューから一般提供 (GA) 状態に格上げされた追加の API セットが含まれています。

  • ベータ版。 このバージョンはプレビュー状態であるため、運用コードでは使用しないでください。 URL の例は、http://outlook.office.com/api/beta/me/events です。 このバージョンには、GA 段階の最新の API と、プレビュー段階の追加 API セットが含まれており、最終処理までに変更される場合があります。

ほとんどの Outlook REST API の REST 操作のはサポートされており、上に一覧表示されているバージョンと同様の方法で動作します。

ターゲット ユーザー

Outlook REST API 要求は常に現在のユーザーに代わって実行されますが、ユーザー写真 REST API を除いて、{user_context} は現在サインインしているユーザーになります。

ユーザー写真 REST API では、{user_context} はサインインしているユーザー、またはユーザー ID で指定されているユーザーになります。

Outlook REST API のセットにかかわらず、REST _要求_で {user_context} を次のいずれかの方法で指定できます。

  • ショートカットを使用する (例: /api/{version}/me)。ルート URL は https://outlook.office.com/api/{version}/me になります。me

  • サインイン ユーザーの UPN またはプロキシ アドレスを渡す users/{upn} 形式を使用する (例: /api/beta/users/sadie@contoso.com)。この例では、ルート URL は https://outlook.office.com/api/beta/users/sadie@contoso.com になります。

  • ユーザー ID および Azure Active Directory のテナント ID を使用して、users/{AAD_userId@AAD_tenandId} 形式を使用する。例: users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77。ルート URL は https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77 になります。

どちらを使用するかは好みの問題です。

サーバーの_応答_では、ユーザー コンテキストは users/{AAD_userId@AAD_tenandId} の形式で識別されます。

コレクション内のアイテムへのアクセス

Outlook REST API は、エンティティ コレクションにアイテムを指定する 2 つの方法をサポートします。いずれも同様に評価されるため、使用は好みの問題です。

  • コレクション後の URL セグメント (例: /api/{version}/me/events/AAMkAGI3...) /api/{version}/me/events/AAMkAGI3...

  • 引用された文字列として括弧で囲む (例: /api/{version}/me/events('AAMkAGI3...')

クライアント ライブラリを使用した Outlook REST API へのアクセス

Office 365 の API クライアント ライブラリにより、REST API とより容易に対話できるようになります。

認証トークンを管理し、Office 365 のデータを照会、使用するのに必要なコードを簡略化するのに役立ちます。

以前のプレビュー エンドポイントの終了

既に https://outlook.office.com/api または https://outlook.office365.com/api をルート URL として使用し、
Outlook REST API にアクセスしている場合、この廃止による影響はありません。それ以前のプレビュー エンドポイント https://outlook.office365.com/ews/odata をまだ使用している場合はこのまま読み進めてください。

Outlook REST API は、2014 年 10 月に、初回プレビューから v1.0 の一般提供に移行しました。 この移行を完了するため、2015 年 10 月 15 日に、従来のプレビュー エンドポイント https://outlook.office365.com/ews/odata を終了しました。

従来のエンドポイント https://outlook.office365.com/ews/odata を使用しているアプリとサービスを、2015 年 10 月 15 日までに https://outlook.office.com/api/v1.0 に移行するように要請しました。 v1.0 は、その日付までに移行する必要のある最小限の一般提供 (GA) エンドポイントでした。

代わりに、優先 GA エンドポイント v2.0 (https://outlook.office.com/api/v2.0)、またはプレビュー エンドポイント (https://outlook.office.com/api/beta) を使用して、最新の API のプレビュー状態を試すこともできます。通常、プレビュー状態の API は最終処理までに変更される場合があることに注意してください。それらを使用する場合は、アプリの機能を確認し、適切な変更を加えられるようにしておいてください。プレビュー状態の API が最終処理されると、これらの機能強化に GA エンドポイントからもアクセスすることができます。

次の手順

Outlook REST API の使用に進みます。