Interfejs Google Picker API

Okno selektora Google.

Selektor Google to okno „Otwórz plik” z informacjami zapisanymi na Dysku Google. Selektor Google obejmuje te funkcje:

  • Podobne do interfejsu Dysku Google.
  • Kilka widoków z podglądem i miniaturami plików z Dysku.
  • Wbudowane okno modalne, dzięki któremu użytkownicy nigdy nie opuszczają głównej aplikacji.

Interfejs Google Picker API to interfejs API w języku JavaScript, którego możesz używać w swoich aplikacjach internetowych do umożliwiania użytkownikom otwierania i przesyłania plików z Dysku.

Wymagania

Aplikacje korzystające z selektora Google muszą być zgodne ze wszystkimi Warunkami usługi. Najważniejsze jest prawidłowe identyfikowanie się żądań reklamy.

Musisz też mieć projekt Google Cloud.

Konfigurowanie środowiska

Aby zacząć korzystać z interfejsu Google Picker API, musisz skonfigurować środowisko.

Włącz API

Zanim zaczniesz korzystać z interfejsów API Google, musisz je włączyć w projekcie Google Cloud. W jednym projekcie Google Cloud możesz włączyć jeden lub więcej interfejsów API.

utworzysz klucz interfejsu API;

Klucz interfejsu API to długi ciąg zawierający duże i małe litery, cyfry, podkreślenia oraz łączniki, takie jak AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Ta metoda uwierzytelniania służy do anonimowego uzyskiwania dostępu do danych dostępnych publicznie, takich jak pliki Google Workspace udostępniane przy użyciu ustawienia udostępniania „Każdy użytkownik internetu mający ten link”. Więcej informacji znajdziesz w artykule Uwierzytelnianie za pomocą kluczy interfejsu API.

Aby utworzyć klucz interfejsu API:

  1. W konsoli Google Cloud kliknij Menu > Interfejsy API i usługi > Dane logowania.

    Otwórz stronę Dane logowania

  2. Kliknij Utwórz dane logowania > Klucz interfejsu API.
  3. Nowy klucz interfejsu API zostanie wyświetlony.
    • Kliknij Kopiuj , aby skopiować klucz interfejsu API do wykorzystania w kodzie aplikacji. Klucz interfejsu API można też znaleźć w sekcji „Klucze interfejsu API” w danych logowania do projektu.
    • Kliknij Ogranicz klucz, aby zaktualizować ustawienia zaawansowane i ograniczyć użycie klucza interfejsu API. Więcej informacji znajdziesz w artykule Stosowanie ograniczeń dotyczących klucza interfejsu API.

Autoryzuj dane logowania do aplikacji internetowej

Aby uwierzytelnić się jako użytkownik końcowy i uzyskać dostęp do danych użytkownika w aplikacji, musisz utworzyć co najmniej 1 identyfikator klienta OAuth 2.0. Identyfikator klienta służy do identyfikowania jednej aplikacji na serwerach OAuth Google. Jeśli Twoja aplikacja działa na wielu platformach, musisz utworzyć oddzielny identyfikator klienta dla każdej z nich.

  1. W konsoli Google Cloud kliknij Menu > Interfejsy API i usługi > Dane logowania.

    Otwórz stronę Dane logowania

  2. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
  3. Kliknij Typ aplikacji > Aplikacja internetowa.
  4. W polu Nazwa wpisz nazwę danych logowania. Ta nazwa jest widoczna tylko w konsoli Google Cloud.
  5. Dodaj autoryzowane identyfikatory URI powiązane z aplikacją:
    • Aplikacje po stronie klienta (JavaScript) – w sekcji Autoryzowane źródła JavaScript kliknij Dodaj identyfikator URI. Następnie wpisz identyfikator URI, który będzie używany w żądaniach przeglądarki. Identyfikuje domeny, z których aplikacja może wysyłać żądania do serwera OAuth 2.0.
    • Aplikacje po stronie serwera (Java, Python i inne) – w sekcji Autoryzowane identyfikatory URI przekierowania kliknij Dodaj identyfikator URI. Następnie wpisz identyfikator URI punktu końcowego, do którego serwer OAuth 2.0 może wysyłać odpowiedzi.
  6. Kliknij Utwórz. Pojawi się ekran utworzony przez klienta OAuth zawierający nowy identyfikator klienta i tajny klucz klienta.

    Zapisz identyfikator klienta. Tajne klucze klienta nie są używane w aplikacjach internetowych.

  7. Kliknij OK. Nowo utworzone dane logowania pojawią się w sekcji Identyfikatory klienta OAuth 2.0.
