Omówienie aplikacji internetowych

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

• W konsoli Google Cloud włącz interfejs Google Picker API.

  Włączanie interfejsu 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 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 content_copy, 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

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

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 danych 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 Google Picker.

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 Twojego projektu Cloud.

Aby utworzyć instancję Google Picker, musisz utworzyć obiekt Picker za pomocą funkcji PickerBuilder. Funkcja PickerBuilder przyjmuje argumenty 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 widok podrzędny „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 widoków 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();