Wybierz zakresy interfejsów API Dysku Google

Ten dokument zawiera informacje o autoryzacji i uwierzytelnianiu w interfejsie Google Drive API. Przed przeczytaniem tego dokumentu zapoznaj się z ogólnymi informacjami o uwierzytelnianiu i autoryzacji w Google Workspace, które znajdziesz w artykule Uwierzytelnianie i autoryzacja.

Konfigurowanie OAuth 2.0 na potrzeby autoryzacji

Aby autoryzować aplikację, interfejs Google Drive API wymaga zdefiniowania zakresów OAuth w dwóch miejscach: w konsoli Google Cloud i w aplikacji.

W konsoli Google Cloud musisz zadeklarować zakresy, których potrzebuje Twoja aplikacja, w konfiguracji ekranu zgody OAuth. To najwyższy poziom uprawnień, o który może poprosić Twoja aplikacja. Jest to formalna prośba do Google, a zadeklarowane zakresy to te, które Google wyświetla użytkownikom na ekranie zgody. Dzięki temu użytkownik może dokładnie sprawdzić, do jakich danych i działań aplikacja chce uzyskać dostęp.

Skonfiguruj ekran zgody OAuth i wybierz zakresy, aby określić, jakie informacje będą wyświetlane użytkownikom i osobom sprawdzającym aplikację, oraz zarejestrować aplikację, aby móc ją później opublikować.

Gdy inicjujesz interfejs API w aplikacji, musisz wyraźnie poprosić o zakresy, których potrzebujesz w danej sesji. Konsola Google Cloud określa najwyższy poziom uprawnień, o które może prosić aplikacja, ale kod określa rzeczywiste uprawnienia danego użytkownika. Dzięki temu aplikacja prosi tylko o uprawnienia potrzebne do wykonania określonego zadania.

W kodzie aplikacji możesz zadeklarować jednocześnie jeden lub więcej zakresów OAuth jako tablicę.

Poniższy przykładowy kod pokazuje, jak zadeklarować wiele zakresów OAuth:

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

Aby zobaczyć, jak zakresy są deklarowane i używane w pełnym przykładzie kodu, zapoznaj się z krótkimi wprowadzeniami.

Zakresy interfejsu Drive API

Aby określić poziom dostępu przyznany aplikacji, musisz zidentyfikować i zadeklarować zakresy autoryzacji. Zakres autoryzacji to ciąg URI OAuth 2.0, który zawiera nazwę aplikacji Google Workspace, rodzaj danych, do których ma ona dostęp, oraz poziom dostępu. Zakresy to żądania aplikacji dotyczące pracy z danymi Google Workspace, w tym z danymi kont Google użytkowników.

Gdy aplikacja zostanie zainstalowana, użytkownik jest proszony o potwierdzenie zakresów używanych przez aplikację. Zazwyczaj należy wybrać jak najwęższy zakres i unikać proszenia o zakresy, których aplikacja nie potrzebuje. Użytkownicy chętniej przyznają dostęp do ograniczonych, jasno opisanych zakresów.

W miarę możliwości używaj zakresów niewrażliwych, ponieważ przyznają one dostęp do poszczególnych plików i ograniczają dostęp do konkretnych funkcji potrzebnych aplikacji.

Zakresy niewrażliwe

W większości przypadków zalecamy te zakresy interfejsu Drive API:

Kod zakresu Opis
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 Wyświetlanie na Dysku Google danych konfiguracyjnych tej aplikacji i zarządzanie nimi.
https://www.googleapis.com/auth/drive.install Zezwalaj aplikacjom na pojawianie się jako opcja w menu „Otwórz za pomocą” lub „Nowy”.
https://www.googleapis.com/auth/drive.file Tworzenie nowych plików na Dysku lub modyfikowanie istniejących plików otwieranych w aplikacji lub udostępnianych jej przez użytkownika podczas korzystania z interfejsu Google Picker API lub selektora plików aplikacji.

Zakresy wrażliwe

Kod zakresu Opis
https://www.googleapis.com/auth/drive.apps.readonly Wyświetl aplikacje, które mają dostęp do Twojego Dysku.

Zakresy z ograniczeniami

Kod zakresu Opis
https://www.googleapis.com/auth/drive wyświetlać wszystkie pliki na Dysku i zarządzać nimi;
https://www.googleapis.com/auth/drive.readonly wyświetlać i pobierać wszystkie pliki na Dysku;
https://www.googleapis.com/auth/drive.activity Wyświetlanie i uzupełnianie rejestru działań na plikach na Dysku.
https://www.googleapis.com/auth/drive.activity.readonly Wyświetlanie rejestru działań na plikach na Dysku.
https://www.googleapis.com/auth/drive.meet.readonly Wyświetlanie plików na Dysku utworzonych lub edytowanych w Google Meet.
https://www.googleapis.com/auth/drive.metadata Wyświetlanie metadanych plików na Dysku i zarządzanie nimi.
https://www.googleapis.com/auth/drive.metadata.readonly Wyświetlaj metadane plików na Dysku.
https://www.googleapis.com/auth/drive.scripts Modyfikowanie zachowania skryptów Google Apps Script.

