Saltar al contenido principal

Cómo funciona Drive

Esta página explica el modelo de Drive y los mecanismos detrás de cada operación de Drive: cómo los archivos y las carpetas se anidan en un árbol, cómo funcionan el acceso y los roles de participantes, cómo se comportan la navegación y la búsqueda, cómo funcionan las descargas con URLs firmadas y el flujo de subida multipart en tres pasos en detalle. Para una orientación rápida y ejemplos listos para copiar y pegar, empieza por la introducción a Drive.

El modelo de Drive​

Drive contiene dos tipos de elementos:

  • Archivos — documentos, imágenes, videos y otro contenido binario que has subido. Cada uno tiene un mimeType y un size.
  • Carpetas — contenedores que agrupan archivos y otras carpetas.

Los elementos se anidan a través de un parentId, construyendo un árbol similar a un sistema de archivos:

Project Assets (folder)
├── Designs (folder)
│   ├── logo.png
│   └── banner.jpg
└── report.pdf

Los elementos sin un padre se ubican en la raíz de Drive.

Modelo de acceso​

El acceso sigue la propiedad y el uso compartido. Con un Personal Access Token, la API devuelve solo los elementos que el usuario autenticado posee o que han sido compartidos con él. Los participantes con quienes se comparte llevan un rol que rige lo que pueden hacer:

  • admin — acceso total, incluida la gestión de participantes.
  • member — puede subir, descargar, crear carpetas y modificar contenido.
  • viewer — acceso de solo lectura (ver metadatos y descargar archivos).
  • Tree — recorre la jerarquía en amplitud (breadth-first). Omite parentId para los elementos de nivel raíz, o pasa el id de una carpeta para su subárbol; controla la profundidad con depth (1–10, por defecto 3). Cada nodo tiene una bandera hasChildren para exploradores con carga diferida, y la respuesta está limitada a 500 elementos (con nextParentIds para continuar cuando se trunca).
  • Search — búsqueda de texto completo en los elementos accesibles mediante q, con sortBy, sortOrder y limit opcionales (1–50, por defecto 20).
  • Get file — devuelve los metadatos de un solo archivo o carpeta.

Descargar archivos​

Llama al endpoint …/download del archivo para obtener una URL firmada con tiempo limitado ({ "url": "…" }). Obtén el archivo con un simple GET HTTP contra esa URL. Las descargas aplican a archivos, no a carpetas.

Crear carpetas​

Haz un POST con un name, y un parentId opcional para anidar la carpeta dentro de otra. La respuesta es el nuevo elemento de carpeta.

Subir archivos (flujo multipart)​

Las subidas usan un flujo multipart al estilo de S3, de modo que los archivos de cualquier tamaño se suben de forma confiable dividiéndose en partes que van directamente al almacenamiento. Hay tres llamadas a la API; los bytes reales de las partes se envían con PUT directamente al almacenamiento, no a través de Copera.

Paso 1 — Start​

Haz un POST con los metadatos del archivo para iniciar la subida:

{
  "fileName": "report.pdf",
  "fileSize": 5242880,
  "mimeType": "application/pdf",
  "parentId": "<optional folder id>"
}

La respuesta te entrega un uploadId y una fileKey. Ambos son obligatorios en los dos pasos siguientes.

Paso 2 — Obtener URLs prefirmadas​

Haz un POST con el uploadId, la fileKey y parts — el número de partes que planeas subir (un conteo, no un arreglo):

{ "uploadId": "<uploadId>", "fileKey": "<fileKey>", "parts": 3 }

Recibes de vuelta un arreglo de { signedUrl, PartNumber }. Sube cada fragmento con un PUT HTTP a su signedUrl, y captura el encabezado ETag que el almacenamiento devuelve para cada parte.

Paso 3 — Finalize​

Haz un POST con el uploadId, la fileKey y las partes recopiladas para ensamblar el archivo y crear el registro en Drive:

{
  "uploadId": "<uploadId>",
  "fileKey": "<fileKey>",
  "parts": [
    { "partNumber": 1, "eTag": "<etag-1>" },
    { "partNumber": 2, "eTag": "<etag-2>" },
    { "partNumber": 3, "eTag": "<etag-3>" }
  ]
}

La respuesta es el elemento de archivo creado.

nota

Ten cuidado con el uso de mayúsculas y minúsculas. Los cuerpos de las solicitudes usan uploadId, partNumber y eTag en minúsculas. La respuesta de presigned-URLs usa signedUrl y PartNumber (con P mayúscula). El ETag de cada parte proviene de los encabezados de respuesta del PUT al almacenamiento — lo devuelves en finalize como eTag.

consejo

Si no necesitas un control detallado, el comando drive upload del CLI ejecuta todo este flujo por ti, incluidas las subidas de directorios.

Autenticación y alcance​

Los endpoints de Drive requieren un Personal Access Token (cp_pat_) con el alcance access_drive. Un token que carezca del alcance recibe un 403. Consulta Autenticación.

Referencia​