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

[アーティクル]
02/29/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、、、setAsyncおよびのほとんどの非同期メソッドとaddAsync同様に、getAsync省略可能な入力パラメーターを受け取ります。これらの省略可能な入力パラメーターを指定する方法の詳細については、「 Office アドインでの非同期プログラミング」の「省略可能なパラメーターを非同期メソッドに渡す」を参照してください。

受信者を取得する

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

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

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

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

重要

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

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

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

Outlook on the webと Windows (クラシックおよび新規 (プレビュー)) では、連絡先またはプロファイルカードから連絡先のメールアドレスリンクを選択して新しいメッセージを作成した場合、最初にメールアドレスを解決して、通話の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 入力引数として指定して、受信者の設定に依存するコードが、その場合にのみ実行されるようにすることができます。コールバック関数を実装する場合は、出力パラメーターのプロパティと error プロパティをasyncResult使用statusして、非同期呼び出しの状態とエラーメッセージをチェックします。コールバック関数に追加情報を提供するには、呼び出しで省略可能な asyncContext パラメーターを setAsync 使用します。

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 は、入力引数が必要な点と同様 setAsync に recipients 機能します。必要に応じて、パラメーターを使用してコールバック関数とコールバックの任意の引数を 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.
        });
    }
}

Share via

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

受信者を取得する

受信者を設定する

受信者を追加する

関連項目

フィードバック

その他のリソース