Adjuntar archivos grandes en mensajes o eventos de Outlook

El uso de la API de Microsoft Graph permite adjuntar archivos hasta 150 MB en un mensaje o evento de Outlook. Según el tamaño del archivo, elija una de las dos formas de adjuntar el archivo:

  • Si el tamaño del archivo es inferior a 3 MB, realice una sola publicación en la propiedad de navegación attachments del elemento de Outlook. Vea cómo hacer esto para un mensaje o para un evento. Si la respuesta POST es correcta, incluirá el ID. del archivo adjunto.
  • Si el tamaño de archivo está entre 3 y 150 MB, cree una sesión de carga e itere solicitudes PUT para cargar partes del archivo hasta cargarlo entero. El encabezado de la respuesta PUT final correcta incluye una dirección URL con el ID. de datos adjuntos.

Para adjuntar varios archivos a un mensaje, seleccione el método para cada archivo en función de su tamaño de archivo y adjúntelos por separado.

Este artículo muestra el segundo enfoque paso a paso, la creación y el uso de una sesión de carga para agregar un archivo adjunto de gran tamaño (de tamaño superior a 3 MB) a un elemento de Outlook. Cada paso muestra el código correspondiente para un mensaje y para un evento. Cuando se carga correctamente todo el archivo, en el artículo se muestra cómo obtener un encabezado de respuesta que contiene un identificador para el archivo adjunto y usar ese ID. de datos adjuntos para obtener los metadatos de datos adjuntos sin procesar.

Importante

Tenga en cuenta que existe un problema conocido si va a adjuntar archivos de gran tamaño a un mensaje en un buzón compartido o delegado.

Paso 1: crear una sesión de carga

Cree una sesión de carga para adjuntar un archivo a un mensaje o evento. Especifique el archivo en el parámetro de entrada AttachmentItem.

Una operación correcta devuelve HTTP 201 Created y una nueva instancia uploadSession con una dirección URL opaca que se puede usar en operaciones de PUT posteriores para cargar partes del archivo. La instancia de uploadSession ofrece una ubicación de almacenamiento temporal en la que se guardan los bytes del archivo hasta que se cargue el archivo completo.

El objeto uploadSession en la respuesta también incluye la propiedad nextExpectedRanges, lo que indica que la primera ubicación de carga inicial debe ser el byte 0.

Permisos

Asegúrese de solicitar el permiso Mail.ReadWrite para crear la uploadSession para un mensaje y Calendars.ReadWrite para un evento.

La dirección URL opaca, devuelta en la propiedad uploadUrl de la nueva uploadSession, está pre autentificado y contiene el símbolo de autorización token apropiada para posteriores PUT consultas en elhttps://outlook.office.comdominio. El token expira en expirationDateTime. No personalice esta dirección URL para las operaciones PUT.

Ejemplo: crear una sesión de carga para un mensaje

Solicitar

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

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

Respuesta

La respuesta de ejemplo siguiente muestra el recurso uploadSession devuelto para el mensaje.

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

Ejemplo: crear una sesión de carga para un evento

Solicitud

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

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

Respuesta

La respuesta de ejemplo siguiente muestra el recurso uploadSession devuelto para el evento.

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

Paso 2: usar la sesión de carga para cargar un rango de bytes del archivo

Para cargar todo el archivo o una parte, realice una solicitud de PUT a la URL devuelta en el paso 1 en la propiedad uploadUrl del recurso uploadSession. Puede cargar el archivo entero o dividirlo en varios trozos de bytes. Para mejorar el rendimiento, haga que cada rango de bytes sea inferior a 4 MB.

Especifique los encabezados y el cuerpo de la solicitud tal y como se describe a continuación.

Encabezados de solicitud

Nombre Tipo Descripción
Content-Length Int32 El número de bytes que se están cargando en esta operación. Para mejorar el rendimiento, limite el número máximo de bytes para cada operación PUT a 4 MB. Obligatorio.
Content-Range Cadena El rango de bytes basado en 0 del archivo que se carga en esta operación, expresado en formato bytes {start}-{end}/{total}. Obligatorio.
Content-Type Cadena El tipo MIME. Especifique application/octet-stream. Obligatorio.

No especifique un encabezado de solicitud de Authorization. La consulta PUT usa una dirección URL autenticada previamente a partir de la propiedad uploadUrl, que permite obtener acceso al dominio de https://outlook.office.com.

Cuerpo de la solicitud

Especifique los bytes reales del archivo que se va a adjuntar y que se encuentran en el rango de la ubicación especificado en el encabezado de solicitud Content-Range.

Respuesta

Si la carga es correcta, devuelve HTTP 200 OK y un objeto uploadSession. Tenga en cuenta lo siguiente en el objeto de respuesta:

  • La propiedad ExpirationDateTime indica la fecha y hora de expiración del token de autenticación insertado en el valor de la propiedad uploadUrl. La fecha y hora de expiración es la misma que devolvió uploadSession en el paso 1.
  • NextExpectedRanges especifica la siguiente ubicación de bytes en la que se iniciará la carga, por ejemplo, "NextExpectedRanges":["2097152"]. Debe cargar los bytes de un archivo en orden.
  • La propiedad uploadUrl no se devuelve explícitamente, ya que todas las operaciones de PUT de una sesión de carga usan la misma dirección URL devuelta al crear la sesión (paso 1).

