Cada archivo, carpeta y unidad compartida de Google Drive tiene recursos permissions
asociados. Cada recurso identifica el permiso para un type
(user
, group
, domain
, anyone
) y role
(owner
, organizer
, fileOrganizer
, writer
, commenter
, reader
) específicos. Por ejemplo, un archivo puede tener un permiso que otorga a un usuario específico (type=user
) acceso de solo lectura (role=reader
), mientras que otro permiso otorga a los miembros de un grupo específico (type=group
) la capacidad de agregar comentarios a un archivo (role=commenter
).
Para obtener una lista completa de los roles y las operaciones que permite cada uno, consulta Roles y permisos.
Cómo funcionan los permisos
Las listas de permisos de una carpeta se propagan hacia abajo. Todos los archivos y carpetas secundarios héritan los permisos de la carpeta superior. Cada vez que se cambian los permisos o la jerarquía, la propagación se realiza de forma recursiva a través de todas las carpetas anidadas. Por ejemplo, si un archivo existe en una carpeta y, luego, esa carpeta se mueve dentro de otra, los permisos de la carpeta nueva se propagan al archivo. Si la carpeta nueva le otorga al usuario del archivo un rol nuevo, como "escritor", anula su rol anterior.
Por el contrario, si un archivo hereda role=writer
de una carpeta y se mueve a otra carpeta que proporciona un rol de “lector”, el archivo ahora hereda role=reader
.
No se pueden quitar los permisos heredados de un archivo o una carpeta en una unidad compartida. En su lugar, estos permisos deben ajustarse en el elemento superior directo o indirecto del que se heredaron. Los permisos heredados se pueden quitar de los elementos de "Mi unidad" o "Compartidos conmigo".
Por el contrario, los permisos heredados se pueden anular en un archivo o una carpeta de
Mi unidad. Por lo tanto, si un archivo hereda role=writer
de una carpeta de Mi Drive, puedes establecer role=reader
en el archivo para disminuir su nivel de permiso.
Comprende las capacidades de los archivos
En última instancia, el recurso permissions
no determina la capacidad del usuario actual para realizar acciones en un archivo o una carpeta.
En su lugar, el recurso files
contiene una colección
de campos capabilities
booleanos que se usan para indicar si se puede realizar una acción
en un archivo o una carpeta. La API de Google Drive establece estos campos en función del recurso de permisos del usuario actual asociado con el archivo o la carpeta.
Por ejemplo, cuando Alex accede a tu app e intenta compartir un archivo, se verifica su rol para ver si tiene permisos en el archivo. Si el rol le permite compartir un archivo, los capabilities
relacionados con el archivo, como canShare
, se completan en función del rol. Si Alex quiere compartir el archivo, tu app verifica el capabilities
para asegurarse de que canShare
esté configurado como true
.
Para ver un ejemplo de cómo recuperar el archivo capabilities
, consulta Cómo obtener las capacidades de un archivo.
Cómo obtener las capacidades de los archivos
Cuando tu app abre un archivo, debe verificar sus capacidades y renderizar la IU para reflejar los permisos del usuario actual. Por ejemplo, si el usuario no tiene una capability canComment
en el archivo, la capacidad de comentar debe estar inhabilitada en la IU.
Para verificar las funciones, llama al método get()
en el recurso files
con el parámetro de ruta fileId
y el parámetro fields
configurado en el campo capabilities
. Para obtener más información sobre cómo mostrar campos con el parámetro fields
, consulta Cómo mostrar campos específicos.
Mostrar un ejemplo
En la siguiente muestra de código, se muestra cómo verificar los permisos del usuario. La respuesta muestra una lista de las capacidades que el usuario tiene en el archivo. Cada capability corresponde a una acción detallada que puede realizar un usuario. Algunos campos solo se completan para los elementos de las unidades compartidas.
Solicitud
GET https://www.googleapis.com/drive/v3/files/FILE_ID
?fields=capabilities
Respuesta
{ "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 } }
Situaciones para compartir recursos de Drive
Existen cinco tipos diferentes de situaciones de uso compartido:
Para compartir un archivo en Mi unidad, el usuario debe tener
role=writer
orole=owner
.Si el valor booleano
writersCanShare
está configurado comofalse
para el archivo, el usuario debe tenerrole=owner
.Si el usuario con
role=writer
tiene acceso temporal regido por una fecha y hora de vencimiento, no puede compartir el archivo. Para obtener más información, consulta Cómo establecer una fecha de vencimiento para limitar el acceso a los archivos.
Para compartir una carpeta en Mi unidad, el usuario debe tener
role=writer
orole=owner
.Si el valor booleano
writersCanShare
se establece enfalse
para el archivo, el usuario debe tener elrole=owner
más permisivo.No se permite el acceso temporal (que se rige por una fecha y hora de vencimiento) en las carpetas de Mi unidad con
role=writer
. Para obtener más información, consulta Cómo establecer una fecha de vencimiento para limitar el acceso a los archivos.
Para compartir un archivo en una unidad compartida, el usuario debe tener
role=writer
,role=fileOrganizer
orole=organizer
.- La configuración de
writersCanShare
no se aplica a los elementos de las unidades compartidas. Se trata como si siempre estuviera configurado entrue
.
- La configuración de
Para compartir una carpeta en una unidad compartida, el usuario debe tener
role=organizer
.- Si la restricción
sharingFoldersRequiresOrganizerPermission
en una unidad compartida se establece enfalse
, los usuarios conrole=fileOrganizer
pueden compartir carpetas en esa unidad.
- Si la restricción
Para administrar la membresía de la unidad compartida, el usuario debe tener
role=organizer
. Solo los usuarios y los grupos pueden ser miembros de las unidades compartidas.
Cómo crear un permiso
Los siguientes dos campos son necesarios cuando se crea un permiso:
type
:type
identifica el permiso (user
,group
,domain
oanyone
). Un permiso contype=user
se aplica a un usuario específico, mientras que un permiso contype=domain
se aplica a todos los usuarios de un dominio específico.role
: El camporole
identifica las operaciones que puede realizartype
. Por ejemplo, un permiso contype=user
yrole=reader
otorga a un usuario específico acceso de solo lectura al archivo o la carpeta. También, un permiso contype=domain
yrole=commenter
permite que todas las personas del dominio agreguen comentarios a un archivo. Para obtener una lista completa de los roles y las operaciones que permite cada uno, consulta Roles y permisos.
Cuando creas un permiso en el que se usa type=user
o type=group
, también debes proporcionar un emailAddress
para vincular el usuario o el grupo específico al permiso.
Cuando creas un permiso en el que type=domain
, también debes proporcionar un domain
para vincular un dominio específico al permiso.
Para crear un permiso, sigue estos pasos:
- Usa el método
create()
con el parámetro de rutafileId
para el archivo o la carpeta asociados. - En el cuerpo de la solicitud, especifica
type
yrole
. - Si es
type=user
otype=group
, proporciona unemailAddress
. Si estype=domain
, proporciona undomain
.
Mostrar un ejemplo
En el siguiente ejemplo de código, se muestra cómo crear un permiso. La respuesta muestra una instancia de un recurso Permission
, incluido el permissionId
asignado.
Solicitud
POST https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
{ "requests": [ { "type": "user", "role": "commenter", "emailAddress": "alex@altostrat.com" } ] }
Respuesta
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "commenter"
}
Usa públicos objetivo
Los usuarios objetivo son grupos de personas, como departamentos o equipos, que puedes recomendar a los usuarios para que compartan sus elementos con ellos. Puedes invitar a los usuarios a compartir elementos con un público más limitado o específico en lugar de toda la organización. Los usuarios objetivo pueden ayudarte a mejorar la seguridad y la privacidad de tus datos, y facilitar que los usuarios los compartan de forma adecuada. Para obtener más información, consulta Acerca de los públicos objetivo.
Para usar los públicos objetivo, sigue estos pasos:
En la Consola del administrador de Google, ve a Menú > Directorio > Públicos objetivo.
Para realizar esta tarea, debes acceder con una cuenta con privilegios de administrador avanzado.
En la lista de públicos objetivo, haz clic en el nombre del público objetivo. Para crear un público objetivo, consulta Cómo crear un público objetivo.
Copia el ID único de la URL del público objetivo:
https://admin.google.com/ac/targetaudiences/ID
.Crea un permiso con
type=domain
y establece el campodomain
enID.audience.googledomains.com
.
Para ver cómo interactúan los usuarios con los públicos objetivo, consulta Experiencia del usuario para compartir vínculos.
Cómo ver todos los permisos
Usa el método list()
en el recurso permissions
para recuperar todos los permisos de un archivo, una carpeta o una unidad compartida.
Mostrar un ejemplo
En la siguiente muestra de código, se muestra cómo obtener todos los permisos. La respuesta muestra una lista de permisos.
Solicitud
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
Respuesta
{
"kind": "drive#permissionList",
"permissions": [
{
"id": "PERMISSION_ID
",
"type": "user",
"kind": "drive#permission",
"role": "commenter"
}
]
}
Actualizar permisos
Para actualizar los permisos de un archivo o carpeta, puedes cambiar el rol asignado. Para obtener más información sobre cómo encontrar la fuente de roles, consulta Cómo determinar la fuente de roles.
Llama al método
update()
en el recursopermissions
con el parámetro de ruta de accesopermissionId
establecido en el permiso de cambio y el parámetro de ruta de accesofileId
establecido en el archivo, la carpeta o la unidad compartida asociada. Para encontrar elpermissionId
, usa el métodolist()
en el recursopermissions
con el parámetro de rutafileId
.En la solicitud, identifica el nuevo
role
.
Puedes otorgar permisos a archivos o carpetas individuales en una unidad compartida, incluso si el usuario o el grupo ya son miembros. Por ejemplo, Alex tiene role=commenter
como parte de su membresía a una unidad compartida. Sin embargo, tu app puede otorgarle a Alex role=writer
para un archivo en una unidad compartida. En este caso, como el rol nuevo es más permisivo que el que se otorga a través de la membresía, el permiso nuevo se convierte en el rol efectivo del archivo o la carpeta.
Mostrar un ejemplo
En la siguiente muestra de código, se muestra cómo cambiar los permisos de un archivo o una carpeta de comentarista a escritor. La respuesta muestra una instancia de un recurso permissions
.
Solicitud
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
{ "requests": [ { "role": "writer" } ] }
Respuesta
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "writer"
}
Determina la fuente del rol
Para cambiar el rol de un archivo o una carpeta, debes conocer la fuente del rol. En el caso de las unidades compartidas, la fuente de un rol puede basarse en la membresía a la unidad compartida, el rol en una carpeta o el rol en un archivo.
Para determinar la fuente de roles de una unidad compartida o los elementos dentro de ella, llama al método get()
en el recurso permissions
con los parámetros de ruta fileId
y permissionId
, y el parámetro fields
configurado en el campo permissionDetails
.
Para encontrar el permissionId
, usa el método list()
en el recurso permissions
con el parámetro de ruta fileId
. Para recuperar el campo permissionDetails
en la solicitud list
, establece el parámetro fields
en permissions/permissionDetails
.
En este campo, se enumeran todos los permisos de archivo heredados y directos del usuario, el grupo o el dominio.
Mostrar un ejemplo
En la siguiente muestra de código, se muestra cómo determinar la fuente del rol. La respuesta muestra el permissionDetails
de un recurso permissions
. El campo inheritedFrom
proporciona el ID del elemento del que se hereda el permiso.
Solicitud
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
?fields=permissionDetails&supportsAllDrives=true
Respuesta
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID
",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}
Cómo actualizar varios permisos con solicitudes por lotes
Te recomendamos que uses solicitudes por lotes para modificar varios permisos.
El siguiente es un ejemplo de cómo realizar una modificación de permisos por lotes con una biblioteca cliente.
Java
Python
Node.js
PHP
.NET
Cómo borrar un permiso
Para revocar el acceso a un archivo o una carpeta, llama al método delete()
en el recurso permissions
con los parámetros de ruta de acceso fileId
y permissionId
configurados para borrar el permiso.
En el caso de los elementos de "Mi unidad", es posible borrar un permiso heredado. Si borras un permiso heredado, se revocará el acceso al elemento y a los elementos secundarios, si los hay.
En el caso de los elementos de una unidad compartida, no se pueden revocar los permisos heredados. En su lugar, actualiza o borra el permiso en el archivo o la carpeta superior.
El método delete()
también se usa para borrar los permisos aplicados directamente a un archivo o una carpeta de Drive compartidos.
Mostrar un ejemplo
En la siguiente muestra de código, se muestra cómo revocar el acceso borrando un permissionId
. Si se ejecuta correctamente, el cuerpo de la respuesta está vacío. Para confirmar que se quitó el permiso, usa el método list()
en el recurso permissions
con el parámetro de ruta fileId
.
Solicitud
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
Cómo establecer una fecha de vencimiento para limitar el acceso a los archivos
Cuando trabajas con otras personas en un proyecto sensible, es posible que quieras restringir su acceso a ciertos archivos de Drive después de un período determinado. En el caso de los archivos de Mi unidad, puedes establecer una fecha de vencimiento para limitar o quitar el acceso a ellos.
Para establecer la fecha de vencimiento, sigue estos pasos:
Usa el método
create()
en el recursopermissions
y establece el campoexpirationTime
(junto con los otros campos obligatorios). Para obtener más información, consulta Cómo crear un permiso.Usa el método
update()
en el recursopermissions
y establece el campoexpirationTime
(junto con los otros campos obligatorios). Para obtener más información, consulta Actualiza los permisos.
El campo expirationTime
indica cuándo vence el permiso con la fecha y hora de RFC 3339. Los tiempos de vencimiento tienen las siguientes restricciones:
- Solo se pueden configurar en los permisos de usuarios y grupos.
- La hora debe ser posterior a la actual.
- La hora no puede ser superior a un año en el futuro.
Para obtener más información sobre la fecha de vencimiento, consulta los siguientes artículos:
Temas relacionados
- Administra las propuestas de acceso pendientes
- Cómo transferir la propiedad de un archivo
- Cómo proteger el contenido de los archivos
- Cómo acceder a archivos de unidades compartidas con vínculos mediante claves de recursos
- Funciones y permisos