Outlook の予定またはメッセージを作成するときに受信者を取得、設定、追加する

[アーティクル]
08/02/2024

Office JavaScript API は、それぞれ、予定またはメッセージの新規作成形式に受信者を取得、設定、または追加するための非同期メソッド (Recipients.getAsync、 Recipients.setAsync、または Recipients.addAsync) を提供します。これらの非同期メソッドは、アドインの作成にのみ使用できます。これらのメソッドを使用するには、「新規作成フォームの Outlook アドインを作成する」で説明されているように、Outlook が新規作成フォームでアドインをアクティブ化するためにアドインマニフェストを適切に設定していることを確認します。

予定やメッセージ内の受信者を表すプロパティの一部は、新規作成フォームと閲覧フォームで読み取りアクセスで使用できます。予定の optionalAttendees と requiredAttendees、メッセージの cc と to がこの種のプロパティに含まれます。

閲覧フォームでは、以下のように親オブジェクトから直接プロパティにアクセスできます。

Office.context.mailbox.item.cc;

ただし、新規作成フォームでは、ユーザーとアドインの両方が同時に受信者を挿入または変更できるため、次の例のように、非同期メソッド getAsync を使用してこれらのプロパティを取得する必要があります。

Office.context.mailbox.item.cc.getAsync(callback);

これらのプロパティは、新規作成フォームでのみ書き込みアクセスでき、読み取りフォームでは使用できません。

JavaScript API for Office のほとんどの非同期メソッドと同様に、 getAsync、 setAsync、 addAsync は省略可能な入力パラメーターを受け取ります。これらの省略可能な入力パラメーターを指定する方法の詳細については、「 Office アドインでの非同期プログラミング」の「省略可能なパラメーターを非同期メソッドに渡す」を参照してください。

受信者を取得する

このセクションでは、新規作成する予定やメッセージの受信者を取得し、その受信者の電子メールアドレスを表示するコード例を示します。

Office JavaScript API では、予定の受信者 (optionalAttendees と requiredAttendees) を表すプロパティがメッセージ (bcc、 cc、 to) とは異なるため、最初に item.itemType プロパティを使用して、構成されているアイテムが予定かメッセージかを特定する必要があります。新規作成モードでは、これらの予定とメッセージのプロパティはすべて Recipients オブジェクトであるため、非同期メソッド ( Recipients.getAsync) を呼び出して対応する受信者を取得できます。

getAsyncを使用するには、コールバック関数を指定して、非同期getAsync呼び出しによって返された状態、結果、エラーを確認します。コールバック関数は、asyncResult 出力パラメーターを返します。 statusプロパティとerrorプロパティを使用して、非同期呼び出しの状態とエラーメッセージを確認し、そのvalue プロパティを使用して実際の受信者を取得します。受信者は、EmailAddressDetails オブジェクトの配列として表されます。また、getAsync 呼び出しで省略可能な asyncContext パラメーターを使用して、コールバック関数に追加情報を提供することもできます。

getAsync メソッドは非同期であるため、受信者を正常に取得することに依存する後続のアクションがある場合は、非同期呼び出しが正常に完了した場合にのみ、対応するコールバック関数でこのようなアクションを開始するようにコードを整理する必要があることに注意してください。

重要

getAsync メソッドは、Outlook クライアントによって解決された受信者のみを返します。解決された受信者には、次の特性があります。

受信者が送信者のアドレス帳に保存されたエントリを持っている場合、Outlook は電子メールアドレスを受信者の保存された表示名に解決します。
Teams 会議の状態アイコンは、受信者の名前またはメールアドレスの前に表示されます。
受信者の名前またはメールアドレスの後にセミコロンが表示されます。
受信者の名前または電子メールアドレスは、下線が付いたり、ボックスに囲まれたりします。

メールアドレスがメールアイテムに追加されたら解決するには、送信者が Tab キーを使用するか、自動入力リストから推奨される連絡先またはメールアドレスを選択する必要があります。

Outlook on the web と windows (new and classic) では、連絡先またはプロファイルカードから連絡先のメールアドレスリンクを選択して新しいメッセージを作成する場合は、最初にメールアドレスを解決して、 getAsync 呼び出しの結果に含める必要があります。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getAllRecipients();
    }
});

