Adicionar propriedades de arquivo personalizadas

As 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 arquivo a todos os documentos gerados pelo departamento de vendas no primeiro trimestre.

Para adicionar propriedades visíveis a todos os aplicativos, use o properties campo do files recurso. Para adicionar propriedades restritas ao seu 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 properties recurso para adicionar propriedades ao seu 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 no arquivo.

API Drive v3

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

API Drive v2

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

Como trabalhar com propriedades de arquivo personalizadas

Esta seção explica como realizar algumas tarefas relacionadas a propriedades de arquivo personalizadas 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 a todos os aplicativos, use o files.update método para definir o properties campo do files recurso.

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

Para conferir as propriedades visíveis a todos os aplicativos, use o files.get método para recuperar as propriedades de arquivo 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 a todos os aplicativos, use o files.update método para definir o properties campo do files recurso como nulo.

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

{
  "name": null
}

Para conferir a mudança, chame o files.get método para recuperar o properties objeto 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, totalizadas de todas as fontes.
• Máximo de 30 propriedades públicas por arquivo, totalizadas de todas as fontes.
• Máximo de 30 propriedades particulares por arquivo de um 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 files recurso. Para a API Drive v2, consulte o properties recurso.

Acessar propriedades de arquivo personalizadas particulares

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