API Google Picker

Boîte de dialogue du sélecteur Google

L'API Google Picker est une API JavaScript que vous pouvez utiliser dans vos applications Web pour permettre aux utilisateurs de sélectionner ou d'importer des fichiers Google Drive. Les utilisateurs peuvent autoriser vos applications à accéder à leurs données Drive, ce qui leur offre un moyen sécurisé et autorisé d'interagir avec leurs fichiers.

Le sélecteur Google fonctionne comme une boîte de dialogue "Ouvrir un fichier" pour les informations stockées sur Drive. Il offre les fonctionnalités suivantes:

  • L'apparence de l'interface utilisateur de Google Drive est similaire.
  • Plusieurs vues affichant des aperçus et des vignettes des fichiers Drive
  • Fenêtre modale intégrée, de sorte que les utilisateurs ne quittent jamais l'application principale.

Notez que le sélecteur Google ne permet pas aux utilisateurs d'organiser, de déplacer ou de copier des fichiers d'un dossier à un autre. Pour ce faire, vous pouvez utiliser l'API Google Drive ou l'UI Drive.

Conditions requises pour les applications

Les applications qui utilisent l'outil de sélection Google doivent respecter toutes les Conditions d'utilisation existantes. Plus important encore, vous devez vous identifier correctement dans vos requêtes.

Vous devez également disposer d'un projet Google Cloud.

Configurer votre environnement

Pour commencer à utiliser l'API Google Picker, vous devez configurer votre environnement.

Activer l'API

Avant d'utiliser les API Google, vous devez les activer dans un projet Google Cloud. Vous pouvez activer une ou plusieurs API dans un même projet Google Cloud.

  • Dans la console Google Cloud, activez l'API Google Picker.

    Activer l'API

Créer une clé API

Une clé API est une longue chaîne contenant des lettres majuscules et minuscules, des chiffres, des traits de soulignement et des traits d'union, comme AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Cette méthode d'authentification permet d'accéder de manière anonyme aux données publiques, telles que les fichiers Google Workspace partagés à l'aide du paramètre de partage "Tous les internautes disposant de ce lien". Pour en savoir plus, consultez S'authentifier à l'aide de clés API.

Pour créer une clé API :

  1. Dans la console Google Cloud, accédez à Menu > API et services > Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur Créer des identifiants > Clé API.
  3. Votre nouvelle clé API s'affiche.
    • Cliquez sur Copier pour copier votre clé API afin de l'utiliser dans le code de votre application. La clé API est également disponible dans la section "Clés API" des identifiants de votre projet.
    • Cliquez sur Restreindre la clé pour mettre à jour les paramètres avancés et limiter l'utilisation de votre clé API. Pour en savoir plus, consultez Appliquer des restrictions de clé API.

Autoriser les identifiants pour une application Web

Pour authentifier les utilisateurs finaux et accéder aux données utilisateur dans votre application, vous devez créer un ou plusieurs ID client OAuth 2.0. Un ID client sert à identifier une application unique auprès des serveurs OAuth de Google. Si votre application s'exécute sur plusieurs plates-formes, vous devez créer un ID client distinct pour chaque plate-forme.

  1. Dans la console Google Cloud, accédez à Menu > API et services > Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur Créer des identifiants > ID client OAuth.
  3. Cliquez sur Type d'application > Application Web.
  4. Dans le champ Name (Nom), saisissez un nom pour l'identifiant. Ce nom ne s'affiche que dans la console Google Cloud.
  5. Ajoutez les URI autorisés associés à votre application :
    • Applications côté client (JavaScript) : sous Origines JavaScript autorisées, cliquez sur Ajouter un URI. Saisissez ensuite un URI à utiliser pour les requêtes du navigateur. Ce champ identifie les domaines à partir desquels votre application peut envoyer des requêtes API au serveur OAuth 2.0.
    • Applications côté serveur (Java, Python, etc.) : sous URI de redirection autorisés, cliquez sur Ajouter un URI. Saisissez ensuite un URI de point de terminaison auquel le serveur OAuth 2.0 peut envoyer des réponses.
  6. Cliquez sur Créer. L'écran du client OAuth créé s'affiche, avec l'ID et le code secret du client que vous venez de créer.

    Notez l'ID client. Les codes secrets des clients ne sont pas utilisés pour les applications Web.

  7. Cliquez sur OK. Les nouveaux identifiants s'affichent sous ID client OAuth 2.0.
Important:Lors de la création d'un objet Picker, votre application doit envoyer un jeton d'accès OAuth 2.0 avec des vues qui accèdent à des données utilisateur privées. Pour demander un jeton d'accès, consultez Utiliser OAuth 2.0 pour accéder aux API Google.

