Ogni file, cartella e Drive condiviso di Google Drive ha risorse
permissions associate. Ogni risorsa
identifica l'autorizzazione per un
type specifico (user,
group, domain, anyone) e
role (owner,
organizer, fileOrganizer, writer, commenter, reader). Ad esempio, un
file potrebbe avere un'autorizzazione che concede a un utente specifico (type=user) l'accesso
di sola lettura (role=reader), mentre un'altra autorizzazione concede ai membri di un gruppo specifico (type=group) la possibilità di aggiungere commenti a un file (role=commenter).
Per un elenco completo dei ruoli e delle operazioni consentite da ciascuno, consulta Ruoli e autorizzazioni.
Come vengono propagate le autorizzazioni
Le autorizzazioni si propagano verso il basso dalle cartelle principali a tutti gli elementi secondari:
- Ereditate per impostazione predefinita: tutti i file e le cartelle secondarie ereditano automaticamente le autorizzazioni dalla cartella principale.
- Non può essere ridotta per i figli: non puoi rimuovere o ridurre un'autorizzazione ereditata su un elemento figlio. Le modifiche devono essere apportate alla cartella principale di origine oppure la cartella deve utilizzare l'impostazione di accesso limitato.
- Può essere espanso sui figli: un elemento secondario può concedere un ruolo più permissivo, ad esempio concedere
role=writersu un file all'interno di una cartella in cui l'utente harole=reader. - Rivalutazione al momento dello spostamento: lo spostamento di un elemento in una nuova cartella principale rivaluta e applica le autorizzazioni della nuova cartella principale all'elemento e ai relativi elementi secondari.
Link ai file e controllo dell'accesso
Quando condividi un file o una cartella con un utente o un gruppo specifico, l'URL per accedere
all'elemento non cambia e non viene generato un link univoco per ogni utente.
L'elemento ha invece un unico link costante basato sul suo fileId.
Drive controlla l'accesso valutando l'ACL dell'elemento. Quando un utente tenta di aprire un link, Drive verifica la sua identità autenticata rispetto all'elenco di controllo dell'accesso. Se un'autorizzazione viene revocata o raggiunge la data di scadenza, l'utente viene rimosso dalla ACL. Se l'utente tenta di visitare di nuovo il link, Drive nega l'accesso.
Informazioni sulle funzionalità dei file
La risorsa permissions definisce chi ha
accesso (l'elenco di controllo dell'accesso), ma non indica direttamente se l'utente corrente può
eseguire un'azione specifica nell'interfaccia utente dell'applicazione.
La risorsa files contiene invece una raccolta di campi booleani capabilities (ad esempio canComment, canShare o canDelete) che l'API Google Drive calcola dinamicamente in base al ruolo dell'utente e alle impostazioni dell'elemento.
Ottenere le funzionalità dei file
Durante il rendering dell'interfaccia utente dell'app, controlla files.capabilities anziché analizzare
direttamente le autorizzazioni:
- Chiama il metodo
files.getconfields=capabilities. Per saperne di più, consulta Restituire campi specifici. - Utilizza i flag booleani restituiti per attivare o disattivare le azioni corrispondenti nell'interfaccia. Ad esempio, disattiva i commenti se
canCommentèfalse.
Scenari per la condivisione delle risorse di Drive
La tabella seguente mostra i ruoli e le condizioni richiesti per la condivisione delle risorse di Drive in diverse località e tipi di elementi:
| Località | Elemento | Ruoli obbligatori | Limitazioni principali |
|---|---|---|---|
| Il mio Drive | File o cartella | owner o writer |
Richiede owner se writersCanShare=false.L'accesso con scadenza alle cartelle richiede reader (vedi Impostare una data di scadenza). |
| Drive condiviso | File | organizer, fileOrganizer o writer |
writersCanShare viene sempre trattato come true. |
| Drive condiviso | Cartella | organizer |
fileOrganizer può condividere anche se sharingFoldersRequiresOrganizerPermission è false. |
| Drive condiviso | Abbonamento | organizer |
Si applica solo a user o group (non ai domini). |
Gestisci autorizzazioni
La tabella seguente riepiloga i metodi disponibili per la risorsa
permissions:
| Metodo | Endpoint API | Parametri chiave | Riferimento |
|---|---|---|---|
| Crea | POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
role, type, emailAddress o domain |
permissions.create |
| Scarica | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
fields |
permissions.get |
| Elenca | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
pageSize, supportsAllDrives e pageToken |
permissions.list |
| Aggiorna | PATCH https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
role, allowFileDiscovery |
permissions.update |
| Elimina | DELETE https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
supportsAllDrives |
permissions.delete |
Crea un'autorizzazione
Per condividere un file, una cartella o un Drive condiviso, chiama il metodo
create sulla risorsa
permissions con fileId.
La creazione di un'autorizzazione aggiunge una nuova voce ACL all'elemento e restituisce un permissionId assegnato.
Nel corpo della richiesta, fornisci i seguenti campi:
role: il livello di accesso da concedere (ad esempioreader,commenterowriter). Per un elenco completo, consulta Ruoli e autorizzazioni.type: l'ambito del beneficiario (user,group,domainoanyone).- Identificatore del beneficiario (obbligatorio in base a
type):emailAddress: Obbligatorio quandotypeèuserogroup.domain: obbligatorio quandotypeèdomain.
Il seguente esempio di codice mostra come creare un'autorizzazione. La risposta restituisce un'istanza di una risorsa permissions, incluso il permissionId assegnato.
Richiesta
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "role": "commenter", "type": "user", "emailAddress": "alex@altostrat.com" }
Risposta
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}Condividere con i segmenti di pubblico di destinazione
I segmenti di pubblico di destinazione sono gruppi di persone, ad esempio reparti o team, che puoi consigliare agli utenti per la condivisione dei propri elementi. Puoi incoraggiare gli utenti a condividere gli elementi con un pubblico più specifico o circoscritto anziché con l'intera organizzazione. I segmenti di pubblico di destinazione possono aiutarti a migliorare la sicurezza e la privacy dei tuoi dati e a semplificare la condivisione appropriata per gli utenti.
Per condividere con un segmento di pubblico di destinazione, imposta type=domain e domain su
<TARGET_AUDIENCE_ID>.audience.googledomains.com. Per informazioni dettagliate su come individuare o
creare segmenti di pubblico di destinazione nella Console di amministrazione Google, vedi Informazioni sui segmenti di pubblico di destinazione.
Per visualizzare il modo in cui gli utenti interagiscono con i segmenti di pubblico di destinazione, consulta Esperienza utente per la condivisione tramite link.
Ottenere un'autorizzazione
Per ottenere un'autorizzazione, chiama il metodo get sulla risorsa permissions con i parametri di percorso fileId e permissionId. Se non conosci l'ID autorizzazione, elenca prima tutte le autorizzazioni.
Elenco autorizzazioni
Per elencare le autorizzazioni per un file, una cartella o un Drive condiviso, chiama il metodo
list sulla risorsa
permissions con il parametro di percorso
fileId richiesto.
Puoi includere uno dei seguenti parametri di query facoltativi per paginare o filtrare la risposta:
pageSize(facoltativo): il numero massimo di autorizzazioni da restituire per pagina. Se non è impostato per i file in un Drive condiviso, vengono restituiti al massimo 100 risultati. Se non è impostato per i file che non si trovano in un Drive condiviso, viene restituito l'intero elenco.pageToken(facoltativo): un token di pagina di una precedente chiamata dell'elenco per recuperare la pagina successiva.supportsAllDrives(facoltativo): indica se l'app richiedente supporta sia Il mio Drive sia i Drive condivisi.useDomainAdminAccess(facoltativo): impostalo sutrueper inviare la richiesta come amministratore di dominio. Al richiedente viene concesso l'accesso se il parametrofileIdsi riferisce a un Drive condiviso e il richiedente è un amministratore del dominio a cui appartiene il Drive condiviso. Per saperne di più, vedi Gestire i Drive condivisi come amministratori del dominio.includePermissionsForView(facoltativo): autorizzazioni di visualizzazione aggiuntive da includere nella risposta. È supportato solopublished.fields(facoltativo): campi specifici da restituire nella risposta. Per impostazione predefinita,listrestituisce soloid,type,kinderole. Per restituire campi aggiuntivi (ad esempiopermissionDetails), specificali utilizzando questo parametro. Per maggiori informazioni, consulta Restituisci campi specifici.
Determinare l'origine del ruolo
Per modificare il ruolo di un file o una cartella, devi conoscere l'origine del ruolo. Per i Drive condivisi, l'origine di un ruolo può essere basata sull'appartenenza al Drive condiviso, sul ruolo in una cartella o sul ruolo in un file.
Per determinare l'origine del ruolo per un Drive condiviso o per gli elementi al suo interno, chiama il metodo get sulla risorsa permissions con i parametri di percorso fileId e permissionId e il parametro fields impostato sul campo permissionDetails.
Per trovare permissionId, utilizza il metodo
list sulla risorsa permissions
con il parametro di percorso fileId. Per recuperare il campo permissionDetails nella richiesta list, imposta il parametro fields su permissions/permissionDetails.
Questo campo elenca tutte le autorizzazioni di file ereditate e dirette per l'utente, il gruppo o il dominio.
Il seguente esempio di codice mostra come determinare l'origine del ruolo. La risposta restituisce l'permissionDetails di una risorsa permissions. Il campo inheritedFrom fornisce l'ID dell'elemento da cui viene ereditata l'autorizzazione.
Richiesta
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true
Risposta
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}Aggiornare un'autorizzazione
Per aggiornare le autorizzazioni per un file o una cartella, puoi modificare il ruolo assegnato. Per maggiori informazioni su come trovare l'origine del ruolo, consulta Determinare l'origine del ruolo.
Chiama il metodo
updatesulla risorsapermissionscon il parametro di percorsofileIdimpostato sul file, sulla cartella o sul Drive condiviso associato e il parametro di percorsopermissionIdimpostato sull'autorizzazione da modificare. Per trovarepermissionId, utilizza il metodolistnella risorsapermissionscon il parametro di percorsofileId.Nella richiesta, identifica il nuovo
role.
Puoi concedere autorizzazioni per singoli file o cartelle in un Drive condiviso anche
se l'utente o il gruppo è già un membro. Ad esempio, Alex ha role=commenter
come parte della sua iscrizione a un Drive condiviso. Tuttavia, la tua app può concedere ad Alex
role=writer per un file in un Drive condiviso. In questo caso, poiché il nuovo ruolo
è più permissivo del ruolo concesso tramite l'iscrizione, la nuova
autorizzazione diventa il ruolo effettivo per il file o la cartella.
Puoi applicare gli aggiornamenti tramite la semantica delle patch, il che significa che puoi apportare modifiche parziali a una risorsa. Nella richiesta devi impostare in modo esplicito i campi che intendi modificare. I campi non inclusi nella richiesta mantengono i valori esistenti. Per saperne di più, consulta Utilizzo delle risorse parziali.
Oltre a modificare i ruoli, puoi anche modificare la visibilità di un elemento quando l'autorizzazione type è domain o anyone. Per rendere un file condiviso
ricercabile o non in elenco, includi il campo
booleano allowFileDiscovery nella richiesta di patch. Se imposti questo valore su true, l'elemento può essere visualizzato nei risultati di ricerca per il pubblico specificato, anche se non è stato fornito il link diretto. Non è necessario eliminare e ricreare l'autorizzazione per modificare questa
impostazione.
Il seguente esempio di codice mostra come modificare le autorizzazioni per un file o una cartella da commenter a writer. La risposta restituisce un'istanza di una risorsa permissions.
Richiesta
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}Risposta
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}Aggiornare più autorizzazioni con le richieste batch
Le modifiche simultanee alle autorizzazioni per lo stesso file, la stessa cartella o lo stesso Drive condiviso non sono supportate. Questa limitazione si applica a tutte le operazioni di modifica (ad esempio aggiornamento o eliminazione), indipendentemente dal fatto che tu stia modificando le autorizzazioni per lo stesso destinatario o per destinatari diversi e che le richieste provengano da una singola app o da più utenti.
Drive valuta e aggiorna le autorizzazioni di un elemento come un singolo
ACL. Le operazioni simultanee causano condizioni di competizione in cui "vince l'ultima scrittura",
che può sovrascrivere silenziosamente le modifiche alle autorizzazioni o attivare
errori sharingRateLimitExceeded.
Per evitare conflitti, esegui le modifiche alle autorizzazioni sullo stesso elemento in sequenza oppure utilizza le richieste batch per modificare più autorizzazioni in una singola richiesta.
Di seguito è riportato un esempio di modifica collettiva delle autorizzazioni con una libreria client.
Java
Python
Node.js
PHP
.NET
Eliminare un'autorizzazione
Per revocare l'accesso a un file o a una cartella, chiama il metodo
delete sulla risorsa
permissions con i parametri di percorso fileId e
permissionId.
Le autorizzazioni ereditate non possono essere revocate direttamente sugli elementi secondari. Aggiorna o elimina l'autorizzazione per la cartella principale (o utilizza l'impostazione di accesso limitato).
Tieni presente che la rimozione dell'accesso di un utente da un elemento principale revoca solo le autorizzazioni
ereditate da quell'elemento principale. Se all'utente sono state concesse anche autorizzazioni dirette su un
elemento secondario, l'accesso diretto persiste. Per confermare la rimozione di un'autorizzazione,
chiama list con fileId.
Imposta una data di scadenza
Per concedere l'accesso temporaneo a un file o a una cartella, imposta il campo
expirationTime (data e ora RFC 3339) quando
chiami i metodi create o update.
Le scadenze presentano le seguenti limitazioni:
- Può essere impostato solo sulle autorizzazioni
useregroup(nondomainoanyone). - L'orario deve essere nel futuro, fino a un massimo di un anno.
- Per le cartelle, l'accesso temporaneo è supportato solo con il ruolo
reader.
Argomenti correlati
- Gestire le proposte di accesso in attesa
- Gestire le cartelle con accesso limitato e ampio
- Trasferire la proprietà di un file
- Proteggere i contenuti dei file
- Accedere ai file di Drive condivisi tramite link utilizzando le chiavi risorsa
- Ruoli e autorizzazioni