次の方法で共有

Office.Mailbox interface

  • リファレンス
パッケージ:
outlook

Microsoft Outlook アドイン オブジェクト モデルへのアクセスを提供します。

主なプロパティ:

  • diagnostics : Outlook アドインに診断情報を提供します。

  • item : Outlook アドインでメッセージまたは予定にアクセスするためのメソッドとプロパティを提供します。

  • userProfile : Outlook アドインのユーザーに関する情報を提供します。

注釈

最小アクセス許可レベル: 制限

適用できる Outlook モード: Composeまたは読み取り

例

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

プロパティ

diagnostics

Outlook アドインに診断情報を提供します。

次のメンバーが含まれます。

  • hostName (string): Office アプリケーションの名前を表す文字列。 値はOutlookOutlookWebAppOutlookIOSnewOutlookWindows、または OutlookAndroidのいずれかである必要があります。 注: Outlook on Windows (クラシック) と Mac では、"Outlook" の値が返されます。

  • hostVersion(string): Office アプリケーションまたはExchange Serverのバージョンを表す文字列 (例: "15.0.468.0")。 メール アドインが Outlook on Windows (クラシック)、Mac、またはモバイル デバイスで実行されている場合、プロパティは hostVersion Outlook クライアントのバージョンを返します。 Outlook on the webおよび新しい Outlook on Windows では、プロパティはExchange Serverのバージョンを返します。

  • OWAView(MailboxEnums.OWAView または string): Outlook on the webの現在のビューを表す列挙型 (または文字列リテラル)。 アプリケーションがOutlook on the webされていない場合、このプロパティにアクセスすると未定義になります。 Outlook on the webには、画面の幅とThreeColumnsウィンドウに対応する 3 つのビュー (OneColumn画面が狭い場合に表示され、 TwoColumns 画面が広い場合に表示されます)、および表示できる列の数があります。

詳細については、「 Office.Diagnostics」を参照してください。
ewsUrl

Gets the URL of the Exchange Web Services (EWS) endpoint for this email account.
item

メールボックスアイテム。 アドインを開いたコンテキストによっては、項目の種類が異なる場合があります。 特定の種類またはモードについてのみ IntelliSense を表示する場合は、この項目を次のいずれかにキャストします。

MessageCompose、 MessageRead、 AppointmentCompose、 AppointmentRead

重要:

  • メッセージを呼び出すとき Office.context.mailbox.item は、Outlook クライアントの閲覧ウィンドウを有効にする必要があることに注意してください。 閲覧ウィンドウを構成する方法のガイダンスについては、「閲覧ウィンドウを 使用してメッセージをプレビューするように構成する」を参照してください。

  • item アドインが作業ウィンドウのピン留めをサポートしている場合は null にすることができます。 処理方法の詳細については、「Outlook でピン留め可能な作業ウィンドウを実装する」を参照してください。
restUrl

この電子メール アカウントの REST エンドポイントの URL を取得します。
userProfile

メールボックスに関連付けられているユーザーに関する情報。 これには、アカウントの種類、表示名、電子メール アドレス、タイム ゾーンが含まれます。

詳細については、「Office.UserProfile」を参照してください。

メソッド

addHandlerAsync(eventType, handler, options, callback)

サポートされているイベントのイベント ハンドラーを追加します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。
addHandlerAsync(eventType, handler, callback)

サポートされているイベントのイベント ハンドラーを追加します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。
convertToEwsId(id, restVersion)

サポートされている ID を Exchange Web Services (EWS) 形式に変換します。
convertToLocalClientTime(timeValue)

クライアントのローカル時間で時間情報が含まれている辞書を取得します。

Outlook クライアントで使用されるタイム ゾーンは、プラットフォームによって異なります。 Outlook on Windows (クラシック) と Mac では、クライアント コンピューターのタイム ゾーンを使用します。 Outlook on the webおよび新しい Outlook on Windows では、Exchange 管理 センター (EAC) で設定されたタイム ゾーンが使用されます。 ユーザー インターフェイスに表示する値が、ユーザーが予期するタイム ゾーンと常に一致するように、日付と時刻の値を処理する必要があります。

Outlook on Windows (クラシック) と Mac では、 メソッドは convertToLocalClientTime 、クライアント コンピューターのタイム ゾーンに設定された値を持つディクショナリ オブジェクトを返します。 Outlook on the webおよび新しい Outlook on Windows では、 メソッドはconvertToLocalClientTime、値が EAC で指定されたタイム ゾーンに設定されたディクショナリ オブジェクトを返します。
convertToRestId(id, restVersion)

サポートされている ID を REST 形式に変換します。
convertToUtcClientTime(input)

時間情報を Date 含むディクショナリからオブジェクトを取得します。

メソッドは convertToUtcClientTime 、ローカルの日付と時刻を含むディクショナリを、 Date ローカルの日付と時刻の正しい値を持つオブジェクトに変換します。
displayAppointmentForm(itemId)

既存の予定を表示します。

メソッドは displayAppointmentForm 、デスクトップ上の新しいウィンドウで既存の予定表の予定を開きます。

Outlook on Mac では、この方法を使用して、定期的な系列の一部ではない 1 つの予定、または定期的な系列のマスター予定を表示できます。 ただし、定期的な系列のインスタンスのプロパティ (項目 ID を含む) にアクセスできないため、系列のインスタンスを表示することはできません。

Outlook on the webおよび新しい Outlook on Windows では、フォームの本文が 32,000 文字以下の場合にのみ、指定したフォームが開きます。

