Freigeben über


Anfügen großer Dateien an Outlook-Nachrichten oder -Ereignisse

Mithilfe der Microsoft Graph-API können Sie Dateien mit einer Größe von bis zu 150 MB an eine Outlook-Nachrichten- oder Ereigniselemente anfügen. Abhängig von der Dateigröße wählen Sie eine von zwei Optionen zum Anfügen der Datei aus:

  • Wenn die Dateigröße weniger als 3 MB beträgt, führen Sie in der Navigationseigenschaft attachments des Outlook-Elements ein einziges POST aus. Hier finden Sie entsprechende Informationen für eine Nachricht oder für ein Ereignis. Die erfolgreiche POST-Antwort enthält die ID der Dateianlage.
  • Wenn die Dateigröße zwischen 3 MB und 150 MB liegt, richten Sie eine Upload-Sitzung ein und laden Sie mit PUT nacheinander Byte-Bereiche der Datei hoch, bis Sie die gesamte Datei hochgeladen haben. Eine Kopfzeile in der endgültigen erfolgreichen PUT-Antwort enthält eine URL mit der Anlagen-ID.

Wenn Sie mehrere Dateien an eine Nachricht anfügen möchten, wählen Sie den Ansatz für jede Datei auf Grundlage der Dateigröße aus, und fügen Sie die Dateien einzeln an.

Dieser Artikel veranschaulicht Schritt für Schritt den zweiten Ansatz, nämlich das Einrichten und Verwenden einer Upload-Sitzung, um einem Outlook-Element einen großen Dateianhang (mit einer Größe von über 3 MB) hinzuzufügen. Jeder Schritt enthält den entsprechenden Code für eine Nachricht und für ein Ereignis. Nach dem erfolgreichen Hochladen der gesamten Datei zeigt der Artikel, wie ein Antwortheader abgerufen wird, der eine ID für die Dateianlage enthält, und dann diese Dateianlagen-ID verwendet wird, um den unformatierten Inhalt des Anhangs oder die Metadaten des Anhangs abzurufen.

Wichtig

Beachten Sie ein bekanntes Problem, wenn Sie große Dateien an eine Nachricht oder ein Ereignis in einem freigegebenen oder delegierten Postfach anfügen.

Schritt 1: Erstellen einer Uploadsitzung

Erstellen Sie eine Upload-Sitzung, um eine Datei an eine Nachricht oder ein Ereignis anzufügen. Geben Sie die Datei im Eingabeparameter AttachmentItem an.

Ein erfolgreicher Vorgang gibt HTTP 201 Created und eine neue uploadSession-Instanz zurück, die eine opake URL enthält, die Sie in nachfolgenden PUT-Vorgängen zum Hochladen von Teilen der Datei verwenden können. Die uploadSession bietet einen temporären Speicherort, an dem die Bytes der Datei gespeichert werden, bis der Upload vollständig abgeschlossen ist.

Das uploadSession-Objekt in der Antwort enthält außerdem die nextExpectedRanges-Eigenschaft, die angibt, dass der Startspeicherort des anfänglichen Uploads Byte 0 sein sollte.

Berechtigungen

Stellen Sie sicher, dass die Mail.ReadWrite-Berechtigung zum Erstellen der uploadSession für eine Nachricht und die Calendars.ReadWrite-Berechtigung für ein Ereignis angefordert wird.

Die opake URL, die in der uploadUrl-Eigenschaft der neuen uploadSession zurückgegeben wird, ist bereits authentifiziert und enthält das entsprechende Autorisierungstoken für nachfolgende PUT-Abfragen in der https://outlook.office.com-Domäne. Dieses Token läuft zum Zeitpunkt expirationDateTimeab. Passen Sie diese URL nicht für die PUT-Vorgänge an.

Beispiel: Upload-Sitzung für eine Nachricht erstellen

Anforderung

POST https://graph.microsoft.com/v1.0/me/messages/AAMkADI5MAAIT3drCAAA=/attachments/createUploadSession
Content-type: application/json

{
  "AttachmentItem": {
    "attachmentType": "file",
    "name": "flower",
    "size": 3483322
  }
}

