REST Resource: users

Risorsa: utente

L'API Directory consente di creare e gestire gli utenti, gli alias utente e le foto del profilo Google del tuo account. Per ulteriori informazioni sulle attività comuni, consulta la Guida per gli sviluppatori degli account utente e la Guida per gli sviluppatori degli alias utente.

Rappresentazione JSON 
{
  "id": string,
  "primaryEmail": string,
  "password": value,
  "hashFunction": string,
  "isAdmin": boolean,
  "isDelegatedAdmin": boolean,
  "agreedToTerms": boolean,
  "suspended": boolean,
  "changePasswordAtNextLogin": boolean,
  "ipWhitelisted": boolean,
  "name": {
    object (UserName)
  },
  "kind": string,
  "etag": string,
  "emails": value,
  "externalIds": value,
  "relations": value,
  "aliases": [
    string
  ],
  "isMailboxSetup": boolean,
  "customerId": string,
  "addresses": value,
  "organizations": value,
  "lastLoginTime": string,
  "phones": value,
  "suspensionReason": string,
  "thumbnailPhotoUrl": string,
  "languages": value,
  "posixAccounts": value,
  "creationTime": string,
  "nonEditableAliases": [
    string
  ],
  "sshPublicKeys": value,
  "notes": value,
  "websites": value,
  "locations": value,
  "includeInGlobalAddressList": boolean,
  "keywords": value,
  "deletionTime": string,
  "gender": value,
  "thumbnailPhotoEtag": string,
  "ims": value,
  "customSchemas": value,
  "isEnrolledIn2Sv": boolean,
  "isEnforcedIn2Sv": boolean,
  "archived": boolean,
  "orgUnitPath": string,
  "recoveryEmail": string,
  "recoveryPhone": string
}
Campi
id

string

L'ID univoco dell'utente. Un utente id può essere utilizzato come URI della richiesta dell'utente userKey.
primaryEmail

string

L'indirizzo email principale dell'utente. Questa proprietà è obbligatoria in una richiesta per creare un account utente. primaryEmail deve essere univoco e non può essere un alias di un altro utente.
password

value (Value format)

Memorizza la password dell'account utente. Il valore della password dell'utente è obbligatorio al momento della creazione di un account utente. È facoltativo quando si aggiorna un utente e deve essere fornito solo se l'utente sta aggiornando la password dell'account. Il valore della password non viene mai restituito nel corpo della risposta dell'API.

Una password può contenere qualsiasi combinazione di caratteri ASCII e deve avere una lunghezza compresa tra 8 e 100 caratteri.

Ti consigliamo di inviare il parametro password come valore hash con codifica esadecimale e di impostare hashFunction di conseguenza. Se hashFunction è specificato, la password deve essere una chiave hash valida.
hashFunction

string

Archivia il formato hash della proprietà password. Sono consentiti i seguenti valori di hashFunction:

  • MD5: accetta valori con codifica esadecimale semplice.
  • SHA-1: accetta valori con codifica esadecimale semplice.
  • crypt - Conforme alla libreria di crittografia C. Supporta gli algoritmi di hash DES, MD5 (prefisso hash $1$), SHA-256 (prefisso hash $5$) e SHA-512 (prefisso hash $6$).

Se gli arrotondamenti sono specificati come parte del prefisso, devono essere al massimo 10.000.
isAdmin

boolean

Solo output. Indica un utente con privilegi di super amministratore. La proprietà isAdmin può essere modificata solo nell'operazione Imposta un utente come amministratore ( metodo makeAdmin). Se modificata nei metodi insert o update dell'utente, la modifica viene ignorata dal servizio API.
isDelegatedAdmin

boolean

Solo output. Indica se l'utente è un utente con delega di amministratore.
Gli amministratori delegati sono supportati dall'API, ma non possono creare o annullare l'eliminazione di utenti né impostare gli utenti come amministratori. Queste richieste vengono ignorate dal servizio API.
I ruoli e i privilegi per gli amministratori vengono assegnati mediante la Console di amministrazione.
agreedToTerms

boolean

Solo output. Questa proprietà è true se l'utente ha completato l'accesso iniziale e accettato il contratto relativo ai Termini di servizio.
suspended

boolean

Indica se l'utente è sospeso.
changePasswordAtNextLogin

boolean

Indica se l'utente è costretto a cambiare la password all'accesso successivo. Questa impostazione non si applica se l'utente accede tramite un provider di identità di terze parti.
ipWhitelisted

boolean

Se true, l'indirizzo IP dell'utente è soggetto a una configurazione dell'indirizzo IP allowlist deprecata.
name

object (UserName)

Contiene il nome assegnato e la famiglia dell'utente e il valore fullName di sola lettura. Il numero massimo di caratteri nei valori givenName e familyName è 60. Inoltre, i valori del nome supportano i caratteri Unicode/UTF-8 e possono contenere spazi, lettere (a-z), numeri (0-9), trattini (-), barre (/) e punti (.). Per ulteriori informazioni sulle regole di utilizzo dei caratteri, visita il Centro assistenza per l'amministrazione. La dimensione massima consentita dei dati per questo campo è 1 kB.
kind

string

Solo output. Il tipo di risorsa API. Per le risorse Utenti, il valore è admin#directory#user.
etag

string

Solo output. ETag della risorsa.
emails

value (Value format)

L'elenco degli indirizzi email dell'utente. La dimensione massima consentita dei dati è 10 kB.

Campi

emails[].address

string

L'indirizzo email dell'utente. Serve anche da ID email. Questo valore può essere l'indirizzo email principale o un alias dell'utente.

emails[].customType

string

Se l'indirizzo email type è custom, questa proprietà contiene il valore personalizzato e deve essere impostato.

emails[].primary

boolean

Indica se questo è l'indirizzo email principale dell'utente. È possibile contrassegnare una sola voce come principale.

emails[].type

string

Il tipo di account email. Se il criterio viene impostato su custom, è necessario impostare anche customType.

Valori accettati: custom, home, other, work.
externalIds

value (Value format)

L'elenco di ID esterni dell'utente, ad esempio un ID dipendente o di rete. La dimensione massima consentita dei dati è 2 kB.

Campi

externalIds[].customType

string

Se l'ID esterno type è custom, questa proprietà contiene il valore personalizzato e deve essere impostato.

externalIds[].type

string

Il tipo di ID esterno. Se impostato su custom, è necessario impostare anche customType.

Valori accettati: account, custom, customer, login_id, network, organization.

externalIds[].value

string

Il valore dell'ID esterno.
relations

value (Value format)

L'elenco delle relazioni dell'utente con altri utenti. La dimensione massima consentita dei dati per questo campo è 2 kB. Per saperne di più, vedi Gestire gli account utente.

Campi

relations[].customType

string

Se la relazione type è custom, questa proprietà contiene il valore personalizzato e deve essere impostata.

relations[].type

string

Il tipo di relazione. Se impostato su custom, è necessario impostare anche customType.

Valori accettati:
  • admin_assistant
  • assistant
  • brother
  • child
  • custom
  • domestic_partner
  • dotted_line_manager
  • exec_assistant
  • father
  • friend
  • manager
  • mother
  • parent
  • partner
  • referred_by
  • relative
  • sister
  • spouse

relations[].value

string

L'indirizzo email della persona a cui è correlato l'utente.
aliases[]

string

Solo output. L'elenco degli indirizzi email alias dell'utente.
isMailboxSetup

boolean

Solo output. Indica se la casella di posta Google dell'utente è stata creata. Questa proprietà è applicabile solo se all'utente è stata assegnata una licenza Gmail.
customerId

string

Solo output. L'ID cliente per recuperare tutti gli utenti dell'account.
Puoi utilizzare l'alias my_customer per rappresentare customerId del tuo account.
In qualità di amministratore del rivenditore, puoi utilizzare customerId dell'account del cliente del rivenditore. Per ottenere un customerId, utilizza il dominio principale dell'account nel parametro domain di una richiesta users.list.
addresses

value (Value format)

L'elenco degli indirizzi dell'utente. La dimensione massima consentita dei dati è 10 kB.

Campi

addresses[].country

string

Paese:.

addresses[].countryCode

string

Il codice del paese. Utilizza lo standard ISO 3166-1.

addresses[].customType

string

Se l'indirizzo type è custom, questa proprietà contiene il valore personalizzato e deve essere impostato.

addresses[].extendedAddress

string

Per gli indirizzi estesi, ad esempio un indirizzo che include una sottoregione.

addresses[].formatted

string

Un indirizzo postale completo e non strutturato. Questa azione non viene sincronizzata con i campi dell'indirizzo strutturato. Include i seguenti attributi: via, indirizzo postale casella, città, stato/provincia, codice postale, paese/regione.

addresses[].locality

string

La città dell'indirizzo.

addresses[].poBox

string

La casella postale, se presente.

addresses[].postalCode

string

Il CAP o il codice postale, se applicabile.

addresses[].primary

boolean

Se questo è l'indirizzo principale dell'utente. L'elenco di indirizzi può contenere un solo indirizzo principale.

addresses[].region

string

La provincia o lo stato abbreviato.

addresses[].sourceIsStructured

boolean

Indica se l'indirizzo fornito dall'utente è stato formattato. Gli indirizzi formattati non sono attualmente supportati.

addresses[].streetAddress

string

La via, ad esempio 1600 Amphitheatre Parkway. Lo spazio vuoto all'interno della stringa viene ignorato; ma i ritorni a capo sono significativi.

addresses[].type

string

Il tipo di indirizzo. Se il criterio viene impostato su custom, è necessario impostare anche customType.

Valori accettati: custom, home, other, work.
organizations

value (Value format)

L'elenco delle organizzazioni a cui appartiene l'utente. La dimensione massima consentita dei dati è 10 kB.

Campi

organizations[].costCenter

string

Il centro di costo dell'organizzazione dell'utente.

organizations[].customType

string

Se il valore del tipo è personalizzato, questa proprietà contiene il tipo personalizzato.

organizations[].department

string

Specifica il reparto all'interno dell'organizzazione, ad esempio sales o engineering.

organizations[].description

string

La descrizione dell'organizzazione.

organizations[].domain

string

Il dominio a cui appartiene l'organizzazione.

organizations[].fullTimeEquivalent

integer

Il millipercento equivalente a tempo pieno all'interno dell'organizzazione (100.000 = 100%).

organizations[].location

string

La località fisica dell'organizzazione. Non deve essere necessariamente un indirizzo completo.

organizations[].name

string

Il nome dell'organizzazione.

organizations[].primary

boolean

Indica se questa è l'organizzazione principale dell'utente. Un utente può avere una sola organizzazione principale.

organizations[].symbol

string

Simbolo della stringa di testo dell'organizzazione. Ad esempio, il simbolo di testo di Google è GOOG.

organizations[].title

string

Il titolo dell'utente all'interno dell'organizzazione. Ad esempio, member o engineer.

organizations[].type

string

Il tipo di organizzazione.

Valori accettati: domain_only, school, unknown, work.
lastLoginTime

string

Solo output. L'ultima volta che l'utente ha eseguito l'accesso all'account. Il valore è nel formato di data e ora ISO 8601. L'ora è la data completa più ore, minuti e secondi nel modulo YYYY-MM-DDThh:mm:ssTZD. Ad esempio: 2010-04-05T17:30:04+01:00.
phones

value (Value format)

Un elenco dei numeri di telefono dell'utente. La dimensione massima consentita dei dati è 1 kB.

Campi

phones[].customType

string

Se il numero di telefono type è custom, questa proprietà contiene il valore personalizzato e deve essere impostato.

phones[].primary

boolean

Se true, si tratta del numero di telefono principale dell'utente. Un utente può avere un solo numero di telefono principale.

phones[].type

string

Il tipo di numero di telefono. Se impostato su custom, è necessario impostare anche customType.

Valori accettati: assistant, callback, car, company_main, custom, grand_central, home, home_fax, isdn, main, mobile, other, other_fax, pager, radio, telex, tty_tdd, work, work_mobile, work_mobile.work_faxwork_pager

phones[].value

string

Un numero di telefono leggibile. Può avere qualsiasi formato di numero di telefono.
suspensionReason

string

Solo output. Indica il motivo per cui un account utente è stato sospeso dall'amministratore o da Google al momento della sospensione. La proprietà viene restituita solo se la proprietà suspended è true.
thumbnailPhotoUrl

string

Solo output. L'URL della foto del profilo dell'utente. L'URL potrebbe essere temporaneo o privato.
languages

value (Value format)

L'elenco delle lingue dell'utente. La dimensione massima consentita dei dati è 1 kB.

Campi

languages[].customLanguage

string

Altra lingua. L'utente può fornire il proprio nome per la lingua se non esiste un codice lingua ISO 639 corrispondente. Se questo criterio è impostato, languageCode non può essere impostato.

languages[].languageCode

string

Rappresentazione stringa ISO 639 di una lingua. Consulta Codici lingua per l'elenco dei codici supportati. L'API accetta codici lingua validi non compresi nel set supportato, ma potrebbero causare comportamenti imprevisti. I valori non validi causano SchemaException. Se questo criterio è impostato, customLanguage non può essere impostato.

languages[].preference

string

(Facoltativo) Se presente, consente di stabilire se il valore languageCode specificato è la lingua preferita dell'utente. Se il criterio customLanguage è impostato, non è possibile farlo. I valori consentiti sono preferred e not_preferred.
posixAccounts

value (Value format)

L'elenco di dati dell'account POSIX per l'utente.

Campi

posixAccounts[].accountId

string

Un identificatore del campo dell'account POSIX.

posixAccounts[].gecos

string

Le informazioni utente (GECOS) per questo account.

posixAccounts[].gid

unsigned long

L'ID gruppo predefinito.

posixAccounts[].homeDirectory

string

Il percorso della home directory per questo account.

posixAccounts[].operatingSystemType

string

Il tipo di sistema operativo per questo account.

Valori accettati: linux, unspecified, windows.

posixAccounts[].primary

boolean

Se si tratta dell'account principale dell'utente all'interno di SystemId.

posixAccounts[].shell

string

Il percorso alla shell di accesso per questo account.

posixAccounts[].systemId

string

Identificatore di sistema a cui si applicano il nome utente o l'ID utente dell'account.

posixAccounts[].uid

unsigned long

L'ID utente conforme a POSIX.

posixAccounts[].username

string

Il nome utente dell'account.
creationTime

string

Solo output. L'ora in cui è stato creato l'account dell'utente. Il valore è nel formato di data e ora ISO 8601. L'ora è la data completa più ore, minuti e secondi nel modulo YYYY-MM-DDThh:mm:ssTZD. Ad esempio: 2010-04-05T17:30:04+01:00.
nonEditableAliases[]

string

Solo output. L'elenco degli indirizzi email alias non modificabili dell'utente. In genere si trovano al di fuori del dominio o sottodominio principale dell'account.
sshPublicKeys

value (Value format)

Un elenco di chiavi pubbliche SSH.

Campi

sshPublicKeys[].expirationTimeUsec

long

Scadenza in microsecondi dall'epoca.

sshPublicKeys[].fingerprint

string

Un'impronta SHA-256 della chiave pubblica SSH. (Sola lettura)

sshPublicKeys[].key

string

Una chiave pubblica SSH.
notes

value (Value format)

Note per l'utente come oggetto nidificato.

Campi

notes.contentType

string

Tipo di contenuti della nota, testo normale o HTML. Il valore predefinito è testo normale.

Valori accettati: text_plain, text_html.

notes.value

string

Contenuti delle note.
websites

value (Value format)

L'elenco dei siti web dell'utente.

Campi

websites[].customType

string

Se il sito web type è custom, questa proprietà contiene il valore personalizzato e deve essere impostato.

websites[].primary

boolean

Se true, si tratta del sito web principale dell'utente.

websites[].type

string

Il tipo o lo scopo del sito web. Ad esempio, un sito web potrebbe essere etichettato come home o blog. In alternativa, una voce può avere un tipo custom. Se impostato su custom, è necessario impostare anche customType.

Valori accettati: app_install_page, blog, custom, ftp, home, home_page, other, profile, reservations, resume, work.

websites[].value

string

L'URL del sito web.
locations

value (Value format)

L'elenco delle località dell'utente. La dimensione massima consentita dei dati è 10 kB.

Campi

locations[].area

string

Posizione testuale. Questa è particolarmente utile ai fini della visualizzazione per descrivere in modo conciso la posizione. Ad esempio, Mountain View, CA o Near Seattle.

locations[].buildingId

string

Identificatore edificio.

locations[].customType

string

Se la località type è custom, questa proprietà contiene il valore personalizzato e deve essere impostata.

locations[].deskCode

string

Codice testuale più specifico della singola posizione della scrivania.

locations[].floorName

string

Nome/numero del piano.

locations[].floorSection

string

Sezione del piano. Posizione più specifica all'interno del piano. Ad esempio, se un prezzo minimo è suddiviso nelle sezioni A, B e C, questo campo identificherà uno di questi valori.

locations[].type

string

Il tipo di località. Se impostato su custom, è necessario impostare anche customType.

Valori accettati: custom, default, desk.
includeInGlobalAddressList

boolean

Indica se il profilo dell'utente è visibile nell'elenco indirizzi globale di Google Workspace quando la funzionalità di condivisione dei contatti è attivata per il dominio. Per ulteriori informazioni sull'esclusione di profili utente, consulta il Centro assistenza per l'amministrazione.
keywords

value (Value format)

L'elenco di parole chiave dell'utente. La dimensione massima consentita dei dati è 1 kB.

Campi

keywords[].customType

string

Se la parola chiave type è custom, questa proprietà contiene il valore personalizzato e deve essere impostata.

keywords[].type

string

Ogni voce può avere un tipo che indica il tipo standard di quella voce.

Ad esempio, la parola chiave potrebbe essere di tipo occupation o outlook. Oltre al tipo standard, una voce può avere un tipo custom e assegnarle un nome qualsiasi. Se il criterio viene impostato su custom, è necessario impostare anche customType.