指定したアイテム識別子が既存の予定を識別しない場合、クライアント コンピューターまたはデバイスで空白のウィンドウが開き、エラー メッセージは返されません。
displayMessageForm(itemId)

既存のメッセージを表示します。

メソッドは displayMessageForm 、デスクトップ上の新しいウィンドウで既存のメッセージを開きます。

Outlook on the webおよび新しい Outlook on Windows では、フォームの本文が 32,000 文字以下の場合にのみ、指定したフォームが開きます。

指定した項目識別子が既存のメッセージを識別しない場合、クライアント コンピューターにメッセージは表示されません。エラー メッセージは返されません。
displayNewAppointmentForm(parameters)

新しい予定を作成するためのフォームを表示します。

displayNewAppointmentForm メソッドを使用すると、ユーザーが新しい予定または会議を作成できるフォームが開きます。 パラメーターを指定すると、予定のフォーム フィールドにパラメーターの内容が自動的に設定されます。

Outlook on the webおよび新しい Outlook on Windows では、このメソッドは常に出席者フィールドを含むフォームを表示します。 入力引数として出席者を指定しない場合、メソッドは [保存] ボタンを含むフォームを表示します。 出席者を指定した場合には、フォームにその出席者と [送信] ボタンが表示されます。

Outlook on Windows (クラシック) および Mac では、または resources パラメーターで出席者またはリソースをrequiredAttendeesoptionalAttendees指定した場合、このメソッドは [送信] ボタンを含む会議フォームを表示します。 受信者を指定せずにこのメソッドを実行すると、[保存して閉じる] ボタンがある予定フォームが表示されます。

パラメータのいずれかが指定されたサイズ制限を超えた場合、または不明なパラメータ名が指定された場合には、例外がスローされます。
displayNewMessageForm(parameters)

新しいメッセージを作成するためのフォームを表示します。

displayNewMessageForm メソッドは、ユーザーが新しいメッセージを作成できるフォームを開きます。 パラメータを指定すると、メッセージ フォーム フィールドにはパラメータのコンテンツが自動的に入力されます。

パラメータのいずれかが指定されたサイズ制限を超えた場合、または不明なパラメータ名が指定された場合には、例外がスローされます。
getCallbackTokenAsync(options, callback)

REST API または Exchange Web Services (EWS) の呼び出しに使用されるトークンを含む文字列を取得します。

getCallbackTokenAsync メソッドは、ユーザーのメールボックスをホストする Exchange Server から不透明なトークンを取得する非同期の呼び出しを行います。 コールバック トークンの有効期間は 5 分です。

トークンは、 プロパティの asyncResult.value 文字列として返されます。
getCallbackTokenAsync(callback, userContext)

Exchange Server から添付ファイルやアイテムを取得するために使用するトークンを含む文字列を取得します。

getCallbackTokenAsync メソッドは、ユーザーのメールボックスをホストする Exchange Server から不透明なトークンを取得する非同期の呼び出しを行います。 コールバック トークンの有効期間は 5 分です。

トークンは、 プロパティの asyncResult.value 文字列として返されます。
getUserIdentityTokenAsync(callback, userContext)

ユーザーと Office アドインを識別するトークンを取得します。

トークンは、 プロパティの asyncResult.value 文字列として返されます。
makeEwsRequestAsync(data, callback, userContext)

ユーザーのメールボックスをホストする Exchange サーバー上の Exchange Web サービス (EWS) サービスに対して非同期要求を行います。

makeEwsRequestAsync メソッドは、アドインの代わりに Exchange に EWS 要求を送信します。
removeHandlerAsync(eventType, options, callback)

サポートされているイベントの種類のイベント ハンドラーを削除します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。
removeHandlerAsync(eventType, callback)

サポートされているイベントの種類のイベント ハンドラーを削除します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。

プロパティの詳細

diagnostics

Outlook アドインに診断情報を提供します。

次のメンバーが含まれます。

  • hostName (string): Office アプリケーションの名前を表す文字列。 値はOutlookOutlookWebAppOutlookIOSnewOutlookWindows、または OutlookAndroidのいずれかである必要があります。 注: Outlook on Windows (クラシック) と Mac では、"Outlook" の値が返されます。

  • hostVersion(string): Office アプリケーションまたはExchange Serverのバージョンを表す文字列 (例: "15.0.468.0")。 メール アドインが Outlook on Windows (クラシック)、Mac、またはモバイル デバイスで実行されている場合、プロパティは hostVersion Outlook クライアントのバージョンを返します。 Outlook on the webおよび新しい Outlook on Windows では、プロパティはExchange Serverのバージョンを返します。

  • OWAView(MailboxEnums.OWAView または string): Outlook on the webの現在のビューを表す列挙型 (または文字列リテラル)。 アプリケーションがOutlook on the webされていない場合、このプロパティにアクセスすると未定義になります。 Outlook on the webには、画面の幅とThreeColumnsウィンドウに対応する 3 つのビュー (OneColumn画面が狭い場合に表示され、 TwoColumns 画面が広い場合に表示されます)、および表示できる列の数があります。

詳細については、「 Office.Diagnostics」を参照してください。

diagnostics: Diagnostics;

プロパティ値

Office.Diagnostics

注釈

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

メールボックス要件セット 1.5 以降では、Office.context.診断 プロパティを使用して同様の情報を取得することもできます。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-diagnostic-information.yaml

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

ewsUrl

Gets the URL of the Exchange Web Services (EWS) endpoint for this email account.

ewsUrl: string;

プロパティ値

string

注釈

