Partager via


Joindre des fichiers volumineux à des messages ou événements Outlook

À l’aide de l’API Microsoft Graph, vous pouvez joindre des fichiers d’une taille allant jusqu’à 150 Mo à un message Outlook ou à un élément d'un événement. Selon la taille du fichier, choisissez l’une des deux façons de joindre le fichier :

  • Si la taille du fichier est inférieure à 3 Mo, effectuez une publication unique sur la propriété de navigation despièces jointes de l’élément Outlook ; Pour plus d’informations, consultez comment procéder pour un message ou pour un événement. La réponse POST réussie inclut l’ID de la pièce jointe.
  • Si la taille du fichier est comprise entre 3 Mo et 150 Mo, créez une session de chargement et utilisez de manière itérative PUT pour charger des plages d’octets du fichier jusqu’à ce que vous ayez chargé l’intégralité du fichier. Un en-tête dans la réponse finale réussie PUT contient une URL avec l’ID de la pièce jointe.

Pour joindre plusieurs fichiers à un message, sélectionnez l’approche pour chaque fichier en fonction de sa taille et joignez les fichiers individuellement.

Cet article illustre la deuxième approche étape par étape, en créant et en utilisant une session de chargement pour ajouter une pièce jointe volumineuse (d’une taille supérieure à 3 Mo) à un élément Outlook. Chaque étape affiche le code correspondant pour un message et un événement. Lorsque vous téléchargez le fichier dans son intégralité, l’article montre comment obtenir un en-tête de réponse contenant un ID pour la pièce jointe, puis utiliser cet ID de pièce jointe pour obtenir le contenu de la pièce jointe brut ou les métadonnées de la pièce jointe.

Importante

Consultez l’article sur lesproblèmes connus si vous souhaitez joindre des fichiers volumineux à un message ou un événement dans une boîte aux lettres partagée ou déléguée.

Etape 1 : création d’une session de chargement

Créer une session de téléchargement pour joindre un fichier à un message ou un événement. Spécifier le fichier dans le paramètre d’entrée AttachmentItem.

Une opération réussie renvoie HTTP 201 Created et une nouvelle instance uploadSession qui contient une URL opaque que vous pouvez utiliser dans les opérations PUT suivantes pour charger des parties du fichier. La uploadSession crée un emplacement de stockage temporaire où les octets du fichier sont enregistrés jusqu’au chargement complet du fichier.

L’objet uploadSession dans la réponse inclut également la propriété nextExpectedRanges, qui indique que l’emplacement de départ du téléchargement initial doit être l’octet 0.

Autorisations

Veillez à demander l'Mail.ReadWriteautorisation de créer la uploadSession pour un message et Calendars.ReadWrite pour un événement.

L’URL opaque, renvoyée dans la propriété uploadUrl de la nouvelle uploadSession, est pré-authentifiée et contient le jeton d’autorisation approprié pour les requêtes PUT suivantes dans le domaine https://outlook.office.com. Ce jeton expire le expirationDateTime. Ne personnalisez pas cette URL pour les opérations PUT.

Exemple : créer une session de téléchargement pour un message

Requête

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

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

Réponse

L’exemple de réponse suivant montre la ressource uploadSession renvoyée pour le message.

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-"
    ]
}

Exemple : créer une session de chargement pour un événement

Requête

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

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

Réponse

L’exemple de réponse suivant montre la ressource uploadSession renvoyée pour l’événement.

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-"
    ]
}

Étape 2 : utiliser la session de téléchargement pour charger une plage d’octets du fichier

Pour télécharger le fichier ou une partie de celui-ci, effectuez une demande PUT à l’URL renvoyée à l’étape 1 de la propriété uploadUrl de la ressource uploadSession. Vous pouvez télécharger l’intégralité du fichier ou fractionner le fichier en plusieurs plages d’octets. Pour de meilleures performances, limitez chaque plage d’octets à 4 Mo.

Spécifiez les en-têtes et le corps de la requête, comme décrit ci-dessous.

En-têtes de demande

Nom Type Description
Content-Length Int32 Nombre d’octets téléchargés dans cette opération. Pour de meilleures performances, limitez le nombre d’octets pour chaque opération PUT à 4 Mo. Obligatoire.
Content-Range Chaîne La plage d’octets basée sur 0 du fichier téléchargé pendant cette opération, exprimée dans le format bytes {start}-{end}/{total}. Obligatoire.
Content-Type String Le type MIME. Précisez application/octet-stream. Obligatoire.

N’indiquez pas d’en-tête de demande Authorization. La requête PUT utilise une URL pré-authentifiée à partir de la propriété uploadUrl, qui permet d’accéder au domaine https://outlook.office.com.

Corps de la requête

Spécifiez les octets réels du fichier à joindre, qui se trouvent dans la plage d’emplacements spécifiée par l’en-tête de demande Content-Range.

Réponse

Un téléchargement réussi renvoie HTTP 200 OK et un objet uploadSession. Notez ce qui suit dans l’objet de réponse :

  • La propriété expirationDateTime indique la date/heure d’expiration du jeton d’authentification incorporé dans la valeur de propriété uploadUrl. Cette date/heure d’expiration reste la même que celle renvoyée par le uploadSession initial de l’étape 1.
  • NextExpectedRanges spécifie l’emplacement d’octet suivant à partir duquel démarrer le chargement, par exemple, "nextExpectedRanges":["2097152"]. Vous devez charger les octets d’un fichier dans l’ordre.
  • La propriété uploadUrl n’est pas explicitement renvoyée, car toutes les opérations PUT d’une session de téléchargement utilisent la même URL, renvoyée lors de la création de la session (étape 1).

