Każdy plik, folder i dysk współdzielony na Dysku Google ma powiązane z nim zasobypermissions. Każdy zasób określa uprawnienia dla konkretnego type (user, group, domain, anyone) i role (owner, organizer, fileOrganizer, writer, commenter, reader). Na przykład plik może mieć uprawnienia przyznające konkretnemu użytkownikowi (type=user) dostęp tylko do odczytu (role=reader), a inne uprawnienia mogą przyznawać członkom konkretnej grupy (type=group) możliwość dodawania komentarzy do pliku (role=commenter).
Pełną listę ról i operacji, które każda z nich umożliwia, znajdziesz w artykule Role i uprawnienia.
Jak uprawnienia są propagowane
Uprawnienia są propagowane w dół z folderów nadrzędnych do wszystkich elementów podrzędnych:
- Dziedziczone domyślnie: wszystkie pliki i foldery podrzędne automatycznie dziedziczą uprawnienia z folderu nadrzędnego.
- Nie można ograniczyć uprawnień dotyczących elementów podrzędnych: nie możesz usunąć ani ograniczyć odziedziczonych uprawnień dotyczących elementu podrzędnego. Zmiany muszą zostać wprowadzone w folderze nadrzędnym, z którego pochodzi plik, lub folder musi korzystać z ustawienia ograniczonego dostępu.
- Można rozszerzyć uprawnienia w przypadku elementów podrzędnych: element podrzędny może przyznawać większe uprawnienia, np.
role=writerw przypadku pliku w folderze, w którym użytkownik ma uprawnieniarole=reader. - Ponowna ocena po przeniesieniu: przeniesienie elementu do nowego folderu nadrzędnego powoduje ponowną ocenę i zastosowanie uprawnień nowego folderu nadrzędnego do elementu i jego elementów podrzędnych.
Linki do plików i kontrola dostępu
Gdy udostępniasz plik lub folder konkretnemu użytkownikowi lub grupie, adres URL umożliwiający dostęp do elementu nie zmienia się i nie jest generowany unikalny link dla każdego użytkownika.
Zamiast tego element ma jeden stały link oparty na jego fileId.
Dysk zarządza dostępem, sprawdzając listę kontroli dostępu do elementu. Gdy użytkownik próbuje otworzyć link, Dysk weryfikuje jego uwierzytelnioną tożsamość na podstawie listy ACL. Jeśli uprawnienie zostanie cofnięte lub osiągnie datę wygaśnięcia, użytkownik zostanie usunięty z listy ACL. Jeśli użytkownik spróbuje ponownie otworzyć link, Dysk odmówi dostępu.
Możliwości plików
Zasób permissions określa kto ma dostęp (lista ACL), ale nie wskazuje bezpośrednio, czy bieżący użytkownik może wykonać określone działanie w interfejsie aplikacji.
Zamiast tego zasób files zawiera zbiór pól logicznych capabilities (np. canComment, canShare lub canDelete), które interfejs Google Drive API oblicza dynamicznie na podstawie roli użytkownika i ustawień elementu.
Pobieranie możliwości pliku
Podczas renderowania interfejsu aplikacji sprawdzaj files.capabilities zamiast bezpośrednio analizować uprawnienia:
- Wywołaj metodę
files.getz parametremfields=capabilities. Więcej informacji znajdziesz w sekcji Zwracanie określonych pól. - Użyj zwróconych flag logicznych, aby włączyć lub wyłączyć odpowiednie działania w interfejsie. Na przykład wyłącz komentowanie, jeśli
canCommentma wartośćfalse.
Scenariusze udostępniania zasobów Dysku
W tabeli poniżej znajdziesz wymagane role i warunki udostępniania zasobów na Dysku w różnych lokalizacjach i typach elementów:
| Lokalizacja | Element | Wymagane role | Najważniejsze ograniczenia |
|---|---|---|---|
| Mój dysk | Plik lub folder | owner lub writer |
Wymaga owner, jeśli writersCanShare=false.Dostęp czasowy do folderów wymaga reader (patrz Ustawianie daty wygaśnięcia). |
| Dysk współdzielony | Plik | organizer, fileOrganizer lub writer |
writersCanShare jest zawsze traktowane jako true. |
| Dysk współdzielony | Folder | organizer |
fileOrganizer może też udostępniać treści, jeśli wartość sharingFoldersRequiresOrganizerPermission to false. |
| Dysk współdzielony | Członkostwo | organizer |
Dotyczy tylko user lub group (nie domen). |
Zarządzaj uprawnieniami
W tabeli poniżej znajdziesz podsumowanie metod dostępnych w zasobie permissions:
| Metoda | punkt końcowy API | Kluczowe parametry | Dokumentacja |
|---|---|---|---|
| Utwórz | POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
role, type, emailAddress lub domain |
permissions.create |
| Pobierz | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
fields |
permissions.get |
| Wyświetl listę | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
pageSize, supportsAllDrives, pageToken |
permissions.list |
| Zaktualizuj | PATCH https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
role, allowFileDiscovery |
permissions.update |
| Usuń | DELETE https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
supportsAllDrives |
permissions.delete |
Tworzenie uprawnień
Aby udostępnić plik, folder lub dysk współdzielony, wywołaj metodę
create w zasobie
permissions z parametrem fileId.
Utworzenie uprawnienia powoduje dodanie do elementu nowego wpisu na liście kontroli dostępu i zwrócenie przypisanego permissionId.
W treści żądania podaj te pola:
role: poziom dostępu, który chcesz przyznać (np.reader,commenterlubwriter). Pełną listę znajdziesz w artykule Role i uprawnienia.type: zakres uprawnień (user,group,domainlubanyone).- Identyfikator beneficjenta (wymagany w zależności od
type):emailAddress: wymagany, gdytypema wartośćuserlubgroup.domain: wymagany, gdytypema wartośćdomain.
Poniższy przykładowy kod pokazuje, jak utworzyć uprawnienie. Odpowiedź zwraca instancję zasobu permissions, w tym przypisany permissionId.
Żądanie
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "role": "commenter", "type": "user", "emailAddress": "alex@altostrat.com" }
Odpowiedź
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}Udostępnianie grupom odbiorców
Grupy odbiorców to obejmujące zbiory osób (na przykład działy lub zespoły) grupy, które możesz polecać użytkownikom, tak by ci udostępniali im swoje elementy. Możesz zachęcić użytkowników do udostępniania elementów konkretnym odbiorcom lub ograniczonej ich grupie, a nie całej organizacji. Grupy odbiorców mogą pomóc Ci zwiększyć bezpieczeństwo i prywatność danych oraz ułatwić użytkownikom odpowiednie udostępnianie.
Aby udostępnić treści grupie docelowych odbiorców, ustaw type=domain i domain na <TARGET_AUDIENCE_ID>.audience.googledomains.com. Szczegółowe informacje o znajdowaniu i tworzeniu grup odbiorców w konsoli administracyjnej Google znajdziesz w artykule Informacje o grupach odbiorców.
Aby dowiedzieć się, jak użytkownicy wchodzą w interakcje z odbiorcami docelowymi, przeczytaj artykuł Wpływ ustawień na interfejs udostępniania linku przez użytkownika.
Uzyskiwanie uprawnień
Aby uzyskać uprawnienie, wywołaj metodę get w zasobie permissions z parametrami ścieżki fileId i permissionId. Jeśli nie znasz identyfikatora uprawnienia, najpierw wyświetl listę wszystkich uprawnień.
Wyświetlanie listy uprawnień
Aby wyświetlić listę uprawnień do pliku, folderu lub dysku współdzielonego, wywołaj metodę
list w zasobie
permissions z wymaganym parametrem ścieżki
fileId.
Możesz uwzględnić dowolny z tych opcjonalnych parametrów zapytania, aby podzielić odpowiedź na strony lub ją filtrować:
pageSize(opcjonalnie): maksymalna liczba uprawnień do zwrócenia na stronie. Jeśli nie jest ustawiona dla plików na dysku współdzielonym, zwracanych jest maksymalnie 100 wyników. Jeśli nie jest ustawiona dla plików, które nie znajdują się na dysku współdzielonym, zwracana jest cała lista.pageToken(opcjonalnie): token strony z poprzedniego wywołania listy, który umożliwia pobranie kolejnej strony.supportsAllDrives(opcjonalnie): czy aplikacja wysyłająca żądanie obsługuje zarówno Mój dysk, jak i dyski współdzielone.useDomainAdminAccess(opcjonalnie): ustaw wartośćtrue, aby wysłać żądanie jako administrator domeny. Osoba wysyłająca prośbę otrzyma dostęp, jeśli parametrfileIdodnosi się do dysku współdzielonego, a osoba wysyłająca prośbę jest administratorem domeny, do której należy dysk współdzielony. Więcej informacji znajdziesz w artykule Zarządzanie dyskami współdzielonymi jako administrator domeny.includePermissionsForView(opcjonalnie): dodatkowe uprawnienia do wyświetlania, które mają być uwzględnione w odpowiedzi. Obsługiwana jest tylko wartośćpublished.fields(opcjonalnie): konkretne pola, które mają być zwracane w odpowiedzi. Domyślnie funkcjalistzwraca tylko wartościid,type,kindirole. Aby zwrócić dodatkowe pola (np.permissionDetails), określ je za pomocą tego parametru. Więcej informacji znajdziesz w artykule Zwracanie określonych pól.
Określanie źródła roli
Aby zmienić rolę w pliku lub folderze, musisz znać źródło roli. W przypadku dysków współdzielonych źródłem roli może być członkostwo na dysku współdzielonym, rola w folderze lub rola w pliku.
Aby określić źródło roli na dysku współdzielonym lub w elementach na tym dysku, wywołaj metodę get w zasobie permissions z parametrami ścieżki fileId i permissionId oraz parametrem fields ustawionym na pole permissionDetails.
Aby znaleźć permissionId, użyj metody list w zasobie permissions z parametrem ścieżki fileId. Aby pobrać pole permissionDetails w żądaniu list, ustaw parametr fields na permissions/permissionDetails.
To pole zawiera wszystkie dziedziczone i bezpośrednie uprawnienia do plików użytkownika, grupy lub domeny.
Poniższy przykładowy kod pokazuje, jak określić źródło roli. Odpowiedź zwraca permissionDetails zasobu permissions. Pole inheritedFrom zawiera identyfikator elementu, z którego dziedziczone jest uprawnienie.
Żądanie
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true
Odpowiedź
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}Aktualizowanie uprawnień
Aby zaktualizować uprawnienia do pliku lub folderu, możesz zmienić przypisaną rolę. Więcej informacji o znajdowaniu źródła roli znajdziesz w artykule Określanie źródła roli.
Wywołaj metodę
updatew zasobiepermissionsz parametrem ścieżkifileIdustawionym na powiązany plik, folder lub dysk współdzielony oraz parametrem ścieżkipermissionIdustawionym na uprawnienia do zmiany. Aby znaleźćpermissionId, użyj metodylistw zasobiepermissionsz parametrem ścieżkifileId.W prośbie podaj nowy
role.
Możesz przyznać uprawnienia do poszczególnych plików lub folderów na dysku współdzielonym, nawet jeśli użytkownik lub grupa jest już członkiem. Na przykład Alex ma role=commenter
w ramach członkostwa na dysku współdzielonym. Aplikacja może jednak przyznać Alexowirole=writer dostęp do pliku na dysku współdzielonym. W tym przypadku nowa rola jest bardziej restrykcyjna niż rola przyznana w ramach subskrypcji, więc nowe uprawnienia stają się efektywną rolą dla pliku lub folderu.
Aktualizacje możesz stosować za pomocą semantyki poprawek, co oznacza, że możesz wprowadzać częściowe modyfikacje zasobu. W żądaniu musisz wyraźnie ustawić pola, które chcesz zmodyfikować. Pola, które nie są uwzględnione w żądaniu, zachowują swoje dotychczasowe wartości. Więcej informacji znajdziesz w artykule Praca z częściowymi zasobami.
Oprócz zmiany ról możesz też modyfikować widoczność elementu, gdy uprawnienie type ma wartość domain lub anyone. Aby udostępniony plik był wyszukiwalny lub niepubliczny, w żądaniu PATCH uwzględnij pole logiczne allowFileDiscovery. Ustawienie tej opcji na true umożliwia wyświetlanie elementu w wynikach wyszukiwania dla określonych odbiorców, nawet jeśli nie otrzymali oni bezpośredniego linku. Aby zmienić to ustawienie, nie musisz usuwać uprawnień i tworzyć ich od nowa.
Poniższy przykładowy kod pokazuje, jak zmienić uprawnienia dotyczące pliku lub folderu z commenter na writer. Odpowiedź zwraca instancję zasobu permissions.
Żądanie
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}Odpowiedź
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}Aktualizowanie wielu uprawnień za pomocą żądań zbiorczych
Jednoczesne modyfikowanie uprawnień do tego samego pliku, folderu lub dysku współdzielonego nie jest obsługiwane. To ograniczenie dotyczy wszystkich operacji zmieniających (takich jak aktualizacja lub usuwanie), niezależnie od tego, czy modyfikujesz uprawnienia tego samego czy różnych odbiorców, oraz od tego, czy żądania pochodzą z jednej aplikacji czy od wielu użytkowników.
Dysk ocenia i aktualizuje uprawnienia do elementu jako pojedynczą listę ACL. Jednoczesne operacje powodują wyścig, w którym „wygrywa ostatni zapis”, co może po cichu zastąpić zmiany uprawnień lub wywołać błędy sharingRateLimitExceeded.
Aby uniknąć konfliktów, wprowadzaj zmiany uprawnień dotyczące tego samego elementu sekwencyjnie lub używaj żądań zbiorczych, aby modyfikować wiele uprawnień w ramach jednego żądania.
Poniżej znajdziesz przykład zbiorczej modyfikacji uprawnień za pomocą biblioteki klienta.
Java
Python
Node.js
PHP
.NET
Usuwanie uprawnień
Aby cofnąć dostęp do pliku lub folderu, wywołaj metodę
delete w zasobie
permissions z parametrami ścieżki fileId i permissionId.
Nie można bezpośrednio cofnąć odziedziczonych uprawnień dotyczących elementów podrzędnych. Zamiast tego zaktualizuj lub usuń uprawnienia w folderze nadrzędnym (albo użyj ustawienia ograniczonego dostępu).
Pamiętaj, że usunięcie dostępu użytkownika do elementu nadrzędnego powoduje tylko cofnięcie uprawnień odziedziczonych po tym elemencie. Jeśli użytkownik otrzymał też uprawnienia bezpośrednie do elementu podrzędnego, zachowa do niego dostęp. Aby potwierdzić usunięcie uprawnienia, wywołaj funkcję list z parametrem fileId.
Ustaw datę wygaśnięcia
Aby przyznać tymczasowy dostęp do pliku lub folderu, ustaw pole
expirationTime (data i godzina w formacie RFC 3339) podczas wywoływania metod create lub update.
Czasy wygaśnięcia podlegają tym ograniczeniom:
- Można go ustawić tylko w przypadku uprawnień
userigroup(niedomainanianyone). - Czas musi przypadać w przyszłości, maksymalnie za rok.
- W przypadku folderów dostęp tymczasowy jest obsługiwany tylko w przypadku roli
reader.
Powiązane artykuły
- Zarządzanie oczekującymi propozycjami dostępu
- Zarządzanie folderami z ograniczonym i szerokim dostępem
- Przenoszenie własności pliku
- Ochrona treści pliku
- Uzyskiwanie dostępu do plików na Dysku udostępnionych za pomocą linku przy użyciu kluczy zasobów
- Role i uprawnienia