Omówienie aplikacji internetowych

Okno wyboru Google.

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

Selektor Google działa jak okno „Otwórz plik” w przypadku informacji przechowywanych na Dysku i ma kilka funkcji:

  • Podobny wygląd i działanie jak w interfejsie Dysku Google.
  • Kilka widoków przedstawiających podglądy i miniatury plików na Dysku.
  • w oknie modalnym w treści, dzięki czemu użytkownicy nigdy nie opuszczają głównej aplikacji;

Pamiętaj, że selektor Google nie umożliwia użytkownikom porządkowania, przenoszenia ani kopiowania plików z jednego folderu do drugiego. Aby zarządzać plikami, musisz użyć interfejsu Google Drive API lub interfejsu Dysku.

Wymagania wstępne

Aplikacje korzystające z Google Picker muszą przestrzegać wszystkich obowiązujących Warunków usługi. Najważniejsze jest prawidłowe zidentyfikowanie się w żądaniach.

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 Google API, musisz je włączyć w projekcie Google Cloud. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs API.

Tworzenie klucza interfejsu API

Klucz API to długi ciąg znaków zawierający wielkie i małe litery, cyfry, podkreślenia i łączniki, np. AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Ta metoda uwierzytelniania służy do anonimowego uzyskiwania dostępu do publicznie dostępnych danych, takich jak pliki Google Workspace udostępnione przy użyciu ustawienia udostępniania „Każdy w internecie, kto ma ten link”. Więcej informacji znajdziesz w artykule Zarządzanie kluczami API.

Aby utworzyć klucz interfejsu API:

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

    Przejdź do danych logowania

  2. Kliknij Utwórz dane logowania > Klucz interfejsu API.
  3. Wyświetli się nowy klucz interfejsu API.
    • Kliknij Kopiuj , aby skopiować klucz interfejsu API do użycia w kodzie aplikacji. Klucz interfejsu API można też znaleźć w sekcji „Klucze interfejsu API” w danych logowania projektu.
    • Aby można było zapobiec nieautoryzowanemu użyciu, zalecamy ograniczenie miejsc i interfejsów API, w których można używać klucza API. Więcej informacji znajdziesz w sekcji Dodawanie ograniczeń interfejsu API.

Autoryzowanie danych logowania w przypadku aplikacji internetowej

