アドインの状態および設定を保持するPersisting add-in state and settings

Office アドインは、基本的にブラウザー コントロールのステートレス環境で動作する Web アプリケーションです。したがって、アドインでは、そのアドインを使用するセッション間で特定の操作または機能を継続して維持するためのデータを保持することが必要な場合があります。たとえば、アドインには、ユーザーの優先ビューや既定の場所など、アドインで保存しておき、アドインが次回初期化されたときにリロードする必要があるカスタム設定または他の値が含まれる場合があります。その場合は、次のようにします。Office Add-ins are essentially web applications running in the stateless environment of a browser control. As a result, your add-in may need to persist data to maintain the continuity of certain operations or features across sessions of using your add-in. For example, your add-in may have custom settings or other values that it needs to save and reload the next time it's initialized, such as a user's preferred view or default location. To do that, you can:

  • 次のどちらかの形式でデータを保存する JavaScript API for Office のメンバー使用します。Use members of the JavaScript API for Office that store data as either:

    • アドインの種類応じた場所に保存されるプロパティ バッグ内の名前と値の組。Name/value pairs in a property bag stored in a location that depends on add-in type.
    • ドキュメント内に保存されるカスタム XML。Custom XML stored in the document.
  • 基になるブラウザー コントロールによって提供される技術である、ブラウザーの Cookie、または HTML5 Web ストレージ (localStorage または sessionStorage) を使用します。Use techniques provided by the underlying browser control: browser cookies, or HTML5 web storage (localStorage or sessionStorage).

この記事では、アドインの状態を保持する JavaScript API for Office の使い方について説明します。ブラウザーの Cookie および Web ストレージの使用例については、「 Excel-Add-in-JavaScript-PersistCustomSettings」を参照してください。This article focuses on how to use the JavaScript API for Office to persist add-in state. For examples of using browser cookies and web storage, see the Excel-Add-in-JavaScript-PersistCustomSettings.

JavaScript API for Office を使用してアドインの状態および設定を保持するPersisting add-in state and settings with the JavaScript API for Office

JavaScript API for Office には、次の表に示すように、セッション間でアドインの状態を保存するために Settings オブジェクト、 RoamingSettings オブジェクト、および CustomProperties オブジェクトが用意されています。すべてのケースで、保存された設定値は、それを作成したアドインの Id にのみ関連付けられます。The JavaScript API for Office provides the Settings, RoamingSettings, and CustomProperties objects for saving add-in state across sessions as described in the following table. In all cases, the saved settings values are associated with the Id of the add-in that created them.

オブジェクトObject アドインの種類のサポートAdd-in type support ストレージの場所Storage location サポートされる Office のホストOffice host support
設定Settings コンテンツおよび作業ウィンドウcontent and task pane アドインが連携しているドキュメント、スプレッドシート、またはプレゼンテーション。コンテンツおよび作業ウィンドウのアドイン設定は、その設定が保存されているドキュメントから、その設定を作成したアドインで使用できます。The document, spreadsheet, or presentation the add-in is working with.Content and task pane add-in settings are available to the add-in that created them from the document where they are saved.

重要:****Settings オブジェクトを使用して、パスワードおよびその他の機密の個人を特定できる情報 (PII) を保存しないでください。保存されたデータはユーザーに対して表示されませんが、ドキュメントの一部として保存されているため、ドキュメントのファイル形式を直接読み取ることでアクセスできます。アドインによる PII の使用と、アドインが必要とするすべての PII の保存は、開発するアドインをユーザーのセキュリティが保護されるリソースとしてホストするサーバーのみで行うよう制限する必要があります。Important: Don't store passwords and other sensitive personally identifiable information (PII) with the Settings object. The data saved isn't visible to end users, but it is stored as part of the document, which is accessible by reading the document's file format directly. You should limit your add-in's use of PII and store any PII required by your add-in only on the server hosting your add-in as a user-secured resource.
Word、Excel、または PowerPointWord, Excel, or PowerPoint

