Criar e gerenciar arquivos

Neste guia, explicamos como criar e gerenciar arquivos no Google Drive usando a API Google Drive.

Criar arquivo

Para criar um arquivo no Drive sem 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 fornecer esse valor.

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

Usar o parâmetro "fields"

Se você quiser especificar os campos a serem retornados na resposta, defina o parâmetro do sistema fields com qualquer método do recurso files. Se você omitir o parâmetro fields, o servidor vai retornar um conjunto padrão de campos específicos do método. Por exemplo, o método list retorna apenas os campos kind, id, name, mimeType e resourceKey de 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 autenticar em nome de um usuário, ele se tornará o proprietário do arquivo. O arquivo fica na pasta "Meu Drive" ou em uma pasta especificada. Ele consome a cota de armazenamento.

  • Conta de serviço: se o aplicativo se autenticar usando uma conta de serviço, ela será a proprietária do arquivo. O arquivo fica no armazenamento dedicado do Drive da conta de serviço. Os arquivos não aparecem em outras contas de armazenamento do Drive, a menos que sejam compartilhados explicitamente. Se a conta de serviço for excluída, todos os arquivos dela 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 arquivo 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 arquivo do seu app, em vez de deixar o Drive atribuí-los automaticamente.

É possível definir o número de IDs gerados usando o parâmetro de consulta count. Se count não estiver definido, 10 serão retornados por padrão. O número máximo de IDs que você pode solicitar é 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 com sucesso, as novas tentativas vão retornar 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 compatíveis com a criação de arquivos do Google Workspace, exceto os application/vnd.google-apps.drive-sdk e application/vnd.google-apps.folder tipos MIME. Da mesma forma, não é possível fazer uploads que referenciem uma conversão para um formato de arquivo do Google Workspace.

Criar arquivos somente de metadados

Arquivos somente de metadados não contêm conteúdo. Metadados são dados (como name, mimeType e createdTime) que descrevem o arquivo. Campos como name são independentes do usuário e aparecem da mesma forma para todos, 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 automaticamente miniaturas para tipos de arquivos comuns ou você pode fornecer uma imagem de 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 método copy no recurso files. Para encontrar o fileId a ser copiado, use o método list.

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

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

Use um escopo da API Drive adequado para autorizar a chamada. Para mais informações sobre os escopos do Drive, consulte Escolher escopos da API Google Drive.

Limitações e considerações

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

  • Permissões:

    • O objeto DownloadRestrictionsMetadata do recurso files determina quem pode copiar o arquivo. Para mais informações, consulte Impedir que os usuários façam o download, imprimam ou copiem seu arquivo.
    • O recurso de campo capabilities.canCopy determina se o usuário pode copiar um arquivo. Para mais informações, consulte Entender os recursos de arquivo.
    • O usuário que criou a cópia é o proprietário do arquivo copiado. Nenhuma outra configuração de compartilhamento do arquivo de origem é replicada. Se a cópia for criada em uma pasta compartilhada, ela vai herdar as permissões dessa pasta.
    • A propriedade de um arquivo copiado pode mudar, e a cópia pode não herdar as configurações de compartilhamento do arquivo original. Talvez seja necessário redefinir essas configurações.

  • Gerenciamento de arquivos:

    • Alguns arquivos, como atalhos de terceiros, nunca podem ser copiados.
    • Só é possível copiar um arquivo para uma pasta principal. Não é possível especificar vários elementos principais. Se o campo parents 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 copiá-la. Em vez disso, crie uma pasta de destino e defina o campo parents dos arquivos atuais como 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 à violação dos limites de cota da API Drive. Para mais informações, consulte Limites de uso.

Confira algumas das próximas etapas: