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

Outlook REST API v2.0 エンドポイントは非推奨です。 新しいアドインの開発には、代わりに Microsoft Graph REST API を使用してください。 この記事では、まだ Microsoft Graph に移行していない既存のアドインの 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 がアドインに必要です。 これは itemId プロパティ (MessageRead、 AppointmentRead) から取得されますが、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 を呼び出して現在のメッセージを取得します。

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 アドインから Microsoft Graph REST API を使用する
• Outlook アドインでの認証と承認
• 入れ子になったアプリの認証を使用して Office アドインで SSO を有効にする