Cómo configurar una integración de IU de Drive

Para mostrar tu app en Google Drive cuando un usuario crea o abre un archivo, primero debes configurar una integración de la interfaz de usuario (IU) de Drive. También se requiere configuración para publicar tu app en Google Workspace Marketplace.

Habilita la API de Drive

Antes de usar las APIs de Google, debes activarlas en un proyecto de Google Cloud. Puedes activar una o más APIs en un solo proyecto de Google Cloud.

Para comenzar a integrar la IU de Google Drive, debes habilitar la API de Drive. Esto te da acceso a las funciones de integración de la API y la IU.

• En la consola de Google Cloud, habilita la API de Google Drive.

  Habilitar la API

Configura la integración en la IU de Drive

1. En la consola de APIs de Google, ve a Menú > APIs y servicios > APIs y servicios habilitados.

   Ir a APIs y servicios habilitados

2. En la parte inferior del panel de APIs y servicios, haz clic en API de Google Drive. Aparecerá la página de configuración de la API de Google Drive.
3. Selecciona la pestaña Integración de la IU de Drive.
4. (Opcional) Ingresa un nombre en el campo Nombre de la aplicación. El nombre de la aplicación se muestra a los usuarios en la pestaña Administrar apps de la configuración de Drive.
5. (Opcional) Ingresa una descripción breve de una línea en el campo Descripción breve. La descripción breve se muestra a los usuarios en la pestaña Administrar apps de la configuración de Drive.
6. (Opcional) Ingresa una descripción completa en el campo Descripción larga.

7. Sube uno o más íconos de aplicación para que se muestren en la lista de apps de Drive conectadas del usuario y en el menú contextual "Abrir con". Los íconos deben estar en formato PNG con un fondo transparente. Los íconos pueden tardar hasta 24 horas en aparecer en Drive.

   Nota: Los íconos de documentos están obsoletos. El ícono de tu aplicación aparece junto a los archivos de accesos directos y de accesos directos de terceros. Para otros tipos de archivos, se usa un conjunto de íconos estándar.

8. Para usar el elemento de menú "Abrir con" de la IU de Drive, ingresa la URL de tu app en el campo Abrir URL. El menú contextual "Abrir con" usa esta URL.

   • Esta URL debe contener un nombre de dominio completamente calificado; localhost no funciona.
   • Se debe poder acceder a esta URL desde los usuarios previstos de tu aplicación. Si tienes varias versiones de la aplicación, como una para el lanzamiento público y otra para el lanzamiento restringido a usuarios seleccionados, cada versión debe usar una URL única. Luego, puedes crear diferentes configuraciones de la app para cada versión.
   • Antes de publicar tu app en Google Workspace Marketplace, debes verificar la propiedad de esta URL.
   • De forma predeterminada, se agrega un parámetro de consulta state a esta URL para pasar datos de la IU de Drive a tu app. Para obtener información sobre el contenido del parámetro state, consulta El parámetro state.
   Advertencia: La opción para mostrar automáticamente la pantalla de consentimiento de OAuth 2.0 está obsoleta. No marques esta casilla. La aplicación debe iniciar todas las solicitudes de autorización.

9. (Opcional) Ingresa los tipos de MIME y las extensiones de archivo predeterminados en los campos Tipos de MIME predeterminados y Extensiones de archivo predeterminadas. Los tipos de MIME y las extensiones de archivo predeterminados representan los archivos que tu app está diseñada de forma exclusiva para abrir. Por ejemplo, tu app podría abrir un formato integrado para superponer y editar imágenes. Incluye solo tipos de medios estándar y asegúrate de que no tengan errores tipográficos ni ortográficos. Si tu app solo abre archivos de accesos directos o de accesos directos de terceros, puedes dejar el tipo de MIME en blanco.

10. (Opcional) Ingresa tipos de MIME y extensiones de archivo secundarios en los campos Tipos de MIME secundarios y Extensiones de archivo secundarias. Los tipos de MIME y las extensiones de archivo secundarios representan archivos que tu app puede abrir, pero no son específicos de ella. Por ejemplo, tu app podría ser una app de edición de imágenes que abre imágenes PNG y JPG. Incluye solo tipos de medios estándar y asegúrate de que no tengan errores tipográficos ni ortográficos. Si tu app solo abre archivos de accesos directos o de accesos directos de terceros, puedes dejar el tipo de MIME en blanco.

    Nota: Si un usuario instala varias apps de Drive que pueden abrir un archivo, se usará la app instalada más recientemente hasta que el usuario elija otra.

11. Para usar el botón "Nuevo" de la IU de Drive y permitir que los usuarios creen un archivo con tu app, marca la casilla Creación de archivos. Aparecerán los campos URL nueva y Nombre del documento (opcional).

    • Esta URL debe contener un nombre de dominio completamente calificado; localhost no funciona.
    • Antes de publicar tu app en Google Workspace Marketplace, debes verificar la propiedad de esta URL.
    • De forma predeterminada, se agrega un parámetro de consulta state a esta URL para pasar datos de la IU de Drive a tu app. Para obtener información sobre el contenido del parámetro state, consulta El parámetro state.

12. Ingresa una URL en el campo URL nueva. El botón "Nuevo" usa esta URL para redireccionar al usuario a tu aplicación.

    Nota: Deja en blanco el campo Nombre del documento. Este campo ya no se usa.

13. (Opcional) Si quieres que tu app abra archivos compatibles con Google Workspace, marca la casilla Importing.

14. (Opcional) Si tu app debe administrar archivos en unidades compartidas, marca la casilla Shared drives support. Para obtener más información sobre cómo admitir unidades compartidas en tu app, consulta Implementa la compatibilidad con unidades compartidas.

15. Haz clic en Enviar.

Solicita el alcance de drive.install

Para permitir que las apps aparezcan como opción en el menú "Abrir con" o "Nuevo", solicita el alcance https://www.googleapis.com/auth/drive.install para integrarte en la IU de Drive. Cuando solicitan este alcance, los usuarios reciben un diálogo similar a este:

Figura 1: Diálogo de instalación cuando se usan permisos para la IU de Drive.

Para obtener más información sobre los permisos que puedes solicitar para las apps de Drive y cómo hacerlo, consulta Información específica sobre la autenticación y autorización de la API.

Nota: Si publicas tu app de Drive en Google Workspace Marketplace, los usuarios y los administradores de dominio podrán buscar e instalar la app directamente desde Google Workspace Marketplace.

El parámetro state

De forma predeterminada, se agrega un parámetro state a la URL de apertura y a la URL nueva para pasar datos de la IU de Drive a tu app. Este parámetro contiene una cadena con codificación JSON que incluye variables de plantilla y datos sobre la solicitud a tu app. Las variables incluidas dependen del tipo de URL que se use (URL de apertura o URL nueva):

Variable de plantilla	Descripción	Solicitud de URL
{ids}	Es una lista separada por comas de los IDs de los archivos que se abren.	Abrir URL
{exportIds}	Es una lista separada por comas de los IDs de los archivos que se exportan (solo se usa cuando se abren documentos integrados de Google).	Abrir URL
{resourceKeys}	Es un diccionario JSON de IDs de archivos asignados a sus respectivas claves de recursos.	Abrir URL
{folderId}	Es el ID de la carpeta principal.	URL nueva
{folderResourceKey}	Es la clave de recurso de la carpeta principal.	URL nueva
{userId}	Es el ID del perfil que identifica al usuario.	Abrir URL y URL nueva
{action}	Es la acción que se está realizando. El valor es open cuando se usa una URL abierta o create cuando se usa una URL nueva.	Abrir URL y URL nueva

El parámetro state está codificado como URL, por lo que tu app debe controlar los caracteres de escape y analizarlo como JSON. Las apps pueden detectar el valor de create en el parámetro state para verificar una solicitud de creación de un archivo.

Ejemplo de información de estado en formato JSON para una URL nueva

La información de state para una URL nueva es la siguiente:

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

Ejemplo de información de estado en JSON para una URL abierta

La información de state para una URL abierta es la siguiente:

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

Los IDs y las claves de recursos se usan para recuperar los metadatos y descargar el contenido de los archivos. Una vez que tu app tenga el ID del archivo y un token de acceso, podrá verificar los permisos, recuperar los metadatos del archivo y descargar el contenido del archivo como se describe en el método files.get.

Nota: Todas las apps, incluidas las que abren archivos desde accesos directos y accesos directos de terceros, deben llamar al método files.get para verificar los permisos del usuario para un documento. Las apps deben advertir a los usuarios de solo lectura cuando abran un archivo que no puedan editar ni guardar (en lugar de permitirles dedicar tiempo a editarlo y, luego, mostrar un error al guardarlo).

Temas relacionados

Una app instalada debe poder crear, administrar y abrir acciones iniciadas desde la IU de Drive. Para obtener más información, consulta Integración con el botón "Nuevo" de la IU de Drive o Integración con el menú contextual "Abrir con" de la IU de Drive.