driveItem: createUploadSession

  • Artículo

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. Las sesiones de carga también permiten que la transferencia se reanude si se quita una conexión mientras la carga está en curso.

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.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

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.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft) Files.ReadWrite Files.ReadWrite.All
Aplicación Sites.ReadWrite.All No disponible.

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. Como alternativa, 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 de aplazamiento 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 el identificador del elemento que se actualizará.

Creación de un nuevo archivo

POST /me/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 /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

Encabezados de solicitud

Nombre Valor Descripción
if-match etag Si se incluye este encabezado de solicitud y la eTag (o cTag) proporcionada no coincide con el etag actual en el elemento, se devuelve una 412 Precondition Failed respuesta de error.
if-none-match ETag Si se incluye este encabezado de solicitud y la eTag (o cTag) proporcionada coincide con el etag actual en el elemento, se devuelve una 412 Precondition Failed respuesta de error.

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",
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234,
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

En el ejemplo siguiente se controla el comportamiento si ya se ha tomado el nombre de archivo. En el 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
}

Encabezados de solicitud opcionales

Nombre Valor Descripción
if-match etag Si se incluye este encabezado de solicitud y la eTag (o cTag) proporcionada no coincide con el etag actual en el elemento, se devuelve una 412 Precondition Failed respuesta de error.

Parámetros

Parámetro Tipo Descripción
deferCommit Booleano Si se establece trueen , la creación final del archivo en el destino requiere una solicitud explícita.
item driveItemUploadableProperties Datos sobre el archivo que se está cargando.

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

La respuesta a esta solicitud, si se realiza correctamente, proporcionará los detalles sobre dónde deben enviarse el resto de las solicitudes como un recurso UploadSession.

Este recurso proporciona detalles sobre dónde debe cargarse el intervalo de bytes del archivo y cuándo expira la sesión de carga.

Si se especifica el fileSize parámetro y supera la cuota disponible, se devuelve una 507 Insufficent Storage respuesta y no se creará 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>

Nota:

  • Para cargar archivos grandes mediante SDK, consulte Carga de archivos grandes mediante los SDK de Microsoft Graph.
  • La aplicación debe asegurarse de que el tamaño total de archivo especificado en el encabezado Content-Range sea el mismo para todas las solicitudes. Si un intervalo de bytes indica un tamaño de archivo diferente, se producirá un error en la solicitud.

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

Comentarios

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

Finalización de un archivo

Si deferCommit es falso o no está establecido, la carga se completará automáticamente cuando el rango de bytes final del archivo sea PUT para la dirección URL de carga.

Si deferCommit es verdadero, puede completar la carga explícitamente 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 incluirá también la propiedad predeterminada establecida del driveItem que representa el archivo completo.

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

<final bytes of the file>

Nota:

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

Nota:

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 haya transcurrido el tiempo de expiración.

Solicitud

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

Nota:

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.

Nota:

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/v1.0/me/drive/root:/{path_to_parent}
Content-Type: application/json
If-Match: {etag or ctag}

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

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 item del 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 confiables, puede obtener mejores resultados de un tamaño de fragmento más pequeño. 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

Consulte el artículo Respuestas a errores para obtener más información sobre cómo se devuelven los errores.

Contenido relacionado

Cargar archivos de gran tamaño