Adicionar propriedades de arquivo personalizadas

As propriedades de arquivo personalizado são pares de chave-valor usados para armazenar metadados personalizados de um arquivo do Google Drive (como tags), IDs de outros armazenamentos de dados, informações compartilhadas entre aplicativos de fluxo de trabalho e assim por diante. Por exemplo, você pode adicionar propriedades de arquivos a todos os documentos gerados pelo departamento de vendas no primeiro trimestre.

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

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.

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

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

Como trabalhar com propriedades de arquivos personalizadas

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

Adicionar ou atualizar propriedades de arquivos personalizados

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 personalizadas do arquivo

Para 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

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 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, totalizando de todas as origens.
• Máximo de 30 propriedades públicas por arquivo, totalizando de todas as origens.
• Máximo de 30 propriedades privadas 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 com 10 caracteres só pode ter 114 caracteres no valor. Da mesma forma, uma propriedade que requer 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 arquivos personalizados particulares

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