Exemple : le premier chargement dans le message

Requête

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>
}

Réponse

L’exemple de réponse suivant illustre la propriété nextNextExpectedRanges le début de la plage d’octets suivante attendue par le serveur.

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"]
}

Exemple : le premier chargement dans l’événement

Requête

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>
}

Réponse

L’exemple de réponse suivant illustre la propriété nextNextExpectedRanges le début de la plage d’octets suivante attendue par le serveur.

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"]
}

Étape 3 : continuer à télécharger des plages d’octets jusqu’à ce que le fichier entier ait été téléchargé

Suite au téléchargement initial à l’étape 2, continuez à charger la partie restante du fichier à l’aide d’une requête PUT similaire, comme décrit à l’étape 2, avant d’atteindre la date/heure d’expiration de la session. Utilisez la collection nextNextExpectedRanges pour déterminer où commencer la prochaine plage octets à télécharger. Plusieurs plages peuvent être spécifiées, indiquant les parties du fichier que le serveur n’a pas encore reçues. Cette fonction est utile si vous avez besoin de reprendre un transfert qui a été interrompu et si votre client n’est pas sûr de l’état du service.

Une fois le dernier octet du fichier correctement téléchargé, l’opération PUT finale renvoie HTTP 201 Created et un en-tête de Location indiquant l’URL de la pièce jointe dans le domaine https://outlook.office.com. Vous pouvez obtenir l’ID de la pièce jointe à partir de l’URL et l’enregistrer pour une utilisation ultérieure. Selon votre scenario, vous pouvez utiliser cet ID pour obtenir les métadonnées de la pièce jointe ou supprimer la pièce jointe de l’élément Outlook à l’aide du point de terminaison Microsoft Graph.

Les exemples suivants montrent comment télécharger la dernière plage d’octets du fichier dans le message et dans l’événement des étapes précédentes.

Exemple : le chargement final dans le message

Requête

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>
}

Réponse

L’exemple de réponse suivant montre un Location en-tête de réponse à partir duquel vous pouvez enregistrer l’ID pièce jointe (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) pour une utilisation ultérieure.

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

Exemple : le chargement final dans l’événement

Demande

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>
}

Réponse

L’exemple de réponse suivant montre un Location en-tête de réponse à partir duquel vous pouvez enregistrer l’ID pièce jointe (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) pour une utilisation ultérieure.

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

Étape 4 (facultative) : récupérer le fichier en pièce jointe à partir de l’élément Outlook

Comme toujours, l’acquisition d’une pièce jointe à partir d’un élément Outlook n’est pas limitée techniquement par la taille des pièces jointes.

Toutefois, l’acquisition d’une pièce jointe de fichier de grande taille dans un format codé en base64 a une incidence sur les performances de l’API. Si vous attendez une pièce jointe de grande taille :

Exemple : obtenir le fichier raw joint à l’événement

Suivi de l’exemple d’événement et utilisation de l’ID de pièce jointe renvoyée dans l’en-tête Location de l’étape précédente, l’exemple de demande dans cette section montre comment utiliser un paramètre $value pour obtenir les données de contenu brutes de la pièce jointe.

Autorisations

Utiliser les autorisations déléguées ou d'application les moins privilégiées, Calendars.Read, le cas échéant, pour cette opération. Pour plus d’informations, reportez-vous à la rubrique Autorisations de calendrier.

Demande

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

Réponse

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

{Raw bytes of the file}

Exemple : obtenir les métadonnées du fichier joint au message

À la suite de l’exemple de message, l’exemple de demande dans cette section montre comment utiliser un paramètre $select pour récupérer certaines des métadonnées d’un fichier joint à un message, à l’exclusion de contentBytes.

Autorisations

Utiliser les autorisations déléguées ou d'application les moins privilégiées, Mail.Read, le cas échéant, pour cette opération. Pour plus d’informations, reportez-vous à la rubrique Autorisations de messagerie.

Demande

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

Réponse

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
}

Alternative : annulation de la session de chargement

À tout moment avant l’expiration de la session de téléchargement, si vous devez annuler le téléchargement, vous pouvez utiliser la même URL opaque qu’initialement pour supprimer la session de téléchargement. Une opération réussie renvoie HTTP 204 No Content.

Autorisations

Étant donné que l’URL opaque initiale est pré-authentifiée et contient le jeton d’autorisation approprié pour les requêtes suivantes pour cette session de téléchargement, ne spécifiez pas d’en-tête de demande d’autorisation pour cette opération.

Exemple : annuler la session de chargement pour le message

Requête

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

Réponse

HTTP/1.1 204 No content

Erreurs

ErrorAttachmentSizeShouldNotBeLessThanMinimumSize

Cette erreur est renvoyée lorsque vous tentez de créer une session de téléchargement pour joindre un fichier d’une taille inférieure à 3 Mo. Si la taille de fichier est inférieure à 3 Mo, vous pouvez effectuer une seule requête POST sur les pièces jointes de la navigation de propriété du message ou de l’événement. La réponse POST réussie inclut l’ID du fichier joint au message.