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.Włącz interfejs Google Picker API w konsoli Google Cloud.
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:
- W konsoli Google Cloud otwórz Menu > Interfejsy API i usługi > Dane logowania.
- Kliknij Utwórz dane logowania > Klucz interfejsu API.
- 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.- 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.
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();