Aby uwierzytelniać użytkowników i uzyskiwać dostęp do danych użytkowników 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 kilku platformach, musisz utworzyć osobny identyfikator klienta dla każdej z nich.
  • W konsoli Google Cloud otwórz Menu  > > Klienci.

    Otwórz stronę Klienci

  • Kliknij Utwórz klienta.
  • Kliknij Typ aplikacji > Aplikacja internetowa.
  • W polu Nazwa wpisz nazwę danych logowania. Ta nazwa jest widoczna tylko w konsoli Google Cloud.
  • Dodaj autoryzowane identyfikatory URI związane z Twoją aplikacją:
    • Aplikacje po stronie klienta (JavaScript) – w sekcji Autoryzowane źródła JavaScriptu kliknij Dodaj URI. Następnie wpisz identyfikator URI, który ma być używany w żądaniach przeglądarki. Określa domeny, z których aplikacja może wysyłać żądania API do serwera OAuth 2.0.
    • Aplikacje po stronie serwera (Java, Python i inne) – w sekcji Autoryzowane identyfikatory URI przekierowania kliknij Dodaj URI. Następnie wpisz identyfikator URI punktu końcowego, do którego serwer OAuth 2.0 może wysyłać odpowiedzi.
  • Kliknij Utwórz.

    Nowo utworzone dane logowania pojawią się w sekcji Identyfikatory klienta OAuth 2.0.

    Zapisz identyfikator klienta. W przypadku aplikacji internetowych nie używa się kluczy klienta.

  • Ważne: podczas tworzenia obiektu Picker aplikacja musi wysyłać token dostępu OAuth 2.0 z widokami, które mają dostęp do prywatnych danych użytkownika. Aby poprosić o token dostępu, zapoznaj się z artykułem Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google.

    Zarządzanie selektorem Google

    W dalszej części tego przewodnika dowiesz się, jak wczytać i wyświetlić selektor Google w aplikacji internetowej oraz jak zaimplementować wywołanie zwrotne. Pełny przykład znajdziesz w sekcji Przykładowy kod aplikacji internetowych.

    Wczytywanie biblioteki selektora Google

    Aby wczytać bibliotekę selektora Google, wywołaj funkcję gapi.load z nazwą biblioteki i funkcją wywołania zwrotnego, która ma zostać 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() {
            // 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, o który musisz poprosić, aby uzyskać dostęp do interfejsów API Google, w zależności od potrzebnego poziomu dostępu. Więcej informacji znajdziesz w artykule Zakresy OAuth 2.0 w interfejsach API Google.

    Biblioteka JavaScript google.accounts.oauth2 pomaga wyświetlać prośby o zgodę użytkownika i uzyskiwać token dostępu do pracy z danymi użytkownika. Metoda initTokenClient inicjuje nowego klienta tokena za pomocą identyfikatora klienta aplikacji internetowej. Więcej informacji znajdziesz w artykule Korzystanie z modelu tokenów.

    Funkcja onApiLoad wczytuje biblioteki selektora Google. Funkcja wywołania zwrotnego onPickerApiLoad jest wywoływana po pomyślnym wczytaniu biblioteki selektora Google.

    Uwaga: jeśli używasz TypeScriptu, możesz zainstalować @types/google.picker, aby używać window.google.picker. Aby zgłosić problem z tymi typami, otwórz zgłoszenie.

    Wyświetlanie selektora Google

    Funkcja createPicker sprawdza, czy interfejs Google Picker API został wczytany i czy utworzono token OAuth 2.0. Użyj metody PickerBuilder.setAppId, aby ustawić identyfikator aplikacji na Dysku za pomocą numeru projektu w Cloud, co umożliwi aplikacji dostęp do plików użytkownika. Następnie 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 = () => {
            // 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: ''});
          }
        }
    

    Zastąp następujące elementy:

    • API_KEY: Twój klucz interfejsu API.
    • APP_ID: numer projektu Cloud.

    Aby utworzyć instancję selektora Google, musisz utworzyć obiekt Picker za pomocą funkcji PickerBuilder. Funkcja PickerBuilder przyjmuje View, token OAuth 2.0, klucz dewelopera i funkcję wywołania zwrotnego, która ma być wywoływana w przypadku powodzenia (pickerCallback).

    Obiekt Picker renderuje po jednym obiekcie View. Określ co najmniej jeden widok, używając ViewId (google.picker.ViewId.*) lub tworząc instancję DocsView, aby uzyskać dodatkową kontrolę nad sposobem renderowania widoku.

    Jeśli do selektora Google dodano więcej niż 1 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.

    Listę prawidłowych widoków znajdziesz w sekcji ViewId w dokumentacji Google Picker. Aby uzyskać token dla dowolnego z tych widoków, użyj zakresu https://www.googleapis.com/auth/drive.file.

    Implementowanie wywołania zwrotnego selektora Google

    Wywołanie 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 przycisku Anuluj. Interfejs ResponseObject przekazuje informacje o wyborach użytkownika.

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

    Funkcja zwrotna otrzymuje obiekt danych zakodowany w formacie JSON. Ten obiekt zawiera Action, które użytkownik wykonuje za pomocą selektora Google (google.picker.Response.ACTION). Jeśli użytkownik wybierze element, wypełniana jest też tablica google.picker.Response.DOCUMENTS. W tym przykładzie google.picker.Document.URL jest widoczny na stronie głównej. Szczegółowe informacje o polach danych znajdziesz w interfejsie ResponseObject.

    Filtrowanie określonych typów plików

    Użyj ViewGroup, aby filtrować konkretne produkty. Poniższy przykładowy kod pokazuje, jak podrzędny widok „Dysk” wyświetla tylko dokumenty i prezentacje.

        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();
    

    Listę prawidłowych typów widoku znajdziesz w 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 metody PickerBuilder.enableFeature lub PickerBuilder.disableFeature. Jeśli np. masz tylko jeden widok, możesz ukryć panel nawigacyjny (Feature.NAV_HIDDEN), aby użytkownicy mieli więcej miejsca na wyświetlanie elementów.

    Poniższy przykładowy kod pokazuje przykład selektora wyszukiwania arkusza kalkulacyjnego korzystającego z tej funkcji:

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