С каждым файлом, папкой и общим диском Google Диска связаны ресурсы 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 Диска устанавливает эти поля на основе ресурса разрешений текущего пользователя, связанного с файлом или папкой.
Например, когда Алекс входит в ваше приложение и пытается поделиться файлом, проверяется наличие у его роли разрешений на доступ к файлу. Если роль позволяет ему делиться файлом, соответствующие 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, "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 } }
Сценарии совместного использования ресурсов Диска
Существует пять различных типов сценариев обмена:
Чтобы поделиться файлом в разделе «Мой диск», пользователь должен иметь
role=writer
илиrole=owner
.Если логическое значение
writersCanShare
для файла равноfalse
, пользователь должен иметьrole=owner
.Если у пользователя с
role=writer
есть временный доступ, ограниченный датой и временем истечения срока действия, он не сможет предоставить общий доступ к файлу. Подробнее см. в разделе Установка даты истечения срока действия для ограничения доступа к файлу .
Чтобы предоставить общий доступ к папке в разделе «Мой диск», пользователь должен иметь
role=writer
илиrole=owner
.Если для файла логическое значение
writersCanShare
равноfalse
, пользователь должен иметь более разрешительнуюrole=owner
.Временный доступ (с указанием даты и времени истечения срока действия) не разрешён для папок «Мой диск» с
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
с параметром path 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
с параметром path fileId
.
Запрос
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
Установите дату истечения срока действия, чтобы ограничить доступ к файлу.
Работая с людьми над конфиденциальным проектом, вы можете ограничить их доступ к определённым файлам на Диске по истечении определённого периода времени. Для файлов в разделе «Мой диск» вы можете установить срок действия, чтобы ограничить или полностью запретить доступ к ним.
Чтобы установить дату истечения срока действия:
Используйте метод
create()
ресурсаpermissions
и задайте полеexpirationTime
(вместе с другими обязательными полями). Подробнее см. в разделе Создание разрешения .Используйте метод
update()
ресурсаpermissions
и задайте полеexpirationTime
(вместе с другими обязательными полями). Подробнее см. в разделе Обновление разрешений .
Поле expirationTime
указывает дату истечения срока действия разрешения, используя дату и время RFC 3339. Срок действия имеет следующие ограничения:
- Их можно устанавливать только на уровне разрешений пользователя и группы.
- Время должно быть в будущем.
- Время не может быть больше, чем через год.
Более подробную информацию о сроке действия можно найти в следующих статьях:
Похожие темы
- Управление ожидающими предложениями доступа
- Управление папками с ограниченным и расширенным доступом
- Передача права собственности на файл
- Защитить содержимое файла
- Доступ к файлам на общем диске по ссылке с помощью ключей ресурсов
- Роли и разрешения