Outlook の REST API (バージョン 1.0) を使用する

  • [アーティクル]

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

注意

Outlook REST API のバージョン 1.0 は廃止されます。 ** 2018 年 11 月 1 日** 以降、アプリは v1.0 REST エンドポイントで基本認証を使用することができなくなります。 2019 年 11 月 1 日までに、v1.0 REST エンドポイントは完全に使用停止になり、v1.0 のドキュメントはその後間もなく削除されます。 Microsoft Graph v1.0 で 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 を使用するにはアプリを書き換える必要があります。 Outlook.com の Windows Live API は廃止されており、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/v1.0/users/sadie@contoso.com)。この例では、ルート URL は https://outlook.office.com/api/v1.0/users/sadie@contoso.com になります。

どちらを使用するかは好みの問題です。サーバーの応答では、ユーザー コンテキストは /api/v1.0/users('sadie@contoso.com') の形式で識別されます。 /api/v1.0/users('sadie@contoso.com')

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

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 を終了しました。

2015 年 10 月 15 日までに、従来のエンドポイントhttps://outlook.office365.com/ews/odataを使用して、すべてのアプリとサービスを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 の使用に進みます。