Gestire gli account utente

L'API Directory fornisce metodi programmatici per la creazione, l'aggiornamento e l'eliminazione degli utenti. Puoi anche ottenere informazioni su singoli utenti o su elenchi di utenti che soddisfano criteri specifici. Di seguito sono riportati alcuni esempi di operazioni utente di base.

Crea un account utente

Puoi aggiungere un account utente a uno qualsiasi dei domini del tuo account Google Workspace. Prima di aggiungere un account utente, verifica 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 puoi creare nuovi account utente finché non sblocchi impostazioni aggiuntive di Google Workspace. Per informazioni dettagliate, vedi Account email aziendali G Suite aggiornati a G Suite Basic.

Per creare un account utente utilizzando uno dei tuoi domini, utilizza la seguente richiesta POST e includi l'autorizzazione descritta in Scopri di più 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 soddisfare la richiesta. Se utilizzi le librerie client, queste convertono gli oggetti dati della lingua scelta in oggetti JSON formattati.

Richiesta JSON

Il seguente JSON mostra una richiesta di esempio per creare un utente. Per l'elenco completo delle proprietà di richiesta e risposta, consulta il riferimento API. 

{
"primaryEmail": "[email protected]",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "[email protected]",
  "primary": true
 }
],
"emails": [
 {
  "address": "[email protected]",
  "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 delle query per le richieste di creazione è troppo elevata, potresti ricevere risposte HTTP 503 dal server API che indicano che la quota è stata superata. Se ricevi queste risposte, utilizza un algoritmo di backoff esponenziale per riprovare a inviare le richieste.

Ecco alcuni aspetti da tenere presenti in merito a un nuovo account:

  • Se l'Account Google ha acquistato licenze per la posta, al nuovo account utente viene assegnata automaticamente una casella di posta. Il completamento e l'attivazione di questo compito potrebbero richiedere alcuni minuti.
  • La modifica di un campo di sola lettura in una richiesta, ad esempio isAdmin, viene ignorata 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 i servizi Google Workspace a cui ha accesso. Se l'utente viene spostato in una nuova organizzazione, il suo accesso cambia. Per ulteriori informazioni sulle strutture dell'organizzazione, visita il Centro assistenza amministrazione. Per ulteriori informazioni 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 hashFunction, la password deve essere una chiave hash valida. Se non è specificato, la password deve essere in testo normale e avere una lunghezza compresa tra 8 e 100 caratteri ASCII. Per ulteriori informazioni, consulta il riferimento all'API.
  • Per gli utenti con un piano flessibile per Google Workspace, la creazione di utenti utilizzando questa API avrà un impatto monetario e comporterà addebiti sul tuo account di fatturazione del cliente. Per ulteriori informazioni, consulta le informazioni di fatturazione dell'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 i servizi con gli utenti di altri domini dell'account. Per saperne di più sugli utenti in più domini, consulta le informazioni sui domini multipli dell'API.
  • Potrebbero essere presenti account in conflitto. Controlla se qualcuno che hai intenzione di aggiungere ha già un Account Google. quindi segui i passaggi per evitare i conflitti con questi account. Leggi l'articolo Individuare e gestire gli account in conflitto.
  • Potrebbero esserci account visitatore. Se gli utenti invitano persone esterne alla tua organizzazione che non dispongono di Account Google a collaborare su Drive, queste riceveranno account visitatore nel formato nome_utente_del_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. e conserverà le sue autorizzazioni attuali per i file di Drive. Vedi Condividere documenti con i visitatori.

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce le proprietà del nuovo account utente.

Aggiornare un account utente

Per aggiornare un account utente, utilizza la seguente richiesta PUT e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. userKey può essere l'indirizzo email principale dell'utente, l'utente univoco 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 quello della risposta contengono un'istanza di User. Tuttavia, l'API Directory supporta la semantica delle patch, quindi devi inviare solo i campi aggiornati nella richiesta.

Richiesta di esempio

Nell'esempio riportato di seguito, il givenName dell'utente era "Elizabeth" quando è stato creato il suo account e è stato fornito solo un indirizzo email di lavoro.

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "[email protected]",
      "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/[email protected]

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    },
    {
      "address": "[email protected]",
      "type": "home"
    }
  ]
}

Una risposta positiva restituisce un codice di stato HTTP 200 e una risorsa User con i campi aggiornati.

Tieni presente quanto segue quando aggiorni il nome dell'account di un utente:

  • La ridenominazione di un account utente modifica l'indirizzo email principale dell'utente e il dominio utilizzato per recuperare le informazioni di questo utente. Prima di rinominare un utente, ti consigliamo di disconnetterlo da tutte le sessioni e da tutti i servizi del browser.
  • La propagazione della ridenominazione di un account utente a tutti i servizi può richiedere fino a 10 minuti.
  • Quando rinomini un utente, il vecchio nome utente viene mantenuto come alias per garantire la continuità del recapito della posta nel 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 permanenti perché è 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 impostare l'utente come super amministratore, utilizza la seguente richiesta POST e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. userKey può essere l'indirizzo email principale dell'utente, l'utente univoco id o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta il riferimento API. Per ulteriori informazioni su un super amministratore, visita il Centro assistenza amministrazione. 

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

