Elige los permisos de la API de Google Drive

Este documento contiene información específica sobre la autorización y la autenticación de la API de Google Drive. Antes de leer este documento, asegúrate de leer la información general sobre la autenticación y la autorización de Google Workspace en Más información sobre la autenticación y la autorización.

Configura OAuth 2.0 para la autorización

Para autorizar tu app, la API de Google Drive requiere que definas permisos de OAuth en dos lugares: la consola de Google Cloud y tu app.

En la consola de Google Cloud, debes declarar los alcances que necesita tu app en la configuración de la pantalla de consentimiento de OAuth. Estos son los permisos de nivel más alto que tu app puede solicitar. Esto funciona como una solicitud formal a Google, y los permisos declarados son los que Google muestra a los usuarios en la pantalla de consentimiento. Permite que el usuario comprenda exactamente a qué datos y acciones solicita acceso tu app.

Configura la pantalla de consentimiento de OAuth y elige permisos para definir qué información se muestra a los usuarios y revisores de apps, y registra tu app para que puedas publicarla más adelante.

En tu app, cuando inicialices la API, debes solicitar explícitamente los alcances específicos que necesitas para esa sesión. Si bien la consola de Google Cloud define el nivel más alto de permisos que tu app puede solicitar, el código determina los permisos reales para un usuario determinado. Esto ayuda a garantizar que la app solo solicite los permisos necesarios para una tarea específica.

Puedes declarar uno o más permisos de OAuth a la vez dentro del código de tu app como un array.

En el siguiente ejemplo de código, se muestra cómo declarar varios alcances de OAuth:

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

Para ver cómo se declaran y usan los permisos en un ejemplo de código completo, consulta Guías de inicio rápido.

Permisos de la API de Drive

Para definir el nivel de acceso que se otorga a tu app, debes identificar y declarar los alcances de autorización. Un alcance de autorización es una cadena de URI de OAuth 2.0 que contiene el nombre de la app de Google Workspace, el tipo de datos a los que accede y el nivel de acceso. Los permisos son las solicitudes de tu app para trabajar con datos de Google Workspace, incluidos los datos de las Cuentas de Google de los usuarios.

Cuando se instala tu app, se le pide al usuario que valide los alcances que usa la app. Por lo general, debes elegir el alcance más específico posible y evitar solicitar alcances que tu app no necesite. Los usuarios otorgan acceso más fácilmente a los permisos limitados y claramente descritos.

Siempre que sea posible, usa permisos no sensibles, ya que otorgan acceso por archivo y limitan el acceso a funciones específicas que necesita una app.

Permisos no sensibles

Se recomiendan los siguientes alcances de la API de Drive para la mayoría de los casos de uso:

Código de alcance Descripción
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 Permite ver y administrar los datos de configuración propios de la app en tu unidad de Google Drive.
https://www.googleapis.com/auth/drive.install Permitir que las apps aparezcan como opción en el menú "Abrir con" o "Nuevo"
https://www.googleapis.com/auth/drive.file Crear archivos nuevos de Drive o modificar los existentes que abras con una app o que el usuario comparta con una app mientras usa la API de Google Picker o el selector de archivos de la app

Permisos sensibles

Código de alcance Descripción
https://www.googleapis.com/auth/drive.apps.readonly Consulta las apps que tienen autorización para acceder a tu Drive.

Permisos restringidos

Código de alcance Descripción
https://www.googleapis.com/auth/drive Consulta y administra todos tus archivos de Drive.
https://www.googleapis.com/auth/drive.readonly Ver y descargar todos tus archivos de Drive
https://www.googleapis.com/auth/drive.activity Ver y agregar contenido en el registro de actividad de los archivos de tu unidad de Drive
https://www.googleapis.com/auth/drive.activity.readonly Ver el registro de actividad de los archivos de tu unidad de Drive
https://www.googleapis.com/auth/drive.meet.readonly Ver los archivos de Drive que creó o editó Google Meet
https://www.googleapis.com/auth/drive.metadata Permite ver y administrar los metadatos de los archivos en tu Drive.
https://www.googleapis.com/auth/drive.metadata.readonly Permite ver los metadatos de los archivos de tu unidad de Drive.
https://www.googleapis.com/auth/drive.scripts Modifica el comportamiento de las secuencias de comandos de Google Apps Script.

Los alcances de las tablas anteriores indican su sensibilidad, según las siguientes definiciones:

Si tu app requiere acceso a otras APIs de Google, también puedes agregar esos permisos. Si deseas obtener más información sobre los permisos de las APIs de Google, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

Si deseas obtener más información sobre permisos específicos de OAuth 2.0, consulta Permisos de OAuth 2.0 para las APIs de Google.

Requisitos para los permisos restringidos

Solo se permiten tipos de aplicaciones específicos para usar permisos restringidos de Google Drive. Para cumplir con los requisitos, tu app debe pertenecer a una de las siguientes categorías:

  1. Copia de seguridad y sincronización: Son apps web y específicas de la plataforma que proporcionan sincronización local o copia de seguridad automática de los archivos de Drive de los usuarios.

  2. Productividad y educación: Apps con una interfaz de usuario principal que puede implicar la interacción con archivos, metadatos o permisos de Drive Estas apps incluyen la administración de tareas, la toma de notas, las comunicaciones de grupos de trabajo y la colaboración en el aula.

  3. Informes y seguridad: Apps que proporcionan estadísticas a los usuarios o clientes sobre cómo se comparten o acceden a los archivos

Para seguir usando los permisos restringidos, debes preparar tu app para la verificación de permisos restringidos.

Migra una app existente desde permisos restringidos

Si tu app de Drive usa alcances restringidos, te recomendamos que migres a un alcance no sensible de la API de Drive. El uso de permisos no sensibles, como drive.file, otorga acceso por archivo y acceso limitado a funciones específicas que necesita una app.

Muchas apps pueden realizar la transición al acceso por archivo sin ningún cambio.

Si usas tu propio selector de archivos, te recomendamos que cambies a la API de Google Picker, que admite diferentes alcances por completo.

Beneficios del alcance de archivos de Drive

Usar el permiso de OAuth drive.file en combinación con la API de Google Picker optimiza la experiencia del usuario y la seguridad de tu app.

El alcance de OAuth drive.file permite que los usuarios elijan qué archivos quieren compartir con tu app, lo que les brinda más control y confianza en que el acceso de tu app a sus archivos es limitado y más seguro. Por el contrario, solicitar acceso amplio a todos los archivos de Drive podría disuadir a los usuarios de interactuar con tu app.

A continuación, se indican algunos motivos por los que deberías usar el alcance de drive.file:

  • Usabilidad: El permiso drive.file funciona con todos los recursos de REST de la API de Drive, lo que significa que puedes usarlo de la misma manera que usas permisos de OAuth más amplios.

  • Funciones: La API de Google Picker proporciona una interfaz similar a la IU de Drive. Esto incluye varias vistas que muestran vistas previas y miniaturas de los archivos de Drive, y una ventana modal intercalada para que los usuarios nunca salgan de la app principal.

  • Comodidad: Las apps pueden aplicar filtros para ciertos tipos de archivos de Drive (como Documentos, Hojas de cálculo y fotos de Google) cuando se usa un filtro en los archivos del Selector de Google.

  • Verificación sencilla: Dado que drive.file no es sensible, permite un proceso de verificación más optimizado.

Almacena tokens de actualización de forma segura

Para acceder a datos privados con la API de Drive, tu app debe obtener un token de acceso que le otorgue acceso a esa API. Un solo token de acceso puede otorgar diferentes grados de acceso a varias APIs, según los permisos que solicites.

Debido a que los tokens de acceso son de corta duración, debes usar tokens de actualización para obtener acceso a largo plazo a la API de Drive. Un token de actualización permite que tu app solicite tokens de acceso nuevos.

Guarda los tokens de actualización en un almacenamiento seguro a largo plazo y sigue usándolos mientras sigan siendo válidos.

Para obtener más información, consulta Usa OAuth 2.0 para acceder a las APIs de Google.