Interfejs Google Picker API

Okno selektora Google.

Google Picker API to interfejs API JavaScript, którego możesz używać w swoich aplikacjach internetowych, aby umożliwiać użytkownikom wybieranie lub przesyłanie plików na Dysk Google. Użytkownicy mogą przyznawać aplikacjom uprawnienia dostępu do danych na Dysku, co pozwala na korzystanie z ich plików w sposób bezpieczny i autoryzowany.

Selektor Google działa jak okno „Otwieranie pliku” w przypadku informacji przechowywanych na Dysku i charakteryzuje się tymi funkcjami:

  • Interfejs podobny 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.

Pamiętaj, że Selektor Google nie pozwala użytkownikom porządkować, przenosić ani kopiować plików między folderami. Możesz to zrobić za pomocą interfejsu Google Drive API lub interfejsu Dysku.

Wymagania dotyczące zgłoszenia

Aplikacje korzystające z selektora Google muszą być zgodne ze wszystkimi obowiązującymi Warunkami korzystania z usługi. Przede wszystkim musisz poprawnie się identyfikować w żądaniach.

Musisz też mieć projekt Google Cloud.

Konfigurowanie środowiska

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

Włącz API

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

Tworzenie klucza interfejsu API

Klucz interfejsu API to długi ciąg zawierający wielkie i małe litery, cyfry, podkreślenia i łączniki, np. AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Ta metoda uwierzytelniania służy do anonimowego dostępu do publicznie dostępnych danych, takich jak pliki Google Workspace udostępnione przy użyciu ustawienia udostępniania „Każdy użytkownik internetu mający ten link”. Więcej informacji znajdziesz w artykule o uwierzytelnianiu 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 został wyświetlony.
    • Kliknij Kopiuj , aby skopiować klucz interfejsu API do użycia w kodzie aplikacji. Klucz interfejsu API znajdziesz też w sekcji „Klucze interfejsów API” danych logowania do projektu.
    • Kliknij Ogranicz klucz, aby zaktualizować ustawienia zaawansowane i ograniczyć wykorzystanie klucza interfejsu API. Więcej informacji znajdziesz w artykule Stosowanie ograniczeń klucza interfejsu API.

Autoryzacja danych logowania dla aplikacji internetowej

Aby uwierzytelnić użytkowników i uzyskać dostęp do ich danych w aplikacji, musisz utworzyć co najmniej 1 identyfikator klienta OAuth 2.0. Identyfikator klienta wskazuje konkretną aplikację na serwerach OAuth Google. Jeśli Twoja aplikacja działa na wielu platformach, musisz utworzyć osobny 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 Twoją aplikacją:
    • Aplikacje po stronie klienta (JavaScript) – w sekcji Autoryzowane źródła JavaScript kliknij Dodaj identyfikator URI. Następnie wpisz identyfikator URI, którego będziesz używać w przypadku żądań przeglądarki. Identyfikuje ona domeny, z których aplikacja może wysyłać żądania interfejsu API 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 i tajny klucz klienta.

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

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

Wyświetl selektor Google

W pozostałej części tego przewodnika dowiesz się, jak wczytać i wyświetlić selektor Google z aplikacji internetowej. Pełny przykład znajdziesz w przykładowym kodzie selektora Google.

Wczytaj bibliotekę Google Picker

Aby wczytać bibliotekę Google Picker, wywołaj gapi.load(), podając nazwę biblioteki i funkcję wywołania zwrotnego, która zostanie wywołana po pomyślnym 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 Twojej aplikacji internetowej.
  • SCOPES: co najmniej jeden zakres OAuth 2.0, który musisz wysłać, aby uzyskać dostęp do interfejsów API Google, w zależności od wymaganego poziomu dostępu. Więcej informacji znajdziesz w artykule Zakresy OAuth 2.0 dla interfejsów API Google.

Biblioteka JavaScript google.accounts.oauth2 ułatwia wyświetlanie prośby o zgodę użytkownika i uzyskiwanie tokena dostępu na potrzeby pracy z danymi użytkownika. Metoda initTokenClient() inicjuje nowego klienta tokena z identyfikatorem klienta Twojej aplikacji internetowej. Więcej informacji znajdziesz w artykule o używaniu modelu tokena.

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

Wyświetl selektor Google

Poniższa funkcja createPicker() sprawdza, czy interfejs Google Picker API zakończy ładowanie i czy zostanie utworzony token OAuth. Ta funkcja tworzy instancję selektora Google i wyświetla ją:

    // 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ę selektora Google, musisz utworzyć obiekt Picker za pomocą PickerBuilder. PickerBuilder używa do tego celu View, tokena OAuth, klucza programisty i funkcji wywołania zwrotnego (pickerCallback).

Obiekt Picker renderuje jeden obiekt View naraz. Określ co najmniej 1 widok: za pomocą właściwości ViewId (google.​picker.​ViewId.*) lub przez utworzenie wystąpienia danego typu (google.​picker.​*View). Określ widok według typu, aby mieć dodatkową kontrolę nad sposobem jego renderowania.

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

Wdrażanie wywołania zwrotnego Google Picker

Wywołania zwrotne selektora Google może służyć do reagowania na interakcje użytkownika w selektorze Google, takie jak wybór pliku lub naciśnięcie Anuluj. Obiekt Response przekazuje informacje o opcjach wybranych przez 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 odbiera obiekt data zakodowany w formacie JSON. Ten obiekt zawiera obiekt Action, który użytkownik wykonuje za pomocą selektora Google (google.picker.Response.ACTION). Jeśli użytkownik wybierze element Document, tablica google.picker.Response.DOCUMENTS też zostanie wypełniona. W tym przykładzie google.picker.Document.URL jest wyświetlany na stronie głównej. Szczegółowe informacje o polach danych znajdziesz w dokumentacji JSON (w języku angielskim).

Filtruj określone typy plików

ViewGroup służy do odfiltrowywania konkretnych elementów. Poniższy przykładowy kod pokazuje, jak w widoku podrzędnym „Dysk Google” wyświetlają się 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 danych znajdziesz w artykule ViewId.

Dostosuj wygląd 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 nawigacji (Feature.NAV_HIDDEN), aby zapewnić użytkownikom więcej miejsca na wyświetlenie elementów.

Poniższy przykładowy kod przedstawia przykładowy selektor wyszukiwania w arkuszu kalkulacyjnym, który korzysta z tej funkcji:

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

Renderuj selektor Google w innych językach

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

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

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

Oto lista obecnie obsługiwanych 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