Adicionar propriedades de arquivo personalizadas

As propriedades personalizadas de arquivos são pares de chave-valor usados para armazenar metadados personalizados de um arquivo do Google Drive (como tags), IDs de outras lojas de dados, informações compartilhadas entre aplicativos de fluxo de trabalho e assim por diante. Por exemplo, é possível adicionar propriedades de arquivo 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), use o recurso properties para adicionar propriedades ao app usando properties.insert. Para uma lista completa de diferenças entre as versões, consulte a referência de comparação da API Drive v2 e v3.

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

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

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 realizar algumas tarefas personalizadas relacionadas a propriedades de arquivo 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 de arquivo personalizadas

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"
  }
}

Também é possível 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.

Receber ou listar propriedades de arquivos personalizadas

Para conferir as propriedades visíveis para todos os aplicativos, use o método files.get para extrair 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

Para 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 recuperar o objeto properties do arquivo.

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

Limites de propriedades de arquivo personalizadas

As propriedades personalizadas têm os seguintes limites:

• Máximo de 100 propriedades personalizadas por arquivo, totalizando todas as origens.
• Máximo de 30 propriedades públicas por arquivo, totalizando 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 para o valor 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 arquivo personalizadas particulares

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