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

インターネット ヘッダーを使用すると、Outlook アドインは、メッセージが Exchange から離れた後も保持される送信メッセージにカスタムキー値データを添付できます。 アイテム レベルのカスタム プロパティとは異なり、インターネット ヘッダーはメールと共に移動するため、受信者のアドインで読み取ることができます。 この記事では、メッセージの作成中にインターネット ヘッダーを設定する方法と、受信したメッセージから読み取る方法について説明します。

インターネット ヘッダーを使用する理由

Outlook アドインは、さまざまなスコープでカスタム データを格納できます。

• 項目レベル: セッション間で 1 つの項目に関連付けられている値には CustomProperties を使用し、現在の作成セッション中にのみ必要な値については SessionData を使用します。
• メールボックス レベル: ユーザーのメールボックス全体に適用される値には RoamingSettings を使用します。

これらのオプションは、Exchange を離れるとメッセージに保持されないため、受信者はこれらの値を読み取ることはできません。 インターネット ヘッダーは、この制限に対処します。

メールボックス要件セット 1.8 で導入されたインターネット ヘッダー API を使用すると、次の処理を行うことができます。

• クライアント間で Exchange を離れた後も保持される電子メールのスタンプ情報。
• クライアント間の読み取りシナリオで、電子メールから永続化された情報を読み取ります。
• メールの完全な MIME ヘッダーにアクセスします。

Exchange オンプレミス環境では、Exchange Web サービス (EWS) 要求を通じてインターネット ヘッダーを設定できます。 ただし、一部のシナリオは失敗する可能性があります。 たとえば、Outlook デスクトップの作成モードでは、アイテム ID はキャッシュ モードの saveAsync では同期されません。

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

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

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

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

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

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

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

// 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
*/

推奨プラクティス

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

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

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

関連項目

• Outlook アドインのアドイン メタデータを取得および設定する
• Outlook アドインでのアクティブ化と API の使用の制限