Z tego dokumentu dowiesz się, jak zintegrować selektor Google z aplikacjami internetowymi za pomocą interfejsu Google Picker API.
Google Picker API to interfejs API JavaScript, który możesz zaimplementować, aby umożliwić użytkownikom wybieranie lub przesyłanie plików z Dysku Google za pomocą selektora Google. Użytkownicy mogą przyznać Twoim aplikacjom uprawnienia dostępu do swoich danych na Dysku, co zapewnia bezpieczny i autoryzowany sposób interakcji z plikami.
Funkcje
Selektor Google ma kilka funkcji:
- Wygląd i działanie podobne do interfejsu Dysku Google.
- Kilka widoków z podglądami i miniaturami plików na Dysku.
- Wstępnie filtrowane widoki, które wyświetlają tylko określone typy plików (np. PDF lub obrazy) albo określone foldery.
- Wbudowane okno modalne, dzięki czemu użytkownicy nie muszą opuszczać głównej aplikacji.
Pamiętaj, że za pomocą selektora Google możesz wybierać i przesyłać pliki, ale nie możesz ich porządkować, przenosić ani kopiować 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 selektora Google muszą przestrzegać wszystkich obowiązujących Warunków korzystania z usługi. Przede wszystkim musisz prawidłowo identyfikować się w żądaniach.
Musisz też mieć projekt w chmurze 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 w chmurze Google. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs API.W konsoli Google Cloud włącz Google Picker API.
Tworzenie klucza interfejsu API
Klucz interfejsu 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 dostępu do danych publicznie dostępnych, takich jak pliki Google Workspace udostępnione za pomocą
ustawienia udostępniania „Każdy w internecie, kto ma ten link”. Więcej informacji znajdziesz w artykule
Zarządzanie kluczami interfejsu 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ę Twój 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ć tego klucza. Więcej informacji znajdziesz w artykule Dodawanie ograniczeń interfejsu API.
Autoryzowanie danych logowania w 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 interfejsów API Google otwórz Menu > Platforma Google Auth > Klienci.
- Kliknij Utwórz klienta.
- Kliknij Typ aplikacji > Aplikacja internetowa.
- W polu Nazwa wpisz nazwę danych logowania. Ta nazwa jest widoczna tylko w Konsoli interfejsów API Google.
- Dodaj autoryzowane identyfikatory URI powią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órego chcesz używać w żądaniach przeglądarki. Określa on domeny, z których Twoja aplikacja może wysyłać żądania interfejsu API do serwera OAuth 2.0.
- Aplikacje po stronie serwera (Java, Python itp.)– 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 klientów OAuth 2.0.
Zapisz identyfikator klienta. W przypadku aplikacji internetowych nie używa się tajnych 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,
przeczytaj artykuł Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google.
Zarządzanie selektorem Google
W pozostałej części tego dokumentu opisujemy, jak wczytywać i wyświetlać selektor Google z aplikacji internetowej oraz jak zaimplementować wywołanie zwrotne. Aby zobaczyć pełny przykładowy kod, przeczytaj artykuł Korzystanie z funkcji Google Picker API w aplikacjach internetowych.
Wczytywanie biblioteki selektora Google
Aby wczytać bibliotekę selektora Google, wywołaj
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 1 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 dla interfejsów API Google.
Biblioteka JavaScript google.accounts.oauth2 pomaga prosić 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 tokena.
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 TypeScript, możesz zainstalować
@types/google.picker aby
używać window.google.picker. Aby zgłosić problem z tymi typami, otwórz zgłoszenie do pomocy.
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 chmurze, co umożliwi aplikacji dostęp do plików użytkownika. Ta funkcja tworzy instancję selektora Google i ją wyświetla:
// 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 w chmurze.
Aby utworzyć instancję selektora Google, musisz utworzyć obiekt Picker za pomocą PickerBuilder. Funkcja PickerBuilder przyjmuje View, token OAuth 2.0, klucz dewelopera i
funkcję wywołania zwrotnego, która ma zostać wywołana po pomyślnym wykonaniu (pickerCallback).
Obiekt Picker renderuje 1 View naraz. Określ co najmniej 1 widok,
używając ViewId
(google.picker.ViewId.*) lub tworząc instancję DocsView, aby mieć większą 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ą ViewGroup obiektów.
Listę prawidłowych widoków znajdziesz w sekcji ViewId w
dokumentacji selektora Google. 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 wybranie 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;
}
Wywołanie zwrotne otrzymuje obiekt danych zakodowany w formacie JSON. Ten obiekt zawiera
Action którą użytkownik wykonuje za pomocą
selektora Google (google.picker.Response.ACTION). Jeśli użytkownik wybierze
element, zostanie też wypełniona tablica google.picker.Response.DOCUMENTS. W tym przykładzie adres google.picker.Document.URL jest wyświetlany 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ć
określone elementy. Poniższy przykładowy kod pokazuje, jak podwidok „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 sekcji
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 PickerBuilder.enableFeature lub
PickerBuilder.disableFeature
metody. Jeśli na przykład masz tylko 1 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();
Powiązane artykuły
- Przykładowy kod: korzystanie z funkcji Google Picker API w aplikacjach internetowych
- Wybieranie zakresów Google Drive API