Hinzufügen und Entfernen von Anhängen bei einem Element in einer Entwurfsvorlage in OutlookAdd and remove attachments to an item in a compose form in Outlook

Zum Anhängen einer Datei oder eines Outlook-Elements an das Element, das gerade erstellt wird, können Sie die Methoden addFileAttachmentAsync und addItemAttachmentAsync verwenden. Beide Methoden sind asynchrone Methoden, das heißt, der Vorgang kann fortgesetzt werden, auch wenn die Aktion zum Hinzufügen der Anlage noch ausgeführt wird. Je nach dem ursprünglichen Speicherort und der Größe der hinzuzufügenden Anlage dauert die Ausführung des asynchronen Aufrufs einen Moment. Stehen Aufgaben an, die vom Abschluss der Aktion abhängig sind, müssen Sie diese Aufgaben mit einer Rückrufmethode ausführen. Diese Rückrufmethode ist optional und wird angestoßen, wenn der Upload der Anlage abgeschlossen ist. Die Rückrufmethode hat ein AsyncResult-Objekt als Ausgabeparameter, das Status, Fehler und Rückgabewert der "add-attachment"-Aktion liefert. Sollte der Rückruf zusätzliche Parameter erfordern, können Sie diese in einem optionalen options.aysncContext-Parameter angeben. options.asyncContext kann von beliebiger Art sein, sofern die Rückrufmethode diese akzeptiert.You can use the addFileAttachmentAsync and addItemAttachmentAsync methods to attach a file and an Outlook item respectively to the item that the user is composing. Both are asynchronous methods, which means execution can go on without waiting for the add-attachment action to complete. Depending on the original location and size of the attachment being added, the add-attachment asynchronous call may take a while to complete. If there are tasks that depend on the action to complete, you should carry out those tasks in a callback method. This callback method is optional and is invoked when the uploading of the attachment is complete. The callback method takes an AsyncResult object as an output parameter that provides any status, error, and returned value from the add-attachment action. If the callback requires any extra parameters, you can specify them in the optional options.aysncContext parameter. options.asyncContext can be of any type that your callback method expects.

Beispiel: Sie legen options.asyncContext als JSON-Objekt fest, das mindestens ein Schlüsselwertpaar enthält. Weitere Beispiele zur Übergabe von optionalen Parametern an asynchrone Methoden finden Sie auf der Office-Add-Ins Plattform in Asynchrone Programmierung in Office-Add-Ins. Im folgenden Beispiel sehen Sie, wie Sie den asyncContext-Parameter zum Übergeben von zwei Argumenten an eine Rückrufmethode verwenden:For example, you can define options.asyncContext as a JSON object that contains one or more key-value pairs, with the ':' character separating a key and the value, and a ',' separating one key-value pair from another. You can find more examples about passing optional parameters to asynchronous methods in the Office Add-ins platform in Asynchronous programming in Office Add-ins. The following example shows how to use the asyncContext parameter to pass 2 arguments to a callback method:

var options = { asyncContext: { var1: 1, var2: 2} };

Office.context.mailbox.item.addFileAttachmentAsync('https://contoso.com/rtm/icon.png', 'icon.png', options, callback);

Mit den Eigenschaften status und error des AsyncResult-Objekts können prüfen, ob der asynchrone Methodenaufruf in der Rückrufmethode erfolgreich war oder nicht. War das Anhängen erfolgreich, verwenden Sie die AsyncResult.value-Eigenschaft, um die Anlage-ID abzurufen. Die Anlage-ID ist eine Ganzzahl, die Sie später zum Entfernen der Anlage benötigen.You can check for success or error of an asynchronous method call in the callback method using the status and error properties of the AsyncResult object. If the attaching completes successfully, you can use the AsyncResult.value property to get the attachment ID. The attachment ID is an integer which you can subsequently use to remove the attachment.

Hinweis

Als bewährte Vorgehensweise sollten Sie die Anlagen-ID nur dann zum Entfernen einer Anlage verwenden, wenn das gleiche Add-In die Anlage in der gleichen Sitzung hinzugefügt hat.Note As a best practice, you should use the attachment ID to remove an attachment only if the same add-in has added that attachment in the same session. In Outlook im Web und OWA für Geräte ist die Anlagen-ID nur innerhalb der gleichen Sitzung gültig.In Outlook on the web and OWA for Devices, the attachment ID is valid only within the same session. Eine Sitzung ist abgeschlossen, wenn der Benutzer das Add-In schließt, oder wenn der Benutzer in einem eingebetteten Formular mit dem Verfassen beginnt und den Vorgang dann in einem separaten Fenster fortsetzt.A session is over when the user closes the add-in, or if the user starts composing in an inline form and subsequently pops out the inline form to continue in a separate window.

Datei anhängenAttaching a file

Sie können einer Nachricht oder einem Termin in einer Entwurfsvorlage eine Anlage mit der addFileAttachmentAsync-Methode hinzufügen und den Datei-URI dabei angeben. Ist die Datei geschützt, können Sie ein entsprechendes Identitäts- oder Authentifizierungstoken als Parameter der URI-Abfragezeichenfolge mit einschließen. Exchange ruft den URI auf, um die Anlage abzurufen, und der Webdienst, der die Datei schützt, verwendet das Token als Authentifizierung.You can attach a file to a message or appointment in a compose form by using the addFileAttachmentAsync method and specifying the URI of the file. 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.