// Gets the email addresses of all the recipients of the item being composed.
function getAllRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Get the recipients from the To or Required field of the item being composed.
    toRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the To or Required field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Cc or Optional field of the item being composed.
    ccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the Cc or Optional field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Bcc field of the message being composed, if applicable.
    if (bccRecipients.length > 0) {
        bccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients.
        write(`Recipients in the Bcc field: ${displayAddresses(asyncResult.value)}`);
        });
    } else {
        write("Recipients in the Bcc field: None");
    }
}

// Displays the email address of each recipient.
function displayAddresses (recipients) {
    for (let i = 0; i < recipients.length; i++) {
        write(recipients[i].emailAddress);
    }
}

// Writes to a div with id="message" on the page.
function write(message) {
    document.getElementById("message").innerText += message;
}

受信者を設定する

このセクションでは、ユーザーが新規作成する予定やメッセージの受信者を設定するコード例を示しています。受信者を設定すると、既存の受信者が上書きされます。この例では、最初にメールアイテムが予定またはメッセージであるかどうかを確認し、予定またはメッセージの受信者を表す適切なプロパティで非同期メソッド ( Recipients.setAsync) を呼び出すことができるようにします。

setAsyncを呼び出すときは、次のいずれかの形式で、recipients パラメーターの入力引数として配列を指定します。

SMTP アドレスである文字列の配列。
辞書の配列。次のコード例に示されているように、それぞれ表示名と電子メールアドレスが含まれています。
getAsync メソッドから返されたものと同様に、EmailAddressDetails オブジェクトの配列。

必要に応じて、 setAsync メソッドへの入力引数としてコールバック関数を指定して、受信者の設定に成功に依存するすべてのコードが、その場合にのみ実行されるようにすることができます。コールバック関数を実装する場合は、asyncResult出力パラメーターの status プロパティと error プロパティを使用して、非同期呼び出しの状態とエラーメッセージを確認します。コールバック関数に追加情報を提供するには、setAsync呼び出しで省略可能な asyncContext パラメーターを使用します。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setRecipients();
    }
});

// Sets the recipients of the item being composed.
function setRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Set the recipients in the To or Required field of the item being composed.
    toRecipients.setAsync(
        [{
            "displayName": "Graham Durkin", 
            "emailAddress": "graham@contoso.com"
         },
         {
            "displayName": "Donnie Weinberg",
            "emailAddress": "donnie@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the To or Required field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Cc or Optional field of the item being composed.
    ccRecipients.setAsync(
        [{
            "displayName": "Perry Horning", 
            "emailAddress": "perry@contoso.com"
         },
         {
            "displayName": "Guy Montenegro",
            "emailAddress": "guy@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the Cc or Optional field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Bcc field of the message being composed.
    if (bccRecipients) {
        bccRecipients.setAsync(
            [{
                "displayName": "Lewis Cate", 
                "emailAddress": "lewis@contoso.com"
            },
            {
                "displayName": "Francisco Stitt",
                "emailAddress": "francisco@contoso.com"
            }],
            (asyncResult) => {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    console.log(asyncResult.error.message);
                    return;
                }
    
                console.log("Successfully set the recipients in the Bcc field.");
                // Run additional operations appropriate to your scenario.
        });
    }
}

受信者を追加する

予定またはメッセージ内の既存の受信者を上書きしない場合は、 Recipients.setAsyncを使用するのではなく、 Recipients.addAsync 非同期メソッドを使用して受信者を追加します。 addAsyncは、recipients入力引数が必要であるという点で、setAsyncと同様に機能します。必要に応じて、コールバック関数と、 asyncContext パラメーターを使用してコールバックの任意の引数を指定できます。次に、コールバック関数のasyncResult出力パラメーターを使用して、非同期addAsync呼び出しの状態、結果、およびエラーを確認します。次の例では、構成されているアイテムが予定であるかどうかを確認し、2 人の必須出席者を追加します。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        addAttendees();
    }
});

// Adds the specified recipients as required attendees of the appointment.
function addAttendees() {
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        item.requiredAttendees.addAsync(
        [{
            "displayName": "Kristie Jensen",
            "emailAddress": "kristie@contoso.com"
         },
         {
            "displayName": "Pansy Valenzuela",
            "emailAddress": "pansy@contoso.com"
          }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully added the required attendees.");
            // Run additional operations appropriate to your scenario.
        });
    }
}

次の方法で共有

Outlook の予定またはメッセージを作成するときに受信者を取得、設定、追加する

受信者を取得する

受信者を設定する

受信者を追加する

関連項目

その他のリソース