Ejemplo: carga inicial al mensaje

Solicitar

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

Respuesta

La siguiente respuesta de ejemplo se muestra en la propiedad NextExpectedRanges el inicio del siguiente intervalo de bytes que espera el servidor.

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

Ejemplo: carga inicial al evento

Solicitar

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

Respuesta

La siguiente respuesta de ejemplo se muestra en la propiedad NextExpectedRanges el inicio del siguiente intervalo de bytes que espera el servidor.

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

Paso 3: seguir cargando intervalos de bytes hasta que se haya cargado todo el archivo

Después de la carga inicial en el paso 2, siga cargando la parte restante del archivo con una solicitud de PUT similar, como se describe en el paso 2, antes de que llegue a la fecha y hora de expiración de la sesión. Use la colección nextExpectedRanges para determinar dónde comenzar el siguiente intervalo de bytes a cargar. Puede ver varios intervalos especificados, lo que indica las partes del archivo que aún no ha recibido el servidor. Esto resulta útil si necesita reanudar una transferencia que se ha interrumpido y su cliente no está seguro del estado del servicio.

Una vez que el último byte del archivo se haya cargado correctamente, la operación final de PUT devuelve HTTP 201 Created y un encabezado Location que indica la dirección URL del archivo adjunto en el dominio de https://outlook.office.com. Puede obtener el ID. de datos adjuntos desde la URL y guardarlo para usarlo más adelante. Según el escenario, puede usar ese ID para obtener los metadatos de los datos adjuntos o quitar los datos adjuntos del elemento de Outlook con el punto de conexión de Microsoft Graph.

En los ejemplos siguientes se muestra cómo cargar el último intervalo de bytes del archivo al mensaje y al evento en los pasos anteriores.

Ejemplo: carga final al mensaje

Solicitar

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

Respuesta

La respuesta de ejemplo siguiente muestra un encabezado de respuesta Location desde el que puede guardar el ID. de datos adjuntos (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) para usarlo más adelante.

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

Ejemplo: carga final al evento

Solicitar

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

Respuesta

La respuesta de ejemplo siguiente muestra un encabezado de respuesta Location desde el que puede guardar el ID. de datos adjuntos (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) para usarlo más adelante.

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

Paso 4 (opcional): obtener el archivo adjunto del elemento de Outlook

Como siempre, la obtención de un dato adjunto de un elemento de Outlook no está técnicamente limitada por el tamaño del dato adjunto.

Sin embargo, obtener un archivo adjunto de gran tamaño en codificación base64 afecta al rendimiento de la API. Si espera un archivo adjunto de gran tamaño:

Ejemplo: obtener el archivo sin formato adjunto al evento

Siguiendo el ejemplo del evento y utilizando el identificador de datos adjuntos devuelto en el encabezado Location del paso anterior, en la siguiente solicitud de ejemplo se muestra el uso de un parámetro $value para obtener los datos de contenido sin procesar de datos adjuntos.

Permisos

Use el permiso de aplicación o delegado con menos privilegios, Calendars.Read, según corresponda, para esta operación. Para obtener más información, vea Permisos para el calendario.

Solicitud

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

Respuesta

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

{Raw bytes of the file}

Ejemplo: obtener los metadatos del archivo adjunto al mensaje

Siguiendo el ejemplo de mensaje, en la siguiente solicitud de ejemplo se muestra el uso de un parámetro $select para obtener algunos de los metadatos de un archivo adjunto en un mensaje, excepto contentBytes.

Permisos

Use el permiso de aplicación o delegado con menos privilegios, Mail.Read, según corresponda, para esta operación. Para obtener más información, vea Permisos para el correo electrónico.

Solicitud

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

Respuesta

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
}

Alternativa: cancelar la sesión de carga

Si tiene que cancelar la carga en cualquier momento antes de que la sesión expire, puede usar la misma URL opaca inicial para eliminar la sesión de carga. Una operación correcta devuelve HTTP 204 No Content.

Permisos

Debido a que la URL opaca inicial está previamente autenticada y contiene el token de autorización adecuado para consultas posteriores para esa sesión de carga, no especifique un encabezado de solicitud de autorización para esta operación.

Ejemplo: cancelar la sesión de carga del mensaje

Solicitar

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

Respuesta

HTTP/1.1 204 No content

Errores

ErrorAttachmentSizeShouldNotBeLessThanMinimumSize

Este error se obtiene al intentar crear una sesión de carga para adjuntar un archivo de menos de 3 MB. Si el tamaño del archivo es inferior a 3 MB, debería hacer una única solicitud POST en la propiedad de navegación de datos adjuntos del mensaje o del evento. Si la respuesta POST es correcta, incluirá el ID. del archivo adjunto al mensaje.