[ API セット: メールボックス 1.1 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

重要:

  • 読 み取り モードでメンバーを呼び出すには、アプリのマニフェストで読み取り項目のアクセス許可が ewsUrl 指定されている必要があります。

  • 新規作成モードでは、メンバーを使用する前に saveAsync メソッドを呼び出す ewsUrl 必要があります。 メソッドを呼び出すには、アプリに アイテムの読み取り/書き込み アクセス許可が saveAsync 必要です。

  • このプロパティは、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

  • The ewsUrl value can be used by a remote service to make EWS calls to the user's mailbox. たとえば、リモート サービスを作成して、 選択した項目から添付ファイルを取得できます。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

item

メールボックスアイテム。 アドインを開いたコンテキストによっては、項目の種類が異なる場合があります。 特定の種類またはモードについてのみ IntelliSense を表示する場合は、この項目を次のいずれかにキャストします。

MessageCompose、 MessageRead、 AppointmentCompose、 AppointmentRead

重要:

  • メッセージを呼び出すとき Office.context.mailbox.item は、Outlook クライアントの閲覧ウィンドウを有効にする必要があることに注意してください。 閲覧ウィンドウを構成する方法のガイダンスについては、「閲覧ウィンドウを 使用してメッセージをプレビューするように構成する」を参照してください。

  • item アドインが作業ウィンドウのピン留めをサポートしている場合は null にすることができます。 処理方法の詳細については、「Outlook でピン留め可能な作業ウィンドウを実装する」を参照してください。

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

プロパティ値

Office.Item & Office.ItemCompose & Office.ItemRead & Office.Message & Office.MessageCompose & Office.MessageRead & Office.Appointment & Office.AppointmentCompose & Office.AppointmentRead

restUrl

この電子メール アカウントの REST エンドポイントの URL を取得します。

restUrl: string;

プロパティ値

string

注釈

[ API セット: メールボックス 1.5 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

重要:

  • Outlook REST v2.0 とベータ エンドポイントは非推奨になりました。 ただし、非公開でリリースされたアドインと AppSource ホスト型アドインは、2025 年 10 月 14 日に Outlook 2019 の延長サポートが終了するまで REST サービスを使用できます。 これらのアドインからのトラフィックは、除外対象として自動的に識別されます。 この除外は、2024 年 3 月 31 日以降に開発された新しいアドインにも適用されます。 アドインは 2025 年まで REST サービスを使用できますが、 Microsoft Graph を使用するようにアドインを移行することを強くお勧めします。 ガイダンスについては、「 Microsoft Graph と Outlook REST API エンドポイントの比較」を参照してください。

  • メンバーを 読み取り モードで呼び出すには、アドインのマニフェストで読み取り項目のアクセス許可が restUrl 指定されている必要があります。

  • In compose mode you must call the saveAsync method before you can use the restUrl member. メソッドを呼び出すには、アドインに アイテムの読み取り/書き込み アクセス許可が saveAsync 必要です。 ただし、デリゲートまたは共有のシナリオでは、代わりに SharedProperties オブジェクトのプロパティを使用targetRestUrlする必要があります (要件セット 1.8 で導入)。 詳細については、 共有フォルダーと共有メールボックス に関する記事を参照してください。

例

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

userProfile

メールボックスに関連付けられているユーザーに関する情報。 これには、アカウントの種類、表示名、電子メール アドレス、タイム ゾーンが含まれます。

詳細については、「Office.UserProfile」を参照してください。

userProfile: UserProfile;

プロパティ値

Office.UserProfile

メソッドの詳細

addHandlerAsync(eventType, handler, options, callback)

サポートされているイベントのイベント ハンドラーを追加します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

eventType

Office.EventType | string

ハンドラーを呼び出す必要のあるイベント。

handler

any

イベントを処理する関数。 関数は、オブジェクト リテラルである単一パラメーターを受け入れる必要があります。 パラメーターの プロパティはtype、 に渡されるaddHandlerAsyncパラメーターとeventType一致します。

options
Office.AsyncContextOptions

コールバックで使用するために、任意の型のコンテキスト データを変更せずに保持するためのオプションを提供します。

callback

(asyncResult: Office.AsyncResult<void>) => void

省略可能。 メソッドが完了すると、 パラメーターで callback 渡された関数が、 型 Office.AsyncResultの 1 つのパラメーターで呼び出されます。

戻り値

void

注釈

[ API セット: メールボックス 1.5 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

例

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

サポートされているイベントのイベント ハンドラーを追加します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

eventType

Office.EventType | string

ハンドラーを呼び出す必要のあるイベント。

handler

any

イベントを処理する関数。 関数は、オブジェクト リテラルである単一パラメーターを受け入れる必要があります。 パラメーターの プロパティはtype、 に渡されるaddHandlerAsyncパラメーターとeventType一致します。

callback

(asyncResult: Office.AsyncResult<void>) => void

省略可能。 メソッドが完了すると、 パラメーターで callback 渡された関数が、 型 Office.AsyncResultの 1 つのパラメーターで呼び出されます。

戻り値

void

注釈

[ API セット: メールボックス 1.5 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

convertToEwsId(id, restVersion)

サポートされている ID を Exchange Web Services (EWS) 形式に変換します。

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

パラメーター

id

string

EWS 形式に変換する ID。 この文字列には、Outlook REST API 用に書式設定されたアイテム ID、または から Office.context.mailbox.item.conversationId取得した会話 ID を指定できます。

restVersion

Office.MailboxEnums.RestVersion | string

アイテム ID の取得に使用された Outlook REST API のバージョンを示す値。

戻り値

string

注釈

[ API セット: メールボックス 1.3 ]

最小アクセス許可レベル: 制限

適用できる Outlook モード: Composeまたは読み取り

重要:

  • 2024 年 10 月には、すべてのExchange Online テナントに対して、従来の Exchange ユーザー ID とコールバック トークンが既定でオフになります。 これは、現在の脅威の状況に対応するために必要なツールを組織に提供する 、Microsoft の Secure Future Initiative の一部です。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。 入れ子になったアプリ認証は、今後のトークンに推奨される方法です。 詳細については、 ブログ投稿 と FAQ ページを参照してください。

  • このメソッドは、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

  • REST API ( Microsoft Graph など) を介して取得されたアイテム ID は、EWS で使用される形式とは異なる形式を使用します。 メソッドは、REST 形式の ID を EWS 用の適切な形式に変換します。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

クライアントのローカル時間で時間情報が含まれている辞書を取得します。

Outlook クライアントで使用されるタイム ゾーンは、プラットフォームによって異なります。 Outlook on Windows (クラシック) と Mac では、クライアント コンピューターのタイム ゾーンを使用します。 Outlook on the webおよび新しい Outlook on Windows では、Exchange 管理 センター (EAC) で設定されたタイム ゾーンが使用されます。 ユーザー インターフェイスに表示する値が、ユーザーが予期するタイム ゾーンと常に一致するように、日付と時刻の値を処理する必要があります。

Outlook on Windows (クラシック) と Mac では、 メソッドは convertToLocalClientTime 、クライアント コンピューターのタイム ゾーンに設定された値を持つディクショナリ オブジェクトを返します。 Outlook on the webおよび新しい Outlook on Windows では、 メソッドはconvertToLocalClientTime、値が EAC で指定されたタイム ゾーンに設定されたディクショナリ オブジェクトを返します。

convertToLocalClientTime(timeValue: Date): LocalClientTime;

パラメーター

timeValue

Date

Date オブジェクト。

戻り値

Office.LocalClientTime

注釈

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

convertToRestId(id, restVersion)

サポートされている ID を REST 形式に変換します。

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

パラメーター

id

string

REST 形式に変換する ID。 この文字列は、通常からOffice.context.mailbox.item.itemId取得される EWS 用に書式設定されたアイテム ID、から取得された会話 ID、または からOffice.context.mailbox.item.conversationIdOffice.context.mailbox.item.seriesId取得された系列 ID を指定できます。

restVersion

Office.MailboxEnums.RestVersion | string

変換された ID で使用される Outlook REST API のバージョンを示す値。

戻り値

string

注釈

[ API セット: メールボックス 1.3 ]

最小アクセス許可レベル: 制限

適用できる Outlook モード: Composeまたは読み取り

重要:

  • このメソッドは、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

  • Exchange Web Services (EWS) またはプロパティを介して itemId 取得されたアイテム ID は、REST API ( Microsoft Graph など) で使用される形式とは異なる形式を使用します。 メソッドは、EWS 形式の ID を REST 用の適切な形式に変換します。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToUtcClientTime(input)

時間情報を Date 含むディクショナリからオブジェクトを取得します。

メソッドは convertToUtcClientTime 、ローカルの日付と時刻を含むディクショナリを、 Date ローカルの日付と時刻の正しい値を持つオブジェクトに変換します。

convertToUtcClientTime(input: LocalClientTime): Date;

パラメーター

input
Office.LocalClientTime

変換するローカル時刻の値。

戻り値

Date

時間が UTC で表現された日付オブジェクト。

注釈

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

例

// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

displayAppointmentForm(itemId)

既存の予定を表示します。

メソッドは displayAppointmentForm 、デスクトップ上の新しいウィンドウで既存の予定表の予定を開きます。

Outlook on Mac では、この方法を使用して、定期的な系列の一部ではない 1 つの予定、または定期的な系列のマスター予定を表示できます。 ただし、定期的な系列のインスタンスのプロパティ (項目 ID を含む) にアクセスできないため、系列のインスタンスを表示することはできません。

Outlook on the webおよび新しい Outlook on Windows では、フォームの本文が 32,000 文字以下の場合にのみ、指定したフォームが開きます。

指定したアイテム識別子が既存の予定を識別しない場合、クライアント コンピューターまたはデバイスで空白のウィンドウが開き、エラー メッセージは返されません。

displayAppointmentForm(itemId: string): void;

パラメーター

itemId

string

既存の予定の Exchange Web サービス (EWS) 識別子。

戻り値

void

注釈

[ API セット: メールボックス 1.1 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

重要: この方法は、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayAppointmentForm(itemId);

displayMessageForm(itemId)

既存のメッセージを表示します。

メソッドは displayMessageForm 、デスクトップ上の新しいウィンドウで既存のメッセージを開きます。

Outlook on the webおよび新しい Outlook on Windows では、フォームの本文が 32,000 文字以下の場合にのみ、指定したフォームが開きます。

指定した項目識別子が既存のメッセージを識別しない場合、クライアント コンピューターにメッセージは表示されません。エラー メッセージは返されません。

displayMessageForm(itemId: string): void;

パラメーター

itemId

string

既存のメッセージの Exchange Web サービス (EWS) 識別子。

戻り値

void

注釈

[ API セット: メールボックス 1.1 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

重要:

  • このメソッドは、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

  • 予定を表す itemId で を displayMessageForm 使用しないでください。 メソッドを使用して既存の displayAppointmentForm 予定を表示し displayNewAppointmentForm 、フォームを表示して新しい予定を作成します。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayMessageForm(itemId);

displayNewAppointmentForm(parameters)

新しい予定を作成するためのフォームを表示します。

displayNewAppointmentForm メソッドを使用すると、ユーザーが新しい予定または会議を作成できるフォームが開きます。 パラメーターを指定すると、予定のフォーム フィールドにパラメーターの内容が自動的に設定されます。

Outlook on the webおよび新しい Outlook on Windows では、このメソッドは常に出席者フィールドを含むフォームを表示します。 入力引数として出席者を指定しない場合、メソッドは [保存] ボタンを含むフォームを表示します。 出席者を指定した場合には、フォームにその出席者と [送信] ボタンが表示されます。

Outlook on Windows (クラシック) および Mac では、または resources パラメーターで出席者またはリソースをrequiredAttendeesoptionalAttendees指定した場合、このメソッドは [送信] ボタンを含む会議フォームを表示します。 受信者を指定せずにこのメソッドを実行すると、[保存して閉じる] ボタンがある予定フォームが表示されます。

パラメータのいずれかが指定されたサイズ制限を超えた場合、または不明なパラメータ名が指定された場合には、例外がスローされます。

displayNewAppointmentForm(parameters: AppointmentForm): void;

パラメーター

parameters
Office.AppointmentForm

AppointmentForm新しい予定を記述する 。 すべてのプロパティは省略可能です。

戻り値

void

注釈

[ API セット: メールボックス 1.1 ]

最小アクセス許可レベル: アイテムの読み取り

適用される Outlook モード: 読み取り

重要: この方法は、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm({
  requiredAttendees: ["bob@contoso.com"],
  optionalAttendees: ["sam@contoso.com"],
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"],
  body: "Hello World!"
});

displayNewMessageForm(parameters)

新しいメッセージを作成するためのフォームを表示します。

displayNewMessageForm メソッドは、ユーザーが新しいメッセージを作成できるフォームを開きます。 パラメータを指定すると、メッセージ フォーム フィールドにはパラメータのコンテンツが自動的に入力されます。

パラメータのいずれかが指定されたサイズ制限を超えた場合、または不明なパラメータ名が指定された場合には、例外がスローされます。

displayNewMessageForm(parameters: any): void;

パラメーター

parameters

any

新しいフォームでユーザーに入力するすべての値を含むディクショナリ。 すべてのパラメーターは省略可能です。

toRecipients : 宛先行の各受信者の電子メール アドレスまたは EmailAddressDetails オブジェクトを含む配列を含む文字列の配列。 配列の上限は 100 エントリです。

ccRecipients : メール アドレスを含む文字列の配列、または Cc 行の各受信者の EmailAddressDetails オブジェクトを含む配列。 配列の上限は 100 エントリです。

bccRecipients : 電子メール アドレスを含む文字列の配列、または Bcc 行の各受信者の EmailAddressDetails オブジェクトを含む配列。 配列の上限は 100 エントリです。

subject : メッセージの件名を含む文字列。 文字列は最大 255 文字に制限されます。

htmlBody : メッセージの HTML 本文。 本文の内容は、最大サイズが 32 KB に制限されます。

attachments : ファイルまたは項目の添付ファイルである JSON オブジェクトの配列。

attachments.type : 添付ファイルの種類を示します。 ファイルの添付ファイルの場合は file、アイテムの添付ファイルの場合は item です。

attachments.name : 添付ファイルの名前を含む文字列(最大 255 文字)。

attachments.url : 添付ファイルの種類が に file設定されている場合にのみ使用されます。 ファイルの場所の URI。 重要: このリンクは、Exchange Online サーバーによる認証を必要とせずに、パブリックにアクセスできる必要があります。 ただし、オンプレミスの Exchange では、追加の認証が必要ない限り、プライベート ネットワークでリンクにアクセスできます。

attachments.isInline : 添付ファイルの種類が に file設定されている場合にのみ使用されます。 true の場合、添付ファイルはメッセージ本文の画像としてインラインで表示され、添付ファイルの一覧には表示されません。

attachments.itemId : 添付ファイルの種類が に item設定されている場合にのみ使用されます。 新しいメッセージに添付する既存の電子メールの EWS アイテム ID。 最大の長さが 100 文字の文字列です。

戻り値

void

注釈

[ API セット: メールボックス 1.6 ]

最小アクセス許可レベル: アイテムの読み取り

適用される Outlook モード: 読み取り

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
  ccRecipients: ["sam@contoso.com"],
  subject: "Outlook add-ins are cool!",
  htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
  attachments: [
    {
      type: "file",
      name: "image.png",
      url: "https://i.imgur.com/9S36xvA.jpg",
      isInline: true
    }
  ]
});

getCallbackTokenAsync(options, callback)

REST API または Exchange Web Services (EWS) の呼び出しに使用されるトークンを含む文字列を取得します。

getCallbackTokenAsync メソッドは、ユーザーのメールボックスをホストする Exchange Server から不透明なトークンを取得する非同期の呼び出しを行います。 コールバック トークンの有効期間は 5 分です。

トークンは、 プロパティの asyncResult.value 文字列として返されます。

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

パラメーター

options

Office.AsyncContextOptions & { isRest?: boolean }

次のプロパティの 1 つ以上を含むオブジェクト リテラル:- isRest: 指定されたトークンを Outlook REST API または Exchange Web サービスに使用するかどうかを決定します。 既定値は です false。 asyncContext : 非同期メソッドに渡される状態データ。

callback

(asyncResult: Office.AsyncResult<string>) => void

メソッドが完了すると、コールバック パラメーターで渡された関数が、 型 Office.AsyncResultの 1 つのパラメーターで呼び出されます。 トークンは、 プロパティの asyncResult.value 文字列として返されます。 エラーが発生した場合、 asyncResult.error および asyncResult.diagnostics のプロパティで追加情報が提供される場合があります。

戻り値

void

注釈

[ API セット: メールボックス 1.5 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

重要:

  • 2024 年 10 月には、すべてのExchange Online テナントに対して、従来の Exchange ユーザー ID とコールバック トークンが既定でオフになります。 これは、現在の脅威の状況に対応するために必要なツールを組織に提供する 、Microsoft の Secure Future Initiative の一部です。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。 入れ子になったアプリ認証は、今後のトークンに推奨される方法です。 詳細については、 ブログ投稿 と FAQ ページを参照してください。

  • Outlook REST v2.0 とベータ エンドポイントは非推奨になりました。 ただし、非公開でリリースされたアドインと AppSource ホスト型アドインは、2025 年 10 月 14 日に Outlook 2019 の延長サポートが終了するまで REST サービスを使用できます。 これらのアドインからのトラフィックは、除外対象として自動的に識別されます。 この除外は、2024 年 3 月 31 日以降に開発された新しいアドインにも適用されます。 アドインは 2025 年まで REST サービスを使用できますが、 Microsoft Graph を使用するようにアドインを移行することを強くお勧めします。 ガイダンスについては、「 Microsoft Graph と Outlook REST API エンドポイントの比較」を参照してください。

  • Outlook.com または Gmail メールボックスにアドインを読み込む場合、このメソッドはサポートされていません。

  • このメソッドは、Outlook on Android と iOS の読み取りモードでのみサポートされます。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

  • EWS 操作は、Outlook on iOS と Android で実行されているアドインではサポートされていません。 が に設定されている場合 options.isRest でも、Outlook モバイル クライアントでは常に falseREST トークンが返されます。

  • 読み取りモードで メソッドを getCallbackTokenAsync 呼び出す場合、 読み取り項目の最小アクセス許可レベルが必要です。

  • 新規作成モードで メソッドを getCallbackTokenAsync 呼び出すには、アイテムを保存する必要があります。 メソッドには saveAsync 、 読み取り/書き込み項目の最小アクセス許可レベルが必要です。

  • 委任または共有シナリオに関するガイダンスについては、 共有フォルダーと共有メールボックス に関する記事を参照してください。

REST トークン

REST トークンが要求されると (options.isRest = true)、結果のトークンは EWS 呼び出しを認証するために機能しません。 アドインがマニフェストでメールボックスの読み取り/書き込みアクセス許可を指定していない限り、トークンは現在のアイテムとその添付ファイルへの 読み取り 専用アクセスのスコープで制限されます。 メールボックスの 読み取り/書き込み アクセス許可が指定されている場合、結果のトークンは、メールの送信機能を含む、メール、予定表、連絡先への読み取り/書き込みアクセスを許可します。

アドインでは、restUrl プロパティを使用して、REST API 呼び出しを行うときに使用する正しい URL を決定する必要があります。

この API は、次のスコープに対して機能します。

  • Mail.ReadWrite

  • Mail.Send

  • Calendars.ReadWrite

  • Contacts.ReadWrite

EWS トークン

EWS トークンが要求されると (options.isRest = false)、結果のトークンは REST API 呼び出しを認証するために機能しません。 トークンの範囲は、現在のアイテムへのアクセスに制限されます。

アドインでは、ewsUrl プロパティを使用して、EWS 呼び出しを行うときに使用する正しい URL を決定する必要があります。

トークンと添付ファイル識別子またはアイテム識別子の両方を外部システムに渡すことができます。 そのシステムでは、トークンをベアラー承認トークンとして使用して、Exchange Web Services (EWS) GetAttachment 操作または GetItem 操作を呼び出して添付ファイルまたはアイテムを返します。 たとえば、リモート サービスを作成して、 選択した項目から添付ファイルを取得できます。

エラー:

  • HTTPRequestFailure : 要求が失敗しました。 HTTP エラーコードの diagnostics オブジェクトを参照してください。

  • InternalServerError : Exchange サーバーからエラーが返されました。 詳細については、diagnostics オブジェクトを参照してください。

  • NetworkError : ユーザーがネットワークに接続されなくなりました。 ネットワーク接続を確認し、やり直してください。

getCallbackTokenAsync(callback, userContext)

Exchange Server から添付ファイルやアイテムを取得するために使用するトークンを含む文字列を取得します。

getCallbackTokenAsync メソッドは、ユーザーのメールボックスをホストする Exchange Server から不透明なトークンを取得する非同期の呼び出しを行います。 コールバック トークンの有効期間は 5 分です。

トークンは、 プロパティの asyncResult.value 文字列として返されます。

getCallbackTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

パラメーター

callback

(asyncResult: Office.AsyncResult<string>) => void

メソッドが完了すると、コールバック パラメーターで渡された関数が、 型 Office.AsyncResultの 1 つのパラメーターで呼び出されます。 トークンは、 プロパティの asyncResult.value 文字列として返されます。 エラーが発生した場合、 asyncResult.error および asyncResult.diagnostics のプロパティで追加情報が提供される場合があります。

userContext

any

省略可能。 非同期メソッドに渡される状態データです。

戻り値

void

注釈

[ API セット: すべてのサポート読み取りモード。メールボックス 1.3 Compose モードのサポートが導入されました ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

重要:

  • 2024 年 10 月には、すべてのExchange Online テナントに対して、従来の Exchange ユーザー ID とコールバック トークンが既定でオフになります。 これは、現在の脅威の状況に対応するために必要なツールを組織に提供する 、Microsoft の Secure Future Initiative の一部です。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。 入れ子になったアプリ認証は、今後のトークンに推奨される方法です。 詳細については、 ブログ投稿 と FAQ ページを参照してください。

  • トークンと添付ファイル識別子またはアイテム識別子の両方を外部システムに渡すことができます。 そのシステムでは、トークンをベアラー承認トークンとして使用して、Exchange Web Services (EWS) GetAttachment または GetItem 操作を呼び出して添付ファイルまたはアイテムを返します。 たとえば、リモート サービスを作成して、 選択した項目から添付ファイルを取得できます。

  • 読み取りモードで メソッドを getCallbackTokenAsync 呼び出す場合、 読み取り項目の最小アクセス許可レベルが必要です。

  • 新規作成モードで メソッドを getCallbackTokenAsync 呼び出すには、アイテムを保存する必要があります。 メソッドには saveAsync 、 読み取り/書き込み項目の最小アクセス許可レベルが必要です。

  • このメソッドは、Outlook on Android または iOS ではサポートされていません。 EWS 操作は、モバイル クライアント上の Outlook で実行されているアドインではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

  • Outlook.com または Gmail メールボックスにアドインを読み込む場合、このメソッドはサポートされていません。

  • 委任または共有シナリオに関するガイダンスについては、 共有フォルダーと共有メールボックス に関する記事を参照してください。

エラー:

  • HTTPRequestFailure : 要求が失敗しました。 HTTP エラーコードの diagnostics オブジェクトを参照してください。

  • InternalServerError : Exchange サーバーからエラーが返されました。 詳細については、diagnostics オブジェクトを参照してください。

  • NetworkError : ユーザーがネットワークに接続されなくなりました。 ネットワーク接続を確認し、やり直してください。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-callback-token.yaml

Office.context.mailbox.getCallbackTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

getUserIdentityTokenAsync(callback, userContext)

ユーザーと Office アドインを識別するトークンを取得します。

トークンは、 プロパティの asyncResult.value 文字列として返されます。

getUserIdentityTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

パラメーター

callback

(asyncResult: Office.AsyncResult<string>) => void

メソッドが完了すると、コールバック パラメーターで渡された関数が、 型 Office.AsyncResultの 1 つのパラメーターで呼び出されます。 トークンは、 プロパティの asyncResult.value 文字列として返されます。 エラーが発生した場合、 asyncResult.error および asyncResult.diagnostics のプロパティで追加情報が提供される場合があります。

userContext

any

省略可能。 非同期メソッドに渡される状態データです。

戻り値

void

注釈

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

重要:

  • 2024 年 10 月には、すべてのExchange Online テナントに対して、従来の Exchange ユーザー ID とコールバック トークンが既定でオフになります。 これは、現在の脅威の状況に対応するために必要なツールを組織に提供する 、Microsoft の Secure Future Initiative の一部です。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。 入れ子になったアプリ認証は、今後のトークンに推奨される方法です。 詳細については、 ブログ投稿 と FAQ ページを参照してください。

  • メソッドは getUserIdentityTokenAsync 、 アドインとユーザーを外部システムで識別および認証するために使用できるトークンを返します。

  • Outlook.com または Gmail メールボックスにアドインを読み込む場合、このメソッドはサポートされていません。

エラー:

  • HTTPRequestFailure : 要求が失敗しました。 HTTP エラーコードの diagnostics オブジェクトを参照してください。

  • InternalServerError : Exchange サーバーからエラーが返されました。 詳細については、diagnostics オブジェクトを参照してください。

  • NetworkError : ユーザーがネットワークに接続されなくなりました。 ネットワーク接続を確認し、やり直してください。

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-identity-token.yaml

Office.context.mailbox.getUserIdentityTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`)
        return;
    }

    console.log(result.value);
});

makeEwsRequestAsync(data, callback, userContext)

ユーザーのメールボックスをホストする Exchange サーバー上の Exchange Web サービス (EWS) サービスに対して非同期要求を行います。

makeEwsRequestAsync メソッドは、アドインの代わりに Exchange に EWS 要求を送信します。

makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

パラメーター

data

any

EWS 要求です。

callback

(asyncResult: Office.AsyncResult<string>) => void

メソッドが完了すると、 パラメーターでcallback渡された関数が、 オブジェクトである 1 つのパラメーターasyncResultOffice.AsyncResultで呼び出されます。 EWS 要求の XML 応答は、 プロパティの asyncResult.value 文字列として提供されます。 Outlook on the web、Windows (新規およびクラシック (バージョン 2303 以降、ビルド 16225.10000)、Mac (バージョン 16.73 (23042601 以降) では、応答のサイズが 5 MB を超えると、エラー メッセージがプロパティにasyncResult.error返されます。 以前のバージョンの Outlook on Windows (クラシック) および Mac では、応答のサイズが 1 MB を超えるとエラー メッセージが返されます。

userContext

any

省略可能。 非同期メソッドに渡される状態データです。

戻り値

void

注釈

[ API セット: メールボックス 1.1 ]

最小アクセス許可レベル: メールボックスの読み取り/書き込み

適用できる Outlook モード: Composeまたは読み取り

重要:

  • 2024 年 10 月には、すべてのExchange Online テナントに対して、従来の Exchange ユーザー ID とコールバック トークンが既定でオフになります。 これは、現在の脅威の状況に対応するために必要なツールを組織に提供する 、Microsoft の Secure Future Initiative の一部です。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。 入れ子になったアプリ認証は、今後のトークンに推奨される方法です。 詳細については、 ブログ投稿 と FAQ ページを参照してください。

  • メソッドが makeEwsRequestAsync EWS 要求を行えるようにするには、サーバー管理者がクライアント アクセス サーバー EWS ディレクトリ で を にtrue設定OAuthAuthenticationする必要があります。

  • アドインには、 メソッドを使用するための 読み取り/書き込みメールボックス のアクセス許可が makeEwsRequestAsync 必要です。 メソッドで呼び出すことができる 読み取り/書き込みメールボックス のアクセス許可と EWS 操作の makeEwsRequestAsync 使用については、「 ユーザーのメールボックスへのメール アドイン アクセスのアクセス許可を指定する」を参照してください。

  • アドインがフォルダー関連アイテムにアクセスする必要がある場合、またはその XML 要求で UTF-8 エンコード (\<?xml version="1.0" encoding="utf-8"?\>) を指定する必要がある場合は、代わりに Microsoft Graph または REST API を使用してユーザーのメールボックスにアクセスする必要があります。

  • このメソッドは、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

  • このメソッドは、アドインが Gmail メールボックスに読み込まれている場合はサポートされません。

  • バージョン 15.0.4535.1004 より前のバージョンの Outlook で実行されるアドインで メソッドを使用 makeEwsRequestAsync する場合は、エンコード値を ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>) に設定する必要があります。 Outlook クライアントのバージョンを確認するには、 プロパティを使用します mailbox.diagnostics.hostVersion 。 Outlook on the webまたは新しい Outlook on Windows でアドインが実行されている場合は、エンコード値を設定する必要はありません。 アドインが実行されている Outlook クライアントを特定するには、 プロパティを mailbox.diagnostics.hostName 使用します。

例

function getSubjectRequest(id) {
    // Return a GetItem operation request for the subject of the specified item.
    const request =
        '<?xml version="1.0" encoding="utf-8"?>' +
        '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
        '               xmlns:xsd="http://www.w3.org/2001/XMLSchema"' +
        '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
        '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
        '  <soap:Header>' +
        '    <RequestServerVersion Version="Exchange2016" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
        '  </soap:Header>' +
        '  <soap:Body>' +
        '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
        '      <ItemShape>' +
        '        <t:BaseShape>IdOnly</t:BaseShape>' +
        '        <t:AdditionalProperties>' +
        '            <t:FieldURI FieldURI="item:Subject"/>' +
        '        </t:AdditionalProperties>' +
        '      </ItemShape>' +
        '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
        '    </GetItem>' +
        '  </soap:Body>' +
        '</soap:Envelope>';

    return request;
}

function sendRequest() {
    // Create a local variable that contains the mailbox.
    Office.context.mailbox.makeEwsRequestAsync(
        getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
    const result = asyncResult.value;
    const context = asyncResult.asyncContext;

    // Process the returned response here.
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/get-icaluid-as-attendee.yaml

const ewsId = Office.context.mailbox.item.itemId;
const request = `<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header><t:RequestServerVersion Version="Exchange2013" /></soap:Header>
      <soap:Body>
        <m:GetItem>
          <m:ItemShape>
            <t:BaseShape>AllProperties</t:BaseShape>
          </m:ItemShape >
          <m:ItemIds>
            <t:ItemId Id="${ewsId}" />
          </m:ItemIds>
        </m:GetItem>
      </soap:Body>
    </soap:Envelope>`;

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  console.log(getUID(result.value));
});

...

const request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">'+
    '  <soap:Header><t:RequestServerVersion Version="Exchange2010" /></soap:Header>'+
    '  <soap:Body>'+
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">'+
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>'+
    '      <m:Items>'+
    '        <t:Message>'+
    '          <t:Subject>Hello, Outlook!</t:Subject>'+
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>'+
    '          <t:ToRecipients>'+
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>'+
    '          </t:ToRecipients>'+
    '        </t:Message>'+
    '      </m:Items>'+
    '    </m:CreateItem>'+
    '  </soap:Body>'+
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
    console.log(result);
});

removeHandlerAsync(eventType, options, callback)

サポートされているイベントの種類のイベント ハンドラーを削除します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

eventType

Office.EventType | string

ハンドラーを取り消すイベント。

options
Office.AsyncContextOptions

コールバックで使用するために、任意の型のコンテキスト データを変更せずに保持するためのオプションを提供します。

callback

(asyncResult: Office.AsyncResult<void>) => void

省略可能。 メソッドが完了すると、 パラメーターで callback 渡された関数が、 型 Office.AsyncResultの 1 つのパラメーターで呼び出されます。

戻り値

void

注釈

[ API セット: メールボックス 1.5 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

removeHandlerAsync(eventType, callback)

サポートされているイベントの種類のイベント ハンドラーを削除します。 注: イベントは、作業ウィンドウの実装でのみ使用できます。

サポートされているイベントについては、「メールボックス オブジェクト モデル のイベント」セクションを参照してください。

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

eventType

Office.EventType | string

ハンドラーを取り消すイベント。

callback

(asyncResult: Office.AsyncResult<void>) => void

省略可能。 メソッドが完了すると、 パラメーターで callback 渡された関数が、 型 Office.AsyncResultの 1 つのパラメーターで呼び出されます。

戻り値

void

注釈

[ API セット: メールボックス 1.5 ]

最小アクセス許可レベル: アイテムの読み取り

適用できる Outlook モード: Composeまたは読み取り

例

Office.context.mailbox.removeHandlerAsync(Office.EventType.OfficeThemeChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});