メモ: Project 2013 の作業ウィンドウ アドインでは、アドインの状態または設定を保存するための Settings API をサポートしていません。ただし、Project (および他の Office ホスト アプリケーション) で動作するアドインの場合は、ブラウザーの Cookie や Web ストレージなどの技術を使用できます。こうした技術の詳細については、「Excel-Add-in-JavaScript-PersistCustomSettings」を参照してください。Note: Task pane add-ins for Project 2013 don't support the Settings API for storing add-in state or settings. However, for add-ins running in Project (as well as other Office host applications) you can use techniques such as browser cookies or web storage. For more information on these techniques, see the Excel-Add-in-JavaScript-PersistCustomSettings.
RoamingSettingsRoamingSettings OutlookOutlook アドインがインストールされている、ユーザーの Exchange サーバー メールボックス。これらの設定はユーザーのサーバー メールボックスに保存されるので、ユーザーと共に "ローミング" でき、そのユーザーのメールボックスにアクセスしている、サポートされているクライアント ホスト アプリケーションまたはブラウザーのコンテキストでアドインが実行されている場合、そのアドインでこれらの設定を利用できます。The user's Exchange server mailbox where the add-in is installed.Because these settings are stored in the user's server mailbox, they can "roam" with the user and are available to the add-in when it is running in the context of any supported client host application or browser accessing that user's mailbox.

Outlook アドインのローミング設定は、その設定を作成したアドインのみが利用でき、また、アドインがインストールされているメールボックスからのみ利用できます。Outlook add-in roaming settings are available only to the add-in that created them, and only from the mailbox where the add-in is installed.
OutlookOutlook
CustomPropertiesCustomProperties OutlookOutlook アドインが連携するメッセージ、予定、または会議出席依頼アイテム。 Outlook アドイン アイテムのカスタム プロパティは、そのプロパティを作成したアドインのみが利用でき、また、プロパティが保存されているアイテムからのみ利用できます。The message, appointment, or meeting request item the add-in is working with. Outlook add-in item custom properties are available only to the add-in that created them, and only from the item where they are saved. OutlookOutlook
CustomXMLPartsCustomXmlParts 作業ウィンドウtask pane アドインが連携しているドキュメント、スプレッドシート、またはプレゼンテーション。作業ウィンドウのアドイン設定は、その設定が保存されているドキュメントから、その設定を作成したアドインで使用できます。The document, spreadsheet, or presentation the add-in is working with. Task pane add-in settings are available to the add-in that created them from the document where they are saved.

