Adicionar propriedades de arquivo personalizadas

Propriedades de arquivo personalizadas são pares de chave-valor usados para armazenar metadados personalizados de um arquivo do Google Drive (como tags), IDs de outros repositórios de dados, informações compartilhadas entre aplicativos de fluxo de trabalho e assim por diante. Por exemplo, é possível adicionar propriedades de arquivos a todos os documentos gerados pelo departamento de vendas no primeiro trimestre.

Para adicionar propriedades visíveis a todos os aplicativos, use o campo properties do recurso files. Para adicionar propriedades restritas ao app, use o campo appProperties do recurso files.

Observação: se você estiver usando a versão mais antiga da API Google Drive (v2), utilize o recurso properties para adicionar propriedades ao app com o properties.insert. Para ver uma lista completa das diferenças entre as versões, consulte a referência da API Drive v2 e v3.

As propriedades também podem ser usadas em expressões de pesquisa.

Essa é a estrutura de uma propriedade típica que pode ser usada para armazenar o ID do banco de dados de um arquivo do Drive no arquivo.

API Drive v3

"appProperties": {
  "additionalID": "ID",
}

API Drive v2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

Como trabalhar com propriedades de arquivo personalizadas

A seção explica como executar algumas tarefas de arquivos personalizados que afetam todos os aplicativos.

Observação :a interface do Google Drive não inclui uma maneira integrada de editar propriedades personalizadas.

Adicionar ou atualizar propriedades personalizadas do arquivo

Para adicionar ou atualizar propriedades visíveis para todos os aplicativos, use o método files.update para definir o campo properties do recurso files.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Você também pode adicionar uma propriedade personalizada a um arquivo usando o serviço avançado do Drive no Google Apps Script. Para mais informações, consulte Como adicionar propriedades personalizadas.

Acessar ou listar propriedades de arquivo personalizadas

Se quiser conferir as propriedades visíveis para todos os aplicativos, use o método files.get para recuperar as propriedades personalizadas do arquivo.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

A resposta consiste em um objeto properties que contém uma coleção de pares de chave-valor.

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Excluir propriedades de arquivo personalizadas

Se quiser excluir valores de propriedade visíveis para todos os aplicativos, use o método files.update para definir o campo properties do recurso files como nulo.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "name": null
}

Para conferir a mudança, chame o método files.get para extrair o objeto properties do arquivo.

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

Limites das propriedades de arquivo personalizadas

As propriedades personalizadas têm os seguintes limites:

• Máximo de 100 propriedades personalizadas por arquivo, totalizadas de todas as origens.
• Máximo de 30 propriedades públicas por arquivo, totalizando de todas as origens.
• Máximo de 30 propriedades particulares por arquivo de qualquer aplicativo.
• Máximo de 124 bytes por string de propriedade (incluindo chave e valor) na codificação UTF-8. Por exemplo, uma propriedade com uma chave de 10 caracteres só pode ter 114 caracteres no valor. Da mesma forma, uma propriedade que exige 100 caracteres pode usar até 24 caracteres para a chave.

Para mais informações, consulte o recurso files. Para a API Drive v2, consulte o recurso properties.

Acessar propriedades de arquivos particulares personalizados

Só é possível recuperar propriedades particulares usando o campo appProperties por meio de uma solicitação autenticada que usa um token de acesso conseguido com um ID do cliente do OAuth 2.0. Não é possível usar uma chave de API para recuperar propriedades privadas.