Ce document explique comment intégrer Google Picker à vos applications Web à l'aide de l'API Google Picker.
L'API Google Picker est une API JavaScript que vous pouvez implémenter pour permettre aux utilisateurs de sélectionner ou d'importer des fichiers Google Drive à l'aide de Google Picker. 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.
Fonctionnalités
Google Picker propose plusieurs fonctionnalités :
- Une apparence semblable à celle de l'interface utilisateur Google Drive.
- Plusieurs vues affichant des aperçus et des miniatures des fichiers Drive.
- Des vues préfiltrées qui n'affichent que des types de fichiers spécifiques (comme des PDF ou des images) ou certains dossiers.
- Une fenêtre modale intégrée, afin que les utilisateurs ne quittent jamais l'application principale.
Notez que si vous pouvez sélectionner et importer des fichiers avec Google Picker, les utilisateurs ne peuvent pas organiser, déplacer ni copier des fichiers d'un dossier à un autre. Pour gérer les fichiers, vous devez utiliser l'API Google Drive ou l'interface utilisateur Drive.
Prérequis
Les applications qui utilisent Google Picker 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.
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, par exemple AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Cette méthode d'authentification
permet d'accéder de manière anonyme aux données disponibles publiquement, telles que les fichiers Google Workspace partagés à l'aide
du paramètre de partage "Toute personne disposant du lien sur Internet". Pour en savoir plus, consultez
Gérer les clés API.
Pour créer une clé API :
- Dans la console Google Cloud, accédez à Menu > API et services > Identifiants.
- Cliquez sur Créer des identifiants > Clé API.
- Votre nouvelle clé API s'affiche.
- Cliquez sur Copy pour copier votre clé API et l'utiliser dans le code de votre application. La clé API se trouve également dans la section "Clés API" des identifiants de votre projet.
- Pour éviter toute utilisation abusive, nous vous recommandons d'ajouter des restrictions pour limiter les emplacements et les API pour lesquels la clé API peut être utilisée. Pour en savoir plus, consultez Ajouter des restrictions d'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 chacune d'elles.- Dans la console Google APIs, accédez à Menu > Plate-forme d'authentification Google > Clients.
- Cliquez sur Créer un client.
- Cliquez sur Type d'application > Application Web.
- Dans le champ Nom, saisissez un nom pour l'identifiant. Ce nom ne s'affiche que dans la console API Google.
- 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. Cela permet d'identifier les domaines à partir desquels votre application peut envoyer des requêtes d'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 vers lequel le serveur OAuth 2.0 peut envoyer des réponses.
- Cliquez sur Créer.
L'identifiant que vous venez de créer s'affiche sous ID client OAuth 2.0.
Notez l'ID client. Les codes secrets du client ne sont pas utilisés pour les applications Web.
Important : Votre application doit envoyer un jeton d'accès OAuth 2.0 avec les vues qui
accèdent aux données utilisateur privées lors de la création d'un objet
Picker. Pour demander un jeton d'accès,
consultez Utiliser OAuth 2.0 pour accéder aux API Google.
Gérer Google Picker
Le reste de ce document explique comment charger et afficher Google Picker à partir d'une application Web, ainsi que comment implémenter le rappel. Pour afficher l'exemple de code complet, consultez Utiliser les fonctionnalités de l'API Google Picker dans les applications Web.
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() {
// 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 que vous devez demander pour accéder aux API Google, en fonction du niveau d'accès dont vous avez besoin. Pour en savoir plus, consultez la section 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 utiliser les données utilisateur. La méthode initTokenClient initialise un nouveau client de jeton avec l'ID client de votre application Web. Pour en savoir plus, consultez 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.
Remarque : Si vous utilisez TypeScript, vous pouvez installer
@types/google.picker pour
utiliser window.google.picker. Pour signaler un problème, envoyez une demande d'assistance.
Afficher Google Picker
La fonction createPicker s'assure que l'API Google Picker a terminé le chargement et qu'un jeton OAuth 2.0 a été créé. Utilisez la méthode PickerBuilder.setAppId pour définir l’ID de l’application Drive
à l’aide du numéro de projet Cloud afin de permettre à l’application
d’accéder aux fichiers de l’utilisateur. Cette fonction crée ensuite une instance de Google Picker et l'affiche :
// Create and render a Google Picker object for selecting from Drive.
function createPicker() {
const showPicker = () => {
// Replace with your API key and App ID.
const picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.DOCS)
.setOAuthToken(accessToken)
.setDeveloperKey('API_KEY')
.setCallback(pickerCallback)
.setAppId('APP_ID')
.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: ''});
}
}
Remplacez les éléments suivants :
API_KEY: votre clé API.APP_ID: numéro de votre projet Cloud.
Pour créer une instance de Google Picker, vous devez créer un Picker objet à l'aide de PickerBuilder. Le PickerBuilder prend un View, un jeton OAuth 2.0, une clé de développeur et une
fonction de rappel à appeler en cas de succès (pickerCallback).
L'objet Picker affiche une View à la fois. Spécifiez au moins une vue,
soit par ViewId
(google.picker.ViewId.*) soit en créant une instance de DocsView pour mieux contrôler le rendu de la vue.
Si plusieurs vues sont ajoutées à Google Picker, les utilisateurs peuvent passer de l'une à l'autre en cliquant sur un onglet à gauche. Les onglets peuvent être regroupés logiquement
avec des ViewGroup objets.
Pour obtenir la liste des vues valides, consultez ViewId dans
la documentation de référence de Google Picker. Pour obtenir le jeton de l'une de ces vues, utilisez le champ d'application https://www.googleapis.com/auth/drive.file.
Implémenter le rappel Google Picker
Un rappel Google Picker peut être utilisé pour réagir aux interactions utilisateur dans Google Picker, par exemple lorsqu'un utilisateur sélectionne un fichier ou appuie sur "Annuler". L'
ResponseObject interface transmet
des informations sur les sélections de l'utilisateur.
// A callback implementation.
function pickerCallback(data) {
let url = 'nothing';
if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
const doc = data[google.picker.Response.DOCUMENTS][0];
url = doc[google.picker.Document.URL];
}
const message = `You picked: ${url}`;
document.getElementById('result').textContent = message;
}
Le rappel reçoit un objet de données encodé au format JSON. Cet objet contient un
Action que l'utilisateur effectue avec le
Google Picker (google.picker.Response.ACTION). Si l'utilisateur sélectionne un
élément, le tableau google.picker.Response.DOCUMENTS est également rempli. Dans cet exemple, google.picker.Document.URL s'affiche sur la page principale. Pour en savoir plus sur les champs de données, consultez l'interface ResponseObject.
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 "Drive" n'affiche que les documents et les présentations.
const 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)
.setAppId(cloudProjectNumber)
.setCallback(pickerCallback)
.build();
Pour obtenir la liste des types de vues valides, consultez
ViewId.
Ajuster l'apparence de Google Picker
Vous pouvez utiliser l'objet Feature pour activer
ou désactiver des fonctionnalités pour différentes vues. Pour affiner l'apparence de la
fenêtre Google Picker, utilisez la méthode 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) pour
donner aux utilisateurs plus d'espace pour afficher les éléments.
L'exemple de code suivant montre un exemple de sélecteur de recherche d'une feuille de calcul utilisant cette fonctionnalité :
const picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.SPREADSHEETS)
.enableFeature(google.picker.Feature.NAV_HIDDEN)
.setDeveloperKey(developerKey)
.setCallback(pickerCallback)
.build();
Articles associés
- Exemple de code : Utiliser les fonctionnalités de l'API Google Picker dans les applications Web
- Choisir les habilitations de l'API Google Drive