Office. Mailbox interface

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

重要:

読 み取り モードで ewsUrl メンバーを呼び出すには、アプリのマニフェストで読み取り項目のアクセス許可が指定されている必要があります。
新規作成モードでは、ewsUrl メンバーを使用する前に、saveAsync メソッドを呼び出す必要があります。 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

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);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

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

重要: アドインが作業ウィンドウのピン留めをサポートしている場合、 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

masterCategories

メールボックスに関連付けられているカテゴリマスターリストを管理するメソッドを提供するオブジェクトを取得します。

masterCategories: MasterCategories;

プロパティ値

Office.MasterCategories

注釈

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

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

適用できる Outlook モード: 新規作成または読み取り

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});

...

const masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

restUrl

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

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

In compose mode you must call the saveAsync method before you can use the restUrl member. saveAsync メソッドを呼び出すには、アプリにアイテムの読み取り/書き込みアクセス許可が必要です。

ただし、委任または共有のシナリオでは、代わりに SharedProperties オブジェクトの targetRestUrl プロパティを使用する必要があります (要件セット 1.8 で導入)。詳細については、デリゲートアクセスに関する記事を参照してください。

restUrl: string;

プロパティ値

string

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

restUrl 値は、ユーザーのメールボックスに REST API 呼び出しを行うために使用できます。

例

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

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

...

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);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

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

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

例

Office.initialize = function (reason) {
    $(document).ready(function () {
        Office.context.mailbox.addHandlerAsync(
            Office.EventType.ItemChanged,
            loadNewItem,
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    // Handle error.
                }
            });
    });
};

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

    // Check that item is not null.
    if (item !== null) {
        // Work with item, e.g., define and call 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

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

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

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 モード: 新規作成または読み取り

重要:

このメソッドは、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイルデバイスで Outlook でサポートされている Outlook JavaScript API」を参照してください。
REST API (Outlook メール 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

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);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

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

Outlook on the web またはデスクトップクライアントのメールアプリで使用される日付と時刻は、異なるタイムゾーンを使用できます。 Outlook では、クライアントコンピューターのタイムゾーンが使用されます。Outlook on the web では、Exchange Admin Center (EAC) で設定されたタイムゾーンが使用されます。ユーザーインターフェイスに表示する値が、ユーザーが予期するタイムゾーンと常に一致するように、日付と時刻の値を処理する必要があります。

デスクトップクライアントで Outlook でメールアプリが実行されている場合、 convertToLocalClientTime メソッドは、クライアントコンピューターのタイムゾーンに設定された値を持つディクショナリオブジェクトを返します。メールアプリが Outlook on the web で実行されている場合、 convertToLocalClientTime メソッドは、値が EAC で指定されたタイムゾーンに設定されたディクショナリオブジェクトを返します。

convertToLocalClientTime(timeValue: Date): LocalClientTime;

パラメーター

timeValue: Date

Date オブジェクト。

戻り値

Office.LocalClientTime

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

convertToRestId(id, restVersion)

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

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

パラメーター

id: string

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

restVersion: Office.MailboxEnums.RestVersion | string

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

戻り値

string

注釈

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

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

適用できる Outlook モード: 新規作成または読み取り

重要:

このメソッドは、Outlook on Android または iOS ではサポートされていません。 Outlook モバイルでサポートされている API の詳細については、「モバイルデバイスで Outlook でサポートされている Outlook JavaScript API」を参照してください。
Exchange Web Services (EWS) または itemId プロパティを介して取得されたアイテム ID は、REST API (Outlook メール 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/basic-rest-cors.yaml

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

...

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);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

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 モード: 新規作成または読み取り

例

// 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 では、このメソッドは、フォームの本文が 32K 文字以下の場合にのみ、指定されたフォームを開きます。

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

displayAppointmentForm(itemId: string): void;

パラメーター

itemId: string

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる 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-existing-appointment.yaml

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

displayAppointmentFormAsync(itemId, options, callback)

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

displayAppointmentFormAsync メソッドは、デスクトップ上の新しいウィンドウやモバイルデバイス上のダイアログボックスに既存の予定を開きます。

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

Outlook on the web では、このメソッドは、フォームの本文が 32K 文字以下の場合にのみ、指定されたフォームを開きます。

注: この方法は、Outlook on iOS または Android ではサポートされていません。

displayAppointmentFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

itemId: string

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

options: Office.AsyncContextOptions

次のプロパティの 1 つ以上を含むオブジェクトリテラル:- asyncContext: 開発者は、コールバック関数でアクセスする任意のオブジェクトを指定できます。

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

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

例

// 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();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayAppointmentFormAsync(itemId, function(asyncResult) {
  console.log("Result: " + JSON.stringify(asyncResult));
});

displayAppointmentFormAsync(itemId, callback)

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

