Die Google Picker API

Dialogfeld der Google-Auswahl.

Die Google Picker API ist eine JavaScript API, die Sie in Ihren Webanwendungen verwenden können, damit Nutzer Google Drive-Dateien auswählen oder hochladen können. Nutzer können Ihren Apps die Berechtigung erteilen, auf ihre Drive-Daten zuzugreifen. So können sie sicher und autorisiert mit ihren Dateien interagieren.

Die Google-Auswahl dient als Dialogfeld „Datei öffnen“ für Informationen, die in Drive gespeichert sind, und bietet folgende Funktionen:

  • Ein ähnliches Design wie die Google Drive-Benutzeroberfläche.
  • Mehrere Ansichten mit Vorschauen und Miniaturansichten von Drive-Dateien
  • Ein modales Inline-Fenster, damit Nutzer die Hauptanwendung nie verlassen

Beachten Sie, dass Nutzer mit der Google-Auswahl keine Dateien von einem Ordner in einen anderen organisieren, verschieben oder kopieren können. Dazu können Sie entweder die Google Drive API oder die Drive-UI verwenden.

Anwendungsanforderungen

Anwendungen, die die Google Auswahl verwenden, müssen alle vorhandenen Nutzungsbedingungen einhalten. Am wichtigsten ist, dass Sie sich in Ihren Anträgen korrekt identifizieren müssen.

Außerdem benötigen Sie ein Google Cloud-Projekt.

Umgebung einrichten

Wenn Sie die Google Picker API verwenden möchten, müssen Sie zuerst Ihre Umgebung einrichten.

API aktivieren

Bevor Sie Google APIs verwenden können, müssen Sie sie in einem Google Cloud-Projekt aktivieren. Sie können eine oder mehrere APIs in einem einzelnen Google Cloud-Projekt aktivieren.

  • Aktivieren Sie in der Google Cloud Console die Google Picker API.

    API aktivieren

API-Schlüssel erstellen

Ein API-Schlüssel ist ein langer String, der Groß- und Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthält, z. B. AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Diese Authentifizierungsmethode wird verwendet, um anonym auf öffentlich verfügbare Daten wie Google Workspace-Dateien zuzugreifen, die über die Freigabeeinstellung „Jeder im Internet, der diesen Link hat“ freigegeben wurde. Weitere Informationen finden Sie unter Mit API-Schlüsseln authentifizieren.

So erstellen Sie einen API-Schlüssel:

  1. Öffnen Sie in der Google Cloud Console das Dreistrich-Menü > APIs und Dienste > Anmeldedaten.

    Zu den Anmeldedaten

  2. Klicken Sie auf Anmeldedaten erstellen > API-Schlüssel.
  3. Ihr neuer API-Schlüssel wird angezeigt.
    • Klicken Sie auf „Kopieren“ , um den API-Schlüssel zur Verwendung im Code Ihrer Anwendung zu kopieren. Den API-Schlüssel finden Sie auch in den Anmeldedaten Ihres Projekts im Abschnitt „API-Schlüssel“.
    • Klicken Sie auf Schlüssel einschränken, um die erweiterten Einstellungen zu aktualisieren und die Verwendung des API-Schlüssels einzuschränken. Weitere Informationen finden Sie unter Einschränkungen für API-Schlüssel anwenden.

Anmeldedaten für eine Webanwendung autorisieren

Um Endnutzer zu authentifizieren und auf Nutzerdaten in der Anwendung zuzugreifen, müssen Sie eine oder mehrere OAuth 2.0-Client-IDs erstellen. Eine Client-ID wird zur Identifizierung einer einzelnen Anwendung bei Googles OAuth-Servern verwendet. Wenn Ihre Anwendung auf mehreren Plattformen ausgeführt wird, müssen Sie für jede Plattform eine separate Client-ID erstellen.

  1. Klicken Sie in der Google Cloud Console auf das Dreistrich-Menü > APIs und Dienste > Anmeldedaten.

    Zu den Anmeldedaten

  2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
  3. Klicken Sie auf Anwendungstyp > Webanwendung.
  4. Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt.
  5. Fügen Sie autorisierte URIs für Ihre App hinzu:
    • Clientseitige Apps (JavaScript): Klicken Sie unter Autorisierte JavaScript-Quellen auf URI hinzufügen. Geben Sie dann einen URI ein, der für Browseranfragen verwendet werden soll. Hiermit werden die Domains identifiziert, von denen deine Anwendung API-Anfragen an den OAuth 2.0-Server senden kann.
    • Serverseitige Apps (z. B. Java, Python und andere): Klicken Sie unter Autorisierte Weiterleitungs-URIs auf URI hinzufügen. Geben Sie dann einen Endpunkt-URI ein, an den der OAuth 2.0-Server Antworten senden kann.
  6. Klicken Sie auf Erstellen. Der Bildschirm "OAuth-Client erstellt" wird mit Ihrer neuen Client-ID und Ihrem Clientschlüssel angezeigt.

    Notieren Sie sich die Client-ID. Clientschlüssel werden nicht für Webanwendungen verwendet.

  7. Klicken Sie auf OK. Die neu erstellten Anmeldedaten werden unter OAuth 2.0-Client-IDs angezeigt.
