Jeder Google Drive-Datei, jedem Google Drive-Ordner und jeder geteilten Ablage sind permissions
-Ressourcen zugeordnet. Jede Ressource gibt die Berechtigung für eine bestimmte type
(user
, group
, domain
, anyone
) und role
(owner
, organizer
, fileOrganizer
, writer
, commenter
, reader
) an. Eine Datei kann beispielsweise eine Berechtigung haben, die einem bestimmten Nutzer (type=user
) Lesezugriff (role=reader
) gewährt, während eine andere Berechtigung Mitgliedern einer bestimmten Gruppe (type=group
) die Möglichkeit gibt, einer Datei Kommentare hinzuzufügen (role=commenter
).
Eine vollständige Liste der Rollen und der jeweils zulässigen Vorgänge finden Sie unter Rollen und Berechtigungen.
Funktionsweise von Berechtigungen
Berechtigungslisten für einen Ordner werden nach unten weitergegeben. Alle untergeordneten Dateien und Ordner übernehmen Berechtigungen vom übergeordneten Element. Wenn Berechtigungen oder die Hierarchie geändert werden, erfolgt die Weitergabe rekursiv durch alle verschachtelten Ordner. Wenn sich beispielsweise eine Datei in einem Ordner befindet und dieser Ordner dann in einen anderen Ordner verschoben wird, werden die Berechtigungen für den neuen Ordner auf die Datei übertragen. Wenn dem Nutzer der Datei durch den neuen Ordner eine neue Rolle zugewiesen wird, z. B. „Mitbearbeiter“, wird seine alte Rolle überschrieben.
Wenn eine Datei hingegen role=writer
von einem Ordner erbt und in einen anderen Ordner verschoben wird, der die Rolle „Leser“ bietet, erbt die Datei nun role=reader
.
Übernommene Berechtigungen können nicht aus einer Datei oder einem Ordner in einer geteilten Ablage entfernt werden. Stattdessen müssen diese Berechtigungen für das direkte oder indirekte übergeordnete Element angepasst werden, von dem sie übernommen wurden. Übernommene Berechtigungen können für Elemente unter „Meine Ablage“ oder „Für mich freigegeben“ entfernt werden.
Umgekehrt können übernommene Berechtigungen für eine Datei oder einen Ordner in „Meine Ablage“ überschrieben werden. Wenn eine Datei also role=writer
von einem „Eigene Dateien“-Ordner erbt, können Sie für die Datei role=reader
festlegen, um die Berechtigungsstufe zu senken.
Dateifunktionen
Die Ressource permissions
bestimmt nicht, ob der aktuelle Nutzer Aktionen für eine Datei oder einen Ordner ausführen kann.
Stattdessen enthält die files
-Ressource eine Sammlung von booleschen capabilities
-Feldern, die angeben, ob eine Aktion für eine Datei oder einen Ordner ausgeführt werden kann. Die Google Drive API legt diese Felder basierend auf der Berechtigungsressource des aktuellen Nutzers fest, die der Datei oder dem Ordner zugeordnet ist.
Wenn sich Alex beispielsweise in Ihrer App anmeldet und versucht, eine Datei freizugeben, wird die Rolle von Alex auf Berechtigungen für die Datei geprüft. Wenn die Rolle es dem Nutzer erlaubt, eine Datei freizugeben, werden die capabilities
für die Datei, z. B. canShare
, entsprechend der Rolle ausgefüllt. Wenn Alex die Datei freigeben möchte, prüft Ihre App die capabilities
, um sicherzustellen, dass canShare
auf true
festgelegt ist.
Ein Beispiel für das Abrufen der Datei capabilities
finden Sie unter Dateifunktionen abrufen.
Dateifunktionen abrufen
Wenn Ihre App eine Datei öffnet, sollte sie die Funktionen der Datei prüfen und die Benutzeroberfläche entsprechend den Berechtigungen des aktuellen Nutzers rendern. Wenn der Nutzer beispielsweise nicht die Funktion canComment
für die Datei hat, sollte die Möglichkeit zum Kommentieren in der Benutzeroberfläche deaktiviert sein.
Rufen Sie zum Prüfen der Funktionen die Methode get()
für die Ressource files
mit dem Pfadparameter fileId
und dem Parameter fields
auf, der auf das Feld capabilities
gesetzt ist. Weitere Informationen zum Zurückgeben von Feldern mit dem Parameter fields
finden Sie unter Bestimmte Felder zurückgeben.
Das folgende Codebeispiel zeigt, wie Nutzerberechtigungen überprüft werden. In der Antwort wird eine Liste der Funktionen zurückgegeben, die der Nutzer für die Datei hat. Jede Funktion entspricht einer detaillierten Aktion, die ein Nutzer ausführen kann. Einige Felder werden nur für Elemente in geteilten Ablagen ausgefüllt.
Anfrage
GET https://www.googleapis.com/drive/v3/files/FILE_ID
?fields=capabilities
Antwort
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeItemDownloadRestriction": true, "canChangeSecurityUpdateEnabled": false, "canChangeViewersCanCopyContent": true, "canComment": true, "canCopy": true, "canDelete": true, "canDisableInheritedPermissions": false, "canDownload": true, "canEdit": true, "canEnableInheritedPermissions": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyEditorContentRestriction": true, "canModifyOwnerContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemIntoTeamDrive": true, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveContentRestriction": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
Szenarien für die Freigabe von Drive-Ressourcen
Es gibt fünf verschiedene Arten von Freigabeszenarien:
Wenn ein Nutzer eine Datei in „Meine Ablage“ freigeben möchte, muss er
role=writer
oderrole=owner
haben.Wenn der boolesche Wert
writersCanShare
für die Datei auffalse
gesetzt ist, muss der Nutzerrole=owner
haben.Wenn der Nutzer mit
role=writer
temporären Zugriff hat, der durch ein Ablaufdatum und eine Ablaufzeit geregelt wird, kann er die Datei nicht freigeben. Weitere Informationen finden Sie unter Ablaufdatum festlegen, um den Dateizugriff einzuschränken.
Wenn ein Nutzer einen Ordner in „Meine Ablage“ freigeben möchte, muss er
role=writer
oderrole=owner
haben.Wenn der boolesche Wert
writersCanShare
für die Datei auffalse
gesetzt ist, muss der Nutzer die restriktivere Berechtigungrole=owner
haben.Temporärer Zugriff (mit Ablaufdatum und ‑uhrzeit) ist für Ordner in „Meine Ablage“ mit
role=writer
nicht zulässig. Weitere Informationen finden Sie unter Ablaufdatum für den Dateizugriff festlegen.
Wenn ein Nutzer eine Datei in einer geteilten Ablage freigeben möchte, muss er
role=writer
,role=fileOrganizer
oderrole=organizer
haben.- Die Einstellung
writersCanShare
gilt nicht für Elemente in geteilten Ablagen. Es wird so behandelt, als wäre es immer auftrue
festgelegt.
- Die Einstellung
Wenn ein Nutzer einen Ordner in einer geteilten Ablage freigeben möchte, muss er
role=organizer
haben.- Wenn die
sharingFoldersRequiresOrganizerPermission
-Einschränkung für eine geteilte Ablage auffalse
festgelegt ist, können Nutzer mitrole=fileOrganizer
Ordner in dieser geteilten Ablage freigeben.
- Wenn die
Um die Mitgliedschaft in geteilten Ablagen zu verwalten, muss der Nutzer
role=organizer
haben. Nur Nutzer und Gruppen können Mitglieder von geteilten Ablagen sein.
Berechtigung erstellen
Die folgenden beiden Felder sind beim Erstellen einer Berechtigung erforderlich:
type
: Dietype
gibt den Berechtigungsbereich an (user
,group
,domain
oderanyone
). Eine Berechtigung mittype=user
gilt für einen bestimmten Nutzer, während eine Berechtigung mittype=domain
für alle Nutzer in einer bestimmten Domain gilt.role
: Das Feldrole
gibt die Vorgänge an, die dertype
ausführen kann. Eine Berechtigung mittype=user
undrole=reader
gewährt einem bestimmten Nutzer beispielsweise schreibgeschützten Zugriff auf die Datei oder den Ordner. Mit einer Berechtigung mittype=domain
undrole=commenter
kann jeder in der Domain einer Datei Kommentare hinzufügen. Eine vollständige Liste der Rollen und der jeweils zulässigen Vorgänge finden Sie unter Rollen und Berechtigungen.
Wenn Sie eine Berechtigung erstellen, bei der type=user
oder type=group
, müssen Sie auch eine emailAddress
angeben, um den jeweiligen Nutzer oder die jeweilige Gruppe mit der Berechtigung zu verknüpfen.
Wenn Sie eine Berechtigung erstellen, bei der type=domain
, müssen Sie auch ein domain
angeben, um eine bestimmte Domain mit der Berechtigung zu verknüpfen.
So erstellen Sie eine Berechtigung:
- Verwenden Sie die Methode
create()
mit dem PfadparameterfileId
für die zugehörige Datei oder den zugehörigen Ordner. - Geben Sie im Anfragetext die Parameter
type
undrole
an. - Wenn
type=user
odertype=group
, geben Sie einemailAddress
an. Geben Sie beitype=domain
einendomain
an.
Das folgende Codebeispiel zeigt, wie eine Berechtigung erstellt wird. Die Antwort gibt eine Instanz einer Permission
-Ressource zurück, einschließlich der zugewiesenen permissionId
.
Anfrage
POST https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
{ "requests": [ { "type": "user", "role": "commenter", "emailAddress": "alex@altostrat.com" } ] }
Antwort
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "commenter"
}
Zielgruppen verwenden
Zielgruppen sind Personengruppen, z. B. Abteilungen oder Teams, die Sie Nutzern zur Freigabe von Elementen empfehlen können. Sie können Nutzer dazu anhalten, Elemente für bestimmte Personen oder Gruppen und nicht für die gesamte Organisation freizugeben. Mit Zielgruppen können Sie die Sicherheit und den Schutz Ihrer Daten verbessern und Nutzern das Teilen von Inhalten erleichtern. Weitere Informationen finden Sie unter Zielgruppen.
So verwenden Sie Zielgruppen:
Gehen Sie in der Admin-Konsole zum Dreistrich-Menü > Verzeichnis > Zielgruppen.
Für diese Aufgabe müssen Sie mit einem Konto mit Super Admin-Berechtigungen angemeldet sein.
Klicken Sie in der Liste der Zielgruppen auf den Namen der Zielgruppe. Informationen zum Erstellen einer Zielgruppe finden Sie unter Zielgruppe erstellen.
Kopieren Sie die eindeutige ID aus der Zielgruppen-URL:
https://admin.google.com/ac/targetaudiences/ID
.Erstellen Sie eine Berechtigung mit
type=domain
und legen Sie das Felddomain
aufID.audience.googledomains.com
fest.
Informationen dazu, wie Nutzer mit Zielgruppen interagieren, finden Sie unter Nutzerfreundlichkeit beim Teilen von Links.
Alle Berechtigungen auflisten
Verwenden Sie die Methode list()
für die Ressource permissions
, um alle Berechtigungen für eine Datei, einen Ordner oder eine geteilte Ablage abzurufen.
Das folgende Codebeispiel zeigt, wie Sie alle Berechtigungen abrufen. Die Antwort enthält eine Liste der Berechtigungen.
Anfrage
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
Antwort
{
"kind": "drive#permissionList",
"permissions": [
{
"id": "PERMISSION_ID
",
"type": "user",
"kind": "drive#permission",
"role": "commenter"
}
]
}
Berechtigungen aktualisieren
Wenn Sie die Berechtigungen für eine Datei oder einen Ordner aktualisieren möchten, können Sie die zugewiesene Rolle ändern. Weitere Informationen zum Ermitteln der Rollenquelle finden Sie unter Rollenquelle ermitteln.
Rufen Sie die Methode
update()
für die Ressourcepermissions
auf. Legen Sie den PfadparameterpermissionId
auf die zu ändernde Berechtigung und den PfadparameterfileId
auf die zugehörige Datei, den zugehörigen Ordner oder die zugehörige geteilte Ablage fest. Verwenden Sie die Methodelist()
für die Ressourcepermissions
mit dem PfadparameterfileId
, um diepermissionId
zu finden.Geben Sie in der Anfrage die neue
role
an.
Sie können Berechtigungen für einzelne Dateien oder Ordner in einer geteilten Ablage gewähren, auch wenn der Nutzer oder die Gruppe bereits Mitglied ist. Beispiel: Alex hat role=commenter
als Teil seiner Mitgliedschaft in einer geteilten Ablage. Ihre App kann jedoch Alex
role=writer
für eine Datei in einer geteilten Ablage gewähren. Da die neue Rolle in diesem Fall großzügiger ist als die Rolle, die durch die Mitgliedschaft gewährt wird, wird die neue Berechtigung zur effektiven Rolle für die Datei oder den Ordner.
Im folgenden Codebeispiel wird gezeigt, wie die Berechtigungen für eine Datei oder einen Ordner von „Kommentator“ in „Mitbearbeiter“ geändert werden. Die Antwort gibt eine Instanz einer permissions
-Ressource zurück.
Anfrage
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
{ "requests": [ { "role": "writer" } ] }
Antwort
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "writer"
}
Rollenquelle ermitteln
Wenn Sie die Rolle für eine Datei oder einen Ordner ändern möchten, müssen Sie die Quelle der Rolle kennen. Bei geteilten Ablagen kann die Quelle einer Rolle auf der Mitgliedschaft in der geteilten Ablage, der Rolle für einen Ordner oder der Rolle für eine Datei basieren.
Wenn Sie die Rollenquelle für eine freigegebene Ablage oder Elemente in dieser Ablage ermitteln möchten, rufen Sie die Methode get()
für die Ressource permissions
mit den Pfadparametern fileId
und permissionId
sowie dem Parameter fields
auf, der auf das Feld permissionDetails
festgelegt ist.
Verwenden Sie die Methode list()
für die Ressource permissions
mit dem Pfadparameter fileId
, um die permissionId
zu finden. Wenn Sie das Feld permissionDetails
in der Anfrage list
abrufen möchten, setzen Sie den Parameter fields
auf permissions/permissionDetails
.
In diesem Feld werden alle übernommenen und direkten Dateiberechtigungen für den Nutzer, die Gruppe oder die Domain aufgeführt.
Das folgende Codebeispiel zeigt, wie die Rollenquelle ermittelt wird. Die Antwort gibt die permissionDetails
einer permissions
-Ressource zurück. Das Feld inheritedFrom
enthält die ID des Elements, von dem die Berechtigung übernommen wird.
Anfrage
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
?fields=permissionDetails&supportsAllDrives=true
Antwort
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID
",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}
Mehrere Berechtigungen mit Batchanfragen aktualisieren
Wir empfehlen dringend, Batchanfragen zu verwenden, um mehrere Berechtigungen zu ändern.
Im Folgenden finden Sie ein Beispiel für die Durchführung einer Batch-Berechtigungsänderung mit einer Clientbibliothek.
Java
Python
Node.js
PHP
.NET
Berechtigung löschen
Wenn Sie den Zugriff auf eine Datei oder einen Ordner widerrufen möchten, rufen Sie die Methode delete()
für die Ressource permissions
auf und legen Sie die Pfadparameter fileId
und permissionId
fest, um die Berechtigung zu löschen.
Bei Elementen in „Meine Ablage“ können Sie eine übernommene Berechtigung löschen. Wenn Sie eine übernommene Berechtigung löschen, wird der Zugriff auf das Element und alle untergeordneten Elemente widerrufen.
Für Elemente in einer geteilten Ablage können übernommene Berechtigungen nicht widerrufen werden. Aktualisieren oder löschen Sie stattdessen die Berechtigung für die übergeordnete Datei oder den übergeordneten Ordner.
Mit der Methode delete()
werden auch Berechtigungen gelöscht, die direkt auf eine Datei oder einen Ordner in einer geteilten Ablage angewendet wurden.
Im folgenden Codebeispiel wird gezeigt, wie der Zugriff durch Löschen eines permissionId
widerrufen wird. Wenn der Vorgang erfolgreich ist, ist der Antworttext leer. Verwenden Sie die Methode list()
für die Ressource permissions
mit dem Pfadparameter fileId
, um zu bestätigen, dass die Berechtigung entfernt wurde.
Anfrage
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
Ablaufdatum festlegen, um den Dateizugriff einzuschränken
Wenn Sie mit anderen an einem vertraulichen Projekt arbeiten, möchten Sie möglicherweise nach einer bestimmten Zeit den Zugriff auf bestimmte Dateien in Drive einschränken. Bei Dateien in „Meine Ablage“ können Sie ein Ablaufdatum festlegen, um den Zugriff auf eine Datei einzuschränken oder zu entfernen.
So legen Sie das Ablaufdatum fest:
Verwenden Sie die Methode
create()
für die Ressourcepermissions
und legen Sie das FeldexpirationTime
(zusammen mit den anderen erforderlichen Feldern) fest. Weitere Informationen finden Sie unter Berechtigung erstellen.Verwenden Sie die Methode
update()
für die Ressourcepermissions
und legen Sie das FeldexpirationTime
(zusammen mit den anderen erforderlichen Feldern) fest. Weitere Informationen finden Sie unter Berechtigungen aktualisieren.
Das Feld expirationTime
gibt an, wann die Berechtigung abläuft. Es verwendet das RFC 3339-Datum/Uhrzeit-Format. Für Ablaufzeiten gelten die folgenden Einschränkungen:
- Sie können nur für Nutzer- und Gruppenberechtigungen festgelegt werden.
- Die Zeit muss in der Zukunft liegen.
- Die Zeit darf nicht mehr als ein Jahr in der Zukunft liegen.
Weitere Informationen zum Ablaufdatum finden Sie in den folgenden Artikeln:
Weitere Informationen
- Ausstehende Zugriffsvorschläge verwalten
- Ordner mit eingeschränktem und umfassendem Zugriff verwalten
- Eigentümerschaft für Dateien übertragen
- Dateiinhalte schützen
- Über Ressourcen-Schlüssel auf Dateien in geteilten Ablagen zugreifen, die über Links freigegeben wurden
- Rollen und Berechtigungen