Outlook アドインのメッセージに対するインターネット ヘッダーの取得と設定

背景

Outlook アドイン開発の一般的な要件は、アドインに関連付けられているカスタム プロパティをさまざまなレベルで格納することです。 現時点では、カスタム プロパティはアイテムまたはメールボックス レベルで格納されます。

• アイテム レベル - 特定のアイテムに適用されるプロパティの場合は、 CustomProperties オブジェクトを使用します。 たとえば、電子メールを送信したユーザーに関連付けられている顧客コードを格納します。
• メールボックス レベル - ユーザーのメールボックス内のすべてのメール アイテムに適用されるプロパティの場合は、 RoamingSettings オブジェクトを 使用します。 たとえば、ユーザーの設定を保存して、特定のスケールの温度を表示します。

どちらの種類のプロパティも、アイテムが Exchange サーバーから離れた後も保持されないため、メール受信者はアイテムに設定されたプロパティを取得できません。 そのため、開発者はこれらの設定やその他の多目的インターネット メール拡張機能 (MIME) プロパティにアクセスして、読み取りシナリオを改善することはできません。

Exchange Web Services (EWS) 要求を介してインターネット ヘッダーを設定する方法もありますが、一部のシナリオでは、EWS 要求を作成しても機能しません。 たとえば、Outlook デスクトップの新規作成モードでは、アイテム ID はキャッシュ モードでは同期 saveAsync されません。

インターネット ヘッダー API の目的

メールボックス要件セット 1.8 で導入されたインターネット ヘッダー API を使用すると、開発者は次の機能を利用できます。

• すべてのクライアント間で Exchange を離れた後も保持される電子メールのスタンプ情報。
• メールがメール読み取りシナリオのすべてのクライアントにわたって Exchange を離れた後に保持された電子メールに関する情報を読み取ります。
• メールの MIME ヘッダー全体にアクセスします。

サポートされるクライアント

アドインでインターネット ヘッダー API を使用するには、Outlook クライアントで要件セット 1.8 以降がサポートされている必要があります。 サポートされているクライアントの詳細については、「 Outlook クライアントのサポート」を参照してください。

インターネット ヘッダー API は、Outlook on Android およびバージョン 4.2405.0 以降の iOS でもサポートされています。 モバイル デバイス上の Outlook でサポートされる機能の詳細については、「モバイル デバイス上の Outlook でサポートされている Outlook JavaScript API」を参照してください。

メッセージの作成中にインターネット ヘッダーを設定する

item.internetHeaders プロパティを使用して、新規作成モードで現在のメッセージに配置するカスタム インターネット ヘッダーを管理します。

カスタム インターネット ヘッダーの設定、取得、削除の例

次の例は、カスタム インターネット ヘッダーを設定、取得、および削除する方法を示しています。

// Set custom internet headers.
function setCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.setAsync(
    { "preferred-fruit": "orange", "preferred-vegetable": "broccoli", "best-vegetable": "spinach" },
    setCallback
  );
}

function setCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully set headers");
  } else {
    console.log("Error setting headers: " + JSON.stringify(asyncResult.error));
  }
}

// Get custom internet headers.
function getSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.getAsync(
    ["preferred-fruit", "preferred-vegetable", "best-vegetable", "nonexistent-header"],
    getCallback
  );
}

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Selected headers: " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Error getting selected headers: " + JSON.stringify(asyncResult.error));
  }
}

// Remove custom internet headers.
function removeSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.removeAsync(
    ["best-vegetable", "nonexistent-header"],
    removeCallback);
}

function removeCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed selected headers");
  } else {
    console.log("Error removing selected headers: " + JSON.stringify(asyncResult.error));
  }
}

setCustomHeaders();
getSelectedCustomHeaders();
removeSelectedCustomHeaders();
getSelectedCustomHeaders();

/* Sample output:
Successfully set headers
Selected headers: {"best-vegetable":"spinach","preferred-fruit":"orange","preferred-vegetable":"broccoli"}
Successfully removed selected headers
Selected headers: {"preferred-fruit":"orange","preferred-vegetable":"broccoli"}
*/

メッセージの読み取り中にインターネット ヘッダーを取得する

item.getAllInternetHeadersAsync を呼び出して、読み取りモードで現在のメッセージのインターネット ヘッダーを取得します。

現在の MIME ヘッダーから送信者の基本設定を取得する例

前のセクションの例を基に、次のコードは、現在のメールの MIME ヘッダーから送信者の基本設定を取得する方法を示しています。

Office.context.mailbox.item.getAllInternetHeadersAsync(getCallback);

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Sender's preferred fruit: " + asyncResult.value.match(/preferred-fruit:.*/gim)[0].slice(17));
    console.log("Sender's preferred vegetable: " + asyncResult.value.match(/preferred-vegetable:.*/gim)[0].slice(21));
  } else {
    console.log("Error getting preferences from header: " + JSON.stringify(asyncResult.error));
  }
}

/* Sample output:
Sender's preferred fruit: orange
Sender's preferred vegetable: broccoli
*/

推奨プラクティス

現在、インターネット ヘッダーは、ユーザーのメールボックス上の有限リソースです。 クォータが不足すると、そのメールボックスにインターネット ヘッダーをこれ以上作成できないため、この機能に依存するクライアントから予期しない動作が発生する可能性があります。

アドインでインターネット ヘッダーを作成する場合は、次のガイドラインを適用します。

• 必要なヘッダーの最小数をCreateします。 ヘッダー クォータは、メッセージに適用されるヘッダーの合計サイズに基づいています。 Exchange Onlineでは、ヘッダーの上限は 256 KB ですが、Exchange オンプレミス環境では、organizationの管理者によって制限が決定されます。 ヘッダーの制限の詳細については、「Exchange Online メッセージ制限とメッセージ制限Exchange Server」を参照してください。
• 後で値を再利用して更新できるように、ヘッダーに名前を付けます。 そのため、(ユーザー入力やタイムスタンプなどに基づくなど) 可変の方法でヘッダーに名前を付けるのは避けてください。

関連項目

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