Antwort

Die folgende Beispielantwort zeigt die für die Nachricht zurückgegebene uploadSession-Ressource.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI",
    "expirationDateTime": "2019-09-25T01:09:30.7671707Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

Beispiel: Upload-Sitzung für ein Ereignis erstellen

Anforderung

POST https://graph.microsoft.com/v1.0/me/events/AAMkADU5CCmSAAA=/attachments/createUploadSession
Content-type: application/json

{
  "AttachmentItem": {
    "attachmentType": "file",
    "name": "flower",
    "size": 3483322
  }
}

Antwort

Die folgende Beispielantwort zeigt die für das Ereignis zurückgegebene uploadSession-Ressource.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw",
    "expirationDateTime": "2020-02-22T02:46:56.7410786Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

Schritt 2: Verwenden der Upload-Sitzung zum Hochladen eines Bytebereichs der Datei

Wenn Sie die Datei oder einen Teil der Datei hochladen möchten, erstellen Sie eine PUT-Anforderung an die in Schritt 1 in der uploadUrl-Eigenschaft der uploadSession-Ressource zurückgegebene URL. Sie können die gesamte Datei auf einmal hochladen oder die Datei in mehrere Bytebereiche aufteilen. Um die Leistung zu verbessern, halten Sie jeden Byte-Bereich kleiner als 4 MB.

Geben Sie den Header und den Text der Anforderung so an, wie es nachstehend beschrieben wird.

Anforderungsheader

Name Typ Beschreibung
Content-Length Int32 Die Anzahl von Bytes, die in diesem Vorgang hochgeladen werden. Um die Leistung zu verbessern, halten Sie die Obergrenze für die Anzahl der Bytes für jeden PUT-Vorgang bei höchstens 4 MB. Erforderlich.
Content-Range Zeichenfolge Der 0-basierte Byte-Bereich der Datei, die in diesem Vorgang hochgeladen wird. Wird im Format bytes {start}-{end}/{total} angegeben. Erforderlich.
Content-Type Zeichenfolge Der MIME-Typ. application/octet-stream angeben. Erforderlich.

Geben Sie keinen Authorization-Anforderungsheader an. Die PUT-Abfrage verwendet eine vorauthentifizierte URL aus der uploadUrl-Eigenschaft, die den Zugriff auf die https://outlook.office.com-Domäne ermöglicht.

Anforderungstext

Geben Sie die tatsächlichen Bytes der anzufügenden Datei an, die sich im im Content-Range-Anforderungsheader angegebenen Speicherbereich befinden.

Antwort

Bei einem erfolgreichen Upload wird HTTP 200 OK und ein uploadSession-Objekt zurückgegeben. Beachten Sie Folgendes im Antwortobjekt:

  • Die Eigenschaft ExpirationDateTime gibt das Ablaufdatum/die Uhrzeit für das Auth-Token an, das in den uploadUrl-Eigenschaftswert eingebettet ist. Dieser Ablauftermin bleibt unverändert gegenüber dem, der vom anfänglichen uploadSession in Schritt 1 zurückgegeben wird.
  • In NextExpectedRanges wird der nächste Byte-Speicherort angegeben, aus dem der Upload gestartet werden soll, z. B. "nextExpectedRanges":["2097152"]. Sie müssen die Bytes einer Datei in der korrekten Reihenfolge hochladen.
  • Die Eigenschaft uploadUrl wird nicht explizit zurückgegeben, da alle PUT-Vorgänge einer Upload-Sitzung die gleiche URL verwenden, die beim Erstellen der Sitzung zurückgegeben wird (Schritt 1).

Beispiel: Erster Upload in die Nachricht

Anforderung

PUT https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI
Content-Type: application/octet-stream
Content-Length: 2097152
Content-Range: bytes 0-2097151/3483322

{
  <bytes 0-2097151 of the file to be attached, in binary format>
}

Antwort

