Una operación de larga duración (LRO) es un método de API que tarda más en completarse de lo que es apropiado para una respuesta de API. Por lo general, no querrás mantener abierto el subproceso de llamada mientras se ejecuta la tarea, ya que esto ofrece una mala experiencia del usuario. En su lugar, es mejor devolver algún tipo de promesa al usuario y permitirle que vuelva a consultar más tarde.
La API de Google Drive devuelve una LRO cada vez que llamas al método download en el recurso files para descargar el contenido de un archivo a través de la API de Drive o sus bibliotecas cliente.
El método devuelve un recurso operations al cliente. Puedes usar el recurso operations para recuperar de forma asíncrona el estado del método de la API sondeando la operación a través del método get. Los LRO de la API de Drive cumplen con el patrón de diseño de LRO de Google Cloud.
Para obtener más información, consulta Operaciones de larga duración.
Descripción general del proceso
En el siguiente diagrama, se muestran los pasos generales de cómo funciona el método file.download.
Llamada a
files.download: Cuando tu app llama al métododownload, se inicia la solicitud de descarga de la API de Drive para el archivo. Para obtener más información, consulta Descarga archivos.Solicitar permisos: La solicitud envía credenciales de autenticación a la API de Drive. Si tu app requiere llamar a la API de Drive con una autenticación de usuario que aún no se otorgó, se le solicitará al usuario que acceda. Tu app también solicita acceso con alcances que especificas cuando configuras la autenticación.
Iniciar descarga: Se realiza una solicitud a la API de Drive para iniciar la descarga del archivo. La solicitud se podría hacer a Google Vids o a algún otro contenido de Google Workspace.
Start LRO: Se inicia una operación de larga duración que administra el proceso de descarga.
Devuelve la operación pendiente: La API de Drive devuelve una operación pendiente que contiene información sobre el usuario que realiza la solicitud y varios campos de metadatos del archivo.
Estado inicial pendiente: Tu app recibe la operación pendiente junto con un estado inicial pendiente de
done=null. Esto indica que el archivo aún no está listo para descargarse y que el estado de la operación es pendiente.Llama a
operations.gety verifica el resultado: Tu app llama ageten los intervalos recomendados para sondear el resultado de la operación y obtener el estado más reciente de una operación de larga duración. Si se devuelve el estado pendiente dedone=false, tu app debe seguir sondeo hasta que la operación devuelva el estado completado (done=true). En el caso de archivos grandes, espera sondear varias veces. Para obtener más información, consulta Obtén detalles sobre una operación de larga duración.Verifica el estado pendiente: Si el LRO devuelve el estado pendiente de
done=true, esto indica que el archivo está listo para descargarse y que el estado de la operación se completó.Devuelve la operación completada con el URI de descarga: Una vez que finaliza la LRO, la API de Drive devuelve el URI de descarga y el archivo ya está disponible para el usuario.
Descarga los archivos correspondientes
Para descargar contenido en una operación de larga duración, usa el método download en el recurso files. El método toma los parámetros de búsqueda de file_id, mime_type y revision_id:
Obligatorio. El parámetro de búsqueda
file_ides el ID del archivo que se descargará.Opcional. El parámetro de consulta
mime_typedenota el tipo de MIME que debe usar el método. Solo está disponible cuando se descarga contenido multimedia que no es de tipo BLOB (como documentos de Google Workspace). Para obtener una lista completa de los tipos de MIME admitidos, consulta Tipos de MIME de exportación para documentos de Google Workspace.Si no se establece el tipo de MIME, el documento de Google Workspace se descarga con un tipo de MIME predeterminado. Para obtener más información, consulta Tipos MIME predeterminados.
Opcional. El parámetro de búsqueda
revision_ides el ID de revisión del archivo que se descargará. Solo está disponible cuando se descargan archivos blob, Documentos de Google y Hojas de cálculo de Google. Devuelve el código de errorINVALID_ARGUMENTcuando se descarga una revisión específica en archivos no compatibles.
El método download es la única forma de descargar archivos de Vids en formato MP4 y, por lo general, es el más adecuado para descargar la mayoría de los archivos de video.
Los vínculos de descarga que se generan inicialmente para Documentos o Hojas de cálculo de Google muestran un redireccionamiento. Haz clic en el vínculo nuevo para descargar el archivo.
Tanto la solicitud al método download que inicia la LRO como la solicitud para recuperar el URI de descarga final deben usar claves de recursos. Para obtener más información, consulta Cómo acceder a archivos de Drive compartidos con un vínculo usando claves de recursos.
Aquí se muestra el protocolo de la solicitud.
POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/downloadReemplaza FILE_ID por el fileId del archivo que deseas descargar.
Tipos de MIME predeterminados
Si no se establece un tipo de MIME cuando se descarga contenido que no es un BLOB, se asignan los siguientes tipos de MIME predeterminados:
| Tipo de documento | Formato | Tipo de MIME | Extensión de archivo |
|---|---|---|---|
| Google Apps Script | JSON | application/vnd.google-apps.script+json | .json |
| Documentos de Google | Microsoft Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx |
| Dibujos de Google | PNG | image/png | .png |
| Formularios de Google | ZIP | application/zip | .zip |
| Hojas de cálculo de Google | Microsoft Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| Google Sites | Texto sin procesar | text/raw | .txt |
| Presentaciones de Google | Microsoft PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx |
| Google Vids | MP4 | application/mp4 | .mp4 |
| Jamboard | application/pdf |
Descarga la respuesta
Cuando llamas al método download, el cuerpo de la respuesta consta de un recurso que representa una operación de larga duración. Por lo general, el método devuelve un vínculo para descargar el contenido del archivo.
{
"done": true,
"metadata": {
"@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
"resourceKey": "RESOURCE_KEY"
},
"name": "NAME",
"response": {
"@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
"downloadUri": "DOWNLOAD_URI",
"partialDownloadAllowed": false
}
}
En esta salida, se incluyen los siguientes valores:
RESOURCE_KEY: Una clave de recurso ayuda a proteger tu archivo del acceso no deseado. Para obtener más información, consulta Cómo acceder a archivos de Drive compartidos con un vínculo usando claves de recursos.
NAME: Es el nombre asignado por el servidor.
DOWNLOAD_URI: Es el URI de descarga final del archivo.
Ten en cuenta que el campo partialDownloadAllowed indica si se permite una descarga parcial. Es verdadero cuando se descarga el contenido de un archivo BLOB.
Obtén los detalles de una operación de larga duración
Las operaciones de larga duración son llamadas a métodos que pueden tardar una cantidad considerable de tiempo en completarse. Por lo general, las operaciones de descarga recién creadas se muestran inicialmente en estado pendiente (done=null), en especial para los archivos de Vids.
Puedes usar el recurso operations que proporciona la API de Drive para verificar el estado de la LRO de procesamiento. Para ello, incluye el nombre único asignado por el servidor.
El método get obtiene de forma asíncrona el estado más reciente de una operación de larga duración. Los clientes pueden usar este método para sondear el resultado de la operación por intervalos según la recomendación del servicio de la API.
Sondea una operación de larga duración
Para sondear una LRO disponible, llama de forma reiterada al método get hasta que finalice la operación.
Usa una retirada exponencial entre cada solicitud de sondeo, por ejemplo, 10 segundos.
Un LRO permanece disponible durante un mínimo de 12 horas, pero, en algunos casos, puede persistir durante más tiempo. Esta duración está sujeta a cambios y puede variar según el tipo de archivo. Una vez que vence el recurso, es necesaria una nueva solicitud del método download.
Todas las solicitudes a get deben usar claves de recursos. Para obtener más información, consulta Cómo acceder a archivos de Drive compartidos con un vínculo usando claves de recursos.
Aquí se muestran los protocolos de solicitud.
Llamada de método
operations.get(name='NAME');
Reemplaza NAME por el nombre asignado por el servidor a la operación, como se muestra en la respuesta a la solicitud del método download.
curl
curl -i -H \
'Authorization: Bearer $(gcloud auth print-access-token)" \
'https://googleapis.com/drive/v3/operations/NAME?alt=json'
Reemplaza NAME por el nombre asignado por el servidor a la operación, como se muestra en la respuesta a la solicitud del método download.
El comando usa la ruta de acceso /drive/v3/operations/NAME.
Ten en cuenta que el name solo se devuelve en la respuesta a una solicitud download.
No hay otra forma de recuperarlo, ya que la API de Drive no admite el método List. Si se pierde el valor de name, debes generar una respuesta nueva llamando de nuevo a la solicitud del método download.
La respuesta de una solicitud get consiste en un recurso que representa una operación de larga duración. Para obtener más información, consulta Descarga la respuesta.
Cuando la respuesta contiene un estado completado (done=true), significa que la operación de larga duración finalizó.
Descarga una revisión
Puedes usar el valor del campo headRevisionId del recurso files para descargar la revisión más reciente. Esto recupera la revisión que corresponde a los metadatos del archivo que recuperaste anteriormente. Para descargar los datos de todas las revisiones anteriores del archivo que aún se almacenan en la nube, puedes llamar al método list en el recurso revisions con el parámetro fileId. Esto devuelve todos los revisionIds del archivo.
Para descargar el contenido de la revisión de los archivos de BLOB, debes llamar al método get en el recurso revisions con el ID del archivo que se descargará, el ID de la revisión y el parámetro de URL alt=media. El parámetro de URL alt=media le indica al servidor que se solicita una descarga de contenido como formato de respuesta alternativo.
Las revisiones de Documentos, Hojas de cálculo, Presentaciones y Vids de Google no se pueden descargar con el método get y la URL alt=media . De lo contrario, genera un error fileNotDownloadable.
El parámetro de URL alt=media es un parámetro del sistema disponible en todas las APIs de REST de Google. Si usas una biblioteca cliente para la API de Drive, no es necesario que establezcas este parámetro de forma explícita.
Aquí se muestra el protocolo de la solicitud.
GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=mediaReemplaza lo siguiente:
- FILE_ID: Es el
fileIddel archivo que deseas descargar. - REVISION_ID: Es el
revisionIdde la revisión que deseas descargar.
Las revisiones de Documentos, Dibujos y Presentaciones de Google incrementan automáticamente los números de revisión. Sin embargo, la serie de números puede tener brechas si se borran revisiones, por lo que no debes confiar en los números secuenciales para recuperar revisiones.
Soluciona problemas de LRO
Cuando falla una LRO, su respuesta incluye un código de error canónico de Google Cloud.
En la siguiente tabla, se proporciona una explicación de la causa de cada código y una recomendación para controlarlo. En el caso de muchos errores, la acción recomendada es volver a intentar la solicitud con la retirada exponencial.
Puedes obtener más información sobre este modelo de error y cómo trabajar con él en la Guía de diseño de APIs.
| Código | Enum | Descripción | Acción recomendada |
|---|---|---|---|
| 1 | CANCELLED |
La operación se canceló (por lo general, la cancela el emisor). | Vuelve a ejecutar la operación. |
| 2 | UNKNOWN |
Este error puede mostrarse cuando un valor Status recibido de otro espacio de direcciones pertenece a un espacio de error desconocido en este espacio de direcciones. Si el error de la API no muestra suficiente información, es posible que el error se convierta en este. |
Vuelve a intentarlo con una retirada exponencial. |
| 3 | INVALID_ARGUMENT |
El cliente especificó un argumento no válido. Este error difiere de FAILED_PRECONDITION. INVALID_ARGUMENT indica los argumentos que son problemáticos sin importar el estado del sistema, como un nombre de archivo con formato incorrecto. |
No vuelvas a intentarlo sin solucionar el problema. |
| 4 | DEADLINE_EXCEEDED |
El plazo venció antes de que la operación se pudiera completar. En el caso de las operaciones que cambian el estado del sistema, es probable que se muestre este error incluso si la operación se completó correctamente. Por ejemplo, una respuesta correcta desde un servidor podría haberse retrasado lo suficiente como para que el plazo venciera. | Vuelve a intentarlo con una retirada exponencial. |
| 5 | NOT_FOUND |
No se encontró alguna entidad solicitada, como un recurso de FHIR. | No vuelvas a intentarlo sin solucionar el problema. |
| 6 | ALREADY_EXISTS |
Ya existe la entidad que un cliente intentó crear, como una instancia de DICOM. | No vuelvas a intentarlo sin solucionar el problema. |
| 7 | PERMISSION_DENIED |
El llamador no tiene permiso para ejecutar la operación especificada. Este código de error no implica que la solicitud sea válida, que la entidad solicitada exista o que satisfaga otras condiciones previas. | No vuelvas a intentarlo sin solucionar el problema. |
| 8 | RESOURCE_EXHAUSTED |
Se agotó algún recurso, como una cuota por proyecto. | Vuelve a intentarlo con una retirada exponencial. Es posible que la cuota esté disponible con el tiempo. |
| 9 | FAILED_PRECONDITION |
La operación se rechazó porque el sistema no se encuentra en un estado necesario para la ejecución de la operación. Por ejemplo, el directorio que se borrará no está vacío, o se aplicará una operación rmdir a un elemento que no es un directorio. |
No vuelvas a intentarlo sin solucionar el problema. |
| 10 | ABORTED |
La operación se anuló, generalmente debido a un problema de simultaneidad, como una falla en la verificación del secuenciador o la anulación de la transacción. | Vuelve a intentarlo con una retirada exponencial. |
| 11 | OUT_OF_RANGE |
La operación se intentó más allá del rango válido, como buscar o leer más allá del final del archivo. A diferencia de INVALID_ARGUMENT, este error indica un problema que se puede solucionar si cambia el estado del sistema. |
No vuelvas a intentarlo sin solucionar el problema. |
| 12 | UNIMPLEMENTED |
La operación no se implementó, no se admite o no está habilitada en la API de Drive. | No volver a intentar. |
| 13 | INTERNAL |
Errores internos. Esto indica que se produjo un error inesperado en el procesamiento del sistema subyacente. | Vuelve a intentarlo con una retirada exponencial. |
| 14 | UNAVAILABLE |
La API de Drive no está disponible. Lo más probable es que esta sea una condición transitoria y que se pueda corregir si vuelves a intentarlo con una retirada exponencial. Ten en cuenta que no siempre es seguro reintentar operaciones no idempotentes. | Vuelve a intentarlo con una retirada exponencial. |
| 15 | DATA_LOSS |
Daño o pérdida de datos no recuperable. | Comunícate con tu administrador del sistema. Es posible que el administrador del sistema quiera comunicarse con un representante de asistencia si se produjo pérdida o corrupción de datos. |
| 16 | UNAUTHENTICATED |
La solicitud no tiene credenciales de autenticación válidas para la operación. | No vuelvas a intentarlo sin solucionar el problema. |