重要: カスタム XML 部分には、パスワードなどの個人情報 (PII) を保存しないでください。保存されたデータはユーザーに対して表示されませんが、ドキュメントの一部として保存されるため、ドキュメントのファイル形式を直接読み取ることでアクセスできます。アドインによる PII の使用と、アドインが必要とするすべての PII の保存は、開発するアドインをユーザーのセキュリティが保護されるリソースとしてホストするサーバーのみで行うよう制限する必要があります。Important: Don't store passwords and other sensitive personally identifiable information (PII) in a custom XML part. The data saved isn't visible to end users, but it is stored as part of the document, which is accessible by reading the document's file format directly. You should limit your add-in's use of PII and store any PII required by your add-in only on the server hosting your add-in as a user-secured resource.
Word (Office JavaScript 共通 API を使用)、Excel (ホスト固有の Excel JavaScript API を使用)Word (using the Office JavaScript Common API) Excel (using the host-specific Excel JavaScript API

実行時のメモリ内での設定データの管理Settings data is managed in memory at runtime

注意

次の 2 つのセクションでは、Office の一般的な JavaScript API のコンテキストでの設定について説明します。ホスト固有の Excel の JavaScript API は、カスタム設定にもアクセスを提供します。Excel API およびプログラミング パターンは、やや異なります。詳細については、 Excel の SettingCollectionを参照してください。The following two sections discuss settings in the context of the Office Common JavaScript API. The host-specific Excel JavaScript API also provides access to the custom settings. The Excel APIs and programming patterns are somewhat different. For more information, see Excel SettingCollection.

内部的には、 設定ユーザー設定プロパティ、または RoamingSettings オブジェクトを使用してアクセスするプロパティ バッグ内のデータは、シリアル化された JavaScript オブジェクト表記法 (JSON) が格納されたオブジェクトの名前と値のペアとして格納されます。Internally, the data in the property bag accessed with the Settings, CustomProperties, or RoamingSettings objects is stored as a serialized JavaScript Object Notation (JSON) object that contains name/value pairs. 各値の名前 (キー) は** string** である必要があり、格納された値は JavaScript の ** string、 ** number, ** date、または object** にすることが可能ですが、 ** function** にすることはできません。The name (key) for each value must be a string, and the stored value can be a JavaScript string, number, date, or object, but not a function.

この例はプロパティ バッグの構造を示し、3 つの定義された string 値 ( firstNamelocation、および defaultView という名前) が含まれます。This example of the property bag structure contains three defined string values named firstName, location, and defaultView.

{
    "firstName":"Erik",
    "location":"98052",
    "defaultView":"basic"
}

前のアドイン セッションで設定プロパティ バッグが保存されると、アドインが初期化されるとき、またはその後のアドインの現在のセッション中の任意の時点で、その設定プロパティ バッグを読み込むことができます。After the settings property bag is saved during the previous add-in session, it can be loaded when the add-in is initialized or at any point after that during the add-in's current session. セッションの間、設定は、作成している設定の種類に対応するオブジェクト ( *Settings*、 *CustomProperties*、または *RoamingSettings*) の *get*、 *set*、および *remove* メソッドを使用して、全体がメモリ内で管理されます。During the session, the settings are managed in entirely in memory using the get, set, and remove methods of the object that corresponds to the kind settings you are creating ( Settings, CustomProperties, or RoamingSettings).

重要

追加、更新、またはアドインの中に行われた削除を保持する現在のセッションが、ストレージの場所にそのような設定を操作するために使用する対応するオブジェクトの saveAsync メソッドを呼び出す必要があります。To persist any additions, updates, or deletions made during the add-in's current session to the storage location, you must call the saveAsync method of the corresponding object used to work with that kind of settings. *取得*、 *設定*、および *削除* の方法は、設定のプロパティ バッグのメモリ内のコピーでのみ動作します。The get, set, and remove methods operate only on the in-memory copy of the settings property bag. ** saveAsync** の呼び出しなしにアドインが閉じられた場合、そのセッションの間に設定に対して行われた変更は失われます。If your add-in is closed without calling saveAsync, any changes made to settings during that session will be lost.

コンテンツ アドインおよび作業ウィンドウ アドインで、ドキュメントごとにアドインの状態と設定を保存する方法How to save add-in state and settings per document for content and task pane add-ins

Word、Excel、または PowerPoint 用のコンテンツ アドインまたは作業ウィンドウ アドインの状態またはカスタム設定を保持するには、Settings オブジェクトとそのメソッドを使用します。Settings オブジェクトのメソッドを使用して作成されたプロパティ バッグは、それを作成したコンテンツ アドインまたは作業ウィンドウ アドインのインスタンスのみが利用でき、プロパティ バッグが保存されているドキュメント以外からは使用できません。To persist state or custom settings of a content or task pane add-in for Word, Excel, or PowerPoint, you use the Settings object and its methods. The property bag created with the methods of the Settings object are available only to the instance of the content or task pane add-in that created it, and only from the document in which it is saved.

Settings オブジェクトは、Document オブジェクトの一部として自動的に読み込まれ、作業ウィンドウ アドインまたはコンテンツ アドインがアクティブ化されると使用できるようになります。The Settings object is automatically loaded as part of the Document object, and is available when the task pane or content add-in is activated. *ドキュメント* オブジェクトのインスタンスを作成した後は、 *ドキュメント* オブジェクトの 設定 のプロパティを *設定* オブジェクトを表示できます。After the Document object is instantiated, you can access the Settings object with the settings property of the Document object. セッションの存続中は、** Settings.get、 ** Settings.set、および ** Settings.remove** メソッドを使用するだけで、永続的な設定およびアドインの状態の読み取り、書き込み、または削除をプロパティ バッグのメモリ内コピーで行うことができます。During the lifetime of the session, you can just use the Settings.get, Settings.set, and Settings.remove methods to read, write, or remove persisted settings and add-in state from the in-memory copy of the property bag.

set メソッドと remove メソッドは設定プロパティ バッグのメモリ内コピーに対してのみ動作するので、アドインが関連付けられているドキュメントに新しい設定を保存、または変更された設定を保存し直すには Settings.saveAsync メソッドを呼び出す必要があります。Because the set and remove methods operate against only the in-memory copy of the settings property bag, to save new or changed settings back to the document the add-in is associated with you must call the Settings.saveAsync method.

設定値の作成または更新Creating or updating a setting value

次のコード例では、Settings.set メソッドを使用して 'themeColor' という名前の設定を作成し、値 'green' を指定する方法を説明します。set メソッドの最初のパラメーターは、設定するか作成する設定の name (Id) であり、これは大文字と小文字が区別されます。2 番目のパラメーターは、設定の value です。The following code example shows how to use the Settings.set method to create a setting called 'themeColor' with a value 'green'. The first parameter of the set method is the case-sensitive name (Id) of the setting to set or create. The second parameter is the value of the setting.

Office.context.document.settings.set('themeColor', 'green');

指定した名前を持つ設定は、それがまだ存在していない場合には作成され、すでに存在している場合はその値が更新されます。Settings.saveAsync メソッドを使用すると、新しい設定または更新された設定をドキュメントに保持できます。The setting with the specified name is created if it doesn't already exist, or its value is updated if it does exist. Use the Settings.saveAsync method to persist the new or updated settings to the document.

設定値の取得Getting the value of a setting

次の例では、Settings.get メソッドを使用して "themeColor" という名前の設定値を取得する方法を示します。get メソッドの唯一のパラメーターは、設定の name であり、これは大文字と小文字が区別されます。The following example shows how use the Settings.get method to get the value of a setting called "themeColor". The only parameter of the get method is the case-sensitive name of the setting.

write('Current value for mySetting: ' + Office.context.document.settings.get('themeColor'));

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

get メソッドでは、指定した name という設定に対して以前に保存した値を返します。設定が存在しない場合、メソッドは null を返します。The get method returns the value that was previously saved for the setting name that was passed in. If the setting doesn't exist, the method returns null.

設定の削除Removing a setting

次の例では、Settings.remove メソッドを使用して、"themeColor" という名前の設定を削除する方法を示します。remove メソッドの唯一のパラメーターは設定の name であり、これは大文字と小文字が区別されます。The following example shows how to use the Settings.remove method to remove a setting with the name "themeColor". The only parameter of the remove method is the case-sensitive name of the setting.

Office.context.document.settings.remove('themeColor');

設定が存在しない場合、何も起こりません。Nothing will happen if the setting does not exist. ドキュメントから設定を削除したままにする場合は、 Settings.saveAsync メソッドを使用します。Use the Settings.saveAsync method to persist removal of the setting from the document.

設定の保存Saving your settings

現在のセッション中に、アドインがメモリ内の設定プロパティ バッグに対して行った追加、変更、または削除を保存するには、Settings.saveAsync メソッドを呼び出してそれらの設定をドキュメントに保存する必要があります。saveAsync メソッドの唯一のパラメーターは callback であり、これはパラメーターを 1 つだけ取るコールバック関数です。To save any additions, changes, or deletions your add-in made to the in-memory copy of the settings property bag during the current session, you must call the Settings.saveAsync method to store them in the document. The only parameter of the saveAsync method is callback, which is a callback function with a single parameter.

Office.context.document.settings.saveAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Settings save failed. Error: ' + asyncResult.error.message);
    } else {
        write('Settings saved.');
    }
});
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