Zakresy w tabelach powyżej wskazują ich wrażliwość zgodnie z tymi definicjami:

Jeśli Twoja aplikacja wymaga dostępu do innych interfejsów API Google, możesz też dodać te zakresy. Więcej informacji o zakresach interfejsów API Google znajdziesz w artykule Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google.

Więcej informacji o poszczególnych zakresach OAuth 2.0 znajdziesz w artykule Zakresy OAuth 2.0 dla interfejsów API Google.

Wymagania dotyczące zakresów z ograniczeniami

Tylko określone typy aplikacji mogą używać ograniczonych zakresów na potrzeby Dysku Google. Aby się zakwalifikować, Twoja aplikacja musi należeć do jednej z tych kategorii:

  1. Kopia zapasowa i synchronizacja: aplikacje internetowe i na poszczególne platformy, które zapewniają lokalną synchronizację lub automatyczne tworzenie kopii zapasowych plików użytkowników na Dysku.

  2. Narzędzia i edukacja: aplikacje z głównym interfejsem użytkownika, który może obejmować interakcje z plikami na Dysku, metadanymi lub uprawnieniami. Obejmują one aplikacje do zarządzania zadaniami, robienia notatek, komunikacji w grupach roboczych i współpracy na zajęciach.

  3. Raportowanie i bezpieczeństwo: aplikacje, które dostarczają użytkownikom lub klientom informacji o tym, jak pliki są udostępniane lub używane.

Aby nadal korzystać z ograniczonych zakresów, przygotuj aplikację do weryfikacji pod kątem ograniczonych zakresów.

Migracja istniejącej aplikacji z zakresów z ograniczeniami

Jeśli Twoja aplikacja na Dysku używa ograniczonych zakresów, zalecamy przejście na zakres interfejsu Drive API, który nie jest wrażliwy. Korzystanie z zakresów niewrażliwych, takich jak drive.file, przyznaje dostęp do poszczególnych plików i ograniczony dostęp do określonych funkcji potrzebnych aplikacji.

Wiele aplikacji może przejść na dostęp do poszczególnych plików bez żadnych zmian.

Jeśli używasz własnego selektora plików, zalecamy przejście na interfejs Google Picker API, który w pełni obsługuje różne zakresy.

Korzyści wynikające z zakresu pliku na Dysku

Używanie drive.file zakresu OAuth w połączeniu z interfejsem Google Picker API optymalizuje zarówno wygodę użytkownika, jak i bezpieczeństwo aplikacji.

drive.file Zakres OAuth umożliwia użytkownikom wybór plików, które chcą udostępnić aplikacji. Zapewnia to większą kontrolę i pewność, że dostęp aplikacji do plików jest ograniczony i bezpieczniejszy. Z kolei wymaganie szerokiego dostępu do wszystkich plików na Dysku może zniechęcić użytkowników do korzystania z aplikacji.

Oto kilka powodów, dla których warto używać zakresu drive.file:

  • Łatwość użycia: zakres drive.file działa ze wszystkimi zasobami REST interfejsu Drive API, co oznacza, że możesz go używać w taki sam sposób jak szerszych zakresów OAuth.

  • Funkcje: interfejs Google Picker API jest podobny do interfejsu użytkownika Dysku. Obejmuje to kilka widoków z podglądami i miniaturami plików na Dysku oraz okno modalne w tekście, dzięki czemu użytkownicy nigdy nie opuszczają głównej aplikacji.

  • Wygoda: aplikacje mogą stosować filtry do określonych typów plików na Dysku (takich jak Dokumenty i Arkusze Google oraz zdjęcia) podczas filtrowania plików w selektorze Google.

  • Prosta weryfikacja: ponieważ drive.file nie zawiera informacji wrażliwych, proces weryfikacji jest prostszy.

Bezpieczne przechowywanie tokenów odświeżania

Aby uzyskać dostęp do danych prywatnych za pomocą interfejsu Drive API, aplikacja musi uzyskać token dostępu, który przyznaje dostęp do tego interfejsu. Pojedynczy token dostępu może przyznawać różny poziom dostępu do wielu interfejsów API, w zależności od zakresów, o które poprosisz.

Tokeny dostępu mają krótki okres ważności, dlatego do długotrwałego dostępu do interfejsu Drive API musisz używać tokenów odświeżania. Token odświeżania umożliwia aplikacji żądanie nowych tokenów dostępu.

Zapisuj tokeny odświeżania w bezpiecznej pamięci długoterminowej i używaj ich tak długo, jak są ważne.

Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 do korzystania z interfejsów API Google.