Para mostrar los campos exactos que necesitas y mejorar el rendimiento, usa el parámetro del sistema fields
en tu llamada al método.
En este documento, se explica cómo usar el parámetro fields
en Google Drive.
Cómo funciona el parámetro de campos
El parámetro fields
usa un FieldMask para filtrar respuestas. Las máscaras de campo se usan para especificar un subconjunto de campos que debe mostrar una solicitud. Usar una máscara de campo es una práctica de diseño recomendada para garantizar que no solicites datos innecesarios, lo que ayuda a evitar tiempos de procesamiento innecesarios.
Si no especificas el parámetro fields
, el servidor muestra un conjunto predeterminado de
campos específicos del método. Por ejemplo, el método list
en el método files
solo muestra los campos kind
, id
, name
y mimeType
. El método get
en el recurso permissions
muestra un conjunto diferente de campos predeterminados.
Para todos los métodos de los recursos about
, comments
(sin incluir delete
) y replies
(sin incluir delete
), debes configurar el parámetro fields
. Estos métodos no muestran un conjunto predeterminado de campos.
Después de que un servidor procesa una solicitud válida que incluye el parámetro fields
, muestra un código de estado HTTP 200 OK
, junto con los datos solicitados. Si el parámetro de campos tiene un error o no es válido, el servidor muestra un código de estado HTTP 400 Bad Request
, junto con un mensaje de error en el que se indica qué es lo que está mal con la selección de campos. Por ejemplo, files.list(fields='files(id,capabilities,canAddChildren)')
genera un error de "Invalid field selection canAddChildren". El parámetro de campos correcto para este ejemplo es files.list(fields='files(id,capabilities/canAddChildren)')
.
Para determinar los campos que puedes mostrar con el parámetro fields
, visita la página de documentación del recurso que consultas. Por ejemplo, para ver qué
campos puedes mostrar para un archivo, consulta la documentación del recurso files
.
Para obtener más términos de búsqueda específicos de archivos, consulta Operadores y términos de búsqueda.
Reglas de formato de parámetros de campo
El formato del valor del parámetro de solicitud de campos se basa de manera general en la sintaxis de XPath. Las siguientes son reglas de formato para el parámetro fields
. En todas estas
reglas, se usan ejemplos relacionados con el método files.get
.
Usa una lista separada por comas para seleccionar varios campos, como
'name, mimeType'
.Usa
a/b
para seleccionar el campob
que se anida en el campoa
, como'capabilities/canDownload'
. Para obtener más información, consulta Cómo recuperar los campos de un recurso anidado.Puedes usar un subselector para solicitar un conjunto de subcampos específicos de objetos o arreglos, si colocas las expresiones entre paréntesis “()”. Por ejemplo,
'permissions(id)'
solo muestra el ID de permiso para cada elemento del arreglo de permisos.Para mostrar todos los campos de un objeto, usa un asterisco (
*
) como comodín en las selecciones de campo. Por ejemplo,'permissions/permissionDetails/*'
selecciona todos los campos de detalles de permisos disponibles por permiso. Ten en cuenta que el uso de la virgulilla puede generar un impacto negativo en el rendimiento de la solicitud.
Mostrar un ejemplo
Solicitud
En este ejemplo, proporcionamos el parámetro de ruta de acceso del ID de archivo y varios campos como un parámetro de consulta en la solicitud. La respuesta muestra los valores de campo del ID de archivo.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared
Respuesta
{ "name": "File1", "starred": false, "shared": true } }
Cómo recuperar los campos de un recurso anidado
Cuando un campo hace referencia a otro recurso, puedes especificar qué campos del recurso anidado se deben recuperar.
Por ejemplo, para recuperar el campo role
(recurso anidado) del recurso permissions
, usa cualquiera de las siguientes opciones:
permissions.get
confields=role
.permissions.get
confields=*
para mostrar todos los campospermissions
files.get
confields=permissions(role)
ofields=permissions/role
files.get
confields=permissions
para mostrar todos los campospermissions
changes.list
confields=changes(file(permissions(role)))
.
Para recuperar varios campos, usa una lista separada por comas. Por ejemplo, files.list
con fields=files(id,name,createdTime,modifiedTime,size)
.
Mostrar un ejemplo
Solicitud
En este ejemplo, proporcionamos el parámetro de ruta de acceso del ID de archivo y varios campos, incluidos ciertos campos del recurso de permisos anidados, como un parámetro de consulta en la solicitud. La respuesta muestra los valores de campo del ID de archivo.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)
Respuesta
{ "name": "File1", "starred": false, "shared": true, "permissions": [ { "kind": "drive#permission", "type": "user", "role": "owner" } ] }
Temas relacionados
- Cómo resolver errores
- Cómo solucionar problemas de autenticación y autorización
- Mejora el rendimiento