匿名関数は、操作が完了したときに コールバック パラメーターを実行するときに、 saveAsync メソッドに渡されます。The anonymous function passed into the saveAsync method as the callback parameter is executed when the operation is completed. AsyncResult のパラメーター、コールバックでは、操作の状態を格納している *AsyncResult* オブジェクトへのアクセスを提供します。The asyncResult parameter of the callback provides access to an AsyncResult object that contains the status of the operation. 例では、関数は ** AsyncResult.status** プロパティを調べて、保存操作が成功したのか失敗したのかを確認し、アドインのページにその結果を表示します。In the example, the function checks the AsyncResult.status property to see if the save operation succeeded or failed, and then displays the result in the add-in's page.

ドキュメントにカスタム XML を保存する方法How to save custom XML to the document

注意

このセクションでは、Word でサポートされている Office 一般的な JavaScript API のコンテキストでカスタム XML 部分について説明します。ホスト固有の Excel の JavaScript API では、カスタム XML 部分へのアクセスも提供します。Excel Api およびプログラミング パターンは、やや異なります。詳細については、 Excel の CustomXmlPartを参照してください。This section discusses custom XML parts in the context of the Office Common JavaScript API which is supported in Word. The host-specific Excel JavaScript API also provides access to the custom XML parts. The Excel APIs and programming patterns are somewhat different. For more information, see Excel CustomXmlPart.