Die folgende Beispielantwort zeigt in der NextExpectedRanges-Eigenschaft den Beginn des nächsten Bytebereichs, den der Server erwartet.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Users('a8e8e219-4931-95c1-b73d-62626fd79c32%4072aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA%3D')/AttachmentSessions/$entity",
  "ExpirationDateTime":"2019-09-25T01:09:30.7671707Z",
  "nextExpectedRanges":["2097152"]
}

Beispiel: Erster Upload in das Ereignis

Anforderung

PUT https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw
Content-Type: application/octet-stream
Content-Length: 2097152
Content-Range: bytes 0-2097151/3483322

{
  <bytes 0-2097151 of the file to be attached, in binary format>
}

Antwort

Die folgende Beispielantwort zeigt in der NextExpectedRanges-Eigenschaft den Beginn des nächsten Bytebereichs, den der Server erwartet.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69%4098a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA%3D')/AttachmentSessions/$entity",
    "ExpirationDateTime":"2020-02-22T02:46:56.7410786Z",
    "nextExpectedRanges":["2097152"]
}

Schritt 3: Fortsetzen des Hochladens von Bytebereichen, bis die gesamte Datei hochgeladen wurde

Fahren Sie nach dem ersten Upload, der in Schritt 2 beschrieben wurde, mit dem Hochladen der verbleibenden Teile der Datei fort, indem Sie eine ähnliche PUT-Anforderung wie in Schritt 2 beschrieben verwenden, bevor Sie den Ablauftermin für die Sitzung erreichen. Verwenden Sie die Sammlung NextExpectedRanges, um zu bestimmen, wo der nächste Bytebereich für den Upload beginnen soll. Eventuell werden mehrere Bereiche angegeben. Sie stehen für Teile der Datei, die der Server noch nicht empfangen hat. Dies ist nützlich, wenn eine Übertragung nach einer Unterbrechung fortgesetzt werden soll und der Client den Dienststatus nicht kennt.

Nachdem das letzte Byte der Datei erfolgreich hochgeladen wurde, gibt der endgültige PUT-Vorgang HTTP 201 Created und einen Location-Header zurück, der die URL der Dateianlage in der https://outlook.office.com-Domäne angibt. Sie können die Anlagen-ID aus der URL abrufen und zur späteren Verwendung speichern. Abhängig vom jeweiligen Szenario können Sie diese ID verwenden, um die Metadaten der Anlage abzurufen oder mithilfe des Microsoft Graph-Endpunkts die Anlage aus dem Outlook-Element zu entfernen.

In den folgenden Beispielen wird gezeigt, wie der letzte Bytebereich der Datei in die Nachricht und das Ereignis in den vorstehenden Schritten hochgeladen wird.

Beispiel: Letzter Upload in die Nachricht

Anforderung

PUT https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI
Content-Type: application/octet-stream
Content-Length: 1386170
Content-Range: bytes 2097152-3483321/3483322

{
  <bytes 2097152-3483321 of the file to be attached, in binary format>
}

Antwort

Die folgende Beispielantwort zeigt einen Location-Antwortheader, von dem aus Sie die Anlagen-ID (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) zur späteren Verwendung speichern können.

HTTP/1.1 201 Created

Location: https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/Attachments('AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=')
Content-Length: 0

Beispiel: Letzter Upload in das Ereignis

Anforderung

PUT https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw
Content-Type: application/octet-stream
Content-Length: 1386170
Content-Range: bytes 2097152-3483321/3483322

{
  <bytes 2097152-3483321 of the file to be attached, in binary format>
}

Antwort

Die folgende Beispielantwort zeigt einen Location-Antwortheader, von dem aus Sie die Anlagen-ID (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) zur späteren Verwendung speichern können.

HTTP/1.1 201 Created

Location: https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/Attachments('AAMkADU5CCmSAAANZAlYPeyQByv7Y=')
Content-Length: 0

Schritt 4 (optional): Abrufen der Dateianlage aus dem Outlook-Element

Wie immer ist das Empfangen einer Anlage aus einem Outlook-Element technisch nicht durch die Anlagengröße eingeschränkt.

