Outlook アドインからの Outlook REST API の使用

2025-04-23

Office.context.mailbox.item 名前空間を使用すると、メッセージと予定の多くの一般的なフィールドにアクセスできます。ただし、一部のシナリオでは、アドインが名前空間によって公開されていないデータにアクセスする必要がある場合があります。たとえば、アドインは外部アプリによって設定されたカスタムプロパティに依存している場合や、ユーザーのメールボックスで同じ送信者からのメッセージを検索する必要があります。これらのシナリオでは、 Outlook REST API を使用して情報を取得することをお勧めします。

重要

Outlook REST v2.0 とベータエンドポイントは非推奨です

Outlook REST v2.0 とベータエンドポイントは非推奨になりました。ただし、非公開でリリースされたアドインと AppSource ホスト型アドインは、 2025 年 10 月 14 日に Outlook 2019 の延長サポートが終了するまで、REST サービスを引き続き使用できます。これらのアドインからのトラフィックは、除外対象として自動的に識別されます。この除外は、2024 年 3 月 31 日以降に開発された新しいアドインにも適用されます。

アドインは 2025 年 10 月まで REST サービスを使用できますが、 Microsoft Graph を使用するようにアドインを移行することを強くお勧めします。

アクセストークンを取得する

重要

従来の Exchange トークンは非推奨です。レガシ Exchange ユーザー ID とコールバックトークンは、ほとんどのExchange Onlineテナントでオフになっています。管理者は、2025 年 6 月までテナントとアドインのレガシトークンを再び有効にすることができます。 2025 年 10 月には、すべてのテナントに対してレガシトークンが完全にオフになります。タイムラインと詳細については、FAQ ページを参照してください。これは、現在の脅威の状況に対応するために必要なツールを組織に提供する、Microsoft の Secure Future Initiative の一部です。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。入れ子になったアプリ認証は、今後のトークンに推奨される方法です。

Outlook REST API では、Authorization ヘッダーにベアラートークンが必要です。通常、アプリは OAuth2 フローを使用してトークンを取得します。ただし、アドインは、メールボックス要件セット 1.5 で導入された新しい Office.context.mailbox.getCallbackTokenAsync メソッドを使用して、OAuth2 を実装せずにトークンを取得できます。

isRest オプションを true に設定することにより、REST API と互換性があるトークンを要求できます。

アドインのアクセス許可とトークンの範囲

REST API を経由してアドインが必要とするアクセスのレベルを考慮することが重要です。ほとんどの場合、getCallbackTokenAsync によって返されるトークンは、現在の項目への読み取り専用のアクセスのみを提供します。これは、アドインがマニフェストでアイテムの読み取り/書き込みアクセス許可レベルを指定している場合でも当てはまります。

アドインで現在のアイテムまたはユーザーのメールボックス内の他のアイテムへの書き込みアクセス権が必要な場合は、アドインでメールボックスの読み取り/書き込みアクセス許可を指定する必要があります。そのマニフェストのレベル。その場合、返されるトークンに、ユーザーのメッセージ、イベント、および連絡先に対する読み取り/書き込みアクセス権限が含まれます。

例

Office.context.mailbox.getCallbackTokenAsync({isRest: true}, function(result){
  if (result.status === "succeeded") {
    const accessToken = result.value;

    // Use the access token.
    getCurrentItem(accessToken);
  } else {
    // Handle the error.
  }
});

項目 ID を取得する

REST を経由して現在の項目を取得するには、REST 用に正しく書式設定された項目の ID がアドインに必要です。これは Office.context.mailbox.item.itemId プロパティから取得されますが、REST 用に書式設定された ID であることを確認するためのいくつかの確認が必要です。

モバイルデバイスの Outlook では、 Office.context.mailbox.item.itemId によって返される値は REST 形式の ID であり、そのまま使用できます。
その他の Outlook クライアントの場合、Office.context.mailbox.item.itemId によって返される値が EWS 用に設定された ID であり、Office.context.mailbox.convertToRestId メソッドを使用して変換する必要があります。
また、これを使用するには、Attachment ID を REST 用に形式設定された ID に変換する必要もあります。 ID を変換する必要がある理由は、EWS ID に URL セーフ以外の値が含まれている可能性があり、その場合は REST で問題が発生するためです。

Office.context.mailbox.diagnostics.hostName プロパティを確認することにより、アドインは読み込まれる Outlook クライアントを判別できます。

例

function getItemRestId() {
  if (Office.context.mailbox.diagnostics.hostName === 'OutlookIOS') {
    // itemId is already REST-formatted.
    return Office.context.mailbox.item.itemId;
  } else {
    // Convert to an item ID for API v2.0.
    return Office.context.mailbox.convertToRestId(
      Office.context.mailbox.item.itemId,
      Office.MailboxEnums.RestVersion.v2_0
    );
  }
}

REST API URL を取得する

REST API を呼び出すためにアドインで必要な情報の最終部分は、API 要求の送信に使用するホスト名です。この情報は Office.context.mailbox.restUrl プロパティにあります。

例

// Example: https://outlook.office.com
const restHost = Office.context.mailbox.restUrl;

API を呼び出す

アドインがアクセストークン、アイテム ID、および REST API URL を取得すると、REST API を呼び出すバックエンドサービスにその情報を渡すか、AJAX を使用して直接呼び出すことができるようになります。次の例は、Outlook Mail REST API を呼び出して現在のメッセージを取得します。

重要

オンプレミスの Exchange 展開の場合、AJAX または同様のライブラリを使用するクライアント側の要求は失敗します。CORS はそのサーバーのセットアップでサポートされていないためです。

function getCurrentItem(accessToken) {
  // Get the item's REST ID.
  const itemId = getItemRestId();

  // Construct the REST URL to the current item.
  // Details for formatting the URL can be found at
  // https://learn.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#get-messages.
  const getMessageUrl = Office.context.mailbox.restUrl +
    '/v2.0/me/messages/' + itemId;

  $.ajax({
    url: getMessageUrl,
    dataType: 'json',
    headers: { 'Authorization': 'Bearer ' + accessToken }
  }).done(function(item){
    // Message is passed in `item`.
    const subject = item.Subject;
    ...
  }).fail(function(error){
    // Handle error.
  });
}

次の方法で共有

Outlook アドインからの Outlook REST API の使用

アクセス トークンを取得する

アドインのアクセス許可とトークンの範囲

例

項目 ID を取得する

例

REST API URL を取得する

例

API を呼び出す

関連項目

その他のリソース

アクセストークンを取得する