文書設定または構成文字を含む、容量制限を超える情報を保存する必要があるときは、追加の保存オプションがあります。There is an addtional storage option when you need to store information that exceeds the size limits of the document Settings or which has a structured character. Word および Excel の作業ウィンドウ アドインには、カスタムの XML マークアップを保持できます (Excel については、このセクションの冒頭にあるノートを参照してください)。You can persist custom XML markup in a task pane add-in for Word (and for Excel, but see the note at the top of this section). Word の場合は、CustomXmlPart とそのメソッドを使用します (繰り返しになりますが、Excel の場合は上記のノートを参照してください)。In Word, you use the CustomXmlPart object and its methods (again, see the note above for Excel). 次のコードは、カスタム XML パーツを作成し、ページ上の div の ID と、そのコンテンツが表示されます。The following code creates a custom XML part and displays its ID and then its content in divs on the page. XML 文字列には xmlns 属性が必ず存在する点に注意してください。Note that there must be an xmlns attribute in the XML string.

function createCustomXmlPart() {
    const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
    Office.context.document.customXmlParts.addAsync(xmlString,
        (asyncResult) => {
            $("#xml-id").text("Your new XML part's ID: " + asyncResult.id);
            asyncResult.value.getXmlAsync(
                (asyncResult) => {
                    $("#xml-blob").text(asyncResult.value);                    
                }
            );
        }
    );
}

カスタム XML 部分を取得するには、getByIdAsync メソッドを使用しますが、ID は XML 部分の作成時に生成された GUID になるため、コードの作成時に ID の内容を知ることはできません。そのため、XML 部分を作成したら、その XML 部分の ID を設定としてすぐに保存して、覚えやすいキーを割り当てることがベスト プラクティスになります。次のメソッドでは、これを行う方法を示します。(ただし、カスタム設定を使用する場合は、詳細情報とベスト プラクティスは、この資料の前半を参照してください)。To retrieve a custom XML part, you use the getByIdAsync method, but the ID is a GUID that is generated when the XML part is created, so you can't know when coding what the ID is. For that reason, it is a good practice when creating an XML part to immediately store the ID of the XML part as a setting and give it a memorable key. The following method shows how to do this. (But see earlier sections of this article for details and best practices when working with custom settings).

function createCustomXmlPartAndStoreId() {
   const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
   Office.context.document.customXmlParts.addAsync(xmlString,
       (asyncResult) => {
           Office.context.document.settings.set('ReviewersID', asyncResult.id);
           Office.context.document.settings.saveAsync();
       }
   );
}

次のコードは、最初に設定から ID を取得することで、XML 部分を取得する方法を示しています。The following code shows how to retrieve the XML part by first getting its ID from a setting.

function getReviewers() {
   const reviewersXmlId = Office.context.document.settings.get('ReviewersID'));
   Office.context.document.customXmlParts.getByIdAsync(reviewersXmlId, 
       (asyncResult) => {
           asyncResult.value.getXmlAsync(
               (asyncResult) => {
                   $("#xml-blob").text(asyncResult.value);                    
               }
           );
       }
   );
}

