次の方法で共有

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

  • [アーティクル]

次のいずれかの方法を使用して、Outlook アドインでカスタム データを管理できます。

  • ユーザーのメールボックスのカスタム データを管理するローミング設定。
  • ユーザーのメールボックス内のアイテムのカスタム データを管理するカスタム プロパティ。

どちらの方法でも、Outlook アドインのみがアクセスできるカスタム データにアクセスできますが、各メソッドはデータを他のメソッドとは別に格納します。 つまり、ローミング設定を介して格納されたデータにはカスタム プロパティからアクセスできません。また、その逆も同様です。 ローミング設定はユーザーのメールボックスに格納され、カスタム プロパティはメッセージまたは予定に格納されます。 保存されたデータは、以降の Outlook セッションで、アドインがサポートするすべてのフォーム ファクターでアクセスできます。

メールボックスごとのカスタム データ: ローミング設定

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

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

ローミング設定の形式

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.initialize イベント ハンドラーでローミング設定を読み込みます。 次の JavaScript コード例は、既存のローミング設定を読み込み、 customerName と customerBalance の 2 つの設定の値を取得する方法を示しています。

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

// The initialize function is required for all add-ins.
Office.initialize = function () {
  // 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 session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

メールボックス内のアイテムごとのカスタム データ: カスタム プロパティ

CustomProperties オブジェクトを使用して、ユーザーのメールボックス内のアイテムに固有のデータを指定することもできます。 たとえば、メール アドインで特定のメッセージを分類し、カスタム プロパティ messageCategory を使用してそのカテゴリのメモを付けることができます。 または、メール アドインでメッセージ内の会議の提案から予定を作成した場合に、カスタム プロパティを使用してそれぞれの予定を追跡できます。 これにより、ユーザーがメッセージをもう一度開いた場合、メール アドインは 2 回目の予定の作成を提供しません。

ローミング設定と同様に、カスタム プロパティに対する変更は現在の Outlook セッションのプロパティのメモリ内コピーに格納されます。 これらのカスタム プロパティが次のセッションで使用できることを確認するには、 CustomProperties.saveAsync を使用します。

これらのアドイン固有の項目固有のカスタム プロパティには、 CustomProperties オブジェクトを使用してのみアクセスできます。 これらのプロパティは、Outlook オブジェクト モデルのカスタム、MAPI ベースの UserProperties 、および Exchange Web Services (EWS) の拡張プロパティとは異なります。 Outlook オブジェクト モデル、EWS、または REST を使用して CustomProperties に直接アクセスすることはできません。 EWS または REST を使用して CustomProperties にアクセスする方法については、「EWS または REST を 使用してカスタム プロパティを取得する」セクションを参照してください。

注:

カスタム プロパティは、それらを作成したアドインでのみ使用でき、保存されたメール アイテムを介してのみ使用できます。 このため、作成モードの間に設定されたプロパティは、メール アイテムの受信者に送信されません。 カスタム プロパティを含むメッセージまたは予定を送信すると、そのプロパティに [送信済みアイテム ] フォルダー内のアイテムからアクセスできます。 受信者がアドイン セットのカスタム データを受信できるようにするには、代わりに InternetHeaders を使用することを検討してください。

カスタム プロパティの使用

カスタム プロパティを使用するには、まず loadCustomPropertiesAsync メソッドを呼び出して読み込む必要があります方法です。 プロパティ バッグを作成したら、 set メソッドと get メソッドを使用して、カスタム プロパティを追加および取得できます。 プロパティ バッグで行った変更を保存するには、saveAsync メソッドを使用する必要があります。

注:

Outlook アドインでカスタム プロパティを使用する場合は、次の点に注意してください。

  • Outlook on Mac では、カスタム プロパティはキャッシュされません。 ユーザーのネットワークがダウンした場合、Outlook on Mac のアドインはカスタム プロパティにアクセスできません。
  • Windows 上の従来の Outlook では、作成モードで保存されたカスタム プロパティは、作成中のアイテムが閉じられた後、または Office.context.mailbox.item.saveAsync が呼び出された後にのみ保持されます。

カスタム プロパティの例

次の例は、カスタム プロパティを使用する Outlook アドインの関数とメソッドの簡略化されたセットを示しています。 この例を出発点として、カスタム プロパティを使用するアドインを作成できます。

この例には、次の関数とメソッドが含まれています。

  • Office.initialize -- アドインを初期化し、Exchange Server からカスタム プロパティ バッグを読み込みます。

  • customPropsCallback -- サーバーから返されるカスタム プロパティ バッグを取得し、後で使用するためにローカルに保存します。

  • updateProperty -- 特定のプロパティを設定または更新し、変更をローカル プロパティ バッグに保存します。

  • removeProperty -- プロパティ バッグから特定のプロパティを削除し、これらの変更を保存します。

let _mailbox;
let _customProps;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  _mailbox = Office.context.mailbox;
  _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}

// Callback function from loading custom properties.
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
  else {
    // Successfully loaded custom properties,
    // can get them from the asyncResult argument.
    _customProps = asyncResult.value;
  }
}

// Get individual custom property.
function getProperty() {
  const myProp = _customProps.get("myProp");
}

// Set individual custom property.
function updateProperty(name, value) {
  _customProps.set(name, value);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Remove a custom property.
function removeProperty(name) {
  _customProps.remove(name);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Callback function from saving custom properties.
function saveCallback() {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

EWS または REST を使用してカスタム プロパティを取得する

EWS または REST を使用して CustomProperties を取得する場合は、最初にMAPI ベースの拡張プロパティの名前を決めるようにします。 その後、MAPI ベースの拡張プロパティを取得するのと同じ方法でそのプロパティを取得できます。

アイテムでのカスタム プロパティの格納方法

アドインによって設定されるカスタム プロパティは、通常の MAPI ベースのプロパティと同じではありません。 アドイン API は、すべてのアドインの CustomProperties を JSON ペイロードとしてシリアル化し、名前が cecp-<app-guid> (アドインの ID <app-guid> ) であり、プロパティ セット GUID が {00020329-0000-0000-C000-000000000046}されている 1 つの MAPI ベースの拡張プロパティに保存します。 (このオブジェクトに関する詳細については、「MS OXCEXT 2.2.5 メール アプリのカスタム プロパティ」を参照してください。) その後、EWS または REST を使用してこの MAPI ベースのプロパティを取得できます。

EWS を使用してカスタム プロパティを取得する

メール アドインは、EWS GetItem 操作を使用して、MAPI ベースの拡張プロパティCustomPropertiesを取得できます。 コールバック トークンを使用してサーバー側で GetItem にアクセスするか、 mailbox.makeEwsRequestAsync メソッドを使用してクライアント側でアクセスします。 GetItem要求で、前のセクション「カスタム プロパティをアイテムに格納する方法」で説明した詳細を使用して、MAPI ベースのCustomPropertiesプロパティをプロパティ セットに指定します。

次の例では、アイテムとそれのカスタム プロパティを取得する方法を示します。

重要

次の例では、<app-guid> を自分のアドインの ID と置き換えてください。

let request_str =
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<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 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"' +
                     'xmlns:wsa="http://www.w3.org/2005/08/addressing">' +
            '<t:RequestServerVersion Version="Exchange2010_SP1"/>' +
        '</soap:Header>' +
        '<soap:Body>' +
            '<m:GetItem>' +
                '<m:ItemShape>' +
                    '<t:BaseShape>AllProperties</t:BaseShape>' +
                    '<t:IncludeMimeContent>true</t:IncludeMimeContent>' +
                    '<t:AdditionalProperties>' +
                        '<t:ExtendedFieldURI ' +
                          'DistinguishedPropertySetId="PublicStrings" ' +
                          'PropertyName="cecp-<app-guid>"' +
                          'PropertyType="String" ' +
                        '/>' +
                    '</t:AdditionalProperties>' +
                '</m:ItemShape>' +
                '<m:ItemIds>' +
                    '<t:ItemId Id="' +
                      Office.context.mailbox.item.itemId +
                    '"/>' +
                '</m:ItemIds>' +
            '</m:GetItem>' +
        '</soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(
    request_str,
    function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log(asyncResult.value);
        }
        else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

要求文字列で他のカスタム プロパティを ExtendedFieldURI 要素として指定すると、それらのカスタム プロパティを取得することができます。

REST を使用してカスタム プロパティを取得する

アドインでメッセージやイベントに対して REST クエリを作成し、すでにカスタム プロパティを持つメッセージやイベントを取得することができます。 「アイテムでのカスタム プロパティの格納方法」セクションで説明されている詳細を参考にして、クエリに MAPI ベースの拡張プロパティ CustomProperties とそのプロパティ セットを含めます。

次の例では、アドインで設定されたいずれかのカスタム プロパティを含むすべてのイベントを取得し、追加のフィルター処理のロジックを適用できるようにプロパティの値を応答に含める方法を示します。

重要

次の例では、<app-guid> を自分のアドインの ID と置き換えてください。

GET https://outlook.office.com/api/v2.0/Me/Events?$filter=SingleValueExtendedProperties/Any
  (ep: ep/PropertyId eq 'String {00020329-0000-0000-C000-000000000046}
  Name cecp-<app-guid>' and ep/Value ne null)
  &$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String
  {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')

REST を使用して単一値の MAPI ベースの拡張プロパティを取得するその他の例は、「singleValueExtendedProperty を取得る」 を参照してください。

次の例では、アイテムとそれのカスタム プロパティを取得する方法を示します。 done メソッドのコールバック関数では、要求されたカスタム プロパティの一覧は item.SingleValueExtendedProperties に含まれます。

重要

次の例では、<app-guid> を自分のアドインの ID と置き換えてください。

Office.context.mailbox.getCallbackTokenAsync(
    {
        isRest: true
    },
    function (asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded
            && asyncResult.value !== "") {
            let item_rest_id = Office.context.mailbox.convertToRestId(
                Office.context.mailbox.item.itemId,
                Office.MailboxEnums.RestVersion.v2_0);
            let rest_url = Office.context.mailbox.restUrl +
                           "/v2.0/me/messages('" +
                           item_rest_id +
                           "')";
            rest_url += "?$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')";

            let auth_token = asyncResult.value;
            $.ajax(
                {
                    url: rest_url,
                    dataType: 'json',
                    headers:
                        {
                            "Authorization":"Bearer " + auth_token
                        }
                }
                ).done(
                    function (item) {
                        console.log(JSON.stringify(item));
                    }
                ).fail(
                    function (error) {
                        console.log(JSON.stringify(error));
                    }
                );
        } else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

メッセージ内のプラットフォームの動作

次の表は、さまざまな Outlook クライアントのメッセージに保存されたカスタム プロパティの動作をまとめたものです。

シナリオ Outlook on the web and on new Windows client Windows 上のクラシック Outlook Outlook on Mac
新しい新規作成 null null null
返信、すべて返信 null null null
転送 null 親のプロパティを読み込む null
新しい新規作成から送信されたアイテム null null null
返信またはすべての返信から送信されたアイテム null null null
前方から送信されたアイテム null 保存されていない場合は親のプロパティを削除します null

従来の Outlook on Windows の状況を処理するには:

  1. アドインの初期化時に既存のプロパティを確認し、それらを保持するか、必要に応じてクリアします。
  2. カスタム プロパティを設定する場合は、カスタム プロパティが読み取りモードで追加されたかどうかを示す追加のプロパティを含めます。 これにより、プロパティが作成モードで作成されたか、親から継承されたかを区別するのに役立ちます。
  3. ユーザーがメッセージを転送または返信しているかどうかを確認するには、 item.getComposeTypeAsync (要件セット 1.10 から使用可能) を使用できます。

関連項目