Administra operaciones de larga duración

Una operación de larga duración (LRO) es un método de API que tarda más tiempo en completarse que lo apropiado para una respuesta de API. Por lo general, no quieres mantener el subproceso de llamada abierto mientras se ejecuta la tarea, ya que ofrece una experiencia del usuario deficiente. En su lugar, es mejor mostrarle al usuario algún tipo de promesa y permitirle que vuelva a consultar más tarde.

La API de Google Drive muestra una LRO cada vez que llamas al método download() en el recurso files para descargar el contenido de un archivo, ya sea a través de la API de Drive o de sus bibliotecas cliente.

El método muestra 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(). Las LRO en la API de Drive se adhieren al 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 de alto nivel del funcionamiento del método file.download.

1. Llama a files.download: Cuando tu app llama al método download(), inicia la solicitud de descarga de la API de Drive para el archivo. Para obtener más información, consulta Cómo descargar archivos.

2. Solicita 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 la autenticación de un usuario que aún no se otorgó, le solicita que acceda. Tu app también solicita acceso con los alcances que especificas cuando configuras la autenticación.

3. Iniciar descarga: Se realiza una solicitud a la API de Drive para iniciar la descarga del archivo. La solicitud se puede realizar a Google Vids o a algún otro contenido de Google Workspace.

4. Iniciar LRO: Comienza una operación de larga duración que administra el proceso de descarga.

5. Devuelve una operación pendiente: La API de Drive muestra una operación pendiente que contiene información sobre el usuario que realiza la solicitud y varios campos de metadatos de archivos.

6. Estado pendiente inicial: Tu app recibe la operación pendiente junto con un estado pendiente inicial de done=null. Esto indica que el archivo aún no está listo para descargarse y que el estado de la operación está pendiente.

7. Llama a operations.get y verifica el resultado: Tu app llama a get() en 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 muestra el estado pendiente de done=false, tu app debe seguir sondeando hasta que la operación muestre el estado completado (done=true). En el caso de los archivos grandes, espera sondear varias veces. Para obtener más información, consulta Obtén los detalles de una operación de larga duración.

8. Verifica el estado pendiente: Si se muestra el estado pendiente de done=true desde la LRO, significa que el archivo está listo para descargarse y que el estado de la operación está completo.

9. Devuelve la operación completada con el URI de descarga: Una vez que se completa la LRO, la API de Drive muestra 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 consulta de file_id, mime_type y revision_id:

• Obligatorio. El parámetro de consulta file_id es el ID del archivo que se descargará.

• Opcional. El parámetro de consulta mime_type indica el tipo de MIME que debe usar el método. Solo está disponible cuando se descarga contenido multimedia que no es de blob (como documentos de Google Workspace). Para obtener una lista completa de los tipos de MIME compatibles, consulta Cómo exportar tipos de MIME para documentos de Google Workspace.

  Si no se establece el tipo MIME, el documento de Google Workspace se descarga con un tipo MIME predeterminado. Para obtener más información, consulta Tipos MIME predeterminadas.

• Opcional. El parámetro de consulta revision_id es el ID de la 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. Muestra el código de error INVALID_ARGUMENT cuando 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 la mejor opción para descargar la mayoría de los archivos de video.

Los vínculos de descarga generados para Documentos o Hojas de cálculo de Google muestran un redireccionamiento al principio. Haz clic en el nuevo vínculo para descargar el archivo.

Una solicitud al método download() que inicia la LRO y 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 solicitud.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Reemplaza 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 de BLOB, se asignan los siguientes tipos de MIME predeterminados:

Descarga la respuesta

Cuando llames al método download(), el cuerpo de la respuesta consistirá en un recurso que representa una operación de larga duración. Por lo general, el método muestra 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 gran cantidad de tiempo en completarse. Por lo general, las operaciones de descarga creadas recientemente se muestran inicialmente en un estado pendiente (done=null), en especial para los archivos de video.

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 el estado más reciente de una operación de larga duración de forma asíncrona. 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.

Cómo sondear 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.

Una LRO permanece disponible durante un mínimo de 12 horas, pero, en algunos casos, puede persistir más tiempo. Esta duración está sujeta a cambios y puede ser diferente entre los tipos de archivo. Una vez que venza el recurso, se necesitará 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 mediante claves de recursos.

Aquí se muestran los protocolos de solicitud.

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

Ten en cuenta que name solo se muestra 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 nuevamente 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 Cómo descargar la respuesta.

Cuando la respuesta contiene un estado completado (done=true), significa que la operación de larga duración finalizó.

Cómo descargar 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 muestra todos los revisionIds del archivo.

Para descargar el contenido de revisión de los archivos blob, debes llamar al método get() en el recurso revisions con el ID del archivo que deseas 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 está solicitando 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() con 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 necesitas configurar este parámetro de forma explícita.

Aquí se muestra el protocolo de solicitud.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Reemplaza lo siguiente:

• FILE_ID: Es el fileId del archivo que deseas descargar.
• REVISION_ID: Es el revisionId de la revisión que deseas descargar.

Las revisiones de Documentos, Presentaciones y Dibujos de Google incrementan automáticamente los números de revisión. Sin embargo, la serie de números podría tener brechas si se borran las revisiones, por lo que no debes depender de los números secuenciales para recuperarlas.

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 manejarlo. Para 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 API.

Temas relacionados

• Descarga y exporta archivos
• Administra las revisiones de archivos