Outlook アドインでユーザーのメールボックスに設定をローミング設定として保存する方法How to save settings in the user's mailbox for Outlook add-ins as roaming settings

Outlook アドインでは、RoamingSettings を使用することにより、アドインの状態およびユーザーのメールボックスに固有の設定データを保存することができます。このデータは、アドインを実行するユーザーに代わり、Outlook アドインだけがアクセスできます。データはユーザーの Exchange Server メールボックスに格納され、そのユーザーが自分のアカウントにログインして Outlookアドインを実行するとアクセスできます。An Outlook add-in can use the RoamingSettings object to save add-in state and settings data that is specific to the user's mailbox. This data is accessible only by that Outlook add-in on behalf of the user running the add-in. The data is stored on the user's Exchange Server mailbox, and is accessible when that user logs into their account and runs the Outlook add-in.

ローミング設定の読み込みLoading roaming settings

通常、Outlook アドインでは、 Office.initialize イベント ハンドラーでローミング設定を読み込みます。次の JavaScript のコード例は、既存のローミング設定を読み込む方法を示しています。An Outlook add-in typically loads roaming settings in the Office.initialize event handler. The following JavaScript code example shows how to load existing roaming settings.

var _mailbox;
var _settings;

// The initialize function is required for all add-ins.
Office.initialize = function (reason) {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
    // After the DOM is loaded, add-in-specific code can run.
   // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    });
}

ローミング設定の作成または割り当てCreating or assigning a roaming setting

前の例に続けて、次の setAppSetting 関数では、 RoamingSettings.set メソッドを使用して、 cookie という名前の設定項目に今日の日付を設定、または今日の日付で更新する方法を示しています。次に、 RoamingSettings.saveAsync メソッドを使用して Exchange Server にすべてのローミング設定を保存し直しています。Continuing with the preceding example, the following setAppSetting function shows how to use the RoamingSettings.set method to set or update a setting named cookie with today's date. Then, it saves all the roaming settings back to the Exchange Server with the RoamingSettings.saveAsync method.

// Set an add-in setting.
function setAppSetting() {
    _settings.set("cookie", Date());
    _settings.saveAsync(saveMyAppSettingsCallback);
}

// Saves all roaming settings.
function saveMyAppSettingsCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    }
}

saveAsync メソッドは、ローミング設定を非同期で保存し、オプションのコールバック関数を受け取ります。このコード例では、saveMyAppSettingsCallback という名前のコールバック関数を saveAsync メソッドに渡します。非同期呼び出しが返ると、saveMyAppSettingsCallback 関数の asyncResult パラメーターが AsyncResult オブジェクトにアクセスします。このオブジェクトを使用すると、AsyncResult.status プロパティで操作の成功または失敗を判定することができます。The saveAsync method saves roaming settings asynchronously and takes an optional callback function. This code sample passes a callback function named saveMyAppSettingsCallback to the saveAsync method. When the asynchronous call returns, the asyncResult parameter of the saveMyAppSettingsCallback function provides access to an AsyncResult object that you can use to determine the success or failure of the operation with the AsyncResult.status property.

ローミング設定の削除Removing a roaming setting

また、次の removeAppSetting 関数は、前の例をさらに拡張するものです。この例では、 RoamingSettings.remove メソッドを使用して cookie 設定を削除し、すべてのローミング設定を Exchange Server に保存し直す方法を示しています。Also extending the preceding examples, the following removeAppSetting function, shows how to use the RoamingSettings.remove method to remove the cookie setting and save all the roaming settings back to the Exchange Server.

// Remove an application setting.
function removeAppSetting()
{
    _settings.remove("cookie");
    _settings.saveAsync(saveMyAppSettingsCallback);
}

Outlook アドインでアイテムごとに設定をカスタムプロパティとして保存する方法How to save settings per item for Outlook add-ins as custom properties

