Gerenciar metadados de arquivos

Este documento aborda considerações importantes para nomear arquivos e trabalhar com metadados, como texto indexável e miniaturas. Para inserir e recuperar arquivos, consulte o files recurso.

Visão geral de metadados

Na API Google Drive, o recurso files representa os metadados. Ao contrário das APIs em que os metadados são um subobjeto, a API Drive trata todo o recurso files como metadados. É possível acessar os metadados diretamente pelos get ou list métodos no files recurso.

Por padrão, os métodos get e list retornam apenas um conjunto parcial de campos. Para recuperar dados específicos, é necessário definir o fields parâmetro do sistema em sua solicitação. Se omitido, o servidor retorna um subconjunto 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 para cada arquivo. Para retornar campos diferentes, consulte Retornar campos específicos.

Além disso, a visibilidade dos metadados depende do papel do usuário no arquivo. O permissions recurso não determina as ações permitidas de um usuário em um arquivo ou pasta. Em vez disso, o recurso files contém uma coleção de campos booleanos capabilities. A API Google Drive deriva esses capabilities do recurso permissions associado ao arquivo ou pasta. Para mais informações, consulte Entender os recursos de arquivos.

A API Drive oferece dois escopos de metadados restritos: drive.metadata e drive.metadata.readonly. O escopo drive.metadata permite visualizar e gerenciar metadados de arquivos, enquanto drive.metadata.readonly é somente leitura. Ambos proíbem estritamente o acesso ao conteúdo do arquivo. Para mais informações, consulte Escolher escopos da API Google Drive.

Por fim, sempre verifique sua lógica em relação a permissões e escopos. Por exemplo, um usuário pode ser proprietário de um arquivo com permissões completas, mas a API Drive vai bloquear tentativas de modificar ou fazer o download do arquivo se o app tiver apenas o escopo drive.metadata.readonly.

Especificar nomes e extensões de arquivos

Os apps precisam especificar uma extensão de arquivo na name) propriedade ao inserir arquivos com a API Google Drive. Por exemplo, uma operação para inserir um arquivo JPEG precisa especificar algo como "name": "cat.jpg" nos metadados.

As respostas GET subsequentes podem incluir a propriedade fileExtension somente leitura preenchida com a extensão originalmente especificada na propriedade name. Quando um usuário do Google Drive solicita o download de um arquivo ou quando o arquivo é baixado pelo cliente de sincronização, o Drive cria um nome de arquivo completo (com extensão) com base no nome. Nos casos em que a extensão está ausente, o Drive tenta determinar a extensão com base no tipo MIME do arquivo.

Salvar texto indexável

O Drive indexa automaticamente os documentos para pesquisa quando reconhece o tipo de arquivo, incluindo documentos de texto, PDFs, imagens com texto e outros tipos comuns. Se o app salvar outros tipos de arquivos (como desenhos, vídeos e atalhos), você poderá melhorar a capacidade de descoberta fornecendo texto indexável no contentHints.indexableText campo do arquivo.

O texto indexável é indexado como HTML. Se você salvar a string de texto indexável <section attribute="value1">Here's some text</section>, então "Here's some text" será indexado, mas "value1" não. Por esse motivo, salvar XML como texto indexável não é tão útil quanto salvar HTML.

Ao especificar indexableText, também tenha em mente:

  • O limite de tamanho para contentHints.indexableText é de 128 KB.
  • Capture os principais termos e conceitos que você espera que um usuário pesquise.
  • Não tente classificar o texto por ordem de importância, porque o indexador faz isso de maneira eficiente para você.
  • O aplicativo precisa atualizar o texto indexável a cada salvamento.
  • Verifique se o texto está relacionado ao conteúdo ou aos metadados do arquivo.

Este último ponto pode parecer óbvio, mas é importante. Não é uma boa ideia adicionar termos pesquisados com frequência para forçar um arquivo a aparecer nos resultados da pesquisa. Isso pode frustrar os usuários e até mesmo motivá-los a excluir o arquivo.

Fazer upload de miniaturas

O Drive gera automaticamente miniaturas para muitos tipos de arquivos comuns, como Documentos, Planilhas e Apresentações Google. As miniaturas ajudam o usuário a identificar melhor os arquivos do Drive.

Para tipos de arquivo que o Drive não pode gerar uma miniatura padrão, você pode fornecer uma imagem de miniatura gerada pelo aplicativo. Durante a criação ou atualização do arquivo, faça o upload de uma miniatura definindo o contentHints.thumbnail campo no files recurso.

Especificamente:

  • Defina o campo contentHints.thumbnail.image como o URL e a imagem codificada em base64 segura para nome de arquivo (consulte a seção5 da RFC 4648).
  • Defina o campo contentHints.thumbnail.mimeType como o tipo MIME apropriado para a miniatura.

Se o Drive puder gerar uma miniatura do arquivo, ele usará a gerada automaticamente e ignorará qualquer outra que você tenha feito o upload. Se não for possível gerar uma miniatura, ele usará a que você fornecer.

As miniaturas precisam seguir estas regras:

  • Podem ser enviadas nos formatos PNG, GIF ou JPG.
  • A largura recomendada é de 1.600 pixels.
  • A largura mínima é de 220 pixels.
  • O tamanho máximo do arquivo é de 2 MB.
  • Elas precisam ser atualizadas pelo aplicativo a cada salvamento.

Para mais informações, consulte o files recurso.

Recuperar miniaturas

É possível recuperar metadados, incluindo miniaturas, para arquivos do Drive. As informações de miniatura estão no thumbnailLink campo do files recurso.

Retornar uma miniatura específica

O exemplo de código a seguir mostra uma solicitação de método get com vários campos como um parâmetro de consulta para retornar os metadados thumbnailLink de um arquivo específico. Para mais informações, consulte Retornar campos específicos de um arquivo.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Substitua FILE_ID pelo fileId do arquivo que você quer encontrar.

Se disponível, a solicitação retorna um URL de curta duração para a miniatura do arquivo. Normalmente, o link dura várias horas. O campo só é preenchido quando o app solicitante pode acessar o conteúdo do arquivo. Se o arquivo não for compartilhado publicamente, o URL retornado em thumbnailLink precisará ser buscado usando uma solicitação autenticada.

Retornar uma lista de miniaturas

O exemplo de código a seguir mostra uma solicitação de método list com vários campos como um parâmetro de consulta para retornar os metadados thumbnailLink de uma lista de arquivos. Para mais informações, consulte Pesquisar arquivos e pastas.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

Para restringir os resultados da pesquisa a um tipo de arquivo específico, aplique uma string de consulta para definir o tipo MIME. Por exemplo, o exemplo de código a seguir mostra como limitar a lista a arquivos do Planilhas Google. Para mais informações sobre tipos MIME, consulte Tipos MIME compatíveis com o Google Workspace e o Google Drive.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)