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

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

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

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

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

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

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

ローミング設定の形式

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

、、および add-in_setting_name_2という名前add-in_setting_name_0add-in_setting_name_1の 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 関数である を使用して、setAddInSettingRoamingSettings.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 を 使用してカスタム プロパティを取得する」セクションを参照してください。

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

カスタム プロパティを使用するには、まず loadCustomPropertiesAsync メソッドを呼び出して読み込む必要があります方法です。 プロパティ バッグを作成したら、 set メソッドと get メソッドを使用して、カスタム プロパティを追加および取得できます。 プロパティ バッグで行った変更を保存するには、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 は、すべてのアドインを JSON ペイロードとしてシリアル化し、名前が (<app-guid>アドインの CustomProperties ID) であり、プロパティ セット GUID が cecp-<app-guid>{00020329-0000-0000-C000-000000000046}である 1 つの MAPI ベースの拡張プロパティに保存します。 (このオブジェクトに関する詳細については、「MS OXCEXT 2.2.5 メール アプリのカスタム プロパティ」を参照してください。) その後、EWS または REST を使用してこの MAPI ベースのプロパティを取得できます。

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

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

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

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 とそのプロパティ セットを含めます。

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

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 に含まれます。

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 Windows の状況を処理するには:

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

関連項目

• MAPI のプロパティの概要
• Outlook のプロパティの概要
• Outlook アドインからの Outlook REST API の呼び出し
• Outlook アドインから Web サービスを呼び出す
• Exchange における EWS のプロパティと拡張プロパティ
• Exchange の EWS でのプロパティ セットと応答の図形
• Outlook アドインのメッセージに対するインターネット ヘッダーの取得と設定