Criar e gerenciar arquivos

Este guia explica como criar e gerenciar arquivos no Google Drive usando a API Google Drive.

Criar arquivo

Para criar um arquivo no Drive que não contenha metadados ou conteúdo, use o método create no recurso files sem parâmetros.

Quando você cria o arquivo, o método retorna um recurso files. O arquivo recebe um kind de drive.file, um id, um name de "Sem título" e um mimeType de application/octet-stream. O uploadType é marcado como obrigatório, mas o padrão é media. Portanto, não é necessário fornecê-lo.

Para mais informações sobre os limites de arquivos do Drive, consulte Limites de arquivos e pastas.

Usar o parâmetro de campos

Se você quiser especificar os campos a serem retornados na resposta, defina o fields parâmetro do sistema com qualquer método do recurso files. Se você omitir o parâmetro fields, o servidor retornará um conjunto padrão de campos específicos do método. Por exemplo, o list método retorna apenas os kind, id, name, mimeType e resourceKey campos para cada arquivo. Para retornar campos diferentes, consulte Retornar campos específicos.

Propriedade do arquivo

Quando um arquivo é criado usando a API Drive, a propriedade depende das credenciais de autenticação usadas pelo app das seguintes maneiras:

  • Conta de usuário (OAuth 2.0): se o aplicativo for autenticado em nome de um usuário, esse usuário se tornará o proprietário do arquivo. O arquivo reside na pasta "Meu Drive" ou em uma pasta especificada. Ele consome a cota de armazenamento.

  • Conta de serviço: se o aplicativo for autenticado usando uma conta de serviço, essa conta será a proprietária do arquivo. O arquivo reside no armazenamento no Drive dedicado da conta de serviço. Os arquivos não aparecem em outras contas de armazenamento no Drive, a menos que sejam compartilhados explicitamente. Se a conta de serviço for excluída, todos os arquivos que ela possui serão excluídos imediatamente.

    Se você estiver usando uma conta de serviço, mas quiser que uma conta de usuário específica seja proprietária de um arquivo, use a delegação em todo o domínio. Isso permite que a conta de serviço represente um usuário e crie arquivos em nome dele. Para mais informações, consulte Delegar autoridade em todo o domínio à conta de serviço.

Para mais informações sobre permissões de arquivos, consulte Compartilhar arquivos, pastas e drives.

Gerar IDs para usar com seus arquivos

O método generateIds no recurso files permite pré-gerar IDs de arquivos exclusivos que podem ser usados ao criar ou copiar arquivos e pastas no Drive. Isso pode ser útil quando você precisa controlar os IDs de arquivos do seu app, em vez de permitir que o Drive os atribua automaticamente.

É possível definir o número de IDs gerados usando o count parâmetro de consulta. Se count não estiver definido, 10 serão retornados por padrão. O número máximo de IDs que você pode solicitar é de 1.000.

Também é possível designar o space em que os IDs podem ser usados e o type de itens para os quais os IDs podem ser usados.

Depois que um ID é gerado, ele pode ser transmitido para o método create ou copy pelo campo id. Isso garante que o arquivo criado ou copiado use o ID predeterminado.

Se o arquivo for criado ou copiado, as novas tentativas retornarão uma resposta de código de status HTTP 409 Conflict, e arquivos duplicados não serão criados.

Os IDs pré-gerados não são aceitos para a criação de arquivos do Google Workspace, exceto para os tipos application/vnd.google-apps.drive-sdk e application/vnd.google-apps.folder MIME. Da mesma forma, os uploads que fazem referência a uma conversão para um formato de arquivo do Google Workspace não são aceitos.

Criar arquivos somente de metadados

Os arquivos somente de metadados não contêm conteúdo. Os metadados são dados (como name, mimeType e createdTime) que descrevem o arquivo. Campos como name são agnósticos do usuário e aparecem da mesma forma para cada usuário, enquanto campos como viewedByMeTime contêm valores específicos do usuário.

Um exemplo de arquivo somente de metadados é uma pasta com o tipo MIME application/vnd.google-apps.folder. Para mais informações, consulte Criar e preencher pastas. Outro exemplo é um atalho que aponta para outro arquivo no Drive com o tipo MIME application/vnd.google-apps.shortcut. Para mais informações, consulte Criar um atalho para um arquivo do Drive.

Gerenciar imagens em miniatura

As miniaturas ajudam os usuários a identificar arquivos do Drive. O Drive pode gerar miniaturas automaticamente para tipos de arquivos comuns ou você pode fornecer uma imagem em miniatura gerada pelo seu app. Para mais informações, consulte Fazer upload de miniaturas.

Copiar um arquivo

Para copiar um arquivo e aplicar as atualizações solicitadas, use o copy método no recurso files. Para encontrar o fileId a ser copiado, use o list método.

É possível aplicar atualizações usando a semântica de patch, o que significa que você pode fazer modificações parciais em um recurso. É necessário definir explicitamente os campos que você pretende modificar na solicitação. Todos os campos não incluídos na solicitação mantêm os valores atuais. Para mais informações, consulte Trabalhar com recursos parciais.

É possível predefinir o ID do arquivo copiado usando o generateIds método. Para mais informações, consulte Gerar IDs para usar com seus arquivos.

É necessário usar um escosto da API Drive adequado para autorizar a chamada. Para mais informações sobre os escopos do Drive, consulte Escolher escopos da API Google Drive.

Limites e considerações

Ao se preparar para copiar arquivos, observe estes limites e considerações:

  • Permissões:

  • Gerenciamento de arquivos:

    • Alguns arquivos, como atalhos de terceiros, nunca podem ser copiados.
    • Só é possível copiar um arquivo para uma pasta mãe. Não é possível especificar várias pastas mãe. Se o parents campo não for especificado, o arquivo vai herdar todos os pais detectáveis do arquivo de origem.
    • Embora uma pasta seja um tipo de arquivo, não é possível copiar uma pasta. Em vez disso, crie uma pasta de destino e defina o campo parents dos arquivos atuais para a pasta de destino. Em seguida, exclua a pasta de origem original.
    • A menos que um novo nome de arquivo seja especificado, o método copy produz um arquivo com o mesmo nome do original.
    • O uso excessivo de copy pode levar à excedência dos limites de cota da API Drive. Para mais informações, consulte Limites de uso.

Confira algumas próximas etapas que você pode tentar: