REST Resource: users

Risorsa: Utente

L'API Directory ti consente di creare e gestire gli utenti del tuo account, gli alias utente e le foto del profilo Google degli utenti. Per ulteriori informazioni sulle operazioni comuni, consulta la Guida per gli sviluppatori relativi agli account utente e la Guida per gli sviluppatori 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 userKey della richiesta dell'utente.

primaryEmail

string

L'indirizzo email principale dell'utente. Questa proprietà è obbligatoria in una richiesta per creare un account utente. Il 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 durante la creazione di un account utente. Questa opzione è facoltativa durante l'aggiornamento di un utente e deve essere fornita solo se l'utente sta aggiornando la password del proprio 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

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

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

Se i cicli vengono specificati come parte del prefisso, non devono superare i 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 viene 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.
L'API supporta gli utenti con delega di amministratore, ma non può creare o annullare l'eliminazione degli utenti né assegnare loro un ruolo di amministratore. 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 un accesso iniziale e ha accettato il contratto relativo ai Termini di servizio.

suspended

boolean

Indica se l'utente è sospeso.

changePasswordAtNextLogin

boolean

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

ipWhitelisted

boolean

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

name

object (UserName)

Contiene il nome e la famiglia dell'utente, oltre al 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 gli amministratori. La dimensione massima dei dati consentita 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 per i dati è 10 kB.

Campi

emails[].address

string

L'indirizzo email dell'utente. Serve anche come 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 si tratta dell'indirizzo email principale dell'utente. Solo una voce può essere contrassegnata 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 dipendente o un ID rete. La dimensione massima consentita per i 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 il criterio viene 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 dei dati consentita 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 il criterio viene 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 degli 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 rivenditore, puoi utilizzare l'account del cliente del rivenditore customerId. 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 per i 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. Non viene sincronizzato con i campi dell'indirizzo strutturato. Include i seguenti attributi: via, casella postale, 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 si tratta dell'indirizzo principale dell'utente. L'elenco degli 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 di organizzazioni a cui appartiene l'utente. La dimensione massima consentita per i dati è 10 kB.

Campi

organizations[].costCenter

string

Il centro di costo dell'organizzazione dell'utente.

organizations[].customType

string

Se il valore di 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 un indirizzo completo.

organizations[].name

string

Il nome dell'organizzazione.

organizations[].primary

boolean

Indica se si tratta dell'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 per Google è GOOG.

organizations[].title

string

La qualifica 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 al suo account. Il valore è nel formato di data e ora ISO 8601. L'ora corrisponde alla data completa più ore, minuti e secondi nel formato 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 per i dati è 1 kB.

Campi

phones[].customType

string

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

phones[].primary

boolean

Se true, è il 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 il criterio viene 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_fax.work_mobilework_pager

phones[].value

string

Un numero di telefono leggibile. Può essere in qualsiasi formato di numero di telefono.

suspensionReason

string

Solo output. Riporta 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 per i dati è 1 kB.

Campi

languages[].customLanguage

string

Altra lingua. L'utente può fornire il proprio nome lingua se non esiste un codice lingua ISO 639 corrispondente. Se questa impostazione è impostata, non è possibile impostare languageCode.

languages[].languageCode

string

Rappresentazione stringa ISO 639 di una lingua. Consulta la sezione Codici lingua per l'elenco dei codici supportati. L'API accetta codici lingua validi al di fuori dell'insieme supportato, ma possono causare comportamenti imprevisti. I valori non consentiti causano SchemaException. Se questa impostazione è impostata, non è possibile impostare customLanguage.

languages[].preference

string

Campo facoltativo. Se presente, consente di stabilire se la lingua languageCode specificata è quella preferita dall'utente. Se il criterio customLanguage è impostato, non è possibile impostare questa opzione. I valori consentiti sono preferred e not_preferred.

posixAccounts

value (Value format)

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

Campi

posixAccounts[].accountId

string

Un identificatore del campo dell'account POSIX.

posixAccounts[].gecos

string

Il GECOS (informazioni utente) per questo account.

posixAccounts[].gid

unsigned long

L'ID gruppo predefinito.

posixAccounts[].homeDirectory

string

Il percorso alla home directory per questo account.

posixAccounts[].operatingSystemType

string

Il tipo di sistema operativo di questo account.

Valori accettati: linux, unspecified, windows.

posixAccounts[].primary

boolean

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

posixAccounts[].shell

string

Il percorso della shell di accesso per questo account.

posixAccounts[].systemId

string

Identificatore di sistema a cui si applica il nome utente o l'Uid 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 di creazione dell'account dell'utente. Il valore è nel formato di data e ora ISO 8601. L'ora corrisponde alla data completa più ore, minuti e secondi nel formato YYYY-MM-DDThh:mm:ssTZD. Ad esempio: 2010-04-05T17:30:04+01:00.

nonEditableAliases[]

string

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

sshPublicKeys

value (Value format)

Un elenco di chiavi pubbliche SSH.

Campi

sshPublicKeys[].expirationTimeUsec

long

Una 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 contenuto della nota: testo normale o HTML. L'impostazione predefinita è 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, è il 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 il criterio viene impostato su custom, è necessario impostare anche customType.

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

websites[].value

string

L'URL del sito web.

locations

value (Value format)

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

Campi

locations[].area

string

Posizione testuale. Questa opzione è più utile a fini di visualizzazione per descrivere concisamente la località. Ad esempio, Mountain View, CA o Near Seattle.

locations[].buildingId

string

Identificatore dell'edificio.

locations[].customType

string

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

locations[].deskCode

string

Il 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 piano viene diviso nelle sezioni A, B e C, questo campo identificherebbe uno di questi valori.

locations[].type

string

Il tipo di località. Se il criterio viene 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 è abilitata per il dominio. Per ulteriori informazioni sull'esclusione di profili utente, consulta il Centro assistenza per gli amministratori.

keywords

value (Value format)

L'elenco di parole chiave dell'utente. La dimensione massima consentita per i 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 della 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 assegnare qualsiasi nome. 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 corrisponde alla data completa più ore, minuti e secondi nel formato 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 dei dati consentita per questo campo è 1 kB.

Campi

gender.addressMeAs

string

Una stringa leggibile da una persona che contiene il modo corretto per fare riferimento al proprietario del profilo, ad esempio "lui/suo" o "loro/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 di chat.

Campi

ims[].customProtocol

string

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

ims[].customType

string

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

ims[].im

string

L'ID di rete IM dell'utente.

ims[].primary

boolean

Se si tratta del messaggio di chat principale dell'utente. Solo una voce nell'elenco di IM 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 IM personalizzato
  • gtalk: protocollo Google Talk
  • icq: protocollo ICQ
  • jabber: protocollo Jabber
  • msn: protocollo MSN Messenger
  • net_meeting: Net Meeting Protocol
  • qq: protocollo QQ
  • skype: protocollo Skype
  • yahoo: protocollo Yahoo Messenger

ims[].type

string

Il tipo di account IM. 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 è 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, iniziando con il segno più (+). Esempio: +16506661212.

UserName

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

string

Nome completo dell'utente formato dalla concatenazione dei valori di nome e 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 del dispositivo e reimposta i cookie di accesso.

undelete

Annulla l'eliminazione di un utente eliminato.

update

Consente di aggiornare un utente.

watch

Verifica la presenza di modifiche nell'elenco degli utenti.