Chaque fichier, dossier et Drive partagé Google Drive est associé à des ressources permissions. Chaque ressource identifie l'autorisation pour un type spécifique (user, group, domain, anyone) et un role (owner, organizer, fileOrganizer, writer, commenter, reader). Par exemple, un fichier peut avoir une autorisation accordant à un utilisateur spécifique (type=user) un accès en lecture seule (role=reader), tandis qu'une autre autorisation accorde aux membres d'un groupe spécifique (type=group) la possibilité d'ajouter des commentaires à un fichier (role=commenter).
Pour obtenir la liste complète des rôles et des opérations autorisées pour chacun d'eux, consultez Rôles et autorisations.
Propagation des autorisations
Les autorisations se propagent vers le bas, des dossiers parents à tous les éléments enfants :
- Héritage par défaut : tous les fichiers et dossiers enfants héritent automatiquement des autorisations de leur dossier parent.
- Impossible de réduire les autorisations sur les éléments enfants : vous ne pouvez pas supprimer ni réduire une autorisation héritée sur un élément enfant. Les modifications doivent être apportées au parent d'origine ou le dossier doit utiliser le paramètre d'accès limité.
- Peut être étendu aux enfants : un élément enfant peut accorder un rôle plus permissif, par exemple
role=writersur un fichier dans un dossier où l'utilisateur dispose derole=reader. - Réévaluation lors du déplacement : lorsque vous déplacez un élément vers un nouveau dossier parent, les autorisations du nouveau parent sont réévaluées et appliquées à l'élément et à ses enfants.
Liens vers des fichiers et contrôle des accès
Lorsque vous partagez un fichier ou un dossier avec un utilisateur ou un groupe spécifique, l'URL permettant d'accéder à l'élément ne change pas et aucun lien unique n'est généré pour chaque utilisateur.
Au lieu de cela, l'élément possède un lien unique et constant basé sur son fileId.
Drive contrôle l'accès en évaluant la LCA de l'élément. Lorsqu'un utilisateur tente d'ouvrir un lien, Drive vérifie son identité authentifiée par rapport à la LCA. Si une autorisation est révoquée ou arrive à expiration, l'utilisateur est supprimé de la LCA. Si l'utilisateur tente d'accéder à nouveau au lien, Drive refuse l'accès.
Comprendre les fonctionnalités des fichiers
La ressource permissions définit qui a accès (la LCA), mais n'indique pas directement si l'utilisateur actuel peut effectuer une action spécifique dans l'UI de votre application.
La ressource files contient plutôt une collection de champs booléens capabilities (tels que canComment, canShare ou canDelete) que l'API Google Drive calcule de manière dynamique en fonction du rôle de l'utilisateur et des paramètres de l'élément.
Obtenir les fonctionnalités des fichiers
Lorsque vous affichez l'UI de votre application, vérifiez files.capabilities au lieu d'analyser directement les autorisations :
- Appelez la méthode
files.getavecfields=capabilities. Pour en savoir plus, consultez Renvoyer des champs spécifiques. - Utilisez les indicateurs booléens renvoyés pour activer ou désactiver les actions correspondantes dans votre interface. Par exemple, désactivez les commentaires si
canCommentest défini surfalse.
Scénarios de partage des ressources Drive
Le tableau suivant indique les rôles et les conditions requis pour partager des ressources Drive dans différents emplacements et pour différents types d'éléments :
| Emplacement | Élément | Rôles requis | Principales contraintes |
|---|---|---|---|
| Mon Drive | Fichier ou dossier | owner ou writer |
owner requis si writersCanShare=false.L'accès temporaire aux dossiers nécessite reader (voir Définir une date d'expiration). |
| Drive partagé | Fichier | organizer, fileOrganizer ou writer |
writersCanShare est toujours traité comme true. |
| Drive partagé | Dossier | organizer |
fileOrganizer peut également partager du contenu si sharingFoldersRequiresOrganizerPermission est défini sur false. |
| Drive partagé | Abonnement | organizer |
S'applique uniquement à user ou group (et non aux domaines). |
Gérer les autorisations
Le tableau suivant récapitule les méthodes disponibles sur la ressource permissions :
| Méthode | Point de terminaison de l'API | Paramètres clés | Référence |
|---|---|---|---|
| Créer | POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
role, type, emailAddress ou domain |
permissions.create |
| Get | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
fields |
permissions.get |
| List | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
pageSize, supportsAllDrives, pageToken |
permissions.list |
| Update | PATCH https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
role, allowFileDiscovery |
permissions.update |
| Supprimer | DELETE https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
supportsAllDrives |
permissions.delete |
Créer une autorisation
Pour partager un fichier, un dossier ou un Drive partagé, appelez la méthode create sur la ressource permissions avec fileId.
La création d'une autorisation ajoute une entrée de LCA à l'élément et renvoie un permissionId attribué.
Dans le corps de la requête, fournissez les champs suivants :
role: niveau d'accès à accorder (par exemple,reader,commenterouwriter). Pour obtenir la liste complète, consultez Rôles et autorisations.type: champ d'application du bénéficiaire (user,group,domainouanyone).- Identifiant du bénéficiaire (obligatoire selon
type) :emailAddress: Obligatoire lorsquetypeest défini suruserougroup.domain: obligatoire lorsquetypeest défini surdomain.
L'exemple de code suivant montre comment créer une autorisation. La réponse renvoie une instance d'une ressource permissions, y compris le permissionId attribué.
Demande
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "role": "commenter", "type": "user", "emailAddress": "alex@altostrat.com" }
Réponse
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}Partager avec des audiences cibles
Les audiences cibles sont des groupes de personnes, comme des services ou des équipes, que vous pouvez recommander aux utilisateurs ayant l'intention de partager des éléments. Vous pouvez encourager les utilisateurs à partager des éléments avec une audience spécifique ou restreinte plutôt qu'avec l'ensemble de votre organisation. Les audiences cibles peuvent vous aider à renforcer la sécurité et la confidentialité de vos données, et à permettre aux utilisateurs de partager des éléments de manière appropriée.
Pour partager avec une audience cible, définissez type=domain et domain sur <TARGET_AUDIENCE_ID>.audience.googledomains.com. Pour savoir comment trouver ou créer des audiences cibles dans la console d'administration Google, consultez À propos des audiences cibles.
Pour savoir comment les utilisateurs interagissent avec les audiences cibles, consultez Expérience utilisateur pour le partage de liens.
Obtenir une autorisation
Pour obtenir une autorisation, appelez la méthode get sur la ressource permissions avec les paramètres de chemin d'accès fileId et permissionId. Si vous ne connaissez pas l'ID d'autorisation, listez d'abord toutes les autorisations.
Lister les autorisations
Pour lister les autorisations d'un fichier, d'un dossier ou d'un Drive partagé, appelez la méthode list sur la ressource permissions avec le paramètre de chemin d'accès fileId requis.
Vous pouvez inclure l'un des paramètres de requête facultatifs suivants pour paginer ou filtrer la réponse :
pageSize(facultatif) : nombre maximal d'autorisations à renvoyer par page. Si ce paramètre n'est pas défini pour les fichiers d'un Drive partagé, 100 résultats au maximum sont renvoyés. Si cette valeur n'est pas définie pour les fichiers qui ne se trouvent pas dans un Drive partagé, la liste entière est renvoyée.pageToken(facultatif) : jeton de page provenant d'un appel de liste précédent pour récupérer la page suivante.supportsAllDrives(facultatif) : indique si l'application à l'origine de la requête est compatible avec Mon Drive et les Drive partagés.useDomainAdminAccess(facultatif) : définissez la valeur surtruepour envoyer la requête en tant qu'administrateur de domaine. L'accès est accordé au demandeur si le paramètrefileIdfait référence à un Drive partagé et si le demandeur est un administrateur du domaine auquel appartient le Drive partagé. Pour en savoir plus, consultez Gérer les Drive partagés en tant qu'administrateur de domaine.includePermissionsForView(facultatif) : autorisations de vue supplémentaires à inclure dans la réponse. Seule la régionpublishedest compatible.fields(facultatif) : champs spécifiques à renvoyer dans la réponse. Par défaut,listne renvoie queid,type,kindetrole. Pour renvoyer des champs supplémentaires (tels quepermissionDetails), spécifiez-les à l'aide de ce paramètre. Pour en savoir plus, consultez Renvoyer des champs spécifiques.
Déterminer la source du rôle
Pour modifier le rôle attribué à un fichier ou à un dossier, vous devez connaître la source du rôle. Pour les Drive partagés, la source d'un rôle peut être basée sur l'appartenance au Drive partagé, le rôle sur un dossier ou le rôle sur un fichier.
Pour déterminer la source du rôle d'un Drive partagé ou des éléments qu'il contient, appelez la méthode get sur la ressource permissions avec les paramètres de chemin d'accès fileId et permissionId, et le paramètre fields défini sur le champ permissionDetails.
Pour trouver le permissionId, utilisez la méthode list sur la ressource permissions avec le paramètre de chemin d'accès fileId. Pour récupérer le champ permissionDetails dans la requête list, définissez le paramètre fields sur permissions/permissionDetails.
Ce champ énumère toutes les autorisations de fichier héritées et directes pour l'utilisateur, le groupe ou le domaine.
L'exemple de code suivant montre comment déterminer la source du rôle. La réponse renvoie le permissionDetails d'une ressource permissions. Le champ inheritedFrom fournit l'ID de l'élément à partir duquel l'autorisation est héritée.
Demande
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true
Réponse
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}Modifier une autorisation
Pour modifier les autorisations sur un fichier ou un dossier, vous pouvez changer le rôle attribué. Pour en savoir plus sur la recherche de la source du rôle, consultez Déterminer la source du rôle.
Appelez la méthode
updatesur la ressourcepermissionsavec le paramètre de chemin d'accèsfileIddéfini sur le fichier, le dossier ou le Drive partagé associé, et le paramètre de chemin d'accèspermissionIddéfini sur l'autorisation à modifier. Pour trouver lepermissionId, utilisez la méthodelistsur la ressourcepermissionsavec le paramètre de chemin d'accèsfileId.Dans la requête, identifiez le nouveau
role.
Vous pouvez accorder des autorisations sur des fichiers ou des dossiers individuels dans un Drive partagé, même si l'utilisateur ou le groupe est déjà membre. Par exemple, Alex dispose de role=commenter en tant que membre d'un Drive partagé. Toutefois, votre application peut accorder à Alexrole=writer l'accès à un fichier dans un Drive partagé. Dans ce cas, comme le nouveau rôle est plus permissif que celui accordé par l'abonnement, la nouvelle autorisation devient le rôle effectif pour le fichier ou le dossier.
Vous pouvez appliquer des mises à jour à l'aide de la sémantique des correctifs, ce qui signifie que vous pouvez apporter des modifications partielles à une ressource. Vous devez définir explicitement les champs que vous souhaitez modifier dans votre requête. Tous les champs non inclus dans la requête conservent leurs valeurs existantes. Pour en savoir plus, consultez Utiliser des ressources partielles.
En plus de modifier les rôles, vous pouvez également modifier la visibilité d'un élément lorsque l'autorisation type est définie sur domain ou anyone. Pour rendre un fichier partagé consultable ou non répertorié, incluez le champ booléen allowFileDiscovery dans votre requête PATCH. Si vous définissez ce paramètre sur true, l'élément peut s'afficher dans les résultats de recherche pour l'audience spécifiée, même si elle n'a pas reçu le lien direct. Vous n'avez pas besoin de supprimer et de recréer l'autorisation pour modifier ce paramètre.
L'exemple de code suivant montre comment modifier les autorisations d'un fichier ou d'un dossier de commenter à writer. La réponse renvoie une instance d'une ressource permissions.
Demande
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}Réponse
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}Mettre à jour plusieurs autorisations avec des requêtes par lot
Les modifications simultanées des autorisations sur un même fichier, dossier ou Drive partagé ne sont pas prises en charge. Cette limite s'applique à toutes les opérations de mutation (comme les mises à jour ou les suppressions), que vous modifiiez les autorisations pour le même destinataire ou pour des destinataires différents, et que les demandes proviennent d'une seule application ou de plusieurs utilisateurs.
Drive évalue et met à jour les autorisations d'un élément en tant qu'une seule LCA. Les opérations simultanées entraînent des conditions de concurrence où la "dernière écriture l'emporte", ce qui peut écraser silencieusement les modifications d'autorisation ou déclencher des erreurs sharingRateLimitExceeded.
Pour éviter les conflits, exécutez les modifications d'autorisation sur le même élément de manière séquentielle ou utilisez des requêtes par lot pour modifier plusieurs autorisations dans une seule requête.
Voici un exemple de modification des autorisations par lot à l'aide d'une bibliothèque cliente.
Java
Python
Node.js
PHP
.NET
Supprimer une autorisation
Pour révoquer l'accès à un fichier ou à un dossier, appelez la méthode delete sur la ressource permissions avec les paramètres de chemin d'accès fileId et permissionId.
Les autorisations héritées ne peuvent pas être révoquées directement sur les éléments enfants. Mettez à jour ou supprimez plutôt l'autorisation sur le dossier parent (ou utilisez le paramètre d'accès limité).
Notez que la suppression de l'accès d'un utilisateur à un élément parent ne révoque que les autorisations héritées de cet élément parent. Si l'utilisateur a également reçu des autorisations directes sur un élément enfant, cet accès direct est conservé. Pour confirmer qu'une autorisation a été supprimée, appelez list avec fileId.
Définir une date d'expiration
Pour accorder un accès temporaire à un fichier ou à un dossier, définissez le champ expirationTime (date et heure au format RFC 3339) lorsque vous appelez les méthodes create ou update.
Les délais d'expiration sont soumis aux restrictions suivantes :
- Ne peut être défini que sur les autorisations
useretgroup(pasdomainnianyone). - L'heure doit être située dans le futur, dans la limite d'un an.
- Pour les dossiers, l'accès temporaire n'est disponible qu'avec le rôle
reader.
Articles associés
- Gérer les propositions d'accès en attente
- Gérer les dossiers en accès limité et étendu
- Transférer la propriété d'un fichier
- Protéger le contenu d'un fichier
- Accéder aux fichiers Drive partagés par lien à l'aide de clés de ressource
- Rôles et autorisations