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:

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

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

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:

Zakresy wrażliwe

Zakresy z ograniczeniami

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

• Niewrażliwe: te zakresy zapewniają najmniejszy zakres autoryzacji i wymagają tylko podstawowej weryfikacji aplikacji OAuth. Więcej informacji znajdziesz w sekcji Wymagania dotyczące weryfikacji.

• Wrażliwe: te zakresy zapewniają dostęp do określonych danych użytkownika Google, które użytkownicy autoryzują dla Twojej aplikacji. Wymagają dodatkowej weryfikacji aplikacji OAuth. Więcej informacji znajdziesz w artykule Wymagania dotyczące zakresu wrażliwego i objętego ograniczeniami.

• Z ograniczeniami: te zakresy zapewniają szeroki dostęp do danych użytkowników Google i wymagają weryfikacji aplikacji OAuth w zakresie z ograniczeniami. Więcej informacji znajdziesz w zasadach dotyczących danych użytkownika w usługach interfejsów API Google i dodatkowych wymaganiach dotyczących zakresów interfejsu API. Zobacz też Warunki korzystania z usługi Dysk Google.

  Jeśli przechowujesz dane z zakresów z ograniczeniami na serwerach (lub je przesyłasz), musisz przejść ocenę zabezpieczeń.

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.

Powiązane artykuły

• Omówienie uwierzytelniania i autoryzacji w Google Workspace znajdziesz w artykule Uwierzytelnianie i autoryzacja.
• Omówienie uwierzytelniania i autoryzacji w Google Cloud znajdziesz w artykule Uwierzytelnianie – omówienie.
• Więcej informacji o kontach usługi znajdziesz w artykule Konta usługi.
• Więcej informacji o rozwiązywaniu problemów znajdziesz w artykule Rozwiązywanie błędów.