API del selector de Google

Diálogo del selector de Google

El selector de Google es un cuadro de diálogo de "Archivo abierto" para la información almacenada en Google Drive. El selector de Google tiene las siguientes características:

  • Una apariencia similar a la de la IU de Google Drive
  • Varias vistas que muestran vistas previas y miniaturas de archivos de Drive.
  • Una ventana modal intercalada para que los usuarios nunca salgan de la aplicación principal

La API de Google Picker es una API de JavaScript que puedes usar en tus aplicaciones web para permitir que los usuarios abran o suban archivos de Drive.

Requisitos de la solicitud

Las aplicaciones que utilizan el selector de Google deben cumplir con todas las Condiciones del Servicio existentes. Lo más importante es que te identifiques correctamente en tus solicitudes.

También debes tener un proyecto de Google Cloud.

Configure su entorno

Para comenzar a usar la API del selector de Google, debes configurar tu entorno.

Cómo habilitar la API

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

Crea una clave de API

Una clave de API es una string larga que contiene letras mayúsculas y minúsculas, números, guiones bajos y guiones, como AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Este método de autenticación se usa para acceder de forma anónima a datos públicos, como los archivos de Google Workspace que se comparten con la configuración de uso compartido “Cualquier usuario de Internet con este vínculo”. Para obtener más detalles, consulta Autentica mediante claves de API.

Para crear una clave de API, sigue estos pasos:

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

    Ir a Credenciales

  2. Haz clic en Crear credenciales > Clave de API.
  3. Se mostrará tu nueva clave de API.
    • Haz clic en Copiar para copiar tu clave de API y usarla en el código de tu app. La clave de API también se encuentra en la sección “Claves de API” de las credenciales de tu proyecto.
    • Haz clic en Restringir clave para actualizar la configuración avanzada y limitar el uso de tu clave de API. Para obtener más detalles, consulta Aplica restricciones de clave de API.

Autoriza credenciales para una aplicación web

Para autenticarte como usuario final y acceder a los datos del usuario en tu app, debes crear uno o más ID de cliente de OAuth 2.0. Se usa un ID de cliente para identificar una sola app en los servidores de OAuth de Google. Si tu app se ejecuta en varias plataformas, debes crear un ID de cliente por separado para cada plataforma.

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

    Ir a Credenciales

  2. Haz clic en Crear credenciales > ID de cliente de OAuth.
  3. Haz clic en Tipo de aplicación > Aplicación web.
  4. En el campo Nombre, escribe un nombre para la credencial. Este nombre solo se muestra en Google Cloud Console.
  5. Agrega URI autorizados relacionados con tu app:
    • Apps del cliente (JavaScript): En Orígenes autorizados de JavaScript, haz clic en Agregar URI. Luego, ingresa un URI para usar en las solicitudes del navegador. Esto identifica los dominios desde los cuales tu aplicación puede enviar solicitudes de API al servidor de OAuth 2.0.
    • Apps del servidor (Java, Python y más): En URI de redireccionamiento autorizados, haz clic en Agregar URI. Luego, ingresa un URI de extremo al que el servidor de OAuth 2.0 pueda enviar respuestas.
  6. Haz clic en Crear. Aparecerá la pantalla del cliente OAuth que muestra tu nuevo ID de cliente y secreto de cliente.

    Anota el ID de cliente. Los secretos del cliente no se usan para las aplicaciones web.

  7. Haz clic en OK. La credencial creada recientemente se muestra en ID de cliente OAuth 2.0.
  8. Opcional: Si creas credenciales como un requisito previo para una guía de inicio rápido de JavaScript, también debes generar una clave de API.
Importante: Tu aplicación debe enviar un token de acceso de OAuth 2.0 con vistas que accedan a datos privados del usuario cuando crea un objeto Picker. A fin de solicitar un token de acceso, consulta la sección sobre cómo usar OAuth 2.0 para acceder a las API de Google.

Mostrar el selector de Google

En el resto de esta guía, se explica cómo cargar y mostrar el selector de Google desde una aplicación web. Para ver el ejemplo completo, navega a la muestra de código del selector de Google.

Carga la biblioteca del selector de Google

A fin de cargar la biblioteca del selector de Google, llama a gapi.load() con el nombre de la biblioteca y una función de devolución de llamada para invocar después de una carga exitosa:

    <script>
      let tokenClient;
      let accessToken = null;
      let pickerInited = false;
      let gisInited = false;

      // Use the API Loader script to load google.picker
      function onApiLoad() {
        gapi.load('picker', onPickerApiLoad);
      }

      function onPickerApiLoad() {
        pickerInited = true;
      }

      function gisLoaded() {
        // TODO(developer): Replace with your client ID and required scopes
        tokenClient = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_CLIENT_ID',
          scope: 'YOUR_SCOPES',
          callback: '', // defined later
        });
        gisInited = true;
    }
    </script>
    <!-- Load the Google API Loader script. -->
    <script async defer src="https://apis.google.com/js/api.js" onload="onApiLoad()"></script>
    <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
    