Afficher le sélecteur Google

Le reste de ce guide explique comment charger et afficher le sélecteur Google à partir d'une application Web. Pour voir l'exemple complet, accédez à l'exemple de code du sélecteur Google.

Charger la bibliothèque Google Picker

Pour charger la bibliothèque Google Picker, appelez gapi.load() avec le nom de la bibliothèque et une fonction de rappel à appeler après un chargement réussi:

    <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: 'CLIENT_ID',
          scope: '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>
    

Remplacez les éléments suivants :

  • CLIENT_ID: ID client de votre application Web.
  • SCOPES: un ou plusieurs champs d'application OAuth 2.0 dont vous devez demander l'accès aux API Google, en fonction du niveau d'accès dont vous avez besoin. Pour en savoir plus, consultez Champs d'application OAuth 2.0 pour les API Google.

La bibliothèque JavaScript google.accounts.oauth2 vous aide à demander le consentement de l'utilisateur et à obtenir un jeton d'accès pour exploiter ses données. La méthode initTokenClient() initialise un nouveau client de jeton avec l'ID client de votre application Web. Pour en savoir plus, consultez la section Utiliser le modèle de jeton.

La fonction onApiLoad() charge les bibliothèques Google Picker. La fonction de rappel onPickerApiLoad() est appelée une fois la bibliothèque Google Picker chargée.

Afficher le sélecteur Google

La fonction createPicker() ci-dessous permet de s'assurer que le chargement de l'API Google Picker est terminé et qu'un jeton OAuth est créé. Cette fonction crée ensuite une instance du sélecteur Google et l'affiche:

    // 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('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: ''});
      }
    }
    

Pour créer une instance de Google Picker, vous devez créer un objet Picker à l'aide de PickerBuilder. PickerBuilder utilise un View, un jeton OAuth, une clé de développeur et une fonction de rappel à appeler en cas de réussite (pickerCallback).

L'objet Picker affiche un élément View à la fois. Spécifiez au moins une vue, à l'aide de la commande ViewId (google.​picker.​ViewId.*) ou en créant une instance d'un type (google.​picker.​*View). Spécifiez la vue par type pour un contrôle supplémentaire sur son rendu.

Si plusieurs vues sont ajoutées au sélecteur Google, les utilisateurs peuvent passer d'une vue à l'autre en cliquant sur un onglet à gauche. Les onglets peuvent être regroupés de manière logique avec des objets ViewGroup.

Implémenter le rappel de l'outil de sélection Google

Un rappel du sélecteur Google peut être utilisé pour réagir aux interactions utilisateur dans le sélecteur Google, telles que la sélection d'un fichier ou l'appui sur "Annuler". L'objet Response fournit des informations sur les sélections de l'utilisateur.

    // 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;
    }
    

Le rappel reçoit un objet data encodé au format JSON. Cet objet contient un Action que l'utilisateur effectue avec le sélecteur Google (google.picker.Response.ACTION). Si l'utilisateur sélectionne un élément Document, le tableau google.picker.Response.DOCUMENTS est également renseigné. Dans cet exemple, google.picker.Document.URL s'affiche sur la page principale. Pour en savoir plus sur les champs de données, consultez la documentation de référence JSON.

Filtrer des types de fichiers spécifiques

Utilisez un ViewGroup pour filtrer des éléments spécifiques. L'exemple de code suivant montre comment la sous-vue "Google Drive" n'affiche que les documents et les présentations.

    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();
    
Pour obtenir la liste des types de vues valides, consultez ViewId.

Régler l'apparence du sélecteur Google

L'objet Feature vous permet d'activer ou de désactiver les fonctionnalités de différentes vues. Pour affiner l'apparence de la fenêtre du sélecteur Google, utilisez la fonction PickerBuilder.enableFeature() ou PickerBuilder.disableFeature(). Par exemple, si vous n'avez qu'une seule vue, vous pouvez masquer le volet de navigation (Feature.NAV_HIDDEN) afin d'offrir plus d'espace aux utilisateurs pour voir les éléments.

L'exemple de code suivant montre un exemple de sélecteur de recherche d'une feuille de calcul utilisant cette fonctionnalité:

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

Afficher le sélecteur Google dans d'autres langues

Spécifiez la langue de l'interface utilisateur en indiquant les paramètres régionaux de l'instance PickerBuilder à l'aide de la méthode setLocale(locale).

L'exemple de code suivant montre comment définir les paramètres régionaux en français:

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

Voici la liste des paramètres régionaux actuellement pris en charge:

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