Wichtig:Beim Erstellen eines Picker-Objekts muss Ihre Anwendung ein OAuth 2.0-Zugriffstoken mit Ansichten senden, die auf private Nutzerdaten zugreifen. Informationen zum Anfordern eines Zugriffstokens finden Sie unter Mit OAuth 2.0 auf Google APIs zugreifen.

Google Picker anzeigen

Im weiteren Verlauf dieses Leitfadens wird beschrieben, wie Sie die Google Auswahl über eine Webanwendung laden und anzeigen lassen. Das vollständige Beispiel finden Sie im Codebeispiel für die Google Auswahl.

Google Picker-Bibliothek laden

Um die Google Picker-Bibliothek zu laden, rufen Sie gapi.load() mit dem Bibliotheksnamen und einer Callback-Funktion auf, die nach einem erfolgreichen Ladevorgang aufgerufen werden soll:

    <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>
    

Ersetzen Sie Folgendes:

  • CLIENT_ID: Die Client-ID Ihrer Web-App.
  • SCOPES: Ein oder mehrere OAuth 2.0-Bereiche, die Sie für den Zugriff auf Google APIs anfordern müssen, je nachdem, welche Zugriffsebene Sie benötigen. Weitere Informationen finden Sie unter OAuth 2.0-Bereiche für Google APIs.

Mit der JavaScript-Bibliothek google.accounts.oauth2 können Sie die Nutzereinwilligung einholen und ein Zugriffstoken für die Arbeit mit Nutzerdaten abrufen. Die Methode initTokenClient() initialisiert einen neuen Token-Client mit der Client-ID Ihrer Webanwendung. Weitere Informationen finden Sie unter Tokenmodell verwenden.

Die Funktion onApiLoad() lädt die Google Picker-Bibliotheken. Die Callback-Funktion onPickerApiLoad() wird aufgerufen, nachdem die Google Auswahlbibliothek erfolgreich geladen wurde.

Google Picker anzeigen

Die folgende createPicker()-Funktion prüft, ob der Ladevorgang der Google Picker API abgeschlossen ist und ein OAuth-Token erstellt wurde. Diese Funktion erstellt dann eine Instanz der Google-Auswahl und zeigt sie an:

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

Zum Erstellen einer Google Picker-Instanz müssen Sie mit PickerBuilder ein Picker-Objekt erstellen. Für PickerBuilder sind ein View, ein OAuth-Token, ein Entwicklerschlüssel und eine Callback-Funktion erforderlich, die bei Erfolg aufgerufen werden soll (pickerCallback).

Das Picker-Objekt rendert immer nur ein View nach dem anderen. Geben Sie mindestens eine Ansicht an, entweder über ViewId (google.​picker.​ViewId.*) oder durch Erstellen einer Instanz eines Typs (google.​picker.​*View). Geben Sie die Ansicht nach Typ an, um besser zu steuern, wie die Ansicht gerendert wird.

Wenn der Google Auswahl mehr als eine Ansicht hinzugefügt wird, können Nutzer durch Klicken auf einen Tab auf der linken Seite von einer Ansicht zur anderen wechseln. Tabs können mit ViewGroup-Objekten logisch gruppiert werden.

Google Picker-Callback implementieren

Ein Google Picker-Callback kann verwendet werden, um auf Nutzerinteraktionen in der Google Auswahl zu reagieren, z. B. durch Auswahl einer Datei oder durch Drücken von „Abbrechen“. Das Objekt Response überträgt Informationen zur Auswahl des Nutzers.

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

Der Callback empfängt ein JSON-codiertes data-Objekt. Dieses Objekt enthält ein Action, das der Nutzer mit der Google Auswahl (google.picker.Response.ACTION) ausführt. Wenn der Nutzer ein Document-Element auswählt, wird auch das google.picker.Response.DOCUMENTS-Array gefüllt. In diesem Beispiel wird google.picker.Document.URL auf der Hauptseite angezeigt. Weitere Informationen zu den Datenfeldern finden Sie in der JSON-Referenz.

Bestimmte Dateitypen filtern

Mit einem ViewGroup lassen sich bestimmte Elemente herausfiltern. Das folgende Codebeispiel zeigt, wie in der Unteransicht „Google Drive“ nur Dokumente und Präsentationen angezeigt werden.

    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();
    
Eine Liste der gültigen Ansichtstypen finden Sie unter ViewId.

Darstellung der Google Auswahl anpassen

Mit dem Objekt Feature können Sie Funktionen für verschiedene Ansichten aktivieren oder deaktivieren. Verwenden Sie die Funktion PickerBuilder.enableFeature() oder PickerBuilder.disableFeature(), um die Darstellung des Google Auswahlfensters anzupassen. Wenn Sie beispielsweise nur eine Ansicht haben, können Sie den Navigationsbereich (Feature.NAV_HIDDEN) ausblenden, damit Nutzer mehr Platz zum Ansehen der Elemente haben.

Das folgende Codebeispiel zeigt ein Beispiel für die Suchauswahl einer Tabelle, in der diese Funktion verwendet wird:

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

Google Auswahl in anderen Sprachen rendern

Geben Sie die UI-Sprache an. Stellen Sie dazu mit der Methode setLocale(locale) für die Instanz PickerBuilder die Sprache bereit.

Das folgende Codebeispiel zeigt, wie Sie die Sprache auf Französisch festlegen:

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

Folgende Sprachen werden derzeit unterstützt:

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