Richiesta JSON

In questo esempio, l'utente il cui userKey è [email protected] è diventato un super amministratore: 

POST https://admin.googleapis.com/admin/directory/v1/users/[email protected]/makeAdmin

{
 "status": true
}

Una risposta riuscita restituisce un codice di stato HTTP 200.

Gestire i rapporti con gli utenti

L'API Directory utilizza il campo relations per definire diversi tipi di relazioni tra gli utenti. In un contesto aziendale, questo campo viene spesso utilizzato per i rapporti tra manager e dipendenti e tra assistenti, ma supporta anche molti altri tipi di relazioni. La relazione viene visualizzata nella scheda "Persone correlate" dell'utente in qualsiasi applicazione Google Workspace che supporta la scheda. Per esempi di dove è visibile la scheda, consulta 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. type descrive il rapporto dell'altra persona con l'utente proprietario. Ad esempio, in una relazione amministratore-dipendente, il dipendente è l'utente proprietario e 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. Puoi 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 il campo relations solo nel suo complesso. Non puoi rivolgerti alle singole persone elencate per modificare il tipo di relazione o rimuoverle. Nell'esempio riportato sopra, per rimuovere il rapporto di amministratore esistente e impostare l'amministratore con linee tratteggiate come amministratore dell'utente proprietario, aggiorna l'account dell'utente proprietario con tutti i valori del campo come preferisci.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

Per rimuovere tutte le relazioni dell'utente proprietario, imposta relations su vuoto:

{
  "relations": []
}

Recuperare un utente

Per recuperare un utente, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. userKey può essere l'indirizzo email principale dell'utente, l'utente univoco id o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta il riferimento API. 

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

Questo esempio restituisce le proprietà dell'account utente per l'utente il cui indirizzo email principale o alias è [email protected]: 

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]

Risposta JSON

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce le proprietà dell'account utente. 

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "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": "[email protected]",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "[email protected]",
   "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": [
  "[email protected]",
  "[email protected]"
 ],
 "nonEditableAliases": [
  "[email protected]"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

Recuperare tutti gli utenti di un dominio

Per recuperare tutti gli utenti nello stesso dominio, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. Per favorire la leggibilità, in questo esempio sono stati inseriti dei ritorni a capo. 

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 il riferimento API.

Risposta JSON

In questo esempio, tutti gli utenti del dominio example.com vengono restituiti con un massimo di 2 domini utente per pagina di risposta. In questa risposta è presente un nextPageToken per l'elenco successivo di utenti. Per impostazione predefinita, il sistema restituisce un elenco di 100 utenti nell'ordine alfabetico dell'indirizzo email dell'utente: 

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce 2 account utente nel dominio example.com (maxResults=2): 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]",
   "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": "[email protected]",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "[email protected]",
     "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": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "next page token"
}

Recupera tutti gli utenti dell'account

Per recuperare tutti gli utenti di un account che può essere composto da più domini, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. Per favorire la leggibilità, in questo esempio sono stati inseriti dei ritorni a capo. 

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 valore my_customer o customerId.
  • Utilizza la stringa my_customer per rappresentare il customerId del tuo account.
  • In qualità di amministratore reseller, utilizza il customerId del cliente a cui è stato rivenduto il dominio. Per customerId, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupero di tutti gli utenti in un dominio. La risposta risultante ha il valore customerId.
  • La stringa di query facoltativa orderBy determina se l'elenco è ordinato in base all'indirizzo email principale, al cognome o al nome dell'utente. Quando utilizzi orderBy, puoi anche utilizzare la stringa di query sortOrder per elencare i risultati in ordine crescente o decrescente.
  • La stringa di query facoltativa query consente di eseguire ricerche in molti campi del profilo di un utente, inclusi i campi principali e personalizzati. Per esempi, consulta Cercare utenti.

Per le proprietà di richiesta e risposta, consulta il riferimento API.

In questo esempio, un amministratore dell'account richiede che tutti gli utenti dell'account vengano restituiti con una voce utente in ogni pagina di risposta. nextPageToken passa 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 con il valore customerId di C03az79cb. 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