Das folgende JavaScript-Beispiel zeigt ein Entwurfs-Add-in, das eine Datei (picture.png) von einem Webserver an die Nachricht bzw. den Termin anhängt, die bzw. der gerade erstellt wird. Die Rückrufmethode verwendet asyncResult als Parameter, prüft den Anhängestatus und ruft die Anlage-ID ab, falls die Methode erfolgreich ist.The following JavaScript example is a compose add-in that attaches a file, picture.png, from a web server to the message or appointment being composed. The callback method takes asyncResult as a parameter, checks for the attaching status, and gets the attachment ID if the attaching succeeds.

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(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 method is invoked and gets the attachment ID. 
        // You can optionally pass any object that you would  
        // access in the callback method 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.
                    var 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; 
}

Outlook-Element anhängenAttaching an Outlook item

Sie können ein Outlook-Element (wie E-Mail, Kalender oder Kontakte) an eine Nachricht oder einen Termin in einer Entwurfsvorlage anhängen, indem Sie die EWS-ID (Exchange Web Services) des Elements angeben und die addItemAttachmentAsync-Methode verwenden. Die EWS-ID eines E-Mail-, Kalender-, Kontakt- oder Aufgabenelements können Sie aus dem Benutzerpostfach mit der mailbox.makeEwsRequestAsync-Methode abrufen, indem Sie auf den EWS-Vorgang FindItem zugreifen. Die item.itemId-Eigenschaft liefert Ihnen auch die EWS-ID eines vorhandenen Elements in einem Leseformular.You can attach an Outlook item (for example, email, calendar, or contact item) to a message or appointment in a compose form by specifying the Exchange Web Services (EWS) ID of the item and using the addItemAttachmentAsync method. You can get the EWS ID of an email, calendar, contact or task item in the user's mailbox by using the mailbox.makeEwsRequestAsync method and accessing the EWS operation FindItem. The item.itemId property also provides the EWS ID of an existing item in a read form.

Die folgende JavaScript-Funktion, addItemAttachment, erweitert das obige erste Beispiel und fügt ein Element als Anlage zu einer E-Mail oder einem Termin hinzu, die bzw. der gerade erstellt wird. Diese Funktion hat die EWS-ID des anzuhängenden Elements als Argument. Ist das Anhängen erfolgreich, ruft sie die Anlage-ID für eine weitere Verarbeitung in derselben Sitzung, wie Entfernen der Anlage, ab.The following JavaScript function, addItemAttachment, extends the first example above, and adds an item as an attachment to the email or appointment that is being composed. The function takes as an argument the EWS ID of the item that is to be attached. If the attaching succeeds, it gets the attachment ID for further processing, including removing that attachment in the same session.

// 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 method is invoked. Here, the callback
    // method 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 method 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 {
                var attachmentID = asyncResult.value;
                write('ID of added attachment: ' + attachmentID);
            }
        });
}

Hinweis

Sie können ein Verfassen-Add-In an eine Instanz einer Terminserie in Outlook im Web oder OWA für Geräte anfügen.Note You can use a compose add-in to attach an instance of a recurring appointment in Outlook on the web or OWA for Devices. In einem unterstützenden Outlook-Rich-Client würde der Versuch, eine Instanz anzufügen, jedoch dazu führen, dass die Terminserie (der Mastertermin) angefügt wird.However, in a supporting Outlook rich client, attempting to attach an instance would result in attaching the recurring series (the master appointment).

Anlage entfernenRemoving an attachment

Sie können eine angehängte Datei oder ein Element aus einer Nachricht oder einem Termin in einer Entwurfsvorlage entfernen, indem Sie die entsprechende Anlage-ID angeben und die Methode removeAttachmentAsync verwenden. Sie können nur Anlagen entfernen, die ein Add-In in ein und derselben Sitzung hinzugefügt hat. Vergewissern Sie sich, dass die Anlage-ID zu einer gültigen Anlage gehört, andernfalls würde die Methode einen Fehler zurückgeben. Ähnlich wie addFileAttachmentAsync und addItemAttachmentAsync ist removeAttachmentAsync eine asynchrone Methode. Mit einer Rückrufmethode und dem AsyncResult-Ausgabeparameterobjekt prüfen Sie Status und mögliche Fehler. Sie können über den optionalen asyncContext-Parameter zusätzliche Parameter an die Rückrufmethode übergeben.You can remove a file or item attachment from a message or appointment item in a compose form by specifying the corresponding attachment ID and using the removeAttachmentAsync method. You should remove only attachments that the same add-in has added in the same session. You should make sure the attachment ID corresponds to a valid attachment, or the method will return an error. Similar to the addFileAttachmentAsync and addItemAttachmentAsync methods, removeAttachmentAsync is an asynchronous method. You should provide a callback method to check for the status and any error by using the AsyncResult output parameter object. You can also pass any additional parameters to the callback method by using the optional asyncContext parameter, which is a JSON object of key-value pairs.

Die folgende JavaScript-Funktion, removeAttachment, erweitert das obige Beispiel und entfernt die angegebene Anlage aus der E-Mail oder dem Termin, die bzw. der gerade erstellt wird. Diese Funktion hat die ID der zu entfernenden Anlage als Argument. Sie rufen die Anlage-ID nach einem erfolgreichen addFileAttachmentAsync- oder addItemAttachmentAsync-Methodenaufruf ab und speichern sie für einen späteren removeAttachmentAsync-Methodenaufruf.The following JavaScript function, removeAttachment, continues to extend the examples above, and removes the specified attachment from the email or appointment that is being composed. The function takes as an argument the ID of the attachment to be removed. You can obtain the ID of an attachment after a successful addFileAttachmentAsync or addItemAttachmentAsync method call, and store it for a subsequent removeAttachmentAsync method call.

// Removes the specified attachment from the composed item.
// ID is the Exchange identifier of the attachment to be 
// removed. 
function removeAttachment(attachmentId) {
    // When the attachment is removed, the
    // callback method is invoked. Here, the callback
    // method 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 method 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);
            }
        });
}

Weitere RessourcenAdditional resources