Outlook アドインで共有フォルダーと共有メールボックスのシナリオを有効にする
この記事では、Office JavaScript API でサポートされているアクセス許可など、Outlook アドインで共有フォルダー (代理人アクセスとも呼ばれます) と共有メールボックスのシナリオを有効にする方法について説明します。
注:
共有フォルダーのサポートは 要件セット 1.8 で導入されましたが、共有メールボックスのサポートは 要件セット 1.13 で導入されました。 これらの機能のクライアント サポートについては、「 サポートされているクライアントとプラットフォーム」を参照してください。
サポートされているクライアントとプラットフォーム
次の表は、この機能でサポートされているクライアントとサーバーの組み合わせを示しています。該当する場合は、最低限必要な累積的な更新プログラムも含まれます。 除外された組み合わせはサポートされていません。
| クライアント | Exchange Online | Exchange 2019 オンプレミス (累積的な更新プログラム 1 以降) |
Exchange 2016 オンプレミス (累積的な更新プログラム 6 以降) |
Exchange 2013 オンプレミス |
|---|---|---|---|---|
| Windows 共有フォルダー: バージョン 1910 (ビルド 12130.20272) 以降 共有メールボックス: バージョン 2304 (ビルド 16327.20248) 以降 |
サポート | サポート* | サポート* | サポート* |
| Mac ビルド 16.47 以降 |
サポート | サポート | サポートされている | サポートされている |
| Web ブラウザー (最新の Outlook UI) | サポートされている | × | 該当なし | 該当なし |
| Web ブラウザー (従来の Outlook UI) | 該当なし | 該当なし | 該当なし | 該当なし |
注:
* オンプレミスの Exchange 環境でのこの機能のサポートは、現在のチャネルの Outlook on Windows バージョン 2206 (ビルド 15330.20000) から、月次エンタープライズ チャネルの場合はバージョン 2207 (ビルド 15427.20000) から利用できます。
サポートされているセットアップ
次のセクションでは、共有メールボックスと共有フォルダーでサポートされる構成について説明します。 機能 API は、他の構成では期待どおりに機能しない可能性があります。 構成方法を学習するプラットフォームを選択します。
共有フォルダー
メールボックスの所有者は、まず、次のいずれかのオプションを使用して代理人へのアクセスを提供する必要があります。
Outlook on Windows でメールボックスからの代理人アクセスを設定します。 詳細については、「 他のユーザーにメールと予定表の管理を許可する」を参照してください。
Microsoft 365 管理センターからデリゲート アクセスを設定します。 このオプションは、管理者のみが完了できます。 詳細については、「別の Microsoft 365 ユーザーにメールボックスのアクセス許可を付与する」を参照してください。
Exchange 管理センターから代理人アクセスを設定します。 このオプションは、管理者のみが完了できます。 詳細については、「 受信者のアクセス許可を管理する」を参照してください。
アクセスが提供されたら、代理人は、記事「別のユーザーの メールと予定表アイテムを管理する」の「他のユーザーのメールボックスをプロファイルに追加する」セクションに記載されている手順に従う必要があります。
共有メールボックス
Exchange サーバー管理者は、アクセスするユーザーのセットの共有メールボックスを作成および管理できます。 Exchange Onlineおよびオンプレミスの Exchange 環境がサポートされています。
"自動マッピング" と呼ばれるExchange Server機能は既定でオンになっています。つまり、Outlook を閉じて再度開いた後、共有メールボックスがユーザーの Outlook アプリに自動的に表示されます。 ただし、管理者が自動マッピングをオフにした場合、ユーザーは、「Outlook で共有メールボックスを 開いて使用する」の「Outlook に共有メールボックスを追加する」セクションに記載されている手動の手順に従う必要があります。
警告
パスワードを使用して共有メールボックスにサインイン しないでください 。 その場合、機能 API は機能しません。
アドインが実行する場所と一般的にアクティブ化しない場所の詳細については、「Outlook アドインの概要」ページの「 アドインで使用できるメールボックスアイテム 」セクションを参照してください。
サポートされているアクセス許可
次の表では、Office JavaScript API が代理人と共有メールボックス ユーザーに対してサポートするアクセス許可について説明します。
| アクセス許可 | 値 | 説明 |
|---|---|---|
| 読み取り | 1 (000001) | 項目を読み取ることができます。 |
| 書き込み | 2 (000010) | アイテムを作成できます。 |
| DeleteOwn | 4 (000100) | 作成したアイテムのみを削除できます。 |
| DeleteAll | 8 (001000) | 任意のアイテムを削除できます。 |
| EditOwn | 16 (010000) | 作成したアイテムのみを編集できます。 |
| EditAll | 32 (100000) | 任意のアイテムを編集できます。 |
注:
現在、API は既存のアクセス許可の取得をサポートしていますが、アクセス許可の設定はサポートしていません。
DelegatePermissions オブジェクトは、アクセス許可を示すためにビットマスクを使用して実装されます。 ビットマスク内の各位置は、特定のアクセス許可を表し、 に 1 設定されている場合、ユーザーはそれぞれのアクセス許可を持ちます。 たとえば、右側の 2 番目のビットが である場合、 1ユーザーは 書き込み アクセス許可を持ちます。 特定のアクセス許可をチェックする方法の例については、この記事の後半の「代理人または共有メールボックス ユーザーとして操作を実行する」セクションを参照してください。
共有フォルダー クライアント間で同期する
所有者のメールボックスに対する代理人の更新は、通常、メールボックス間で直ちに同期されます。
ただし、REST または Exchange Web Services (EWS) 操作を使用してアイテムの拡張プロパティを設定した場合、このような変更の同期には数時間かかることがあります。このような遅延を回避するには、代わりに CustomProperties オブジェクトと関連 API を使用することをお勧めします。 詳細については、「Outlook アドインでメタデータを取得して設定する」の 「カスタム プロパティ」セクション を参照してください。
重要
デリゲート シナリオでは、現在 office.js API によって提供されているトークンで EWS を使用することはできません。
マニフェストを構成する
アドインで共有フォルダーと共有メールボックスのシナリオを有効にするには、マニフェストで必要なアクセス許可を有効にする必要があります。
まず、デリゲートからの REST 呼び出しをサポートするには、アドインがメールボックスの 読み取り/書き込み アクセス許可を要求する必要があります。 マークアップはマニフェストの種類によって異なります。
- XML マニフェスト: Permissions> 要素を<ReadWriteMailbox に設定します。
- Microsoft 365 (プレビュー) の統合マニフェスト: "authorization.permissions.resourceSpecific" 配列内のオブジェクトの "name" プロパティを "Mailbox.ReadWrite.User" に設定します。
次に、共有フォルダーのサポートを有効にします。 マークアップはマニフェストの種類によって異なります。
"authorization.permissions.resourceSpecific" 配列にオブジェクトを追加し、その "name" プロパティを "Mailbox.SharedFolder" に設定します。
"authorization": {
"permissions": {
"resourceSpecific": [
...
{
"name": "Mailbox.SharedFolder",
"type": "Delegated"
},
]
}
},
代理人または共有メールボックス ユーザーとして操作を実行する
アイテムの共有プロパティは、 item.getSharedPropertiesAsync メソッドを呼び出すことによって作成モードまたは読み取りモードで取得できます。 これにより、現在、ユーザーのアクセス許可、所有者のメール アドレス、REST API のベース URL、およびターゲット メールボックスを提供する SharedProperties オブジェクトが返されます。
次の例は、代理人または共有メールボックス ユーザーが書き込みアクセス許可を持っている場合にチェック、メッセージまたは予定の共有プロパティを取得し、REST 呼び出しを行う方法を示しています。
function performOperation() {
Office.context.mailbox.getCallbackTokenAsync({
isRest: true
},
function (asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value !== "") {
Office.context.mailbox.item.getSharedPropertiesAsync({
// Pass auth token along.
asyncContext: asyncResult.value
},
function (asyncResult1) {
let sharedProperties = asyncResult1.value;
let delegatePermissions = sharedProperties.delegatePermissions;
// Determine if user can do the expected operation.
// E.g., do they have Write permission?
if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Write) != 0) {
// Construct REST URL for your operation.
// Update <version> placeholder with actual Outlook REST API version e.g. "v2.0".
// Update <operation> placeholder with actual operation.
let rest_url = sharedProperties.targetRestUrl + "/<version>/users/" + sharedProperties.targetMailbox + "/<operation>";
$.ajax({
url: rest_url,
dataType: 'json',
headers:
{
"Authorization": "Bearer " + asyncResult1.asyncContext
}
}
).done(
function (response) {
console.log("success");
}
).fail(
function (error) {
console.log("error message");
}
);
}
}
);
}
}
);
}
ヒント
代理人として、REST を使用して、 Outlook アイテムまたはグループ投稿に添付された Outlook メッセージのコンテンツを取得できます。
共有アイテムと共有以外のアイテムで REST を呼び出す処理
アイテムが共有されているかどうかに関係なく、アイテムに対して REST 操作を呼び出す場合は、API を getSharedPropertiesAsync 使用して、アイテムが共有されているかどうかを判断できます。 その後、適切なオブジェクトを使用して、操作の REST URL を作成できます。
if (item.getSharedPropertiesAsync) {
// In Windows, Mac, and the web client, this indicates a shared item so use SharedProperties properties to construct the REST URL.
// Add-ins don't activate on shared items in mobile so no need to handle.
// Perform operation for shared item.
} else {
// In general, this isn't a shared item, so construct the REST URL using info from the Call REST APIs article:
// https://learn.microsoft.com/office/dev/add-ins/outlook/use-rest-api
// Perform operation for non-shared item.
}
制限事項
アドインのシナリオによっては、共有フォルダーや共有メールボックスの状況を処理する際に考慮すべきいくつかの制限事項があります。
メッセージ作成モード
メッセージ作成モードでは、次の条件が満たされていない限り、Outlook on the webまたは Windows では getSharedPropertiesAsync はサポートされません。
a. アクセス/共有フォルダーを委任する
- メールボックスの所有者がメッセージを開始します。 これは、新しいメッセージ、返信、転送のいずれかです。
- メッセージを保存し、独自の Drafts フォルダーからデリゲートと共有されているフォルダーに移動します。
- デリゲートは、共有フォルダーから下書きを開き、作成を続行します。
b. 共有メールボックス (Outlook on Windows にのみ適用)
- 共有メールボックス ユーザーがメッセージを開始します。 これは、新しいメッセージ、返信、転送のいずれかです。
- メッセージを保存し、独自の 下書き フォルダーから共有メールボックス内のフォルダーに移動します。
- 別の共有メールボックス ユーザーが共有メールボックスから下書きを開き、作成を続行します。
メッセージは共有コンテキストに入り、これらの共有シナリオをサポートするアドインはアイテムの共有プロパティを取得できます。 メッセージが送信されると、通常は送信者の [送信済みアイテム] フォルダーに表示されます。
REST と EWS
アドインでは REST を使用できます。 所有者のメールボックスまたは共有メールボックスへの REST アクセスを有効にするには、アドインがマニフェストで メールボックスの読み取り/書き込み アクセス許可を要求する必要があります。 マークアップはマニフェストの種類によって異なります。
- XML マニフェスト: Permissions> 要素を<ReadWriteMailbox に設定します。
- Microsoft 365 (プレビュー) の統合マニフェスト: "authorization.permissions.resourceSpecific" 配列内のオブジェクトの "name" プロパティを "Mailbox.ReadWrite.User" に設定します。
EWS はサポートされていません。
アドレス一覧に表示されないユーザーまたは共有メールボックス
管理者がグローバル アドレス一覧 (GAL) などのアドレス一覧からユーザーまたは共有メールボックス アドレスを隠した場合、影響を受けるメール アイテムは null としてメールボックス レポート Office.context.mailbox.item で開かれます。 たとえば、ユーザーが GAL から非表示になっている共有メールボックス内のメール アイテムを開いた場合、 Office.context.mailbox.item そのメール アイテムが null であることを表します。
関連項目
Office Add-ins
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示