Risposta JSON

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce tutti gli utenti presenti in questo account: 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "[email protected]"
   ],
   "nonEditableAliases": [
     "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

Recuperare gli utenti eliminati di recente

Per recuperare tutti gli utenti eliminati negli ultimi 20 giorni da un account o da uno dei domini dell'account, utilizza le seguenti richieste GET e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. Per annullare l'eliminazione di un utente, consulta Annullare l'eliminazione di un utente.

Per recuperare gli utenti eliminati negli 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à della richiesta e della risposta utente, consulta il riferimento API. Per favorire la leggibilità, in questo esempio sono stati inseriti dei ritorni a capo: 

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=true
 Se 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 favorire la leggibilità, in questo esempio sono stati inseriti dei ritorni a capo. 
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 valore my_customer o customerId.
  • In qualità di amministratore dell'account, utilizza la stringa my_customer per rappresentare il customerId del tuo account.
  • In qualità di amministratore reseller, utilizza il customerId del cliente a cui è stato rivenduto il dominio. Per customerId, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupero di tutti gli utenti in un dominio. La risposta risultante ha il valore customerId.

Per le proprietà di richiesta e risposta, consulta il riferimento API.

In questo esempio, un amministratore dell'account richiede tutti gli utenti eliminati nell'account: 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true

Risposta JSON

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre 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": "[email protected]"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "[email protected]"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

Recuperare la foto di un utente

L'API recupera una miniatura di una foto, l'ultima foto del profilo di Google. Per recuperare l'ultima foto dell'utente, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. userKey può essere l'indirizzo email principale dell'utente, l'utente id o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta il riferimento API. 

GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

In questo esempio viene restituita l'ultima foto di [email protected]:

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail

Risposta JSON

Una risposta riuscita restituisce un codice di stato HTTP 200. 

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "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 sicura per il web delle foto dell'API è simile a "base64url" di RFC 4648. Ciò significa che:

  • Il carattere barra (/) viene sostituito dal carattere trattino basso (_).
  • Il carattere del segno più (+) viene sostituito con il carattere del trattino (-).
  • Il carattere del segno di uguale (=) viene sostituito dall'asterisco (*).
  • Per il riempimento, viene utilizzato il carattere punto (.) anziché la definizione baseURL RFC-4648 che utilizza il segno di uguale (=) per il riempimento. Questo viene fatto per semplificare l'analisi dell'URL.
  • Indipendentemente dalle 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 funzioni di codifica e decodifica Base64 rilasciate in base alla licenza Apache.

Recuperare un utente come utente non amministratore

Sebbene gli account utente possano essere modificati solo dagli amministratori, qualsiasi utente del dominio può leggere i profili degli utenti. 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 visualizzazione domain_public consente a un utente non amministratore di accedere a un insieme standard di campi di base. Per un campo personalizzato, puoi scegliere se deve essere pubblico o privato durante la definizione dello schema.

Aggiornare la foto di un utente

Per aggiornare la foto di un utente, utilizza la seguente richiesta PUT e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. userKey può essere l'indirizzo email principale dell'utente, l'utente id o uno degli indirizzi email degli alias dell'utente. Per le proprietà di richiesta e risposta, consulta il riferimento API. 

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

In questo esempio, la foto di [email protected] viene aggiornata: 

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail
 
{
"photoData": "web safe base64 encoded photo data"
}

Quando aggiorni una foto, height e width vengono ignorati dall'API.

Risposta JSON

Una risposta riuscita restituisce un codice di stato HTTP 200. 

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "[email protected]",
 "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 nell'articolo relativo all'autorizzazione delle richieste. userKey può essere l'indirizzo email principale dell'utente, l'utente id o uno degli indirizzi email degli alias dell'utente. Per le proprietà di richiesta e risposta, consulta il riferimento API. 

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

Una volta eliminata, la foto dell'utente non viene mostrata. Ovunque sia 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 nell'articolo relativo all'autorizzazione delle richieste. userKey può essere l'indirizzo email principale dell'utente, l'utente univoco id o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta il riferimento API. 

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey

In questo esempio, l'account utente [email protected] viene eliminato: 

DELETE https://admin.googleapis.com/admin/directory/v1/users/[email protected]

Una risposta riuscita restituisce solo un codice di stato HTTP 200.

Aspetti importanti da considerare prima di eliminare un utente:

Annulla l'eliminazione di un account utente

Un utente eliminato negli ultimi 20 giorni deve soddisfare determinate condizioni prima che il suo account possa essere ripristinato.

Per annullare l'eliminazione di un account utente, utilizza la seguente richiesta POST e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. userKey è l'utente univoco id trovato nella risposta all'operazione Recupero degli utenti eliminati negli ultimi 20 giorni. L'indirizzo email principale dell'utente o uno dei suoi indirizzi email alias non può essere utilizzato in userKey per questa operazione. Per le proprietà di richiesta e risposta, consulta il riferimento API. 

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

In questo esempio, l'utente [email protected] viene ripristinato. Tutte le proprietà dell'account precedente dell'utente vengono ripristinate: 

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

Una risposta riuscita restituisce solo un codice di stato HTTP 204. Per visualizzare l'account dell'utente non eliminato, utilizza l'operazione Recupero di un utente.