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 contenha conteúdo (mídia), faça o upload dos dados do arquivo. É possível fazer o upload dos metadados e do conteúdo de um arquivo em uma única solicitação (upload de várias partes) ou fazer o upload apenas da mídia (upload simples). Para mais informações, consulte Fazer upload de dados de arquivos.

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

Ao criar 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.

Os exemplos de código a seguir mostram como criar um arquivo sem metadados ou conteúdo:

Node.js

/**
 * Create an empty file.
 * @return {string} The created file's ID.
 */
async function createEmptyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.create({});
    console.log('File ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

Substitua:

  • ACCESS_TOKEN: o token OAuth 2.0 do seu app.

Usar o parâmetro "fields"

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, 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 do usuário.

  • Conta de serviço: se o aplicativo for autenticado 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 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 compatíveis com a criação de arquivos do Google Workspace, exceto para os application/vnd.google-apps.drive-sdk e application/vnd.google-apps.folder tipos MIME. Da mesma forma, não há suporte para uploads que referenciam uma conversão para um formato de arquivo do Google Workspace.

Os exemplos de código a seguir mostram como pré-gerar IDs de arquivos exclusivos:

Node.js

/**
 * Pre-generate unique file IDs.
 */
async function generateFileIds() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.generateIds({
      count: 10,
      space: 'drive'
    });
    const ids = response.data.ids;
    console.log('Generated IDs:');
    for (const id of ids) {
      console.log(id);
    }
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl 'https://www.googleapis.com/drive/v3/files/generateIds?count=10&space=drive' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

Substitua:

  • ACCESS_TOKEN: o token OAuth 2.0 do seu app.

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.

Os exemplos de código a seguir mostram como copiar um arquivo e atualizar o nome dele:

Node.js

/**
 * Copy an existing file.
 * @return {string} The copied file's ID.
 */
async function copyFile() {
  // Get credentials and build service
  // TODO(developer): Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  try {
    const response = await service.files.copy({
      fileId: 'FILE_ID',
      requestBody: {
        name: 'FILE_COPY_NAME'
      }
    });
    console.log('Copied file ID: ' + response.data.id);
    return response.data.id;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

Substitua:

  • FILE_ID: o ID do arquivo a ser copiado.
  • FILE_COPY_NAME: o nome do novo arquivo.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/copy' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "name": "FILE_COPY_NAME"
 }'

Substitua:

  • FILE_ID: o ID do arquivo a ser copiado.
  • ACCESS_TOKEN: o token OAuth 2.0 do seu app.
  • FILE_COPY_NAME: o nome do novo arquivo.

Copiar comentários

Para copiar comentários e sugestões ao copiar um arquivo do Documentos Google, Planilhas ou Apresentações, defina o copyComments parâmetro de consulta como true. O Drive copia apenas comentários abertos (não resolvidos). Para outros tipos de arquivo, o Drive ignora esse parâmetro.

Para mais informações sobre permissões, atribuição de comentários e considerações de acesso , consulte Limites e considerações.

Limites e considerações

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

  • Permissões:

    • O DownloadRestrictionsMetadata objeto 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 arquivos.
    • Para copiar comentários, você precisa ter permissão para ler comentários no arquivo de origem. Se você não tiver permissão para ler comentários e definir copyComments como true, a operação de cópia ainda será bem-sucedida, mas os comentários não serão copiados.
    • A cópia de comentários não concede aos autores de comentários originais acesso ao novo arquivo. As listas de controle de acesso (ACLs) do novo arquivo são independentes das ACLs do arquivo de origem.
    • 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. Essas configurações podem precisar ser redefinidas.

  • 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 há suporte para especificar vários pais. 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 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 à 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: