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. La configuración también es necesaria para que tu app aparezca 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 la API y a las funciones de integración de la IU.

Configura la integración de la IU de Drive

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

    Ve a APIs y servicios habilitados

  2. En la parte inferior del panel 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. De manera 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. De forma 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 de un 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.

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

    • Esta URL debe contener un nombre de dominio completamente calificado. localhost no funciona.
    • Los usuarios previstos de tu aplicación deben poder acceder a esta URL. Si tienes varias versiones de la aplicación, como una para la versión pública y una para la versión restringida a usuarios seleccionados, cada versión debe usar una URL única. Luego, puedes crear diferentes configuraciones de apps para cada versión.
    • Debes verificar la propiedad de esta URL antes de poder publicar tu app en Google Workspace Marketplace.
    • 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.

  9. De forma 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 se compiló de forma exclusiva para abrir. Por ejemplo, tu app podría abrir un formato integrado para aplicar capas y editar imágenes. Incluye solo tipos de medios estándar y asegúrate de que no tengan errores tipográficos. Si tu app solo abre archivos de acceso directo o de terceros, puedes dejar el tipo de MIME en blanco.

  10. (Opcional) Ingresa los tipos de MIME y las extensiones de archivo secundarios en los campos Tipos de MIME secundarios y Extensiones de archivo secundarios. Los tipos de MIME y las extensiones de archivo secundarios representan archivos que tu app puede abrir, pero no son específicos para ella. Por ejemplo, tu app podría ser una 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. Si tu app solo abre archivos de acceso directo o de terceros, puedes dejar el tipo de MIME en blanco.

  11. Para usar el botón “Nuevo” de la IU de Drive y hacer que los usuarios creen un archivo con tu app, marca la casilla Crear archivos. Aparecerán los campos Nueva URL y Nombre del documento opcional.

    • Esta URL debe contener un nombre de dominio completamente calificado. localhost no funciona.
    • Debes verificar la propiedad de esta URL antes de poder publicar tu app en Google Workspace Marketplace.
    • 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 Nueva URL. El botón “Nuevo” usa esta URL para redireccionar al usuario a tu aplicación.

  13. (Opcional) Si deseas que tu app abra archivos compatibles con Google Workspace, marca la casilla Importación.

  14. (Opcional) Si tu app debe administrar archivos en unidades compartidas, marca la casilla Compatibilidad con unidades compartidas. Para obtener más información sobre cómo admitir viajes compartidos en tu app, consulta Cómo implementar la compatibilidad con viajes compartidos.

  15. Haz clic en Enviar.

Solicita el permiso drive.install

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

Diálogo de instalación de la IU de Google Drive.
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 la información de autenticación y autorización específicas de la API.

El parámetro state

De forma predeterminada, se agrega un parámetro state a la URL abierta 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 con variables de plantilla y datos sobre la solicitud a tu app. Las variables incluidas dependen del tipo de URL que se usa (URL abierta o URL nueva):

Variable de plantilla Descripción Aplicación de URL
{ids} Es una lista separada por comas de los IDs de archivo que se abrirán. Abrir URL
{exportIds} Es una lista separada por comas de los IDs de archivo que se exportarán (se usa solo cuando se abren documentos de Google integrados). Abrir URL
{resourceKeys} Un diccionario JSON de IDs de archivos asignados a sus respectivas claves de recursos Abrir URL
{folderId} El ID de la carpeta superior. URL nueva
{folderResourceKey} Es la clave de recurso de la carpeta superior. URL nueva
{userId} El ID de perfil que identifica al usuario. Abrir URL y Nueva URL
{action} 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 Nueva URL

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

Ejemplo de información de estado en 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 de los archivos y descargar su contenido. Una vez que tu app tenga el ID de archivo y un token de acceso, podrá verificar los permisos, recuperar los metadatos del archivo y descargar su contenido como se describe en el método files.get.

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