driveItem: createUploadSession

Espacio de nombres: microsoft.graph

Cree una sesión de carga para permitir que la aplicación cargue archivos de hasta el tamaño de archivo máximo.

Una sesión de carga permite que la aplicación cargue intervalos del archivo en solicitudes de API secuenciales. También permite que la transferencia se reanude si la conexión se quita durante la carga.

Para cargar un archivo mediante una sesión de carga:

1. Crear una sesión de carga
2. Cargar bytes a la sesión de carga

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Crear una sesión de carga

Para comenzar la carga de archivos de gran tamaño, su aplicación debe solicitar primero una nueva sesión de carga. Esta solicitud crea una ubicación de almacenamiento temporal donde se guardan los bytes del archivo hasta que se carga el archivo completo. Cuando se carga el último byte del archivo, se completa la sesión de carga y el archivo final se muestra en la carpeta de destino. También puede aplazar la creación final del archivo en el destino hasta que realice explícitamente una solicitud para completar la carga estableciendo la propiedad deferCommit en los argumentos de solicitud.

Solicitud HTTP

Para cargar un nuevo archivo, debe proporcionar tanto el identificador primario como el nuevo nombre de archivo en la solicitud. Sin embargo, una actualización solo requiere que se actualice el identificador del elemento.

Creación de un nuevo archivo

POST /drives/{driveId}/items/{parentItemId}:/{fileName}:/createUploadSession
POST /groups/{groupId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /users/{userId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession

Actualización del archivo existente

POST /drives/{driveId}/items/{itemId}/createUploadSession
POST /groups/{groupId}/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}/createUploadSession
POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

Encabezados de solicitud

Cuerpo de solicitud

No es necesario ningún cuerpo de solicitud. Sin embargo, puede especificar propiedades en el cuerpo de la solicitud para proporcionar más información sobre el archivo que se carga y personalizar la semántica de la operación de carga.

Por ejemplo, la propiedad item permite establecer los parámetros siguientes:

{
  "@microsoft.graph.conflictBehavior": "fail (default) | replace | rename",
  "description": "description", // only available for OneDrive (personal)
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234, // only available for OneDrive (personal)
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

En el ejemplo siguiente se controla el comportamiento cuando ya se ha tomado el nombre de archivo. En este ejemplo también se especifica que no se debe crear el archivo final hasta que se realice una solicitud de finalización explícita.

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  },
  "deferCommit": true
}

Solicitud

La respuesta a esta solicitud proporciona los detalles de la uploadSession recién creada, que incluye la dirección URL utilizada para cargar las partes del archivo.

Nota: {item-path} debe contener el nombre del elemento especificado en el cuerpo de la solicitud.

POST /me/drive/items/{itemID}:/{item-path}:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename",
    "name": "largefile.dat"
  }
}

Respuesta

Si se ejecuta correctamente, la respuesta a esta solicitud proporciona los detalles de dónde se debe enviar el resto de las solicitudes como recurso uploadSession .

Cuando se crea una sesión y genera direcciones URL de carga autenticadas previamente, la dirección URL de carga se puede usar para completar la carga dentro de un período de tiempo suficiente para archivos grandes.

El recurso uploadSession proporciona detalles sobre dónde se debe cargar cada intervalo de bytes del archivo y especifica cuándo expira la sesión. La propiedad expirationDateTime indica la hora a la que expira la sesión actual si no se produce ninguna actividad adicional. Esto da como resultado el siguiente comportamiento:

• Debe cargar el siguiente fragmento o confirmar la sesión antes de la hora especificada en la propiedad expirationDateTime .
• Cada fragmento cargado amplía el tiempo de expiración, lo que permite que las cargas de archivos grandes se completen correctamente. La hora de expiración actualizada se devuelve en cada solicitud para cargar un fragmento de archivo.
• Si no se recibe ningún fragmento y no se confirma la sesión, se descartan todos los fragmentos cargados anteriormente.

Este proceso admite cargas de archivos grandes y garantiza que las sesiones de carga se administren de forma eficaz evitando que los datos obsoletos o abandonados permanezcan demasiado tiempo en el sistema.

Si se especifica el fileSize parámetro y supera la cuota disponible, se devuelve una 507 Insufficient Storage respuesta y no se crea la sesión de carga.

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

{
  "uploadUrl": "https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337",
  "expirationDateTime": "2015-01-29T09:21:55.523Z"
}

Cargar bytes en la sesión de carga

