Pular para o conteúdo principal

Como o Drive Funciona

Esta página explica o modelo do drive e a mecânica por trás de cada operação de Drive: como arquivos e pastas se aninham em uma árvore, como o acesso e os papéis de participante funcionam, como a navegação e a busca se comportam, como os downloads via URL assinada funcionam, e o fluxo de upload multipart em três etapas em detalhes. Para uma orientação rápida e exemplos prontos para copiar e colar, comece pela introdução de Drive.

O modelo do drive​

O Drive contém dois tipos de itens:

  • Arquivos — documentos, imagens, vídeos e outros conteúdos binários enviados. Cada um tem um mimeType e um size.
  • Pastas — containers que agrupam arquivos e outras pastas.

Os itens se aninham por um parentId, construindo uma árvore parecida com um sistema de arquivos:

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

Itens sem um parent ficam na raiz do drive.

Modelo de acesso​

O acesso segue a propriedade e o compartilhamento. Com um Personal Access Token, a API retorna apenas itens que o usuário autenticado possui ou que foram compartilhados com ele. Participantes compartilhados carregam um papel que determina o que podem fazer:

  • admin — acesso total, incluindo gerenciamento de participantes.
  • member — pode fazer upload, download, criar pastas e modificar conteúdo.
  • viewer — acesso somente leitura (visualizar metadados e baixar arquivos).
  • Tree — percorre a hierarquia em largura (breadth-first). Omita parentId para itens de nível raiz, ou passe um id de pasta para sua subárvore; controle a profundidade com depth (1–10, padrão 3). Cada nó tem uma flag hasChildren para exploradores com lazy-loading, e a response é limitada a 500 itens (com nextParentIds para continuar quando truncada).
  • Search — busca full-text nos itens acessíveis por q, com sortBy, sortOrder e limit opcionais (1–50, padrão 20).
  • Get file — retorna os metadados de um único arquivo ou pasta.

Baixando arquivos​

Chame o endpoint …/download do arquivo para obter uma URL assinada com tempo limitado ({ "url": "…" }). Busque o arquivo com um GET HTTP simples nessa URL. Downloads se aplicam a arquivos, não a pastas.

Criando pastas​

Faça POST de um name, com um parentId opcional para aninhar a pasta dentro de outra. A response é o novo item de pasta.

Enviando arquivos (fluxo multipart)​

Uploads usam um fluxo multipart no estilo S3, então arquivos de qualquer tamanho são enviados de forma confiável ao serem divididos em partes que vão direto para o armazenamento. São três chamadas de API; os bytes das partes em si vão via PUT direto para o armazenamento, não pelo Copera.

Etapa 1 — Start​

POST dos metadados do arquivo para iniciar o upload:

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

A response te dá um uploadId e um fileKey. Ambos são exigidos pelas duas etapas seguintes.

Etapa 2 — Obter URLs presigned​

POST do uploadId, do fileKey e de parts — o número de partes que você pretende enviar (uma contagem, não um array):

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

Você recebe de volta um array de { signedUrl, PartNumber }. Envie cada chunk com um PUT HTTP para sua signedUrl, e capture o header ETag que o armazenamento retorna para cada parte.

Etapa 3 — Finalize​

POST do uploadId, do fileKey e das partes coletadas para montar o arquivo e criar o registro no Drive:

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

A response é o item de arquivo criado.

observação

Atenção ao uso de maiúsculas e minúsculas. Os corpos de request usam uploadId, partNumber e eTag em minúsculas. A response de presigned-urls usa signedUrl e PartNumber (P maiúsculo). O ETag de cada parte vem dos headers da response do PUT no armazenamento — você o passa de volta no finalize como eTag.

dica

Se você não precisa de controle fino, o drive upload da CLI executa todo esse fluxo para você, incluindo uploads de diretórios.

Autenticação e escopo​

Endpoints de Drive exigem um Personal Access Token (cp_pat_) com o escopo access_drive. Um token sem o escopo recebe um 403. Veja Autenticação.

Referência​