La función onApiLoad() carga las bibliotecas del selector de Google. Se llama a la función de devolución de llamada onPickerApiLoad() después de que se carga correctamente la biblioteca del selector de Google.

Mostrar el selector de Google

La función createPicker() comprueba que la API del selector de Google termine de cargarse y que se cree un token de OAuth. Luego, esta función crea una instancia del selector de Google y la muestra:

    // Create and render a Google Picker object for selecting from Drive
    function createPicker() {
      const showPicker = () => {
        // TODO(developer): Replace with your API key
        const picker = new google.picker.PickerBuilder()
            .addView(google.picker.ViewId.DOCS)
            .setOAuthToken(accessToken)
            .setDeveloperKey('YOUR_API_KEY')
            .setCallback(pickerCallback)
            .build();
        picker.setVisible(true);
      }

      // Request an access token
      tokenClient.callback = async (response) => {
        if (response.error !== undefined) {
          throw (response);
        }
        accessToken = response.access_token;
        showPicker();
      };

      if (accessToken === null) {
        // Prompt the user to select a Google Account and ask for consent to share their data
        // when establishing a new session.
        tokenClient.requestAccessToken({prompt: 'consent'});
      } else {
        // Skip display of account chooser and consent dialog for an existing session.
        tokenClient.requestAccessToken({prompt: ''});
      }
    }
    

Para crear una instancia del selector de Google, debes proporcionar un View, un oauthToken, un developerKey y una función de devolución de llamada para llamar al éxito (pickerCallback).

Un objeto Picker renderiza un View a la vez. Especifica al menos una vista, ya sea mediante ViewId (google.​picker.​ViewId.*) o mediante la creación de una instancia de un tipo (google.​picker.​*View). Especifica la vista por tipo a fin de obtener un control adicional sobre la renderización.

Si se agrega más de una vista al selector de Google, los usuarios cambian de una vista a otra haciendo clic en una pestaña de la izquierda. Las pestañas se pueden agrupar de forma lógica con objetos ViewGroup.

Implementa la devolución de llamada del selector

Se puede usar una devolución de llamada de selector para reaccionar a las interacciones del usuario en el selector de Google, como seleccionar un archivo o presionar Cancelar.

    // A simple callback implementation.
    function pickerCallback(data) {
      let url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        let doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      let message = `You picked: ${url}`;
      document.getElementById('result').innerText = message;
    }
    

La devolución de llamada recibe un objeto data codificado en JSON. Este objeto contiene cualquier acción que el usuario realice con el selector de Google (google.picker.Response.ACTION). Si el usuario selecciona un elemento, también se propaga el arreglo google.picker.Response.DOCUMENTS. En este ejemplo, el google.picker.Document.URL se muestra en la página principal. Para obtener detalles sobre los campos de datos, consulta la referencia de JSON.

Filtrar tipos de archivos específicos

Usa un objeto ViewGroup para filtrar elementos específicos. En el siguiente ejemplo, la subvista "Google Drive" muestra solo documentos y presentaciones.

    let picker = new google.picker.PickerBuilder()
        .addViewGroup(
          new google.picker.ViewGroup(google.picker.ViewId.DOCS)
              .addView(google.picker.ViewId.DOCUMENTS)
              .addView(google.picker.ViewId.PRESENTATIONS))
        .setOAuthToken(oauthToken)
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

Ajustar la apariencia del selector de Google

Usa la función PickerBuilder.enableFeature() para ajustar la apariencia de la ventana del selector de Google. Por ejemplo, si solo tienes una vista, es posible que desees ocultar el panel de navegación para brindar a los usuarios más espacio para ver los elementos. A continuación, se muestra un ejemplo de un selector de búsqueda de hojas de cálculo en el que se demuestra esta función:

     let picker = new google.picker.PickerBuilder()
         .addView(google.picker.ViewId.SPREADSHEETS)
         .enableFeature(google.picker.Feature.NAV_HIDDEN)
         .setDeveloperKey(developerKey)
         .setCallback(pickerCallback)
         .build();
     

Procesar el selector de Google en otros lenguajes

Para especificar el idioma de la IU, proporciona la configuración regional a la instancia PickerBuilder con el método setLocale(locale). El siguiente es un ejemplo de idioma francés:

    let picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.IMAGE_SEARCH)
        .setLocale('fr')
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

La siguiente es la lista de configuraciones regionales admitidas actualmente:

af
am
ar
bg
bn
ca
cs
da
de
el
en
en-GB
es
es-419
et
eu
fa
fi
fil
fr
fr-CA
gl
gu
hi
hr
hu
id
is
it
iw
ja
kn
ko
lt
lv
ml
mr
ms
nl
no
pl
pt-BR
pt-PT
ro
ru
sk
sl
sr
sv
sw
ta
te
th
tr
uk
ur
vi
zh-CN
zh-HK
zh-TW
zu