displayAppointmentFormAsync メソッドは、デスクトップ上の新しいウィンドウやモバイルデバイス上のダイアログボックスに既存の予定を開きます。

Outlook on the web では、このメソッドは、フォームの本文が 32K 文字以下の場合にのみ、指定されたフォームを開きます。

注: この方法は、Outlook on iOS または Android ではサポートされていません。

displayAppointmentFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

itemId: string

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

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

displayMessageForm(itemId)

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

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

Outlook on the web では、このメソッドは、フォームの本文が 32K 文字以下の場合にのみ、指定されたフォームを開きます。

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

displayMessageForm(itemId: string): void;

パラメーター

itemId: string

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

重要:

このメソッドは、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);

displayMessageFormAsync(itemId, options, callback)

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

displayMessageFormAsync メソッドは、デスクトップ上の新しいウィンドウやモバイルデバイス上のダイアログボックスに既存のメッセージを開きます。

Outlook on the web では、このメソッドは、フォームの本文が 32K 文字以下の場合にのみ、指定されたフォームを開きます。

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

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

注: この方法は、Outlook on iOS または Android ではサポートされていません。

displayMessageFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

itemId: string

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

options: Office.AsyncContextOptions

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

例

// 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();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayMessageFormAsync(itemId, function (asyncResult) {
 console.log("Result: " + JSON.stringify(asyncResult));
});

displayMessageFormAsync(itemId, callback)

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

displayMessageFormAsync メソッドは、デスクトップ上の新しいウィンドウやモバイルデバイス上のダイアログボックスに既存のメッセージを開きます。

Outlook on the web では、このメソッドは、フォームの本文が 32K 文字以下の場合にのみ、指定されたフォームを開きます。

注: この方法は、Outlook on iOS または Android ではサポートされていません。

displayMessageFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

itemId: string

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

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

displayNewAppointmentForm(parameters)

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

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

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

Outlook リッチクライアントと Outlook RT で、 requiredAttendees、 optionalAttendees、または resources パラメーターで出席者またはリソースを指定した場合、このメソッドは [ 送信 ] ボタンを含む会議フォームを表示します。受信者を指定せずにこのメソッドを実行すると、[保存して閉じる] ボタンがある予定フォームが表示されます。

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

displayNewAppointmentForm(parameters: AppointmentForm): void;

パラメーター

parameters: Office.AppointmentForm

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

該当する Outlook モード: 読み取り

例

// 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!"
});

displayNewAppointmentFormAsync(parameters, options, callback)

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

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

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

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

注: この方法は、Outlook on iOS または Android ではサポートされていません。

displayNewAppointmentFormAsync(parameters: AppointmentForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

parameters: Office.AppointmentForm

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

options: Office.AsyncContextOptions

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

該当する Outlook モード: 読み取り

例

// 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);

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new appointment form has been created.
Office.context.mailbox.displayNewAppointmentFormAsync(
  {
    requiredAttendees: ["bob@contoso.com"],
    optionalAttendees: ["sam@contoso.com"],
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"],
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewAppointmentFormAsync(parameters, callback)

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

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

注: この方法は、Outlook on iOS または Android ではサポートされていません。

displayNewAppointmentFormAsync(parameters: AppointmentForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

parameters: Office.AppointmentForm

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

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

該当する Outlook モード: 読み取り

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 : 添付ファイルの種類を示します。ファイルの添付ファイルまたはアイテムの添付ファイルである必要があります。

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

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

attachments.isInline : type が 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
    }
  ]
});

displayNewMessageFormAsync(parameters, options, callback)

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

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

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

displayNewMessageFormAsync(parameters: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

parameters: any

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

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

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

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

attachments.type : 添付ファイルの種類を示します。ファイルの添付ファイルまたはアイテムの添付ファイルである必要があります。

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

options: Office.AsyncContextOptions

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

該当する Outlook モード: 読み取り

例

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

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new message form has been created.
Office.context.mailbox.displayNewMessageFormAsync(
  {
    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
      }
    ]
  },
  (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewMessageFormAsync(parameters, callback)

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

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

displayNewMessageFormAsync(parameters: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

パラメーター

parameters: any

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

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

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

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

attachments.type : 添付ファイルの種類を示します。ファイルの添付ファイルまたはアイテムの添付ファイルである必要があります。

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

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

該当する Outlook モード: 読み取り

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.3 で作成モードのサポートが導入されました ]

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

重要:

2024 年 10 月には、すべての Exchange Online テナントに対してレガシ Exchange ユーザー ID とコールバックトークンが既定でオフになります。これは、Microsoft の Secure Future Initiative の一部であり、組織は現在の脅威の状況に対応するために必要なツールを提供します。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。入れ子になったアプリ認証は、今後のトークンに推奨される方法です。詳細については、ブログ投稿と FAQ ページを参照してください。
Outlook.com または Gmail メールボックスにアドインを読み込む場合、このメソッドはサポートされていません。
このメソッドは、Outlook on Android と iOS の読み取りモードでのみサポートされます。 Outlook モバイルでサポートされている API の詳細については、「モバイルデバイスで Outlook でサポートされている Outlook JavaScript API」を参照してください。
EWS 操作は、Outlook on iOS と Android で実行されているアドインではサポートされていません。 options.isRestが false に設定されている場合でも、Outlook モバイルクライアントでは常に REST トークンが返されます。
読み取りモードで 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 : ユーザーがネットワークに接続されなくなりました。ネットワーク接続を確認し、やり直してください。

例

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

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

getCallbackTokenAsync(callback, userContext)

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

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

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

パラメーター

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

userContext: any

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

重要:

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(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        console.log(result.value);
    }
});

