La API de Google Drive te permite subir datos de archivos cuando creas o actualizas un File
. Para obtener información sobre cómo crear un File
de solo metadatos, consulta Cómo crear archivos.
Existen 3 tipos de cargas que puedes realizar:
Carga simple (
uploadType=media
): Usa este tipo de carga para transferir un archivo multimedia pequeño (5 MB o menos) sin proporcionar metadatos. Para realizar una carga simple, consulta Realiza una carga simple.Carga multiparte (
uploadType=multipart
): Usa este tipo de carga para transferir un archivo pequeño (5 MB o menos) junto con los metadatos que describen el archivo, en una sola solicitud. Para realizar una carga multiparte, consulta Realiza una carga multiparte.Carga reanudable (
uploadType=resumable
): Usa este tipo de carga para archivos grandes (más de 5 MB) y cuando haya una alta probabilidad de interrupción de la red, como cuando se crea un archivo desde una app para dispositivos móviles. Las cargas reanudables también son una buena opción para la mayoría de las aplicaciones, ya que también funcionan para archivos pequeños a un costo mínimo de una solicitud HTTP adicional por carga. Para realizar una carga reanudable, consulta Realiza una carga reanudable.
Las bibliotecas cliente de la API de Google implementan al menos uno de estos tipos de cargas. Consulta la documentación sobre la biblioteca cliente para obtener más detalles acerca de cómo usar cada uno de los tipos.
Usa PATCH
en comparación con PUT
A modo de repaso, el verbo HTTP PATCH
admite una actualización parcial de los recursos de archivo, mientras que el verbo HTTP PUT
admite el reemplazo completo de recursos. Ten en cuenta que PUT
puede introducir cambios rotundos cuando se agrega un campo nuevo a un recurso existente.
Cuando subas un recurso de archivo, usa los siguientes lineamientos:
- Usa el verbo HTTP documentado en la referencia de la API para la solicitud inicial de una carga reanudable o para la única solicitud de una carga simple o de varias partes.
- Usa
PUT
para todas las solicitudes posteriores de una carga reanudable una vez que se haya iniciado la solicitud. Estas solicitudes suben contenido sin importar el método al que se llama.
Realiza una carga simple
Para realizar una carga simple, usa el método files.create con uploadType=media
.
A continuación, se muestra cómo realizar una carga simple:
HTTP
Crea una solicitud
POST
para el URI /upload del método con el parámetro de búsquedauploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Agrega los datos del archivo al cuerpo de la solicitud.
Agrega estos encabezados HTTP:
Content-Type
. Se establece como el tipo de archivo multimedia de MIME del objeto que se sube.Content-Length
. Se establece como la cantidad de bytes que subes. Si usas la codificación de transferencia fragmentada, este encabezado no es obligatorio.
Envía la solicitud. Si la solicitud se realiza correctamente, el servidor muestra el código de estado
HTTP 200 OK
junto con los metadatos del archivo. {HTTP}
Cuando realizas una carga simple, se crean metadatos básicos y algunos atributos se infieren del archivo, como el tipo de MIME o modifiedTime
. Puedes usar una carga simple en los casos en que tengas archivos pequeños y los metadatos de archivos no sean importantes.
Cómo realizar una carga multiparte
Una solicitud de carga multiparte te permite subir metadatos y datos en la misma solicitud. Usa esta opción si los datos que envías son lo suficientemente pequeños como para volver a subirlos por completo si falla la conexión.
Para realizar una carga multiparte, usa el método files.create con uploadType=multipart
.
A continuación, se muestra cómo realizar una carga multiparte:
Java
Python
Node.js
PHP
.NET
HTTP
Crea una solicitud
POST
para el URI /upload del método con el parámetro de búsquedauploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Crea el cuerpo de la solicitud. Dale formato al cuerpo según el tipo de contenido multiparte o relacionado [RFC 2387], que contiene 2 partes:
- Metadatos. Los metadatos deben ir primero y tener un encabezado
Content-Type
establecido enapplication/json;
charset=UTF-8
. Agrega los metadatos del archivo en formato JSON. - Contenido multimedia. El contenido multimedia debe ir en segundo lugar y debe tener un encabezado
Content-Type
de cualquier tipo de MIME. Agrega los datos del archivo a la parte multimedia.
Identifica cada parte con una string de límite, precedida por 2 guiones. Además, agrega 2 guiones después de la string de límite final.
- Metadatos. Los metadatos deben ir primero y tener un encabezado
Agrega estos encabezados HTTP de nivel superior:
Content-Type
. Se establece enmultipart/related
y, luego, incluye la string de límite que usas para identificar las diferentes partes de la solicitud. Por ejemplo:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Configurado como la cantidad total de bytes en el cuerpo de la solicitud.
Envía la solicitud.
Para crear o actualizar solo la parte de metadatos, sin los datos asociados, envía una solicitud POST
o PATCH
al extremo de recurso estándar: https://www.googleapis.com/drive/v3/files
Si la solicitud se realiza correctamente, el servidor muestra el código de estado HTTP 200 OK
junto con los metadatos del archivo.
Cuando creas archivos, deben especificar una extensión en el campo name
del archivo. Por ejemplo, cuando crees un archivo JPEG de foto, puedes especificar algo como "name": "photo.jpg"
en los metadatos. Las llamadas posteriores a files.get muestran la propiedad de solo lectura fileExtension
que contiene la extensión que se especificó originalmente en el campo name
.
Realiza una carga reanudable
Una carga reanudable te permite reanudar una operación de carga después de que una falla de comunicación interrumpa el flujo de datos. Debido a que no es necesario reiniciar grandes cargas de archivos desde el principio, las cargas reanudables también pueden reducir el uso del ancho de banda si hay una falla de red.
Las cargas reanudables son útiles cuando los tamaños de tus archivos pueden variar mucho o cuando hay un límite de tiempo fijo para las solicitudes (como tareas en segundo plano del SO para dispositivos móviles y ciertas solicitudes de App Engine). También puedes usar cargas reanudables para las situaciones en las que desees mostrar una barra de progreso de carga.
Una carga reanudable consiste en varios pasos de alto nivel:
- Envía la solicitud inicial y recupera el URI de la sesión reanudable.
- Sube los datos y supervisa el estado de carga.
- (Opcional) Si se interrumpe la carga, reanúdala.
Envía la solicitud inicial
Para iniciar una carga reanudable, usa el método files.create con uploadType=resumable
.
HTTP
Crea una solicitud
POST
para el URI /upload del método con el parámetro de búsquedauploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Si la solicitud de inicio se realiza de forma correcta, la respuesta incluye un código de estado HTTP
200 OK
. Además, incluye un encabezadoLocation
que especifica el URI de la sesión reanudable:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Guarda el URI de la sesión reanudable para que puedas subir los datos del archivo y consultar el estado de la carga. Los URI de sesión reanudables vencen después de una semana.
Si tienes metadatos para el archivo, agrégalos al cuerpo de la solicitud en formato JSON. De lo contrario, deja el cuerpo de la solicitud vacío.
Agrega estos encabezados HTTP:
X-Upload-Content-Type
. Es opcional. Se establece en el tipo de MIME de los datos del archivo, que se transfieren en solicitudes posteriores. Si el tipo de MIME de los datos no se especifica en los metadatos o a través de este encabezado, el objeto se entrega comoapplication/octet-stream.
.X-Upload-Content-Length
. Es opcional. Se establece como la cantidad de bytes de datos del archivo que se transfieren en solicitudes posteriores.Content-Type
. Es obligatorio si existen metadatos para el archivo. Se establece enapplication/json;
charset=UTF-8
.Content-Length
. Es obligatorio, a menos que uses la codificación de transferencia fragmentada. Configurado como la cantidad de bytes en el cuerpo de esta solicitud inicial.
Envía la solicitud. Si la solicitud de inicio de sesión se realiza de forma correcta, la respuesta incluirá un código de estado
200 OK HTTP
. Además, la respuesta incluye un encabezadoLocation
que especifica el URI de la sesión reanudable. Usa el URI de la sesión reanudable para subir los datos del archivo y consultar el estado de la carga. Los URI de sesión reanudables vencen después de una semana.Copia y guarda la URL de la sesión reanudable.
Continúa con el proceso para subir el contenido.
Sube el contenido
Existen 2 maneras de subir un archivo con una sesión reanudable:
- Sube contenido en una sola solicitud: Usa este enfoque cuando el archivo se pueda subir en una solicitud, si no hay un límite de tiempo fijo para una sola solicitud, o si no necesitas mostrar un indicador de progreso de carga. Este enfoque es mejor porque requiere menos solicitudes y da como resultado un mejor rendimiento.
Sube el contenido en varios fragmentos: Usa este enfoque si debes reducir la cantidad de datos transferidos en una sola solicitud. Es posible que debas reducir los datos transferidos cuando haya un límite de tiempo fijo para las solicitudes individuales, como puede ser el caso de ciertas clases de solicitudes de App Engine. Este enfoque también es útil si debes proporcionar un indicador personalizado para mostrar el progreso de la carga.
HTTP: solicitud única
- Crea una solicitud
PUT
para el URI de la sesión reanudable. - Agrega los datos del archivo al cuerpo de la solicitud.
- Agrega un encabezado HTTP Content-Length, configurado en la cantidad de bytes del archivo.
- Envía la solicitud. Si se interrumpe la solicitud de carga o si recibes una respuesta
5xx
, sigue el procedimiento que se describe en Cómo reanudar una carga interrumpida.
HTTP: Varias solicitudes
Crea una solicitud
PUT
para el URI de la sesión reanudable.Agrega los datos del fragmento al cuerpo de la solicitud. Crea fragmentos en múltiplos de 256 KB (256 x 1024 bytes), excepto el último fragmento que completa la carga. Mantén el tamaño del fragmento lo más grande posible para que la carga sea eficiente.
Agrega estos encabezados HTTP:
Content-Length
. Se establece en la cantidad de bytes del fragmento actual.Content-Range
. Configurado para mostrar qué bytes del archivo subes. Por ejemplo,Content-Range: bytes 0-524287/2000000
muestra que subes los primeros 524,288 bytes (256 x 1,024 x 2) de un archivo de 2,000,000 bytes.
Envía la solicitud y procesa la respuesta. Si se interrumpe la solicitud de carga o si recibes una respuesta
5xx
, sigue el procedimiento que se describe en Cómo reanudar una carga interrumpida.Repite los pasos del 1 al 4 para cada fragmento que permanezca en el archivo. Usa el encabezado
Range
en la respuesta para determinar dónde comenzar el siguiente fragmento. No supongas que el servidor recibió todos los bytes que se enviaron en la solicitud anterior.
Cuando se complete la carga del archivo, recibirás una respuesta 200 OK
o 201 Created
, junto con los metadatos asociados al recurso.
Reanuda una carga interrumpida
Si una solicitud de carga se finaliza antes de una respuesta, o si recibes una respuesta 503 Service Unavailable
, debes reanudar la carga interrumpida.
HTTP
Crea una solicitud
PUT
vacía para el URI de sesión reanudable a fin de solicitar el estado de la carga.Agrega un encabezado
Content-Range
para indicar que se desconoce la posición actual en el archivo. Por ejemplo, configuraContent-Range
como*/2000000
si el tamaño total del archivo es de 2,000,000 bytes. Si no sabes el tamaño del archivo, estableceContent-Range
en*/*
.Envía la solicitud.
Procesa la respuesta:
- Una respuesta
200 OK
o201 Created
indica que se completó la carga y que no es necesario realizar ninguna otra acción. - Una respuesta
308 Resume Incomplete
indica que debes seguir subiendo el archivo. - Una respuesta
404 Not Found
indica que venció la sesión de carga y que la carga debe reiniciarse desde el principio.
- Una respuesta
Si recibiste una respuesta
308 Resume Incomplete
, procesa el encabezadoRange
de la respuesta para determinar qué bytes recibió el servidor. Si la respuesta no tiene un encabezadoRange
, no se recibió ningún byte. Por ejemplo, un encabezadoRange
debytes=0-42
indica que los primeros 43 bytes del archivo se recibieron y que el siguiente fragmento que se subió debería comenzar con el byte 44.Ahora que sabes dónde reanudar la carga, continúa subiendo el archivo comenzando con el siguiente byte. Incluye un encabezado
Content-Range
para indicar qué parte del archivo envías. Por ejemplo,Content-Range: bytes 43-1999999
indica que envías bytes 44 a 2,000,000.
Cómo solucionar errores de carga de contenido multimedia
Cuando subas contenido multimedia, sigue estas prácticas recomendadas para controlar los errores:
- Para los errores
5xx
, reanuda o vuelve a intentar cargas que no se realizaron de forma correcta debido a interrupciones en la conexión. Para obtener más información sobre el manejo de errores de5xx
, consulta Cómo resolver un error5xx
. - Para ver
403 rate limit
error, vuelva a subir el archivo. Para obtener más información sobre cómo solucionar errores403 rate limit
, consulta Resuelve un403 error: Rate limit exceeded
. - Para cualquier error
4xx
(incluido403
) durante una carga reanudable, reinicia la carga. Estos errores indican que la sesión de carga venció y se debe solicitar un URI de sesión nuevo para reiniciarla. Las sesiones de carga también vencen después de una semana de inactividad.
Importar a tipos de Documentos de Google
Cuando crees un archivo en Drive, es posible que desees convertirlo en un tipo de archivo de Google Workspace, como un documento de Google o una hoja de cálculo de Google. Por ejemplo, es posible que desees convertir un documento de tu procesador de texto favorito en un Documento de Google para aprovechar sus funciones.
Para convertir un archivo en un tipo de archivo específico de Google Workspace, especifica el mimeType
de Google Workspace cuando crees el archivo.
A continuación, se muestra cómo convertir un archivo CSV en una hoja de cálculo de Google Workspace:
Java
Python
Node.js
PHP
.NET
Para ver si hay una conversión disponible, verifica el array importFormats
del recurso About antes de crear el archivo. Las conversiones admitidas están disponibles de forma dinámica en este array. Estos son algunos formatos comunes de importación:
Desde | A |
---|---|
Microsoft Word, texto de OpenDocument, HTML, RTF, texto sin formato | Documentos de Google |
Microsoft Excel, hoja de cálculo de OpenDocument, CSV, TSV, texto sin formato | Hojas de cálculo de Google |
Microsoft PowerPoint, presentación de OpenDocument | Presentaciones de Google |
JPEG, PNG, GIF, BMP, PDF | Documentos de Google (incorpora la imagen en un documento) |
Texto sin formato (tipo de MIME especial) JSON | Google Apps Script |
Cuando subes y conviertes contenido multimedia durante una solicitud update
a un documento, una hoja de cálculo o una presentación, se reemplaza todo el contenido del documento.
Cuando conviertes una imagen en un documento, Drive usa el reconocimiento óptico de caracteres (OCR) para convertir la imagen en texto. Puedes mejorar la calidad del algoritmo de OCR si especificas el código de idioma BCP 47 aplicable en el parámetro ocrLanguage
.
El texto extraído aparece en el documento junto a la imagen incorporada.
Use un ID generado previamente para subir archivos
La API de Drive te permite recuperar una lista de ID de archivos generados previamente que se usan para subir y crear recursos. Las solicitudes de carga y creación de archivos pueden usar estos ID generados previamente. Establece el campo id
en los metadatos del archivo.
Para crear ID generados con anterioridad, llama a file.generateIds con la cantidad de ID que quieras crear.
Puedes volver a intentarlo de forma segura con los ID generados previamente si hay un tiempo de espera o un error del servidor indeterminado. Si el archivo se creó correctamente, los reintentos posteriores mostrarán un error HTTP 409
y no se crearán archivos duplicados.
Cómo definir texto indexable para tipos de archivos desconocidos
Los usuarios pueden usar la IU de Drive para buscar contenido de documentos. También puedes usar files.list y el campo fullText
para buscar contenido de tu app. Si deseas obtener más información, consulta Cómo buscar archivos y carpetas.
Drive indexa documentos automáticamente para la búsqueda cuando reconoce el tipo de archivo, incluidos los documentos de texto, los PDF, las imágenes con texto y otros tipos comunes. Si tu app guarda otros tipos de archivos (como dibujos, video y accesos directos), puedes proporcionar texto indexable en el campo contentHints.indexableText
del archivo para mejorar la visibilidad.
Para obtener más información sobre el texto indexable, consulta Administra metadatos de archivos.