Outlook の新規作成フォームでアイテムの添付ファイルを管理する
Office JavaScript API には、ユーザーが作成するときにアイテムの添付ファイルを管理するために使用できるいくつかの API が用意されています。
ファイルまたは Outlook アイテムを添付する
添付ファイルの種類に適したメソッドを使用して、ファイルまたは Outlook アイテムを新規作成フォームに添付できます。
- addFileAttachmentAsync: ファイルをアタッチします。
- addFileAttachmentFromBase64Async: Base64 でエンコードされた文字列を使用してファイルをアタッチします。
- addItemAttachmentAsync: Outlook アイテムをアタッチします。
これらは非同期メソッドです。つまり、アクションの完了を待たずに実行を実行できます。 追加される添付ファイルの元の場所とサイズによっては、非同期呼び出しが完了するまでに時間がかかる場合があります。
完了するアクションに依存するタスクがある場合は、コールバック関数でこれらのタスクを実行する必要があります。 このコールバック関数は省略可能であり、添付ファイルのアップロードが完了したときに呼び出されます。 コールバック関数は、 AsyncResult オブジェクトを出力パラメーターとして受け取り、添付ファイルを追加した状態、エラー、および返された値を提供します。 コールバックがその他のパラメーターを必要とする場合、オプションの options.asyncContext パラメーターでそれを指定することができます。
options.asyncContext は、コールバック関数が予期する任意の型にすることができます。
たとえば、 options.asyncContext を、1 つ以上のキーと値のペアを含む JSON オブジェクトとして定義できます。 省略可能なパラメーターを非同期メソッドに渡す方法の詳細については、「Office アドインでの 非同期プログラミング」の Office アドイン プラットフォームを参照してください。次の例では、 asyncContext パラメーターを使用して 2 つの引数をコールバック関数に渡す方法を示します。
const options = { asyncContext: { var1: 1, var2: 2 } };
Office.context.mailbox.item.addFileAttachmentAsync('https://contoso.com/rtm/icon.png', 'icon.png', options, callback);
AsyncResult オブジェクトの status プロパティと error プロパティを使用して、コールバック関数の非同期メソッド呼び出しの成功またはエラーをチェックできます。 アタッチが正常に完了した場合は、 AsyncResult.value プロパティを使用して添付ファイル ID を取得できます。 添付ファイル ID は整数であり、後で添付ファイルを削除するときに使用できます。
注:
添付ファイル ID は同じセッション内でのみ有効であり、セッション間で同じ添付ファイルにマップすることは保証されません。 セッションが終了した場合の例としては、ユーザーがアドインを閉じる場合や、ユーザーがインライン フォームで作成を開始し、その後インライン フォームをポップアウトして別のウィンドウで続行する場合などがあります。
ヒント
添付ファイルの数やサイズなど、メール アイテムに添付できるファイルまたは Outlook アイテムには制限があります。 詳細については、「 JavaScript API の制限」を参照してください。
ファイルを添付する
addFileAttachmentAsync メソッドを使用し、ファイルの URI を指定することで、新規作成フォームのメッセージまたは予定にファイルを添付できます。 また、base64 でエンコードされた文字列を入力として指定して、 addFileAttachmentFromBase64Async メソッドを使用することもできます。 If the file is protected, you can include an appropriate identity or authentication token as a URI query string parameter. Exchange will make a call to the URI to get the attachment, and the web service which protects the file will need to use the token as a means of authentication.
注:
添付するファイルの URI は、運用環境でのキャッシュをサポートしている必要があります。 イメージをホストしているサーバーは、HTTP 応答でno-cache、no-store、または同様のオプションを指定するCache-Control ヘッダーを返すべきではありません。 ただし、アドインを開発し、ファイルに変更を加えると、キャッシュによって変更が表示されない可能性があります。 開発中に Cache-Control ヘッダーを使用することをお勧めします。
次の JavaScript の例は、Web サーバーのファイル picture.png を作成中のメッセージまたは予定に添付する新規作成アドインです。 コールバック関数は、パラメーターとして asyncResult を受け取り、結果の状態を確認し、メソッドが成功した場合に添付ファイル ID を取得します。
Office.initialize = function () {
// Checks for the DOM to load using the jQuery ready method.
$(document).ready(function () {
// After the DOM is loaded, app-specific code can run.
// Add the specified file attachment to the item
// being composed.
// When the attachment finishes uploading, the
// callback function is invoked and gets the attachment ID.
// You can optionally pass any object that you would
// access in the callback function as an argument to
// the asyncContext parameter.
Office.context.mailbox.item.addFileAttachmentAsync(
`https://webserver/picture.png`,
'picture.png',
{ asyncContext: null },
function (asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Failed){
write(asyncResult.error.message);
} else {
// Get the ID of the attached file.
const attachmentID = asyncResult.value;
write('ID of added attachment: ' + attachmentID);
}
});
});
}
// Writes to a div with id='message' on the page.
function write(message){
document.getElementById('message').innerText += message;
}
作成中のメッセージまたは予定の本文にインライン base64 イメージを追加するには、addFileAttachmentFromBase64Async メソッドを使用してイメージを挿入する前に、Office.context.mailbox.item.body.getAsync メソッドを使用して現在のアイテム本文を取得する必要があります。 それ以外の場合、イメージは挿入後に本文にレンダリングされません。 ガイダンスについては、項目本文の先頭にインライン Base64 イメージを追加する次の JavaScript の例を参照してください。
const mailItem = Office.context.mailbox.item;
const base64String =
"iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";
// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
if (bodyResult.status === Office.AsyncResultStatus.Succeeded) {
// Insert the Base64 image to the beginning of the body.
const options = { isInline: true, asyncContext: bodyResult.value };
mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
if (attachResult.status === Office.AsyncResultStatus.Succeeded) {
let body = attachResult.asyncContext;
body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);
mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
if (setResult.status === Office.AsyncResultStatus.Succeeded) {
console.log("Inline Base64 image added to the body.");
} else {
console.log(setResult.error.message);
}
});
} else {
console.log(attachResult.error.message);
}
});
} else {
console.log(bodyResult.error.message);
}
});
Outlook アイテムを添付する
アイテムの Exchange Web Services (EWS) ID を指定し、 addItemAttachmentAsync メソッドを使用して、Outlook アイテム (メール、予定表、連絡先アイテムなど) を作成フォームのメッセージまたは予定に添付できます。
mailbox.makeEwsRequestAsync メソッドを使用し、EWS 操作 FindItem にアクセスすることで、ユーザーのメールボックス内の電子メール、予定表、連絡先、またはタスク アイテムの EWS ID を取得できます。 閲覧フォームの既存のアイテムでは、 item.itemId プロパティでも EWS ID が取得できます。
次の JavaScript 関数 addItemAttachment、上記の最初の例を拡張し、構成されているメールまたは予定に添付ファイルとしてアイテムを追加します。 この関数は、添付するアイテムの EWS ID を引数として受け取ります。 アタッチが成功した場合は、同じセッションでその添付ファイルを削除するなど、さらに処理するための添付ファイル ID を取得します。
// Adds the specified item as an attachment to the composed item.
// ID is the EWS ID of the item to be attached.
function addItemAttachment(itemId) {
// When the attachment finishes uploading, the
// callback function is invoked. Here, the callback
// function uses only asyncResult as a parameter,
// and if the attaching succeeds, gets the attachment ID.
// You can optionally pass any other object you wish to
// access in the callback function as an argument to
// the asyncContext parameter.
Office.context.mailbox.item.addItemAttachmentAsync(
itemId,
'Welcome email',
{ asyncContext: null },
function (asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Failed){
write(asyncResult.error.message);
} else {
const attachmentID = asyncResult.value;
write('ID of added attachment: ' + attachmentID);
}
});
}
注:
新規作成アドインを使用すると、Outlook on the web、モバイル デバイス、または新しい Outlook on Windows で定期的な予定のインスタンスをアタッチできます。 ただし、Windows または Mac でサポートされている Outlook クライアントでは、インスタンスをアタッチしようとすると、定期的なシリーズ (親の予定) がアタッチされます。
添付ファイルを取得する
作成モードで添付ファイルを取得する API は、 要件セット 1.8 から使用できます。
getAttachmentsAsync メソッドを使用して、構成されているメッセージまたは予定の添付ファイルを取得できます。
添付ファイルのコンテンツを取得するには、 getAttachmentContentAsync メソッドを使用します。 サポートされている形式は 、AttachmentContentFormat 列挙型に一覧表示されます。
AsyncResult出力パラメーター オブジェクトを使用して、状態とエラーをチェックするコールバック関数を指定する必要があります。 省略可能な asyncContext パラメーターを使用して、コールバック関数に追加のパラメーターを渡すこともできます。
次の JavaScript の例では、添付ファイルを取得し、サポートされている添付ファイル形式ごとに個別の処理を設定できます。
const item = Office.context.mailbox.item;
const options = {asyncContext: {currentItem: item}};
item.getAttachmentsAsync(options, callback);
function callback(result) {
if (result.value.length > 0) {
for (let i = 0 ; i < result.value.length ; i++) {
result.asyncContext.currentItem.getAttachmentContentAsync(result.value[i].id, handleAttachmentsCallback);
}
}
}
function handleAttachmentsCallback(result) {
// Parse string to be a url, an .eml file, a Base64-encoded string, or an .icalendar file.
switch (result.value.format) {
case Office.MailboxEnums.AttachmentContentFormat.Base64:
// Handle file attachment.
break;
case Office.MailboxEnums.AttachmentContentFormat.Eml:
// Handle email item attachment.
break;
case Office.MailboxEnums.AttachmentContentFormat.ICalendar:
// Handle .icalender attachment.
break;
case Office.MailboxEnums.AttachmentContentFormat.Url:
// Handle cloud attachment.
break;
default:
// Handle attachment formats that are not supported.
}
}
添付ファイルを削除する
removeAttachmentAsync メソッドを使用する場合は、対応する添付ファイル ID を指定することで、新規作成フォームのメッセージまたは予定アイテムからファイルまたはアイテムの添付ファイルを削除できます。
重要
要件セット 1.7 以前を使用している場合は、同じアドインが同じセッションで追加した添付ファイルのみを削除する必要があります。
addFileAttachmentAsync、addItemAttachmentAsync、getAttachmentsAsyncメソッドと同様に、removeAttachmentAsyncは非同期メソッドです。
AsyncResult出力パラメーター オブジェクトを使用して、状態とエラーをチェックするコールバック関数を指定する必要があります。 省略可能な asyncContext パラメーターを使用して、コールバック関数に追加のパラメーターを渡すこともできます。
次の JavaScript 関数 ( removeAttachment) は、上記の例を引き続き拡張し、構成されているメールまたは予定から指定された添付ファイルを削除します。 この関数は、削除する添付ファイルの ID を引数として受け取ります。
addFileAttachmentAsync、addFileAttachmentFromBase64Async、またはaddItemAttachmentAsyncメソッド呼び出しが成功した後に添付ファイルの ID を取得し、後続のremoveAttachmentAsync メソッド呼び出しで使用できます。
getAttachmentsAsync (要件セット 1.8 で導入) を呼び出して、そのアドイン セッションの添付ファイルとその ID を取得することもできます。
// Removes the specified attachment from the composed item.
function removeAttachment(attachmentId) {
// When the attachment is removed, the callback function is invoked.
// Here, the callback function uses an asyncResult parameter and
// gets the ID of the removed attachment if the removal succeeds.
// You can optionally pass any object you wish to access in the
// callback function as an argument to the asyncContext parameter.
Office.context.mailbox.item.removeAttachmentAsync(
attachmentId,
{ asyncContext: null },
function (asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
write(asyncResult.error.message);
} else {
write('Removed attachment with the ID: ' + asyncResult.value);
}
});
}
ヒント
removeAttachmentAsync メソッドは、メール アイテムからインライン添付ファイルを削除しません。 インライン添付ファイルを削除するには、まずアイテムの本文を取得し、その内容から添付ファイルの参照を削除します。
Office.Body API を使用して、アイテムの本文を取得および設定します。
関連項目
Office Add-ins