Para cargar el archivo o una parte del archivo, la aplicación envía una solicitud PUT al valor uploadUrl recibido en la respuesta createUploadSession. Puede cargar el archivo completo o dividir el archivo en varios intervalos de bytes, siempre y cuando el número máximo de bytes de cualquier solicitud dada sea inferior a 60 MiB.

Los fragmentos del archivo se deben cargar secuencialmente en orden. La carga de fragmentos fuera de orden produce un error.

Nota: Si su aplicación divide un archivo en varios intervalos de bits, el tamaño de cada uno DEBE ser un múltiplo de 320 KiB (327 680 bytes).

El uso de un tamaño de fragmento que no se divide uniformemente por 320 KiB produce errores al confirmar algunos archivos.

Ejemplo

En este ejemplo, la aplicación carga los primeros 26 bytes de un archivo de 128 bytes.

• El encabezado Content-Length especifica el tamaño de la solicitud actual.
• El encabezado Content-Range indica el intervalo de bytes en el archivo global que representa esta solicitud.
• La longitud total del archivo se conoce antes de cargar el primer fragmento del archivo.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 26
Content-Range: bytes 0-25/128

<bytes 0-25 of the file>

Respuesta

Una vez completada la solicitud, el servidor responde con 202 Accepted si hay más intervalos de bytes que deben cargarse.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["26-"]
}

Su aplicación puede usar el valor nextExpectedRanges para determinar dónde comenzar el siguiente intervalo de bytes. Es posible que vea varios intervalos especificados, lo que indica partes del archivo que el servidor aún no ha recibido. Esto resulta útil si necesita reanudar una transferencia que se ha interrumpido y su cliente no está seguro del estado del servicio.

Siempre debe determinar el tamaño de los intervalos de bytes según las siguientes recomendaciones. No suponga que nextExpectedRanges devuelve intervalos de tamaño adecuado para que se cargue un intervalo de bytes. La propiedad nextExpectedRanges indica intervalos del archivo que no se han recibido y no un patrón de cómo debe cargar el archivo la aplicación.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": [
  "12345-55232",
  "77829-99375"
  ]
}

Observaciones

• La propiedad nextExpectedRanges no siempre enumera todos los intervalos que faltan.
• En las escrituras correctas de fragmentos, devuelve el siguiente intervalo desde el que comenzar (por ejemplo, 523-).
• En los errores en los que el cliente envió un fragmento que el servidor ya recibió, el servidor responde con HTTP 416 Requested Range Not Satisfiable. Para obtener una lista más detallada de los intervalos que faltan, puede solicitar el estado de carga.
• Si incluye el Authorization encabezado al emitir la llamada PUT, podría dar lugar a una HTTP 401 Unauthorized respuesta. Incluya solo el encabezado y el Authorization token de portador al emitir la solicitud POST durante el primer paso. No lo incluya al emitir la llamada PUT.

Finalización de un archivo

Si deferCommit es o no está false establecido, la carga se completa automáticamente cuando el intervalo de bytes final del archivo es PUT en la dirección URL de carga.

Si deferCommit es true, puede completar explícitamente la carga de dos maneras:

• Después de que el rango de bytes final del archivo sea PUT para la dirección URL de carga, envíe una solicitud POST a la dirección URL con una carga con contenido de longitud cero (actualmente solo es compatible con OneDrive para la Empresa y SharePoint).
• Después de que el rango de bytes final del archivo sea PUT para la dirección URL de carga, envíe una solicitud PUT de la misma forma en que administraría los errores de carga (actualmente solo es compatible con OneDrive Personal).

Cuando se completa la carga, el servidor responde a la solicitud final con o HTTP 201 CreatedHTTP 200 OK. El cuerpo de la respuesta también incluye la propiedad predeterminada establecida para el driveItem que representa el archivo completado.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 21
Content-Range: bytes 101-127/128

<final bytes of the file>

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

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

POST https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 0

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

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Controlar conflictos de carga

Si se produce un conflicto después de que se cargue el archivo (por ejemplo, se ha creado un elemento con el mismo nombre durante la sesión de carga), se devuelve un error cuando se carga el último intervalo de bytes.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error":
  {
    "code": "nameAlreadyExists",
    "message": "Another file exists with the same name as the uploaded session. You can redirect the upload session to use a new filename by calling PUT with the new metadata and @microsoft.graph.sourceUrl attribute.",
  }
}

Cancelar la sesión de carga

Para cancelar una sesión de carga, envíe una solicitud DELETE a la dirección URL de carga. Esto limpia el archivo temporal que contiene los datos previamente cargados. Debe utilizarse en los casos en los que se anula la carga, por ejemplo, si el usuario cancela la transferencia.

Los archivos temporales y la sesión de carga que los acompaña se limpian automáticamente cuando pasa la expirationDateTime. Es posible que los archivos temporales no se eliminen inmediatamente después de que transcurra el tiempo de expiración.

Solicitud

DELETE https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Reanudar una carga en curso

Si una solicitud de carga se desconecta o si falla antes de que se complete la solicitud, se pasan por alto todos los bytes de dicha solicitud. Esto puede ocurrir si se interrumpe la conexión entre la aplicación y el servicio. Si esto ocurre, la aplicación todavía puede reanudar la transferencia de archivos desde el fragmento completado anteriormente.

Para averiguar qué intervalos de bytes se han recibido anteriormente, su aplicación puede solicitar el estado de una sesión de carga.

Ejemplo

Consulte el estado de la carga mediante el envío de una solicitud GET a uploadUrl.

GET https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF86633784148bb98a1zjcUhf7b0mpUadahs

El servidor responde con una lista de intervalos de bytes que faltan que deben cargarse y la hora de expiración de la sesión de carga.

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

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["12345-"]
}

Cargar los datos restantes

Ahora que la aplicación sabe desde dónde iniciar la carga, reanude la carga siguiendo los pasos descritos en cargar bytes a la sesión de carga.

Controlar errores de carga

Cuando se carga el último intervalo de bytes de un archivo, es posible que se produzca un error. Esto puede deberse a un conflicto de nombre o a que se ha excedido un límite de cuota. La sesión de carga se conserva hasta la hora de expiración, lo que permite que la aplicación recupere la carga confirmando explícitamente la sesión de carga.

Para confirmar explícitamente la sesión de carga, la aplicación debe realizar una solicitud PUT con un nuevo recurso driveItem que se usará al confirmar la sesión de carga. Esta nueva solicitud debería corregir el origen del error que ha generado el error de carga original.

Para indicar que su aplicación está confirmando una sesión de carga existente, la solicitud PUT debe incluir la propiedad @microsoft.graph.sourceUrl con el valor de la URL de la sesión de carga.

PUT https://graph.microsoft.com/beta/me/drive/root:/{path_to_file}
Content-Type: application/json
If-Match: {etag or ctag}

{
  "name": "largefile.vhd",
  "@microsoft.graph.conflictBehavior": "rename",
  "@microsoft.graph.sourceUrl": "{upload session URL}"
}

Nota: Puede usar los encabezados @microsoft.graph.conflictBehavior y if-match como se esperaba en esta llamada.

Respuesta

Si el archivo se puede confirmar mediante los nuevos metadatos, se devuelve una HTTP 201 Created respuesta o HTTP 200 OK con los metadatos driveItem para el archivo cargado.

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

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Procedimientos recomendados

• Reanude o vuelva a ejecutar las cargas que fallaron debido a las interrupciones de la conexión o a los errores 5xx, como:
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout
• Utilice una estrategia de interrupción exponencial si se devuelve cualquier error 5xx del servidor al reanudar o volver a ejecutar solicitudes de carga.
• Para otros errores, no debe usar una estrategia de retroceso exponencial, sino limitar el número de reintentos realizados.
• Controle los errores 404 Not Found al realizar cargas reanudables volviendo a iniciar la carga completa. Esto indica que ya no existe la sesión de carga.
• Use transferencias de archivo reanudables para los archivos de más de 10 MiB (10.485.760 bytes).
• Un tamaño de intervalo de bytes de 10 MiB para conexiones estables de alta velocidad es óptimo. Para conexiones más lentas o menos fiables puede obtener mejores resultados con tamaños de fragmento más pequeños. El tamaño de fragmento recomendado es entre 5 y 10 MiB.
• Use un tamaño de intervalo de bytes que sea múltiplo de 320 KiB (327 680 bytes). Si no usa un tamaño de fragmento que sea múltiplo de 320 KiB, se puede producir un error en las transferencias de archivos de gran tamaño después de que se cargue el último intervalo de bytes.

Respuestas de error

Vea Respuestas de error para obtener detalles sobre la manera en que se devuelven los errores.

Contenido relacionado

Cargar archivos de gran tamaño