Gerenciar metadados de arquivos

Este documento aborda considerações importantes sobre como nomear arquivos e trabalhar com metadados como miniaturas e texto indexável. Para começar a inserir e recuperar arquivos, consulte Referência de arquivos.

Especificar extensões e nomes de arquivos

Os apps precisam especificar uma extensão de arquivo na propriedade de título ao inserir arquivos com a API. 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 especificada originalmente na propriedade name. Quando um usuário do Google Drive solicita o download de um arquivo ou o download do arquivo pelo cliente de sincronização, o Drive cria um nome de arquivo completo (com extensão) com base no título. 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

Observação :a partir de 31 de outubro de 2022, o texto indexável pode ser exibido em snippets de resultado e afetará os resultados em mais lugares, incluindo o Cloud Search e a sobreposição no Drive e no Gmail.

O Drive indexa documentos automaticamente 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 arquivo, como desenhos, vídeos e atalhos, você poderá melhorar a possibilidade de descoberta fornecendo texto indexável no campo contentHints.indexableText 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>, o valor "aqui está algum texto" será indexado, mas "value1" não. Por isso, salvar XML como texto indexável não é tão útil quanto salvar HTML.

Ao especificar indexableText, lembre-se também:

• O limite de tamanho para contentHints.indexableText é de 128 KB.
• Capture os principais termos e conceitos que você espera que o usuário pesquise.
• Não tente classificar o texto em ordem de importância, porque o indexador faz isso de forma 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.

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

Enviar miniaturas

O Drive gera miniaturas automaticamente para vários tipos de arquivo comuns. Para atalhos e outros tipos de arquivo que o Drive não pode renderizar, forneça uma imagem de miniatura gerada pelo seu app. Faça upload de uma miniatura definindo a propriedade contentHints.thumbnail no recurso Files durante uma chamada create ou update, conforme mostrado a seguir:

• Defina contentHints.thumbnail.image como a imagem codificada em Base64 segura para URL (consulte a seção 5 do RFC 4648).
• Defina contentHints.thumbnail.mimeType como o tipo apropriado para o formato da imagem.

Se o Drive puder gerar uma miniatura a partir do arquivo, ele usará a miniatura gerada e ignorará qualquer arquivo enviado por você. Se ela não puder gerar uma miniatura, ela sempre vai usar a sua, caso você tenha fornecido uma. Lembretes:

• As miniaturas podem ser enviadas nos formatos PNG, GIF ou JPG.
• A largura recomendada é de 1.600 pixels.
• O tamanho máximo do arquivo para uma miniatura é de 2 MB.
• A largura mínima das miniaturas é de 220 pixels.
• Seu aplicativo deve atualizar as miniaturas a cada salvamento.

Importante :as miniaturas são invalidadas sempre que o conteúdo do arquivo muda. Ao fornecer miniaturas, é importante enviar novas miniaturas sempre que o conteúdo for modificado. As alterações nos metadados não invalidam as miniaturas.

Para mais informações, consulte a referência de arquivos.