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

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

重要

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

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

アドインは 2025 年まで REST サービスを使用できますが、 Microsoft Graph を使用するようにアドインを移行することを強くお勧めします。 ガイダンスについては、「 Microsoft Graph と Outlook REST API エンドポイントの比較」を参照してください。

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

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 アドインから REST API を呼び出す例については、GitHub の command-demo をご覧ください。
• Outlook REST API は、Microsoft Graph エンドポイントからでも利用できますが、アドインでアクセス トークンを取得する方法など、重要な違いがいくつかあります。 詳細については、「Microsoft Graph を介して使用する Outlook REST API」を参照してください。