Ważne: podczas tworzenia obiektu Picker Twoja aplikacja musi wysłać token dostępu OAuth 2.0 z widokami danych, które uzyskują dostęp do prywatnych danych użytkownika. Aby dowiedzieć się, jak poprosić o token dostępu, przeczytaj artykuł Uzyskiwanie dostępu do interfejsów API Google przy użyciu protokołu OAuth 2.0.

Wyświetlanie selektora Google

Pozostała część tego przewodnika opisuje, jak wczytywać i wyświetlać selektor Google w aplikacji internetowej. Aby zobaczyć pełny przykład, przejdź do przykładowego kodu selektora Google.

Wczytaj bibliotekę selektora Google

Aby wczytać bibliotekę Google Picker, wywołaj gapi.load() z nazwą biblioteki i funkcją wywołania zwrotnego, która zostanie wywołana po udanym wczytaniu:

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

Zastąp następujące elementy:

  • CLIENT_ID: identyfikator klienta aplikacji internetowej.
  • SCOPES: co najmniej jeden zakres OAuth 2.0 wymagany do uzyskania dostępu do interfejsów API Google (w zależności od wymaganego poziomu dostępu). Więcej informacji znajdziesz w sekcji Zakresy OAuth 2.0 dla interfejsów API Google.

Biblioteka JavaScript google.accounts.oauth2 pomaga wyświetlać prośbę o zgodę użytkownika i uzyskać token dostępu umożliwiający pracę z danymi użytkownika. Metoda initTokenClient() inicjuje nowego klienta tokena z identyfikatorem klienta aplikacji internetowej. Więcej informacji znajdziesz w artykule Używanie modelu tokena.

Funkcja onApiLoad() wczytuje biblioteki selektora Google. Funkcja wywołania zwrotnego onPickerApiLoad() jest wywoływana po wczytaniu biblioteki wyboru Google.

Wyświetlanie selektora Google

Funkcja createPicker() poniżej sprawdza, czy interfejs Google Picker API kończy się podczas ładowania i czy utworzono token OAuth. Ta funkcja tworzy wtedy selektor Google i wyświetla go:

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

Aby utworzyć instancję Google Picker, musisz utworzyć obiekt Picker za pomocą PickerBuilder. PickerBuilder wymaga wywołania View, tokena OAuth, klucza programisty i funkcji wywołania zwrotnego, gdy wywołanie (pickerCallback).

Obiekt Picker renderuje pojedynczo element View. Określ co najmniej 1 widok danych za pomocą ViewId (google.​picker.​ViewId.*) lub przez utworzenie wystąpienia typu (google.​picker.​*View). Określ widok według typu, aby uzyskać dodatkową kontrolę nad jego renderowaniem.

Jeśli do selektora Google dodasz więcej niż jeden widok, użytkownicy będą mogli przełączać się między nimi, klikając kartę po lewej stronie. Karty można logicznie pogrupować za pomocą obiektów ViewGroup.

Wdrażanie wywołania zwrotnego selektora Google

Wywołania zwrotnego Google Picker możesz użyć, aby zareagować na interakcje użytkownika w selektorze Google, np. wybierając plik lub klikając Anuluj. Obiekt Response przekazuje informacje o wyborach użytkownika.

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

Wywołanie zwrotne otrzymuje obiekt data w formacie JSON. Ten obiekt zawiera element Action, który użytkownik wykonuje przy użyciu selektora Google (google.picker.Response.ACTION). Jeśli użytkownik wybierze element Document, pole google.picker.Response.DOCUMENTS też zostanie wypełnione. W tym przykładzie google.picker.Document.URL jest widoczny na stronie głównej. Szczegółowe informacje o polach danych znajdziesz w dokumentacji plików JSON.

Filtrowanie określonych typów plików

Używaj ViewGroup do filtrowania konkretnych elementów. Poniższy przykładowy kod pokazuje, jak w widoku podrzędnym „Dysk Google” widać tylko dokumenty i prezentacje.

    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();
    
Listę prawidłowych typów widoków znajdziesz w artykule ViewId.

Dostosowywanie wyglądu selektora Google

Za pomocą obiektu Feature możesz włączać i wyłączać funkcje w różnych widokach. Aby dostosować wygląd okna selektora Google, użyj funkcji PickerBuilder.enableFeature() lub PickerBuilder.disableFeature(). Jeśli na przykład masz tylko jeden widok, możesz ukryć panel nawigacyjny (Feature.NAV_HIDDEN), aby użytkownicy mieli więcej miejsca, aby wyświetlić elementy.

Poniższy przykładowy kod pokazuje przykład selektora wyszukiwania w arkuszu kalkulacyjnym za pomocą tej funkcji:

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

Renderowanie selektora Google w innych językach

Określ język interfejsu użytkownika, podając język w instancji PickerBuilder za pomocą metody setLocale(locale).

Poniższy przykładowy kod pokazuje, jak ustawić język francuski:

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

Oto lista obsługiwanych obecnie języków:

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