Devuelve campos específicos

En este documento, se explica cómo usar el parámetro fields en Google Drive.

Para mostrar los campos exactos que necesitas y mejorar el rendimiento, usa el fields parámetro del sistema en la llamada de método.

Para obtener información sobre otros parámetros del sistema que se aplican a la API de Drive, consulta Parámetros del sistema alternativos.

Cómo funciona el parámetro fields

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 list método en el files recurso solo muestra los campos kind, id, name, y mimeType campos. El método get en el recurso permissions muestra un conjunto diferente de campos predeterminados.

Para todos los métodos de los recursos about, approvals, comments (excepto delete) y replies (excepto 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, devuelve un código de estado HTTP 200 OK, junto con los datos solicitados. Si el parámetro fields 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é fue lo que falló con tu selección de campos. Por ejemplo, files.list(fields='files(id,capabilities,canAddChildren)') genera un error de "Invalid field selection canAddChildren." El parámetro fields 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 estás consultando. 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 consulta específicos del archivo, consulta Términos y operadores de búsqueda.

Reglas de formato de parámetros de campo

El formato del valor del parámetro de solicitud de fields se basa de manera general en la sintaxis de XPath. Las siguientes son reglas de formato para el parámetro fields. Todas estas reglas 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 campo b que está anidado dentro del campo a, 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 array de permisos.

  • Para mostrar todos los campos de un objeto, usa un asterisco (*) como comodín en las selecciones de campos. Por ejemplo, 'permissions/permissionDetails/*' selecciona todos los campos de detalles de permisos disponibles por permiso. Ten en cuenta que usar el comodín puede generar un impacto negativo en el rendimiento de la solicitud.

  • No puedes seleccionar elementos individuales de un mapa cuando sus claves contienen caracteres especiales (como barras diagonales / o puntos .). Por ejemplo, si intentas seleccionar una clave de formato de exportación específica en exportLinks con fields=exportLinks/application/pdf, se genera un error HTTP 400 Bad Request porque el analizador de ruta de acceso interpreta la / como un delimitador de propiedad anidada. Para recuperar pares clave-valor con caracteres especiales en sus claves, solicita el mapa completo (como fields=exportLinks) y filtra los resultados del cliente.

Solicitud

En este ejemplo, proporcionamos el parámetro de ruta de acceso del ID de archivo y varios campos como parámetro de consulta en la solicitud. La respuesta muestra los valores de campo para el 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 con fields=role.
  • permissions.get con fields=* para mostrar todos los campos permissions.
  • files.get con fields=permissions(role) o fields=permissions/role.
  • files.get con fields=permissions para mostrar todos los campos permissions.
  • changes.list con fields=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).

Para especificar campos anidados dentro de arrays u objetos anidados, usa paréntesis anidados. Por ejemplo, para enumerar archivos con su ID, nombre y detalles del propietario anidados (nombre visible y dirección de correo electrónico) y, al mismo tiempo, recuperar el token de página siguiente para la paginación: files.list con fields=nextPageToken,files(id,name,owners(displayName,emailAddress)).

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 parámetro de consulta en la solicitud. La respuesta muestra los valores de campo para el 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"
    }
  ]
}

Parámetros del sistema alternativos

Los parámetros de consulta que se aplican a todas las operaciones de la API de Google Drive se documentan en Parámetros del sistema.