Wybierz zakresy interfejsów API Dysku Google

Ten dokument zawiera informacje o autoryzacji i uwierzytelnianiu w interfejsie Google Drive API. Zanim przeczytasz ten dokument, 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 protokołu OAuth w 2 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. Są to uprawnienia najwyższego poziomu, o które może poprosić Twoja aplikacja. Jest to formalna prośba do Google, a zadeklarowane zakresy są wyświetlane użytkownikom na ekranie zgody. Dzięki temu użytkownik może dokładnie sprawdzić, do jakich danych i działań Twoja aplikacja prosi o 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 zarejestruj aplikację, aby móc ją później opublikować.

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

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

Poniższy przykład kodu pokazuje, jak zadeklarować kilka 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 deklaruje się i używa zakresów w pełnym przykładzie kodu, zapoznaj się z przewodnikami Szybki start.

Zakresy interfejsu Drive API

Aby określić poziom dostępu przyznany Twojej 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 danych na kontach Google użytkowników.

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

Jeśli to możliwe, 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 używanie tych zakresów 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 wyświetlanie się jako opcja w menu „Otwórz za pomocą” lub „Nowy”.
https://www.googleapis.com/auth/drive.file Twórz nowe pliki na Dysku lub modyfikuj istniejące pliki otwarte w aplikacji albo udostępnione aplikacji przez użytkownika podczas korzystania z interfejsu Google Picker API lub okna wyboru plików aplikacji.

Zakresy wrażliwe

Kod zakresu Opis
https://www.googleapis.com/auth/drive.apps.readonly Wyświetlanie aplikacji, którym pozwalasz na dostęp do Dysku.

Zakresy z ograniczeniami

Kod zakresu Opis
https://www.googleapis.com/auth/drive Wyświetlanie wszystkich plików na Dysku i zarządzanie nimi.
https://www.googleapis.com/auth/drive.readonly Wyświetlanie i pobieranie wszystkich plików 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 z Dysku Google 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 Zmienianie działania skryptów Google Apps Script.

Zakresy w tabelach powyżej wskazują na swoją 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 OAuth 2.0 na potrzeby dostępu do interfejsów API Google.

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

Kryteria kwalifikacji do zakresów z ograniczeniami

Tylko określone typy aplikacji mogą używać zakresów z ograniczeniami 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 konkretne platformy, które zapewniają lokalną synchronizację lub automatyczną kopię zapasową plików użytkowników na Dysku.

  2. Wydajność i edukacja: aplikacje z głównym interfejsem użytkownika, który może obejmować interakcję z plikami, metadanymi lub uprawnieniami na Dysku. Te aplikacje obejmują zarządzanie zadaniami, robienie notatek, komunikację w grupach roboczych i współpracę w klasie.

  3. Raportowanie i bezpieczeństwo: aplikacje, które zapewniają użytkownikom lub klientom wgląd w sposób udostępniania plików lub uzyskiwania do nich dostępu.

Aby nadal korzystać z zakresów z ograniczeniami, przygotuj aplikację do weryfikacji w zakresie z ograniczeniami.

Migracja istniejącej aplikacji z zakresów z ograniczeniami

Jeśli Twoja aplikacja na Dysku używa zakresów z ograniczeniami, zalecamy migrację do zakresu interfejsu Drive API, który nie jest wrażliwy. Używanie zakresów niewrażliwych, takich jak drive.file, przyznaje dostęp do poszczególnych plików i ogranicza dostęp do konkretnych 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 okna wyboru plików, zalecamy przejście na interfejs Google Picker API, który w pełni obsługuje różne zakresy.

Korzyści z zakresu plików na Dysku

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

Zakres OAuth drive.file umożliwia użytkownikom wybieranie plików, które chcą udostępnić Twojej aplikacji. Daje im to większą kontrolę i pewność, że dostęp aplikacji do ich 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 Twojej aplikacji.

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

  • Użyteczność: 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 szersze zakresy OAuth.

  • Funkcje: interfejs Google Picker API jest podobny do interfejsu Dysku. Obejmuje to kilka widoków z podglądami i miniaturami plików na Dysku oraz wbudowane okno modalne, 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, Arkusze i zdjęcia Google) podczas używania filtra w plikach Google Picker.

  • Prosta weryfikacja: ponieważ drive.file nie jest wrażliwy, umożliwia bardziej usprawniony proces weryfikacji.

Bezpieczne przechowywanie tokenów odświeżania

Aby uzyskać dostęp do danych prywatnych za pomocą interfejsu Drive API, Twoja 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 żądanych zakresów.

Ponieważ tokeny dostępu mają krótki okres ważności, 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 bezpiecznym, długoterminowym miejscu i używaj ich tak długo, jak są ważne.

Więcej informacji znajdziesz w artykule Używanie OAuth 2.0 na potrzeby dostępu do interfejsów API Google.