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 archivo a todos los documentos generados por el departamento de ventas en el primer trimestre.
Si quieres 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 las 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 personalizadas de los archivos
En esta sección, se explica cómo realizar algunas tareas personalizadas de la propiedad de archivos que afectan a todas las aplicaciones.
Cómo agregar o actualizar propiedades de archivos personalizadas
Si deseas agregar o actualizar las 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 Agrega propiedades personalizadas.
Obtén o enumera propiedades de archivos personalizadas
Si quieres ver las propiedades visibles para todas las aplicaciones, usa el método files.get a fin de 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"
}
}
Borra las propiedades del archivo personalizado
A fin de borrar los valores de propiedad visibles para todas las aplicaciones, usa el método files.update a fin de 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 a fin de recuperar el objeto properties para el archivo.
{
"properties": {
"mass": "1.3kg",
"count": "3"
}
}
Límites de las propiedades personalizadas de los archivos
Las propiedades personalizadas tienen los siguientes límites:
- Máximo de 100 propiedades personalizadas por archivo, totales de todas las fuentes.
- Máximo de 30 propiedades públicas por archivo, totales de todas las fuentes.
- Máximo de 30 propiedades privadas por archivo desde cualquier aplicación.
- Máximo de 124 bytes por string de propiedad (incluidos el valor y la clave) 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 en el caso de la clave.
Para obtener más información, consulta el recurso files. Para la API de Drive v2, consulta el recurso properties.
Cómo acceder a propiedades privadas de archivos personalizados
Solo puedes recuperar propiedades privadas con el campo appProperties a través de una solicitud autenticada que use 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.