Outlook の新規作成フォームでアイテムの添付ファイルを管理する

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

Office JavaScript API には、ユーザーが作成するときにアイテムの添付ファイルを管理するために使用できるいくつかの API が用意されています。

ファイルまたは Outlook アイテムを添付する

添付ファイルの種類に適したメソッドを使用して、ファイルまたは Outlook アイテムを新規作成フォームに添付できます。

addFileAttachmentAsync: ファイルをアタッチします。
addFileAttachmentFromBase64Async: Base64 でエンコードされた文字列を使用してファイルをアタッチします。
addItemAttachmentAsync: Outlook アイテムをアタッチします。

これらは非同期メソッドです。つまり、アクションの完了を待たずに実行を実行できます。追加される添付ファイルの元の場所とサイズによっては、非同期呼び出しが完了するまでに時間がかかる場合があります。

完了するアクションに依存するタスクがある場合は、コールバック関数でこれらのタスクを実行する必要があります。このコールバック関数は省略可能であり、添付ファイルのアップロードが完了したときに呼び出されます。コールバック関数は、 AsyncResult オブジェクトを出力パラメーターとして受け取り、添付ファイルを追加した状態、エラー、および返された値を提供します。コールバックがその他のパラメーターを必要とする場合、オプションの options.asyncContext パラメーターでそれを指定することができます。 options.asyncContext は、コールバック関数が予期する任意の型にすることができます。

たとえば、1 つ以上のキーと値のペアを含む JSON オブジェクトとして定義 options.asyncContext できます。省略可能なパラメーターを非同期メソッドに渡す方法の詳細については、「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);

オブジェクトのプロパティと error プロパティAsyncResultを使用してstatus、コールバック関数の非同期メソッド呼び出しの成功またはエラーをチェックできます。添付が正常に完了した場合は、プロパティを 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.

次の 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 を指定し、メソッドを使用して、Outlook アイテム (メール、予定表、連絡先アイテムなど) を作成フォームのメッセージまたは予定に addItemAttachmentAsync 添付できます。 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 以前を使用している場合は、同じアドインが同じセッションで追加した添付ファイルのみを削除する必要があります。

、addFileAttachmentAsyncaddItemAttachmentAsync、およびメソッドとgetAttachmentsAsync同様に、removeAttachmentAsync非同期メソッドです。出力パラメーターオブジェクトを使用して、状態とエラーをチェックするコールバック関数を指定するAsyncResult必要があります。省略可能な asyncContext パラメーターを使用して、コールバック関数に追加のパラメーターを渡すこともできます。

次の JavaScript 関数は、 removeAttachment上記の例を引き続き拡張し、構成されているメールまたは予定から指定された添付ファイルを削除します。この関数は、削除する添付ファイルの ID を引数として受け取ります。添付ファイルの ID は、またはaddItemAttachmentAsyncメソッド呼び出しが成功したaddFileAttachmentAsyncaddFileAttachmentFromBase64Async後に取得し、後続removeAttachmentAsyncのメソッド呼び出しで使用できます。 (要件セット 1.8 で導入された) を呼び出 getAttachmentsAsync して、そのアドインセッションの添付ファイルとその 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);
            }
        });
}

Share via

Outlook の新規作成フォームでアイテムの添付ファイルを管理する

ファイルまたは Outlook アイテムを添付する

ファイルを添付する

Outlook アイテムを添付する

添付ファイルを取得する

添付ファイルを削除する

関連項目

フィードバック

その他のリソース