Cada archivo, carpeta y unidad compartida de Google Drive tiene recursos de permisos asociados. Cada recurso identifica el permiso para un type
(usuario, grupo, dominio, cualquiera) y role
específicos, como "comentarista" o "lector". 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 las funciones y las operaciones que permite cada una, consulta Funciones y permisos.
Situaciones en las que se comparten 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
se configura 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 podrá compartir el archivo. Si quieres obtener más información, consulta Establece 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 configura comoFalse
para el archivo, el usuario debe tener elrole=owner
más permisivo.No se permite el acceso temporal (regido por una fecha y hora de vencimiento) en las carpetas de Mi unidad con
role=writer
. Para obtener más información, consulta Establece 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
.- El parámetro de configuración
writersCanShare
no se aplica a los elementos de las unidades compartidas. Se considera como si siempre estuviera establecido enTrue
.
- El parámetro de configuración
Para compartir una carpeta en una unidad compartida, el usuario debe tener
role=organizer
.- Si la restricción
sharingFoldersRequiresOrganizerPermission
de una unidad compartida se configura comoFalse
, los usuarios conrole=fileOrganizer
podrán compartir carpetas en esa unidad compartida.
- 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 unidades compartidas.
Establece una fecha de vencimiento para limitar el acceso al archivo
Cuando trabajes con personas en un proyecto sensible, es posible que desees restringir su acceso a ciertos archivos de Drive después de un período determinado. Para los archivos de Mi unidad, puedes establecer una fecha de vencimiento a fin de limitar o quitar el acceso a ese archivo.
Para establecer la fecha de vencimiento, haz lo siguiente:
- Usa el método
permissions.create
y configura el campopermissions.expirationTime
(junto con los otros campos obligatorios). Para obtener más información, consulta Cómo crear un permiso. - Usa el método
permissions.update
y configura el campopermissions.expirationTime
(junto con los otros campos obligatorios). Para obtener más información, consulta Cómo cambiar los permisos.
El campo expirationTime
denota cuándo vence el permiso con la fecha y hora de RFC 3339. Las fechas de vencimiento tienen las siguientes restricciones:
- Solo se pueden configurar en los permisos de usuario y grupo.
- La hora debe ser futura.
- La fecha no puede ser superior a un año a partir de la fecha actual.
Para obtener más información sobre las fechas de vencimiento, consulta los siguientes artículos:
Propagación de permisos
Las listas de permisos de una carpeta se propagan hacia abajo, y todos los archivos y carpetas secundarios heredan los permisos del superior. Cada vez que se cambian los permisos o la jerarquía, la propagación se produce de manera recursiva a través de todas las carpetas anidadas. Por ejemplo, si existe un archivo en una carpeta que luego se mueve dentro de otra carpeta, los permisos de la carpeta nueva se propagan al archivo. Si la carpeta nueva otorga al usuario del archivo una función nueva, como “escritor”, se anula la anterior.
Por el contrario, si un archivo hereda role=writer
de una carpeta y se mueve a otra carpeta que proporciona la función de "lector", 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 se deben ajustar en el superior directo o indirecto desde el 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 Mi unidad, puedes configurar role=reader
en el archivo para reducir su nivel de permiso.
Capacidades
En última instancia, el recurso Permissions no determina la capacidad del usuario actual para realizar acciones en un archivo o una carpeta.
En cambio, un recurso Files contiene una colección de campos booleanos capabilities
que se usan para indicar si se puede realizar una acción en un archivo o una carpeta. La API de Google Drive configura estos campos según el 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 el rol de Alex para obtener los permisos correspondientes. Si la función les permite compartir un archivo, los capabilities
relacionados con el archivo, como canShare
, se completan en relación con la función. Si Alex quiere compartir el archivo, tu app verifica capabilities
para asegurarse de que canShare
esté configurado como true
.
Para ver un ejemplo de cómo recuperar el archivo capabilities
, consulta Cómo verificar los permisos del usuario.
Cómo crear un permiso
Los dos campos siguientes son necesarios cuando se crea un permiso:
type
:type
identifica el alcance del 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 en un dominio específico.role
: El camporole
identifica las operaciones quetype
puede realizar. Por ejemplo, un permiso contype=user
yrole=reader
otorga a un usuario específico acceso de solo lectura al archivo o la carpeta. O bien, un permiso contype=domain
yrole=commenter
permite que todos los miembros del dominio agreguen comentarios a un archivo. Para obtener una lista completa de las funciones y las operaciones que permite cada una, consulta Funciones y permisos.
Cuando creas un permiso donde type=user
o type=group
, también debes proporcionar un emailAddress
para vincular el usuario o grupo específico con el 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
permissions.create
con elfileId
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 la siguiente muestra de código, se indica 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"
}
Utilizar usuarios objetivo
Los usuarios objetivo son grupos de personas, como departamentos o equipos, que puedes recomendar para que los usuarios compartan sus elementos. Puedes alentar a los usuarios a compartir elementos con un público más específico o limitado 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 compartan contenido de manera adecuada. Para obtener más información, consulta Acerca de los públicos objetivo.
Para utilizar los usuarios objetivo, sigue estos pasos:
En la Consola del administrador de Google, ve a Menú > Directorio > Usuarios objetivo.
Para esta tarea, debes acceder con una cuenta con privilegios de superusuario.
En la Lista de usuarios 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 los usuarios interactúan con el público objetivo, consulta Experiencia del usuario para el uso compartido de vínculos.
Recuperar todos los permisos de un archivo, una carpeta o una unidad compartida
Usa el método permissions.list
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. En la respuesta, se 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"
}
]
}
Verifica los permisos de los usuarios
Cuando tu app abre un archivo, debe verificar las capacidades del archivo y renderizar la IU para que refleje los permisos del usuario actual. Por ejemplo, si el usuario no tiene una función canComment
en el archivo, se debe inhabilitar la capacidad de comentar en la IU.
Para obtener más información sobre capabilities
, consulta la sección anterior Funciones.
Para verificar las capacidades, llama a files.get
con el fileId
y el parámetro fields
establecidos en el campo capabilities
. Si quieres obtener más información sobre cómo mostrar campos con el parámetro fields
, consulta Cómo mostrar campos específicos para un archivo.
Mostrar un ejemplo
En la siguiente muestra de código, se indica cómo verificar los permisos del usuario. La respuesta muestra una lista de capacidades que el usuario tiene en el archivo. Cada función corresponde a una acción detallada que un usuario puede realizar. Algunos campos solo se propagan 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 } }
Determina la fuente del rol de los archivos y las carpetas de las unidades compartidas
Para cambiar el rol en un archivo o una carpeta, debes conocer la fuente del rol. En el caso de las unidades compartidas, la fuente de una función puede basarse en la membresía de la unidad compartida, la función en una carpeta o la función en un archivo.
Para determinar la fuente del rol de una unidad compartida o sus elementos, llama a permissions.get
con los parámetros fileId
, permissionId
y fields
establecidos en el campo permissionDetails
. Para encontrar el permissionId
, usa permissions.list
con el fileId
. Para recuperar el campo permissionDetails
en la solicitud permissions.list
, establece el parámetro fields
en permissions/permissionDetails
.
En este campo, se enumeran todos los permisos heredados y directos de los archivos del usuario, el grupo o el dominio.
Mostrar un ejemplo
En la siguiente muestra de código, se indica cómo determinar la fuente de la función. La respuesta muestra el permissionDetails
de un recurso Permission
. El campo inheritedFrom
proporciona el ID del elemento desde el 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
}
]
}
Cambiar permisos
Para cambiar los permisos de un archivo o una carpeta, puedes cambiar el rol asignado:
Llama a
permissions.update
con elpermissionId
del permiso que se puede cambiar y elfileId
del archivo, la carpeta o la unidad compartida asociados. Para encontrar elpermissionId
, usapermissions.list
con elfileId
.En la solicitud, identifica el
role
nuevo.
Puedes otorgar permisos sobre carpetas o archivos individuales de 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 otorgar a Alex role=writer
para un archivo de una unidad compartida. En este caso, debido a que la función nueva tiene más permisos que la función otorgada a través de su membresía, el permiso nuevo se convierte en la función real para el archivo o la carpeta.
Mostrar un ejemplo
En la siguiente muestra de código, se indica cómo cambiar los permisos de un archivo o una carpeta de comentarista a escritor. La respuesta muestra una instancia de un recurso Permission
.
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"
}
Cómo revocar el acceso a un archivo o una carpeta
Para revocar el acceso a un archivo o una carpeta, llama a delete
con fileId
y permissionId
para borrar el permiso.
Para los elementos de “Mi unidad”, es posible borrar un permiso heredado. Si borras un permiso heredado, se revoca el acceso al elemento y a los elementos secundarios, si los hubiera.
No se pueden revocar los permisos heredados de los elementos de una unidad compartida. Actualiza o revoca el permiso en el archivo o la carpeta superior.
La operación delete
también se usa para borrar los permisos aplicados directamente a un archivo o una carpeta de una unidad compartida.
Mostrar un ejemplo
En la siguiente muestra de código, se indica cómo borrar un permissionId
para revocar el acceso. Si se ejecuta correctamente, el cuerpo de la respuesta está vacío. Para confirmar que se quitó el permiso, usa permissions.list
con fileId
.
Solicitud
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
Transferir la propiedad del archivo a otra cuenta de Google Workspace de la misma organización
La propiedad de los archivos que existen en “Mi unidad” se puede transferir de una cuenta de Google Workspace a otra cuenta de la misma organización. Una organización propietaria de una unidad compartida es propietaria de los archivos que contiene. Por lo tanto, las transferencias de propiedad no son compatibles con archivos y carpetas en unidades compartidas. Los organizadores de una unidad compartida pueden mover elementos de ella a su propia unidad, que les transfiere la propiedad.
Para transferir la propiedad de un archivo de “Mi unidad”, realiza una de las siguientes acciones:
Crea un permiso de archivo que otorgue acceso de propietario (
role=owner
) a un usuario específico (type=user
).Actualiza el permiso de un archivo existente con
role=owner
y transfiere la propiedad al usuario especificado (transferOwnership=true
).
Transferir la propiedad de los archivos de una cuenta personal a otra
La propiedad de los archivos se puede transferir de una cuenta personal a otra. Sin embargo, Drive no transfiere la propiedad de un archivo entre dos cuentas personales hasta que el nuevo propietario potencial da su consentimiento explícitamente para la transferencia. Para transferir la propiedad de los archivos de una cuenta personal a otra, sigue estos pasos:
El propietario actual inicia una transferencia de propiedad mediante la creación o actualización del permiso de archivo del nuevo propietario potencial. El permiso debe incluir las siguientes opciones de configuración:
role=writer
,type=user
ypendingOwner=true
. Si el propietario nuevo crea un permiso para el propietario potencial, se envía una notificación por correo electrónico al nuevo propietario potencial en la que se indica que se le pide que asuma la propiedad del archivo.El nuevo propietario acepta la solicitud de transferencia de propiedad mediante la creación o actualización de su permiso de archivo. El permiso debe incluir las siguientes opciones de configuración:
role=owner
ytransferOwnership=true
. Si el propietario nuevo está creando un permiso nuevo, se enviará una notificación por correo electrónico al propietario anterior en la que se indicará que se transfirió la propiedad.
Cuando se transfiere un archivo, el rol del propietario anterior cambia a writer
.
Cambia 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.