次の方法で共有

Outlook アドインのアドイン メタデータを取得および設定する

  • [アーティクル]

ローミング設定、カスタム プロパティ、またはセッション データを使用して、Outlook アドインのカスタム データを管理します。 これらのオプションを使用すると、Outlook アドインのみがアクセスできるカスタム データにアクセスできますが、各メソッドはデータを他のメソッドとは別に格納します。 つまり、ローミング設定を介して格納されたデータにはカスタム プロパティからアクセスできません。また、その逆も同様です。

次の表は、Outlook アドインでカスタム データを管理するために使用できるオプションの概要を示しています。

カスタム データ オプション 最小要件セット 適用対象 説明
ローミング設定 1.1 Mailbox ユーザーのメールボックス内のカスタム データを管理します。 カスタム データを設定するアドインは、ユーザーのメールボックスが設定されている他のサポートされているデバイスからアクセスできます。 保存されたデータは、後続の Outlook セッションでアクセスできます。
カスタム プロパティ 1.1 メール アイテム ユーザーのメールボックス内のメール アイテムのカスタム データを管理します。 カスタム データを設定するアドインは、ユーザーのメールボックスが設定されているサポートされているデバイス上のメール アイテムからアクセスできます。 保存されたデータは、後続の Outlook セッションでアクセスできます。
セッション データ 1.11 メール アイテム ユーザーの現在の Outlook セッションのメール アイテムのカスタム データを管理します。 カスタム データを設定するアドインは、作成中にメール アイテムからのみアクセスできます。

注:

要件セットとそのサポートされているクライアントについては、「 Outlook JavaScript API 要件セット」を参照してください。

各カスタム データ オプションの詳細については、該当するタブを選択します。

RoamingSettings オブジェクトを使用して、ユーザーの Exchange メールボックスに固有のデータを指定できます。 このタイプのデータには、たとえばユーザーの個人データや基本設定があります。 メール アドインは、その実行を許可されているデバイス (デスクトップ、タブレット、またはスマートフォン) でローミングするときにローミング設定にアクセスできます。

このデータへの変更は、現在の Outlook セッションの設定値のメモリ内コピーに格納されます。 ローミング設定は、更新後に明示的に保存し、次回ユーザーがアドインを開いた時点で、同じデバイスまたは他のサポートされているデバイスで使用できるようにします。

重要

Outlook アドイン API では、これらの設定へのアクセスは、それらの設定を作成したアドインのみに制限しますが、これらの設定はセキュリティで保護されたストレージと見なすべきではありません。 Microsoft Graph などの他のサービスからアクセスできます。 ユーザー資格情報やセキュリティ トークンなどの機密情報を格納するために使用しないでください。

ローミング設定の形式

RoamingSettings オブジェクトのデータは、シリアル化された JavaScript Object Notation (JSON) 文字列として格納されます。

次の構造体の例は、 add-in_setting_name_0、 add-in_setting_name_1、 add-in_setting_name_2という名前の 3 つの定義されたローミング設定があると仮定します。

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

ローミング設定の読み込み

通常、メール アドインは 、Office.onReady ハンドラーでローミング設定を読み込みます。 次の JavaScript コード例は、既存のローミング設定を読み込み、 customerName と customerBalance の 2 つの設定の値を取得する方法を示しています。

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    _customerName = _settings.get("customerName");
    _customerBalance = _settings.get("customerBalance");
  }
});

ローミング設定の作成または割り当て

前の例を続けて、次の JavaScript 関数 setAddInSettingは、 RoamingSettings.set メソッドを 使用して、今日の日付に cookie という名前の設定を設定する方法を示しています。 次に、 RoamingSettings.saveAsync メソッドを使用してデータを保持し、すべてのローミング設定をユーザーのメールボックスに保存します。

set メソッドは、設定がまだ存在しない場合に設定を作成し、指定した値に設定を割り当てます。 saveAsync メソッドは、ローミング設定を非同期的に保存します。 このコード サンプルでは、コールバック関数 ( saveMyAddInSettingsCallback) を saveAsyncに渡します。 非同期呼び出しが完了すると、 saveMyAddInSettingsCallback は 1 つのパラメーター asyncResult を使用して呼び出されます。 このパラメーターは AsyncResult オブジェクトであり、非同期呼び出しについての結果と詳細情報が格納されています。 オプションの userContext パラメーターを使用すると、非同期呼び出しからコールバック関数に任意の状態情報を渡すことができます。

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

ローミング設定の削除

前の例を引き続き拡張します。次の JavaScript 関数 removeAddInSettingは、 RoamingSettings.remove メソッドを 使用して cookie 設定を削除し、すべてのローミング設定をメールボックスに保存する方法を示しています。

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next Outlook session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Script Labのコード例を試す

RoamingSettings オブジェクトを作成および管理する方法については、Outlook アドインのScript Labを取得し、「アドイン設定を使用する」サンプルを試してください。 Script Lab の詳細については、「Script Lab を使用して Office JavaScript API を探索する」を参照してください。

関連項目