Las propiedades de archivos personalizadas son pares clave-valor que se usan para almacenar metadatos personalizados de un archivo de Google Drive (como etiquetas), los ID de otros almacenes de datos, la información que se comparte entre las aplicaciones de flujo de trabajo, etcétera. Por ejemplo, puedes agregar propiedades de archivo a todos los documentos que generó el departamento de ventas en el primer trimestre.
Si deseas 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 se podría usar 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 personalizados
En esta sección, se explica cómo realizar algunas tareas relacionadas con las propiedades de los archivos personalizados que afectan a todas las aplicaciones.
Agrega o actualiza propiedades de archivos personalizados
Si deseas agregar o actualizar propiedades visibles para todas las aplicaciones, usa el método files.update a fin de configurar 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 con el servicio avanzado de Drive en Google Apps Script. Para obtener más información, consulta Cómo agregar propiedades personalizadas.
Cómo obtener o enumerar propiedades de archivos personalizados
Si quieres 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"
}
}
Borrar propiedades del archivo personalizado
Para borrar los 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 para recuperar el objeto properties del archivo.
{
"properties": {
"mass": "1.3kg",
"count": "3"
}
}
Límites de las propiedades de los archivos personalizados
Las propiedades personalizadas tienen los siguientes límites:
- Un máximo de 100 propiedades personalizadas por archivo, en total de todas las fuentes.
- Se permite un máximo de 30 propiedades públicas por archivo, desde todas las fuentes.
- Se permite un máximo de 30 propiedades privadas por archivo desde cualquier aplicación.
- Un máximo de 124 bytes por string de propiedad (incluidos la clave y el valor) en la codificación UTF-8. Por ejemplo, una propiedad con una clave de 10 caracteres solo puede tener 114 caracteres en el valor. De manera similar, 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 con el campo appProperties mediante 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.