Die Google Picker API

Dialogfeld von Google Picker.

Die Auswahl von Google ist ein Dialogfeld zum Öffnen von Dateien mit Informationen in Google Drive. Google Picker bietet folgende Funktionen:

  • Ein ähnliches Erscheinungsbild wie bei der Google Drive-Benutzeroberfläche
  • Mehrere Ansichten mit Vorschauen und Miniaturansichten von Drive-Dateien
  • Ein modales Inline-Fenster, in dem die Nutzer die Hauptanwendung nicht verlassen.

Die Google Picker API ist eine JavaScript API, mit der Sie in Ihren Webanwendungen Drive-Dateien öffnen oder hochladen können.

Anwendungsanforderungen

Anwendungen, die Google Picker verwenden, müssen allen vorhandenen Nutzungsbedingungen entsprechen. Vor allem müssen Sie sich in Ihren Anfragen korrekt identifizieren.

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

Umgebung einrichten

Um die Google Picker API verwenden zu können, müssen Sie 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 mit Groß- und Kleinbuchstaben, Ziffern, Unterstrichen und Bindestrichen, 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 über diesen Link“ freigegeben wurden. Weitere Informationen finden Sie unter Authentifizierung mit API-Schlüsseln (in englischer Sprache).

So erstellen Sie einen API-Schlüssel:

  1. Gehen Sie in der Google Cloud Console zu „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 Ihren API-Schlüssel zur Verwendung im Code Ihrer App zu kopieren. Sie finden ihn auch im Bereich „API-Schlüssel“ der Anmeldedaten Ihres Projekts.
    • Klicken Sie auf Schlüssel einschränken, um die erweiterten Einstellungen zu aktualisieren und die Nutzung Ihres API-Schlüssels einzuschränken. Weitere Informationen finden Sie unter Einschränkungen für API-Schlüssel anwenden.

Anmeldedaten für eine Webanwendung autorisieren

Damit Sie sich als Endnutzer authentifizieren und auf Nutzerdaten in Ihrer Anwendung zugreifen können, müssen Sie eine oder mehrere OAuth 2.0-Client-IDs erstellen. Mit einer Client-ID kann eine einzelne Anwendung den OAuth-Servern von Google zugeordnet werden. Wenn Ihre App auf mehreren Plattformen ausgeführt wird, müssen Sie für jede Plattform eine separate Client-ID erstellen.

  1. Gehen Sie in der Google Cloud Console zu „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 in das 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. Damit werden die Domains identifiziert, von denen aus Ihre Anwendung API-Anfragen an den OAuth 2.0-Server senden kann.
    • Serverseitige Anwendungen (Java, Python und mehr): 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:Ihre Anwendung muss beim Erstellen eines Picker-Objekts 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-Auswahl anzeigen

In diesem Leitfaden wird erläutert, wie Sie den Google Picker über eine Webanwendung laden und anzeigen. Das vollständige Beispiel finden Sie im Google Picker-Codebeispiel.

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

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

Dabei gilt:

  • CLIENT_ID ist die Client-ID Ihrer Webanwendung.
  • SCOPES: Mindestens ein OAuth 2.0-Bereich, den Sie für den Zugriff auf Google APIs anfordern müssen, je nach der erforderlichen Zugriffsebene. 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 abrufen, um mit Nutzerdaten zu arbeiten. Die Methode initTokenClient() initialisiert einen neuen Token-Client mit der Client-ID Ihrer Webanwendung. Weitere Informationen finden Sie unter Tokenmodell verwenden.

Mit der Funktion onApiLoad() werden die Google Picker-Bibliotheken geladen. Die Callback-Funktion onPickerApiLoad() wird aufgerufen, nachdem die Google Picker-Bibliothek erfolgreich geladen wurde.

Google-Auswahl anzeigen

Mit der folgenden createPicker()-Funktion wird sichergestellt, dass die Google Picker API vollständig geladen wird und ein OAuth-Token erstellt wird. Diese Funktion erstellt dann eine Instanz von Google Picker 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 wird (pickerCallback).

Das Picker-Objekt rendert jeweils nur ein View. Geben Sie mindestens eine Ansicht an, indem Sie entweder ViewId (google.​picker.​ViewId.*) oder eine Instanz eines Typs (google.​picker.​*View) erstellen. Geben Sie die Ansicht nach Typ an, um die Darstellung der Ansicht zusätzlich zu steuern.

Wenn der Google-Auswahl mehrere Ansichten hinzugefügt werden, können Nutzer auf der linken Seite auf einen Tab klicken, um zwischen den Ansichten zu 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. auf die Auswahl einer Datei oder das Drücken von „Abbrechen“. Das Objekt Response liefert Informationen über die 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 einen Action, den der Nutzer mit der Google-Auswahl (google.picker.Response.ACTION) ausführt. Wenn der Nutzer ein Document-Element auswählt, wird auch das Array google.picker.Response.DOCUMENTS ausgefü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

Verwenden Sie ViewGroup, um bestimmte Elemente herauszufiltern. Im folgenden Codebeispiel sehen Sie, 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 von Google Picker anpassen

Sie können das Objekt Feature verwenden, um Funktionen für verschiedene Ansichten zu aktivieren oder zu deaktivieren. Verwenden Sie die Funktion PickerBuilder.enableFeature() oder PickerBuilder.disableFeature(), um das Design des Google Picker-Fensters zu optimieren. Wenn Sie beispielsweise nur eine Ansicht haben, können Sie den Navigationsbereich (Feature.NAV_HIDDEN) ausblenden, damit Nutzer mehr Platz zum Ansehen von Elementen 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 Picker in anderen Sprachen rendern

Geben Sie die UI-Sprache an, indem Sie das Gebietsschema für die Instanz PickerBuilder mit der Methode setLocale(locale) angeben.

Im folgenden Codebeispiel sehen Sie, wie die Sprache auf Französisch eingestellt wird:

    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