Las propiedades de archivo personalizadas son pares clave-valor que se usan para almacenar metadatos personalizados de un archivo de Google Drive (como etiquetas), ID de otros almacenes de datos, información compartida entre aplicaciones de flujo de trabajo, etcétera. Por ejemplo, puedes agregar propiedades de archivos a todos los documentos generados por el departamento de Ventas en el primer trimestre.
Para agregar propiedades visibles para todas las aplicaciones, usa el campo properties del recurso files. Para agregar propiedades restringidas a tu app, usa el campo appProperties del recurso files.
Las propiedades también se pueden usar en expresiones de búsqueda.
Esta es la estructura de una propiedad típica que podría usarse para almacenar el ID de la base de datos de un archivo de Drive en el archivo.
API de Drive v3
"appProperties": {
"additionalID": "ID",
}
API de Drive v2
{
'key': 'additionalID',
'value': 'ID',
'visibility': 'PRIVATE'
}
Cómo trabajar con propiedades de archivos personalizadas
En esta sección, se explica cómo realizar algunas tareas relacionadas con la propiedad de un archivo personalizado que afectan a todas las aplicaciones.
Cómo agregar o actualizar propiedades de archivos personalizadas
Para agregar o actualizar propiedades visibles para todas las aplicaciones, usa el método files.update para establecer el campo properties del recurso files.
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
"properties": {
"name": "wrench",
"mass": "1.3kg",
"count": "3"
}
}
También puedes agregar una propiedad personalizada a un archivo mediante el servicio avanzado de Drive en Google Apps Script. Para obtener más información, consulta Agrega propiedades personalizadas.
Cómo obtener o enumerar propiedades de archivos personalizadas
Con el fin de ver las propiedades visibles para todas las aplicaciones, usa el método files.get para recuperar las propiedades personalizadas del archivo.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties
La respuesta consta de un objeto properties que contiene una colección de pares clave-valor.
{
"properties": {
"name": "wrench",
"mass": "1.3kg",
"count": "3"
}
}
Cómo borrar propiedades de archivos personalizadas
Para borrar valores de propiedad visibles para todas las aplicaciones, usa el método files.update para establecer el campo properties del recurso files en nulo.
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
"name": null
}
Para ver el cambio, llama al método files.get y recupera el objeto properties del archivo.
{
"properties": {
"mass": "1.3kg",
"count": "3"
}
}
Límites de las propiedades de archivos personalizados
Las propiedades personalizadas tienen los siguientes límites:
- Máximo de 100 propiedades personalizadas por archivo, en total de todas las fuentes.
- Un máximo de 30 propiedades públicas por archivo, en total de todas las fuentes.
- Se permite un máximo de 30 propiedades privadas por archivo de cualquier aplicación.
- Un máximo de 124 bytes por string de propiedad (incluidos la clave y el valor) en codificación UTF-8 Por ejemplo, una propiedad con una clave de 10 caracteres solo puede tener 114 caracteres en el valor. Del mismo modo, una propiedad que requiere 100 caracteres para el valor puede usar hasta 24 caracteres para la clave.
Para obtener más información, consulta el recurso files. Para la versión 2 de la API de Drive, consulta el recurso properties.
Cómo acceder a propiedades de archivos personalizados privados
Solo puedes recuperar propiedades privadas mediante el campo appProperties a través de una solicitud autenticada que usa un token de acceso obtenido con un ID de cliente de OAuth 2.0. No puedes usar una clave de API para recuperar propiedades privadas.