Valori accettati: custom, mission, occupation, outlook.

keywords[].value

string

Parola chiave.
deletionTime

string

Solo output. L'ora in cui l'account dell'utente è stato eliminato. Il valore è nel formato di data e ora ISO 8601. L'ora è la data completa più ore, minuti e secondi nel modulo YYYY-MM-DDThh:mm:ssTZD. Ad esempio 2010-04-05T17:30:04+01:00.
gender

value (Value format)

Un oggetto nidificato contenente il genere dell'utente. La dimensione massima consentita dei dati per questo campo è 1 kB.

Campi

gender.addressMeAs

string

Una stringa leggibile contenente il modo corretto per indicare da persone il proprietario del profilo, ad esempio "lui/lui" o "loro/loro".

gender.customGender

string

Nome di un genere personalizzato.

gender.type

string

 Il tipo di genere.

Valori accettati:
  • female
  • male
  • other
  • unknown

thumbnailPhotoEtag

string

Solo output. ETag della foto dell'utente (sola lettura)
ims

value (Value format)

Gli account di messaggistica immediata (IM) dell'utente. Un account utente può avere più proprietà ims, ma solo una di queste proprietà ims può essere il contatto principale per la messaggistica immediata.

Campi

ims[].customProtocol

string

Se il valore del protocollo è custom_protocol, questa proprietà contiene la stringa del protocollo personalizzato.

ims[].customType

string

Se type di messaggistica immediata è custom, questa proprietà contiene il valore personalizzato e deve essere impostato.

ims[].im

string

L'ID rete di messaggistica immediata dell'utente.

ims[].primary

boolean

Se si tratta dell'IM principale dell'utente. Solo una voce nell'elenco di messaggistica immediata può avere il valore true.

ims[].protocol

string

 Un protocollo IM identifica la rete IM. Il valore può essere una rete personalizzata o la rete standard.

Valori accettati:
  • aim: protocollo AOL Instant Messenger
  • custom_protocol: un protocollo di rete di messaggistica immediata personalizzato
  • gtalk: protocollo di Google Talk
  • icq: protocollo ICQ
  • jabber: protocollo Jabber
  • msn: protocollo MSN Messenger
  • net_meeting: protocollo Net Meeting
  • qq: protocollo QQ
  • skype: protocollo Skype
  • yahoo: protocollo Yahoo Messenger

ims[].type

string

Il tipo di account di messaggistica immediata. Se il criterio viene impostato su custom, è necessario impostare anche customType.

Valori accettati: custom, home, other, work.
customSchemas

value (Value format)

Campi personalizzati dell'utente. La chiave è una schemaName e i suoi valori sono 'fieldName': 'field_value'.

  • customSchemas.(key) è un oggetto nidificato.
  • customSchemas.(key).(key) può essere qualsiasi valore.
isEnrolledIn2Sv

boolean

Solo output. È registrato per la verifica in due passaggi (sola lettura)
isEnforcedIn2Sv

boolean

Solo output. È applicata la verifica in due passaggi (sola lettura)
archived

boolean

Indica se l'utente è archiviato.
orgUnitPath

string

Il percorso completo dell'organizzazione principale associata all'utente. Se l'organizzazione principale è l'organizzazione di primo livello, è rappresentata da una barra (/).
recoveryEmail

string

Email di recupero dell'utente.
recoveryPhone

string

Numero di telefono di recupero dell'utente. Il numero di telefono deve essere nel formato E.164 e deve iniziare con il segno più (+). Esempio: +16506661212.

UserName

Rappresentazione JSON 
{
  "fullName": string,
  "familyName": string,
  "givenName": string,
  "displayName": string
}
Campi
fullName

string

Il nome completo dell'utente formato concatenando i valori del nome e del cognome.
familyName

string

Il cognome dell'utente. Obbligatorio durante la creazione di un account utente.
givenName

string

Il nome dell'utente. Obbligatorio durante la creazione di un account utente.
displayName

string

Il nome visualizzato dell'utente. Limite: 256 caratteri.

Metodi

delete

 Elimina un utente.

get

 Recupera un utente.

insert

 Crea un utente.

list

 Recupera un elenco impaginato degli utenti eliminati o di tutti gli utenti di un dominio.

makeAdmin

 Imposta un utente come super amministratore.

patch

 Aggiorna un utente utilizzando la semantica della patch.

signOut

 Disconnette un utente da tutte le sessioni web e sul dispositivo e reimposta i cookie di accesso.

undelete

 Annulla l'eliminazione di un utente eliminato.

update

 Aggiorna un utente.

watch

 Rileva le modifiche nell'elenco di utenti.