カスタム プロパティを使用すると、Outlook アドインは処理しているアイテムに関する情報を保存できます。たとえば、Outlook アドインを使用して、メッセージ内の会議の提案から予定を作成する場合は、カスタム プロパティを使用して、会議が作成されたという事実を保存できます。これにより、メッセージを再び開いたときに、Outlook アドインが再び予定の作成を行うことはありません。Custom properties let your Outlook add-in store information about an item it is working with. For example, if your Outlook add-in creates an appointment from a meeting suggestion in a message, you can use custom properties to store the fact that the meeting was created. This makes sure that if the message is opened again, your Outlook add-in doesn't offer to create the appointment again.

メッセージ、予定、または会議出席依頼の特定のアイテムに対してカスタム プロパティを使用するには、その前に、 Item オブジェクトの loadCustomPropertiesAsync メソッドを呼び出して、プロパティをメモリに読み込む必要があります。現在のアイテムに対してカスタム プロパティが既に設定されている場合は、この時点で Exchange サーバーから読み込まれます。プロパティを読み込んだ後、 CustomProperties オブジェクトの set メソッドおよび get メソッドを使用して、メモリ内のプロパティの追加、更新、および取得を実行できます。アイテムのカスタム プロパティに対して行った変更を保存するには、 saveAsync メソッドを使用して、アイテムに加えた変更を Exchange サーバー上で保持する必要があります。Before you can use custom properties for a particular message, appointment, or meeting request item, you must load the properties into memory by calling the loadCustomPropertiesAsync method of the Item object. If any custom properties are already set for the current item, they are loaded from the Exchange server at this point. After you have loaded the properties, you can use the set and get methods of the CustomProperties object to add, update, and retrieve properties in memory. To save any changes that you make to the item's custom properties, you must use the saveAsync method to persist the changes to the item on the Exchange server.

カスタム プロパティの例Custom properties example

以下の例では、カスタム プロパティを使用する Outlook アドインの一連の関数を、簡略化して示しています。この例を出発点として、カスタム プロパティを使用する Outlook アドインを作成できます。The following example shows a simplified set of functions for an Outlook add-in that uses custom properties. You can use this example as a starting point for your Outlook add-in that uses custom properties.

これらの関数を使用する Outlook アドインは、次の例に示すように、 _customProps 変数で get メソッドを呼び出すことによって、任意のカスタム プロパティを取得します。An Outlook add-in that uses these functions retrieves any custom properties by calling the get method on the _customProps variable, as shown in the following example.

var property = _customProps.get("propertyName");

以下の例には、次の関数が含まれています。This example includes the following functions:

関数名Function name 説明Description
Office.initialize アドインを初期化し、Exchange サーバーから現在のアイテムのカスタム プロパティを読み込みます。Initializes the add-in and loads the custom properties for the current item from the Exchange server.
customPropsCallback Exchange サーバーから返されるカスタム プロパティを取得し、後で使用できるように保存します。Gets the custom properties that are returned from the Exchange server and saves it for later use.
updateProperty 特定のプロパティを設定または更新し、その変更を Exchange サーバーに保存します。Sets or updates a specific property, and then saves the change to the Exchange server.
removeProperty 特定のプロパティを削除し、その削除を Exchange サーバーに保存します。Removes a specific property, and then persists the removal to the Exchange server.
saveCallback updateProperty関数および removeProperty関数内でsaveAsync メソッドを呼び出すためのコールバック。Callback for calls to the saveAsync method in the updateProperty and removeProperty functions.
var _mailbox;
var _customProps;

// The initialize function is required for all add-ins.
Office.initialize = function (reason) {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
    // After the DOM is loaded, add-in-specific code can run.
    _mailbox = Office.context.mailbox;
    _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
    });
}

// Get the item's custom properties from the server and save for later use.
function customPropsCallback(asyncResult) {
    _customProps = asyncResult.value;
}

// Sets or updates the specified property, and then saves the change 
// to the server.
function updateProperty(name, value) {
    _customProps.set(name, value);
    _customProps.saveAsync(saveCallback);
}

// Removes the specified property, and then persists the removal 
// to the server.
function removeProperty(name) {
   _customProps.remove(name);
   _customProps.saveAsync(saveCallback);
}

// Callback for calls to saveAsync method. 
function saveCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    }
}

関連項目See also