getSelectedItemsAsync(options, callback)

アドインが操作をアクティブ化および実行できる現在選択されているメッセージを取得します。アドインは、一度に最大 100 個のメッセージでアクティブ化できます。アイテムの複数選択の詳細については、「複数のメッセージで Outlook アドインをアクティブ化する」を参照してください。

getSelectedItemsAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

パラメーター

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

メソッドが完了すると、callback パラメーターで渡された関数が、Office.AsyncResult オブジェクトである 1 つのパラメーターasyncResultで呼び出されます。項目 ID や件名など、選択したメッセージのプロパティは、asyncResult.value プロパティの SelectedItemDetails オブジェクトの配列として返されます。配列内のオブジェクトは、メッセージが選択された順序に従います。

戻り値

void

注釈

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

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

適用できる Outlook モード: 新規作成、読み取り

重要: このメソッドはメッセージにのみ適用されます。

getSelectedItemsAsync(callback)

getSelectedItemsAsync(callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

パラメーター

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

戻り値

void

注釈

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

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

適用できる Outlook モード: 新規作成、読み取り

重要: このメソッドはメッセージにのみ適用されます。

例

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

// Retrieves the selected messages' properties and logs them to the console.
Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  asyncResult.value.forEach((message) => {
    console.log(`Item ID: ${message.itemId}`);
    console.log(`Conversation ID: ${message.conversationId}`);
    console.log(`Internet message ID: ${message.internetMessageId}`);
    console.log(`Subject: ${message.subject}`);
    console.log(`Item type: ${message.itemType}`);
    console.log(`Item mode: ${message.itemMode}`);
    console.log(`Has attachment: ${message.hasAttachment}`);
  });
});

getUserIdentityTokenAsync(callback, userContext)

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

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

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

パラメーター

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

userContext: any

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

戻り値

void

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

重要:

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(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        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 パラメーターで渡された関数が、Office.AsyncResult オブジェクトである 1 つのパラメーターasyncResultで呼び出されます。 EWS 要求の XML 応答は、 asyncResult.value プロパティの文字列として提供されます。 Outlook on the web、Windows (バージョン 2303 以降 (ビルド 16225.10000))、Mac (バージョン 16.73 (23042601 以降) では、応答のサイズが 5 MB を超えると、 asyncResult.error プロパティにエラーメッセージが返されます。以前のバージョンの Outlook デスクトップクライアントでは、応答のサイズが 1 MB を超えるとエラーメッセージが返されます。

userContext: any

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

戻り値

void

注釈

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

適用できる Outlook モード: 新規作成または読み取り

重要:

2024 年 10 月には、すべての Exchange Online テナントに対してレガシ Exchange ユーザー ID とコールバックトークンが既定でオフになります。これは、Microsoft の Secure Future Initiative の一部であり、組織は現在の脅威の状況に対応するために必要なツールを提供します。 Exchange ユーザー ID トークンは、引き続き Exchange オンプレミスで機能します。入れ子になったアプリ認証は、今後のトークンに推奨される方法です。詳細については、ブログ投稿と FAQ ページを参照してください。
makeEwsRequestAsync メソッドが EWS 要求を行えるようにするには、サーバー管理者がクライアントアクセスサーバー EWS ディレクトリの true にOAuthAuthenticationを設定する必要があります。
アドインには、makeEwsRequestAsync メソッドを使用するためのメールボックスの読み取り/書き込みアクセス許可が必要です。 makeEwsRequestAsync メソッドで呼び出すことができる読み取り/書き込みメールボックスのアクセス許可と EWS 操作の使用については、「ユーザーのメールボックスへのメールアドインアクセスのアクセス許可を指定する」を参照してください。
アドインがフォルダー関連アイテムにアクセスする必要がある場合、またはその 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 クライアントを特定するには、 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, function (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

注釈

最小アクセス許可レベル: 読み取り項目

適用できる Outlook モード: 新規作成または読み取り

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

注釈