L'API Directory fornisce metodi programmatici per la creazione, l'aggiornamento e l'eliminazione degli utenti. Puoi anche ottenere informazioni su singoli utenti o elenchi di utenti che soddisfano criteri specificati. Di seguito sono riportati alcuni esempi di alcune operazioni utente di base.
Crea un account utente
Puoi aggiungere un account utente a qualsiasi dominio del tuo account Google Workspace. Prima di aggiungere un account utente, conferma la proprietà del dominio.
Se hai eseguito l'upgrade del tuo account Gmail personale a un account email aziendale con il tuo nome di dominio, non potrai creare nuovi account utente finché non sblocchi le impostazioni aggiuntive di Google Workspace. Per maggiori dettagli, vedi Account email aziendali G Suite aggiornati a G Suite Basic.
Per creare un account utente utilizzando uno dei tuoi domini, usa la seguente richiesta POST
e includi l'autorizzazione descritta in Informazioni su autenticazione e autorizzazione. Puoi visualizzare gli ambiti disponibili per l'API Directory nell'elenco degli ambiti OAuth 2.0. Per le proprietà della stringa di query della richiesta, consulta il metodo users.insert()
.
POST https://admin.googleapis.com/admin/directory/v1/users
Per tutte le richieste di creazione, devi inviare le informazioni necessarie per soddisfarla. Se utilizzi librerie client, queste convertono gli oggetti dati del linguaggio scelto in oggetti con formato dati JSON.
Richiesta JSON
Il seguente JSON mostra una richiesta di esempio per creare un utente. Per l'elenco completo delle proprietà delle richieste e delle risposte, consulta la documentazione di riferimento API.
{
"primaryEmail": "liz@example.com",
"name": {
"givenName": "Elizabeth",
"familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
{
"type": "work",
"protocol": "gtalk",
"im": "liz_im@talk.example.com",
"primary": true
}
],
"emails": [
{
"address": "liz@example.com",
"type": "home",
"customType": "",
"primary": true
}
],
"addresses": [
{
"type": "work",
"customType": "",
"streetAddress": "1600 Amphitheatre Parkway",
"locality": "Mountain View",
"region": "CA",
"postalCode": "94043"
}
],
"externalIds": [
{
"value": "12345",
"type": "custom",
"customType": "employee"
}
],
"organizations": [
{
"name": "Google Inc.",
"title": "SWE",
"primary": true,
"type": "work",
"description": "Software engineer"
}
],
"phones": [
{
"value": "+1 nnn nnn nnnn",
"type": "work"
}
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}
Se la frequenza di query per le richieste di creazione è troppo elevata, potresti ricevere risposte 503
HTTP dal server API che indicano il superamento della quota. Se ricevi queste risposte, utilizza un algoritmo di backoff esponenziale per riprovare a inviare le richieste.
Aspetti da considerare in merito a un nuovo account:
- Se l'Account Google ha acquistato licenze di posta, al nuovo account utente viene assegnata automaticamente una casella di posta. Potrebbero essere necessari alcuni minuti per completare e attivare questo compito.
- La modifica di un campo di sola lettura in una richiesta, come
isAdmin
, viene ignorata automaticamente dal servizio API. - Il numero massimo di domini consentiti in un account è 600 (1 dominio principale + 599 domini aggiuntivi)
- Se un utente non è stato assegnato a un'unità organizzativa specifica al momento della creazione dell'account utente, l'account si trova nell'unità organizzativa di primo livello. L'unità organizzativa di un utente determina a quali servizi di Google Workspace ha accesso l'utente. Se l'utente viene spostato in una nuova organizzazione, l'accesso dell'utente cambia. Per ulteriori informazioni sulle strutture organizzative, consulta il Centro assistenza per l'amministrazione. Per saperne di più su come spostare un utente in un'altra organizzazione, vedi Aggiornare un utente.
- Per i nuovi account utente è necessario un
password
. Se viene specificato un valorehashFunction
, la password deve essere una chiave hash valida. Se non è specificata, la password deve essere in chiaro e deve essere compresa tra 8 e 100 caratteri ASCII. Per ulteriori informazioni, consulta la sezione Riferimento API. - Per gli utenti che hanno sottoscritto un piano flessibile per Google Workspace, la creazione di utenti tramite questa API avrà un impatto monetario e comporterà addebiti sul tuo account di fatturazione del cliente. Per ulteriori informazioni, consulta le informazioni di fatturazione delle API.
- Un account Google Workspace può includere uno qualsiasi dei tuoi domini. In un account con più domini, gli utenti di un dominio possono condividere servizi con gli utenti di altri domini di account. Per ulteriori informazioni sugli utenti di più domini, consulta le informazioni sui domini multipli delle API.
- Potrebbero esserci account in conflitto. Verifica se qualcuno che intendi aggiungere ha già un Account Google. e poi segui i passaggi per evitare conflitti con questi account. Vedi Trovare e risolvere gli account in conflitto.
- Potrebbero esserci account visitatore. Se gli utenti invitano persone esterne all'organizzazione che non hanno un Account Google a collaborare su Drive, riceveranno account visitatore nel formato nomeutente_visitatore@tuo_dominio.com. Se aggiungi un utente con lo stesso nome utente di un account visitatore, l'account verrà convertito in un account Google Workspace completo. L'account manterrà le attuali autorizzazioni per i file di Drive. Vedi Condividere documenti con i visitatori.
Una risposta corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce le proprietà per il nuovo account utente.
Aggiornare un account utente
Per aggiornare un account utente, utilizza la seguente richiesta PUT
e includi l'autorizzazione descritta in Autorizzare richieste. userKey
può essere l'indirizzo email principale dell'utente, l'utente unico id
o uno degli indirizzi email alias dell'utente.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey
Sia il corpo della richiesta che della risposta contengono un'istanza di
User
. Tuttavia, l'API Directory supporta la semantica della patch, quindi nella richiesta devi solo inviare i campi aggiornati.
Richiesta di esempio
Nell'esempio riportato di seguito, il givenName
dell'utente era "Elizabeth" al momento della creazione dell'account
utente ed è stato fornito solo un indirizzo email di lavoro.
{
"name": {
"givenName": "Elizabeth",
"familyName": "Smith"
},
"emails": [
{
"address": "liz@example.com",
"type": "work",
"primary": true
}
}
La richiesta riportata di seguito aggiorna givenName
da "Elizabeth" a "Liz" e
aggiunge anche un indirizzo email di casa. Tieni presente che entrambi gli indirizzi email vengono forniti
completamente perché il campo è un array.
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
{
"name": {
"givenName": "Liz",
},
"emails": [
{
"address": "liz@example.com",
"type": "work",
"primary": true
},
{
"address": "liz@home.com",
"type": "home"
}
]
}
Una risposta corretta restituisce un codice di stato HTTP 200
e una risorsa User
con i campi aggiornati.
Tieni presente quanto segue durante l'aggiornamento del nome dell'account di un utente:
- La ridenominazione di un account utente comporta la modifica dell'indirizzo email principale dell'utente e del dominio utilizzato nel recupero delle informazioni dell'utente. Prima di rinominare un utente, ti consigliamo di disconnetterlo da tutte le sessioni e tutti i servizi del browser.
- La propagazione a tutti i servizi della procedura di ridenominazione di un account utente può richiedere fino a 10 minuti.
- Quando rinomini un utente, il vecchio nome utente viene conservato come alias per garantire la consegna continua della posta in caso di impostazioni di inoltro email e non è disponibile come nuovo nome utente.
- In generale, consigliamo inoltre di non utilizzare l'indirizzo email dell'utente come chiave per i dati persistenti perché l'indirizzo email è soggetto a modifiche.
- Per un elenco completo degli effetti della ridenominazione di un utente nelle app Google Workspace, consulta il Centro assistenza per amministratori.
Impostare un utente come amministratore
Per assegnare a un utente il ruolo di super amministratore, utilizza la seguente richiesta POST
e includi l'autorizzazione descritta in Autorizzare le richieste. userKey
può essere l'indirizzo email principale dell'utente, l'utente unico id
o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API. Per ulteriori informazioni su un super amministratore, consulta il Centro assistenza per l'amministrazione.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin
Richiesta JSON
In questo esempio, l'utente il cui userKey
è liz@example.com è diventato un super amministratore:
POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin
{ "status": true }
Una risposta corretta restituisce un codice di stato HTTP 200.
Gestire le relazioni con gli utenti
L'API Directory utilizza il campo relations
per definire diversi tipi di relazioni tra gli utenti. In un ambiente aziendale, si usano in genere questo campo per le relazioni tra manager-dipendenti e assistenti, ma il campo supporta anche molti altri tipi. La relazione viene visualizzata nella scheda "Persone correlate" dell'utente in qualsiasi applicazione Google Workspace che la supporti. Per esempi di dove è visibile la scheda, vedi Aggiungere informazioni al profilo della directory di un utente.
Creare una relazione tra gli utenti
Puoi definire una relazione in una sola direzione, a partire dall'utente "proprietario", il cui record include il campo relations
. L'type
descrive la relazione tra l'altra persona e l'utente proprietario. Ad esempio, in una relazione tra gestore e dipendente, il dipendente è l'utente proprietario e tu aggiungi un campo relations
al suo account con il tipo manager
. Per i tipi consentiti, consulta il riferimento all'oggetto User
.
Configura la relazione creando o aggiornando l'utente proprietario con un corpo della richiesta JSON che includa il campo relations
.
È possibile creare più relazioni in una singola richiesta.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_1",
"type": "manager"
},
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "dotted_line_manager"
}
]
}
Aggiornare o eliminare una relazione
Puoi aggiornare solo il campo relations
perché può essere aggiornato solo nel suo complesso: non puoi rivolgerti alle singole persone elencate per modificare il tipo di relazione o per rimuoverle. Nell'esempio precedente, per rimuovere la relazione con il gestore esistente e impostare il gestore tratteggiato come gestore dell'utente proprietario, aggiorna l'account proprietario con tutti i valori del campo che ora vuoi.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "manager"
}
]
}
Per rimuovere tutte le relazioni dell'utente proprietario, imposta il campo relations
in modo che sia vuoto:
{
"relations": []
}
Recupera un utente
Per recuperare un utente, utilizza la seguente richiesta GET
e includi l'autorizzazione descritta in Autorizzare le richieste. userKey
può essere l'indirizzo email principale dell'utente, l'utente unico id
o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey
Questo esempio restituisce le proprietà dell'account utente dell'utente il cui indirizzo email principale o alias è liz@example.com:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
Risposta JSON
Una risposta corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce le proprietà per l'account utente.
{ "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "name": { "givenName": "Liz", "familyName": "Smith", "fullName": "Liz Smith" }, "isAdmin": true, "isDelegatedAdmin": false, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "addresses": [ { "type": "work", "customType": "", "streetAddress": "1600 Amphitheatre Parkway", "locality": "Mountain View", "region": "CA", "postalCode": "94043" } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "organizations": [ { "name": "Google Inc.", "title": "SWE", "primary": true, "customType": "", "description": "Software engineer" } ], "phones": [ { "value": "+1 nnn nnn nnnn", "type": "work" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }
Recupera tutti gli utenti in un dominio
Per recuperare tutti gli utenti nello stesso dominio, utilizza la seguente richiesta GET
e includi l'autorizzazione descritta in Autorizzare le richieste. Per la leggibilità, in questo esempio vengono utilizzati i ritorni a riga:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=email, givenName, or familyName:the query's value*
Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
Risposta JSON
In questo esempio, vengono restituiti tutti gli utenti del dominio example.com con un massimo di 2 domini utente per pagina di risposta. In questa risposta è presente un nextPageToken
per l'elenco di utenti successivi. Per impostazione predefinita, il sistema restituisce un elenco di 100 utenti in ordine alfabetico in base all'indirizzo email dell'utente:
GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2
Una risposta corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce due account utente nel dominio example.com (maxResults=2
):
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "name": { "givenName": "Liz", "familyName": "Smith", "fullName": "Liz Smith" }, "isAdmin": true, "isDelegatedAdmin": false, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "type": "work", "customType": "", "primary": true } ], "addresses": [ { "type": "work", "customType": "", "streetAddress": "1600 Amphitheatre Parkway", "locality": "Mountain View", "region": "CA", "postalCode": "94043" } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "organizations": [ { "name": "Google Inc.", "title": "SWE", "primary": true, "customType": "", "description": "Software engineer" } ], "phones": [ { "value": "+1 nnn nnn nnnn", "type": "work" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "user unique ID", "primaryEmail": "admin2@example.com", "name": { "givenName": "admin", "familyName": "two", "fullName": "admin two" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": true, "suspensionReason": "ADMIN", "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "contractor license number", "type": "custom", "customType": "work" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "admin@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true } ], "nextPageToken": "next page token" }
Recupera tutti gli utenti dell'account
Per recuperare tutti gli utenti in un account che può essere composto da più domini, usa la seguente richiesta GET
e includi l'autorizzazione descritta in Autorizzare le richieste. Per la leggibilità, in questo esempio vengono utilizzati i ritorni a riga:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=user attributes
- La stringa di query
customer
è il valoremy_customer
ocustomerId
. - Utilizza la stringa
my_customer
per rappresentare il valorecustomerId
del tuo account. - In qualità di amministratore rivenditore, utilizza il
customerId
del cliente del rivenditore. PercustomerId
, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupera tutti gli utenti in un dominio. La risposta risultante ha il valorecustomerId
. - La stringa di query
orderBy
facoltativa determina se l'elenco è ordinato in base all'indirizzo email principale, al cognome o al nome dell'utente. Quando usiorderBy
, puoi anche usare la stringa di querysortOrder
per elencare i risultati in ordine crescente o decrescente. - La stringa di query
query
facoltativa consente di eseguire la ricerca in molti campi di un profilo utente, inclusi sia i campi principali sia quelli personalizzati. Consulta Cercare utenti per alcuni esempi.
Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
In questo esempio, un amministratore account richiede che tutti gli utenti dell'account vengano restituiti con una voce utente in ogni pagina di risposta. nextPageToken
rimanda alla pagina successiva dei risultati:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1
In questo esempio, un amministratore rivenditore richiede tutti gli utenti di un account rivenduto che ha il valore customerId
di C03az79cb
.
GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1
Risposta JSON
Una risposta corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce tutti gli utenti di questo account:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "username": "admin2@example.com", "name": { "givenName": "admin", "familyName": "two", "fullName": "admin two" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "another_admin@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "liz@example.com", "name": { "givenName": "Elizabeth", "familyName": "Smith", "fullName": "Elizabeth Smith" }, "isAdmin": false, "isDelegatedAdmin": false, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": false, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "bank" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "test3@example.com", "name": { "givenName": "Tester", "familyName": "Three", "fullName": "Tester Three" }, "isAdmin": false, "isDelegatedAdmin": false, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "test@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "tester3@example.com" ], "nonEditableAliases": [ "third@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "work_admin@example.com", "name": { "givenName": "Admin", "familyName": "Work", "fullName": "Admin Work" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "work_admin@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "my_alias@example.com" ], "nonEditableAliases": [ "other_alias@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true } ], "nextPageToken": "NNNNN" }
Recuperare gli utenti eliminati di recente
Per recuperare tutti gli utenti eliminati nell'arco degli ultimi 20 giorni da un account o da uno dei domini dell'account, utilizza le seguenti richieste GET
e includi l'autorizzazione descritta in Autorizzazione delle richieste. Per annullare l'eliminazione di un utente, vedi Annullare l'eliminazione di un utente.
Per recuperare gli utenti eliminati nell'arco degli ultimi 20 giorni dal dominio principale o da un sottodominio dell'account, utilizza la seguente richiesta GET
. La stringa di query domain
è il nome di dominio principale del dominio. Per le proprietà di richiesta e risposta dell'utente, consulta la documentazione di riferimento API. Per una migliore leggibilità, in questo esempio vengono utilizzati i ritorni a riga:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &showDeleted=trueSe un account ha più domini, puoi recuperare gli utenti eliminati nell'arco degli ultimi 20 giorni dall'intero account utilizzando la seguente richiesta
GET
. Per la leggibilità, in questo esempio vengono utilizzati i ritorni a riga:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page&showDeleted=true
- La stringa di query
customer
è il valoremy_customer
ocustomerId
. - In qualità di amministratore dell'account, utilizza la stringa
my_customer
per rappresentare lecustomerId
del tuo account. - In qualità di amministratore rivenditore, utilizza il
customerId
del cliente del rivenditore. PercustomerId
, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupera tutti gli utenti in un dominio. La risposta risultante ha il valorecustomerId
.
Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
In questo esempio, un amministratore di account richiede l'eliminazione di tutti gli utenti dell'account:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true
Risposta JSON
Una risposta corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce tutti gli utenti dell'account eliminati negli ultimi 20 giorni:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "user1@example.com" }, { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "user3@example.com" } ], "nextPageToken": "token for next page of deleted users" }
Recupera la foto di un utente
L'API recupera la miniatura della foto, ovvero l'ultima foto del profilo Google. Per recuperare l'ultima foto dell'utente, usa la seguente richiesta GET
e includi l'autorizzazione descritta in Autorizzare le richieste. userKey
può essere l'indirizzo email principale dell'utente, l'utente id
o qualsiasi indirizzo email alias dell'utente. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
In questo esempio, viene restituita l'ultima foto di liz@example.com:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
Risposta JSON
Una risposta corretta restituisce un codice di stato HTTP 200.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "mimeType": "the photo mime type", "height": "the photo height in pixels", "width": "the photo width in pixels", "photoData": "web safe base64 encoded photo data" }
La codifica Base64 delle foto dell'API è simile a quella del documento RFC 4648 "base64url". Ciò significa che:
- Il carattere barra (/) viene sostituito dal trattino basso (_).
- Il segno più (+) è sostituito dal trattino (-).
- Il segno di uguale (=) viene sostituito dall'asterisco (*).
- Per la spaziatura interna, viene utilizzato il carattere punto (.) al posto della definizione baseURL di RFC-4648, che usa il segno uguale (=) per la spaziatura interna. Ciò viene fatto per semplificare l'analisi degli URL.
- Qualunque siano le dimensioni della foto caricata, l'API la ridimensiona proporzionalmente a 96 x 96 pixel.
Se devi creare link compatibili da JavaScript, la libreria Google Closure include le funzioni di codifica e decodifica Base64 rilasciate con la licenza Apache.
Recuperare un utente come non amministratore
Mentre gli account utente possono essere modificati solo dagli amministratori, qualsiasi utente del dominio può leggere i profili utente. Un utente non amministratore può effettuare una richiesta users.get
o users.list
con il parametro viewType
uguale a domain_public
per recuperare il profilo pubblico di un utente. L'ambito https://www.googleapis.com/auth/admin.directory.user.readonly
è ideale per questo caso d'uso.
La vista domain_public
consente a un utente non amministratore di accedere a un insieme standard di campi principali. Per un campo personalizzato, puoi scegliere se deve essere pubblico o privato quando definisci lo schema.
Aggiornare la foto di un utente
Per aggiornare la foto di un utente, utilizza la seguente richiesta PUT
e includi l'autorizzazione descritta in Autorizzare le richieste. userKey
può essere l'indirizzo email principale dell'utente, l'utente id
o qualsiasi indirizzo email degli alias utente. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
In questo esempio, la foto liz@example.com viene aggiornata:
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}
Quando aggiorni una foto, i height
e le width
vengono ignorati dall'API.
Risposta JSON
Una risposta corretta restituisce un codice di stato HTTP 200.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "mimeType": "the photo mime type", "height": "the photo height in pixels", "width": "the photo width in pixels", "photoData": "web safe base64 encoded photo data" }
Eliminare la foto di un utente
Per eliminare la foto di un utente, utilizza la seguente richiesta DELETE
e includi l'autorizzazione descritta in Autorizzare le richieste. userKey
può essere l'indirizzo email principale dell'utente, l'utente id
o qualsiasi indirizzo email degli alias utente. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
Una volta eliminata, la foto dell'utente non viene più visualizzata. Ogni volta che è richiesta la foto di un utente, verrà mostrata una sagoma.
Eliminare un account utente
Per eliminare un account utente, utilizza la seguente richiesta DELETE
e includi l'autorizzazione descritta in Autorizzare le richieste. userKey
può essere l'indirizzo email principale dell'utente, l'utente unico id
o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey
In questo esempio, l'account utente liz@example.com viene eliminato:
DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
Una risposta corretta restituisce solo un codice di stato HTTP 200.
Aspetti importanti da considerare prima di eliminare un utente:
- L'utente eliminato non potrà più accedere.
- Per ulteriori informazioni sull'eliminazione degli account utente, consulta il Centro assistenza per l'amministrazione.
Annullare l'eliminazione di un account utente
Un utente eliminato negli ultimi 20 giorni deve soddisfare determinate condizioni prima che l'account possa essere ripristinato.
Per annullare l'eliminazione di un account utente, utilizza la seguente richiesta POST
e includi l'autorizzazione descritta in Autorizzare le richieste. userKey
è l'utente unico id
trovato nella risposta all'operazione Recupera gli utenti eliminati negli ultimi 20 giorni. L'indirizzo email principale dell'utente o uno degli indirizzi email alias dell'utente non può essere utilizzato in userKey
per questa operazione. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete
In questo esempio, l'eliminazione dell'utente liz@example.com viene annullata. Tutte le proprietà dell'account precedenti di questo utente vengono ripristinate:
POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete
Una risposta corretta restituisce solo un codice di stato HTTP 204. Per visualizzare l'account dell'utente non eliminato, utilizza l'operazione Recupera un utente.