Eine große Dateianlage im base64-codierten Format wirkt sich jedoch auf die API-Leistung aus. Falls Sie eine große Anlage erwarten:

  • Als Alternative zum Abrufen des Anlageninhalts im base64-Format können Sie die Rohdaten der Dateianlage abrufen.
  • Wenn Sie die Metadaten der Dateianlage abrufen möchten, fügen Sie einen $select-Parameter an, damit nur die gewünschten Metadatentypen einbezogen werden, ohne die contentBytes-Eigenschaft einzuschließen, die die Dateianlage im base64-Format zurückgibt.

Beispiel: Abrufen der an ein Ereignis angefügten Rohdatei

Nach dem Ereignisbeispiel und unter Verwendung der Anlagen-ID, die im vorherigen Schrittes im Location-Header zurückgegeben wurde, zeigt die Beispielanforderung in diesem Abschnitt die Verwendung eines $value-Parameters, um die unformatierten Inhaltsdaten der Anlage abzurufen.

Berechtigungen

Verwenden Sie für diesen Vorgang die am wenigsten privilegierte delegierte Berechtigung oder die Anwendungsberechtigung (Calendars.Read) je nach Bedarf. Weitere Informationen finden Sie unter Kalender-Berechtigungen.

Anforderung

GET https://graph.microsoft.com/v1.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/Attachments('AAMkADU5CCmSAAANZAlYPeyQByv7Y=')/$value

Antwort

HTTP/1.1 200 OK
content-length: 3483322
Content-type: image/jpeg

{Raw bytes of the file}

Beispiel: Abrufen der Metadaten der an die Nachricht angefügten Datei

Nach dem Nachrichtenbeispiel zeigt die Beispielanforderung in diesem Abschnitt die Verwendung eines $select-Parameters, um einige der Metadaten einer Dateianlage einer Nachricht zu erhalten, mit Ausnahme von contentBytes.

Berechtigungen

Verwenden Sie für diesen Vorgang die am wenigsten privilegierte delegierte Berechtigung oder die Anwendungsberechtigung (Mail.Read) je nach Bedarf. Weitere Informationen finden Sie unter Mail-Berechtigungen.

Anforderung

GET https://graph.microsoft.com/api/v1.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/Attachments('AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=')?$select=lastModifiedDateTime,name,contentType,size,isInline

Antwort

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('a8e8e219-4931-95c1-b73d-62626fd79c32%4072aa88bf-76f0-494f-91ab-2d7cd730db47')/messages('AAMkADI5MAAIT3drCAAA%3D')/attachments/$entity",
    "@odata.type": "#microsoft.graph.fileAttachment",
    "@odata.mediaContentType": "image/jpeg",
    "id": "AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=",
    "lastModifiedDateTime": "2019-09-24T23:27:43Z",
    "name": "flower",
    "contentType": "image/jpeg",
    "size": 3640066,
    "isInline": false
}

Alternativ: Abbrechen der Uploadsitzung

Zu jedem beliebigen Zeitpunkt vor Ablauf der Upload-Sitzung können Sie mit derselben opaken URL die Upload-Sitzung auch löschen, falls dies erforderlich wird. Ein erfolgreicher Vorgang gibt HTTP 204 No Content zurück.

Berechtigungen

Da die anfängliche undurchsichtige URL vor-authentifiziert wird und das entsprechende Autorisierungstoken für nachfolgende Abfragen in dieser Uploadsitzung enthält, müssen Sie für diesen Vorgang keine Kopfzeile der Autorisierungsanforderung angeben.

Beispiel: Upload-Sitzung für die Nachricht abbrechen

Anforderung

DELETE https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI

Antwort

HTTP/1.1 204 No content

Fehler

ErrorAttachmentSizeShouldNotBeLessThanMinimumSize

Dieser Fehler wird zurückgegeben, wenn versucht wird, eine Upload-Sitzung zu erstellen, um eine Datei anzufügen, die kleiner als 3 MB ist. Wenn die Dateigröße weniger als 3 MB beträgt, sollten Sie einen einzelnen POST in der Navigationseigenschaft attachmentsder Nachricht oder des Ereignisses ausführen. Die erfolgreiche POST Antwort enthält die ID der Datei, die der Nachricht angefügt ist.