Каждый файл, папка и общий диск Google Drive имеют связанные ресурсы permissions
. Каждый ресурс определяет разрешение для определенного type
( user
, group
, domain
, anyone
) и role
( owner
, organizer
, организатор fileOrganizer
, writer
, commenter
, reader
). Например, файл может иметь разрешение, предоставляющее определенному пользователю ( type=user
) доступ только для чтения ( role=reader
), в то время как другое разрешение предоставляет членам определенной группы ( type=group
) возможность добавлять комментарии к файлу ( role=commenter
).
Полный список ролей и разрешенных каждой из них операций см. в разделе Роли и разрешения .
Как работают разрешения
Списки разрешений для папки распространяются сверху вниз. Все дочерние файлы и папки наследуют разрешения от родительского. Всякий раз, когда разрешения или иерархия изменяются, распространение происходит рекурсивно по всем вложенным папкам. Например, если файл существует в папке, а затем эта папка перемещается в другую папку, разрешения новой папки распространяются на файл. Если новая папка предоставляет пользователю файла новую роль, например «писатель», она переопределяет его старую роль.
И наоборот, если файл наследует role=writer
от папки и перемещается в другую папку, которая предоставляет роль «читатель», файл теперь наследует role=reader
.
Унаследованные разрешения не могут быть удалены из файла или папки на общем диске. Вместо этого эти разрешения должны быть скорректированы на прямом или косвенном родителе, от которого они были унаследованы. Унаследованные разрешения могут быть удалены из элементов в разделе «Мой диск» или «Доступно мне».
И наоборот, унаследованные разрешения могут быть переопределены для файла или папки в Моем диске. Таким образом, если файл наследует role=writer
из папки Моего диска, вы можете установить role=reader
для файла, чтобы понизить его уровень разрешений.
Понять возможности файлов
Ресурс permissions
в конечном итоге не определяет способность текущего пользователя выполнять действия с файлом или папкой. Вместо этого ресурс files
содержит набор полей логических capabilities
, используемых для указания того, можно ли выполнить действие с файлом или папкой. API Google Drive устанавливает эти поля на основе ресурса разрешений текущего пользователя, связанного с файлом или папкой.
Например, когда Алекс входит в ваше приложение и пытается поделиться файлом, роль Алекса проверяется на наличие разрешений на файл. Если роль позволяет им делиться файлом, capabilities
связанные с файлом, такие как canShare
, заполняются относительно роли. Если Алекс хочет поделиться файлом, ваше приложение проверяет capabilities
, чтобы убедиться, что canShare
установлен в true
.
Пример получения capabilities
файла см. в разделе Получение возможностей файла .
Получить возможности файла
Когда ваше приложение открывает файл, оно должно проверить возможности файла и отобразить пользовательский интерфейс, чтобы отразить разрешения текущего пользователя. Например, если у пользователя нет возможности canComment
для файла, возможность комментирования должна быть отключена в пользовательском интерфейсе.
Чтобы проверить возможности, вызовите метод get()
на ресурсе files
с параметром пути fileId
и параметром fields
, установленным в поле capabilities
. Для получения дополнительной информации о возврате полей с использованием параметра fields
см. раздел Возврат определенных полей .
Следующий пример кода показывает, как проверить разрешения пользователя. Ответ возвращает список возможностей, которые пользователь имеет для файла. Каждая возможность соответствует детальному действию, которое может выполнить пользователь. Некоторые поля заполняются только для элементов на общих дисках.
Запрос
GET https://www.googleapis.com/drive/v3/files/FILE_ID
?fields=capabilities
Ответ
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeSecurityUpdateEnabled": false, "canComment": true, "canCopy": true, "canDelete": true, "canDownload": true, "canEdit": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
Сценарии совместного использования ресурсов Диска
Существует пять различных типов сценариев обмена:
Чтобы поделиться файлом в Моем диске, пользователь должен иметь
role=writer
илиrole=owner
.Если логическое значение
writersCanShare
для файла установлено равнымfalse
, пользователь должен иметьrole=owner
.Если пользователь с
role=writer
имеет временный доступ, регулируемый датой и временем истечения срока действия, он не может поделиться файлом. Для получения дополнительной информации см. Установка даты истечения срока действия для ограничения доступа к файлу .
Чтобы предоставить общий доступ к папке в Моем диске, пользователь должен иметь
role=writer
илиrole=owner
.Если логическое значение
writersCanShare
для файла установлено равнымfalse
, пользователь должен иметь более разрешительнуюrole=owner
.Временный доступ (регулируемый датой и временем истечения срока действия) не разрешен для папок My Drive с
role=writer
. Для получения дополнительной информации см. Установка даты истечения срока действия для ограничения доступа к файлам .
Чтобы предоставить общий доступ к файлу на общем диске, пользователь должен иметь
role=writer
,role=fileOrganizer
илиrole=organizer
.- Параметр
writersCanShare
не применяется к элементам на общих дисках. Он рассматривается так, как будто он всегда установлен вtrue
.
- Параметр
Чтобы предоставить общий доступ к папке на общем диске, пользователь должен иметь
role=organizer
.- Если ограничение
sharingFoldersRequiresOrganizerPermission
для общего диска установлено наfalse
, пользователи сrole=fileOrganizer
могут предоставлять общий доступ к папкам на этом общем диске.
- Если ограничение
Для управления членством в общем диске пользователь должен иметь
role=organizer
. Только пользователи и группы могут быть членами общих дисков.
Создать разрешение
При создании разрешения необходимы следующие два поля:
type
:type
определяет область разрешения (user
,group
,domain
илиanyone
). Разрешение сtype=user
применяется к определенному пользователю, тогда как разрешение сtype=domain
применяется ко всем в определенном домене.role
: Полеrole
определяет операции, которые может выполнятьtype
. Например, разрешение сtype=user
иrole=reader
предоставляет определенному пользователю доступ только для чтения к файлу или папке. Или разрешение сtype=domain
иrole=commenter
позволяет всем в домене добавлять комментарии к файлу. Полный список ролей и операций, разрешенных каждой из них, см. в разделе Роли и разрешения .
При создании разрешения, где type=user
или type=group
, необходимо также указать emailAddress
, чтобы связать конкретного пользователя или группу с разрешением.
При создании разрешения, где type=domain
, необходимо также указать domain
, чтобы привязать определенный домен к разрешению.
Чтобы создать разрешение:
- Используйте метод
create()
с параметром путиfileId
для связанного файла или папки. - В теле запроса укажите
type
иrole
. - Если
type=user
илиtype=group
, укажитеemailAddress
. Еслиtype=domain
, укажитеdomain
.
Следующий пример кода показывает, как создать разрешение. Ответ возвращает экземпляр ресурса Permission
, включая назначенный permissionId
.
Запрос
POST https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
{ "requests": [ { "type": "user", "role": "commenter", "emailAddress": "alex@altostrat.com" } ] }
Ответ
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "commenter"
}
Используйте целевую аудиторию
Целевые аудитории — это группы людей, например, отделы или команды, с которыми вы можете рекомендовать пользователям делиться своими элементами. Вы можете поощрять пользователей делиться элементами с более конкретной или ограниченной аудиторией, а не со всей вашей организацией. Целевые аудитории могут помочь вам улучшить безопасность и конфиденциальность ваших данных и упростить для пользователей надлежащий обмен. Для получения дополнительной информации см. О целевых аудиториях .
Для использования целевых аудиторий:
В консоли администратора Google перейдите в > Каталог > Целевые аудитории .
Для выполнения этой задачи вам необходимо войти в систему, используя учетную запись с правами суперадминистратора .
В списке Целевые аудитории щелкните название целевой аудитории. Чтобы создать целевую аудиторию, см. Создание целевой аудитории
Скопируйте уникальный идентификатор из URL целевой аудитории:
https://admin.google.com/ac/targetaudiences/ ID
.Создайте разрешение с
type=domain
и установите для поляdomain
значениеID .audience.googledomains.com
.
Чтобы узнать, как пользователи взаимодействуют с целевой аудиторией, см. раздел Пользовательский опыт при обмене ссылками .
Список всех разрешений
Используйте метод list()
ресурса permissions
, чтобы получить все разрешения для файла, папки или общего диска.
Следующий пример кода показывает, как получить все разрешения. Ответ возвращает список разрешений.
Запрос
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
Ответ
{
"kind": "drive#permissionList",
"permissions": [
{
"id": "PERMISSION_ID
",
"type": "user",
"kind": "drive#permission",
"role": "commenter"
}
]
}
Обновление разрешений
Чтобы обновить разрешения на файл или папку, вы можете изменить назначенную роль. Для получения дополнительной информации о поиске источника роли см. Определение источника роли .
Вызовите метод
update()
на ресурсеpermissions
с параметром путиpermissionId
, установленным на разрешение на изменение, и параметром путиfileId
, установленным на связанный файл, папку или общий диск. Чтобы найтиpermissionId
, используйте методlist()
на ресурсеpermissions
с параметром путиfileId
.В запросе укажите новую
role
.
Вы можете предоставить разрешения на отдельные файлы или папки на общем диске, даже если пользователь или группа уже являются участниками. Например, у Алекса есть role=commenter
как часть его членства на общем диске. Однако ваше приложение может предоставить Алексу role=writer
для файла на общем диске. В этом случае, поскольку новая роль более разрешительная, чем роль, предоставленная через членство, новое разрешение становится эффективной ролью для файла или папки.
Следующий пример кода показывает, как изменить разрешения на файл или папку с комментатора на писателя. Ответ возвращает экземпляр ресурса permissions
.
Запрос
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
{ "requests": [ { "role": "writer" } ] }
Ответ
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "writer"
}
Определить источник роли
Чтобы изменить роль для файла или папки, необходимо знать источник роли. Для общих дисков источник роли может быть основан на членстве в общем диске, роли для папки или роли для файла.
Чтобы определить источник роли для общего диска или элементов на этом диске, вызовите метод get()
для ресурса permissions
с параметрами пути fileId
и permissionId
, а параметр fields
задайте равным полю permissionDetails
.
Чтобы найти permissionId
, используйте метод list()
на ресурсе permissions
с параметром пути fileId
. Чтобы извлечь поле permissionDetails
в запросе list
, установите параметр fields
на permissions/permissionDetails
.
В этом поле перечислены все унаследованные и прямые разрешения на доступ к файлам для пользователя, группы или домена.
Следующий пример кода показывает, как определить источник роли. Ответ возвращает permissionDetails
ресурса permissions
. Поле inheritedFrom
предоставляет идентификатор элемента, от которого наследуется разрешение.
Запрос
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
?fields=permissionDetails&supportsAllDrives=true
Ответ
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID
",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}
Обновление нескольких разрешений с помощью пакетных запросов
Мы настоятельно рекомендуем использовать пакетные запросы для изменения нескольких разрешений.
Ниже приведен пример выполнения пакетного изменения разрешений с помощью клиентской библиотеки.
Ява
Питон
Node.js
PHP
.СЕТЬ
Удалить разрешение
Чтобы отозвать доступ к файлу или папке, вызовите метод delete()
для ресурса permissions
с параметрами fileId
и permissionId
, установленными для удаления разрешения.
Для элементов в "Моем диске" можно удалить унаследованное разрешение. Удаление унаследованного разрешения отменяет доступ к элементу и дочерним элементам, если таковые имеются.
Для элементов на общем диске унаследованные разрешения не могут быть отозваны. Вместо этого обновите или удалите разрешение на родительский файл или папку.
Метод delete()
также используется для удаления разрешений, непосредственно примененных к файлу или папке общего диска.
Следующий пример кода показывает, как отозвать доступ, удалив permissionId
. В случае успеха тело ответа пустое. Чтобы подтвердить удаление разрешения, используйте метод list()
на ресурсе permissions
с параметром пути fileId
.
Запрос
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
Установите дату истечения срока действия, чтобы ограничить доступ к файлу
Когда вы работаете с людьми над важным проектом, вы можете захотеть ограничить их доступ к определенным файлам на Диске после определенного периода времени. Для файлов на Моем Диске вы можете установить дату истечения срока действия, чтобы ограничить или удалить доступ к этому файлу.
Чтобы установить дату истечения срока действия:
Используйте метод
create()
на ресурсеpermissions
и установите полеexpirationTime
(вместе с другими обязательными полями). Для получения дополнительной информации см. Создание разрешения .Используйте метод
update()
на ресурсеpermissions
и установите полеexpirationTime
(вместе с другими обязательными полями). Для получения дополнительной информации см. Обновление разрешений .
Поле expirationTime
обозначает, когда истекает срок действия разрешения, используя дату-время RFC 3339. Срок действия имеет следующие ограничения:
- Их можно устанавливать только на уровне разрешений пользователей и групп.
- Время должно быть в будущем.
- Время не может быть больше, чем через год.
Более подробную информацию о сроке годности можно найти в следующих статьях:
Похожие темы
- Управление ожидающими рассмотрения предложениями о доступе
- Управление папками с ограниченным и расширенным доступом
- Передача права собственности на файл
- Защитить содержимое файла
- Доступ к файлам на диске, размещенном по ссылке, с помощью ключей ресурсов
- Роли и разрешения