Share via

attachment: createUploadSession

  • Artikel

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Erstellen Sie eine Uploadsitzung, die es einer App ermöglicht, Bereiche einer Datei iterativ hochzuladen, um die Datei an ein Outlook-Element anzufügen. Das Element kann eine Nachricht oder ein Ereignis sein.

Verwenden Sie diesen Ansatz, um eine Datei anzufügen, wenn die Dateigröße zwischen 3 MB und 150 MB liegt. Um eine Datei anzufügen, die kleiner als 3 MB ist, führen Sie einen POST Vorgang für die Attachments-Navigationseigenschaft des Outlook-Elements aus. Informationen hierzu finden Sie für eine Nachricht oder für ein Ereignis.

Als Teil der Antwort gibt diese Aktion eine Upload-URL zurück, die Sie in nachfolgenden sequenziellen PUT Abfragen verwenden können. Mit Anforderungsheadern für jeden PUT Vorgang können Sie den genauen Bytesbereich angeben, der hochgeladen werden soll. Dadurch kann die Übertragung fortgesetzt werden, falls die Netzwerkverbindung während des Uploads unterbrochen wird.

Im Folgenden werden die Schritte zum Anfügen einer Datei an ein Outlook-Element mithilfe einer Uploadsitzung beschrieben:

  1. Erstellen Sie eine Uploadsitzung.
  2. Innerhalb dieser Uploadsitzung laden Sie Bytebereiche (bis zu 4 MB pro Mal) iterativ hoch, bis alle Bytes der Datei hochgeladen wurden und die Datei an das angegebene Element angefügt wird.
  3. Speichern Sie die ID für die Anlage für den zukünftigen Zugriff.
  4. Optional: Löschen Sie die Uploadsitzung.

Ein Beispiel finden Sie unter Anfügen großer Dateien an Outlook-Nachrichten oder -Ereignisse .

Tipp

Exchange Online können Administratoren den Grenzwert für die Nachrichtengröße für Microsoft 365-Postfächer anpassen, einschließlich aller Nachrichtenanlagen. Standardmäßig beträgt dieser Grenzwert für die Nachrichtengröße 35 MB. Erfahren Sie, wie Sie die maximale Nachrichtengröße anpassen , um Anlagen zu unterstützen, die den Standardgrenzwert für Ihren Mandanten überschreiten.

Wichtig

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

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ❌ ❌ ✅

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Calendars.ReadWrite Mail.ReadWrite
Delegiert (persönliches Microsoft-Konto) Calendars.ReadWrite Mail.ReadWrite
Anwendung Calendars.ReadWrite Mail.ReadWrite

HTTP-Anforderung

So erstellen Sie eine Uploadsitzung zum Anfügen einer Datei an ein Ereignis:

POST /me/events/{id}/attachments/createUploadSession

So erstellen Sie eine Uploadsitzung zum Anfügen einer Datei an eine Nachricht:

POST /me/messages/{id}/attachments/createUploadSession

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.

Anforderungstext

Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an.

Parameter Typ Beschreibung
AttachmentItem attachmentItem Stellt Attribute des elements dar, das hochgeladen und angefügt werden soll. Geben Sie mindestens den Anlagentyp (file), einen Namen und die Größe der Datei an.

Antwort

Bei erfolgreicher Ausführung gibt die Methode den 201 Created Antwortcode und ein neues uploadSession-Objekt im Antworttext zurück.

Hinweis:

Die uploadUrl-Eigenschaft , die als Teil des uploadSession-Antwortobjekts zurückgegeben wird, ist eine nicht transparente URL für nachfolgende PUT Abfragen zum Hochladen von Bytebereichen der Datei. Es enthält das entsprechende Authentifizierungstoken für nachfolgende PUT Abfragen, die um expirationDateTime ablaufen. Passen Sie diese URL nicht an.

Die nextExpectedRanges-Eigenschaft gibt den Speicherort des nächsten Dateibytes an, aus dem hochgeladen werden soll, "NextExpectedRanges":["2097152"]z. B. . Sie müssen die Bytes einer Datei in der korrekten Reihenfolge hochladen.

Beispiele

Beispiel 1: Erstellen einer Uploadsitzung zum Hinzufügen einer großen Anlage zu einem Nachrichtenentwurf

Das folgende Beispiel zeigt, wie Sie eine Uploadsitzung erstellen, die Sie in nachfolgenden Dateiuploadvorgängen in die angegebene Nachricht verwenden können.

Anforderung

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

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

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

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

Beispiel 2: Erstellen einer Uploadsitzung zum Hinzufügen einer großen Inlineanlage zu einem Nachrichtenentwurf

Das folgende Beispiel zeigt, wie Sie eine Uploadsitzung erstellen, die verwendet werden kann, um einem Nachrichtenentwurf eine große Inlineanlage hinzuzufügen.The following example shows how to create an upload session that can be used to add a large inline attachment to a draft message.

Legen Sie für eine Inlineanlage die isInline-Eigenschaft auf true fest, und verwenden Sie die contentId-Eigenschaft , um eine CID für die Anlage anzugeben, wie unten gezeigt. Verwenden Sie im Textkörper des Nachrichtenentwurfs denselben CID-Wert, um die Position anzugeben, an der Sie die Anlage einschließen möchten, indem Sie ein CID-HTML-Verweistag verwenden, z. B <img src="cid:my_inline_picture">. . Nach dem erfolgreichen Hochladen der Datei enthält die gerenderte Nachricht die Anlage als Teil des Nachrichtentexts am angegebenen Speicherort.

Anforderung

POST https://graph.microsoft.com/beta/me/messages/AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=/attachments/createUploadSession
Content-type: application/json

{
  "AttachmentItem": {
    "attachmentType": "file",
    "name": "scenary",
    "size": 7208534,
    "isInline": true,
    "contentId": "my_inline_picture"
  }
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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/gv1.0/users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=')/AttachmentSessions('AAMkAGUwNjQ4ZjIxLTAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IjFTeXQ1bXdXYVh5UFJ",
    "expirationDateTime": "2021-12-27T14:20:12.9708933Z",
    "nextExpectedRanges": [
        "0-"
    ]
}