Gestire gli account utente

L'API Directory fornisce metodi programmatici per creare, aggiornare ed eliminare gli utenti. Puoi anche ottenere informazioni sui singoli utenti o 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, 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 puoi creare nuovi account utente finché non sblocchi le impostazioni aggiuntive di Google Workspace. Per maggiori dettagli, vedi Account email aziendali di Google Workspace aggiornati.

Per creare un account utente utilizzando uno dei tuoi domini, utilizza la seguente POST richiesta 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, vedi il users.insert metodo.

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

Tutte le richieste di creazione richiedono l'invio delle informazioni necessarie per soddisfare la richiesta. Se utilizzi le librerie client, queste convertono gli oggetti dati dalla lingua scelta in oggetti in formato JSON.

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": "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 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.

Quando crei un nuovo account, tieni presente quanto segue:

  • Se l'Account Google ha acquistato licenze di posta, al nuovo account utente viene assegnata automaticamente una casella di posta. L'assegnazione potrebbe richiedere alcuni minuti per essere completata e attivata.
  • La modifica di un campo di sola lettura in una richiesta, ad esempio isAdmin, viene ignorata silenziosamente dal servizio API.
  • Il numero massimo di domini consentiti in un account è 600 (1 dominio principale + 599 domini aggiuntivi).
  • Se a un utente non è stata assegnata 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 l'utente ha accesso. Se l'utente viene spostato in una nuova organizzazione, il suo accesso cambia. Per saperne di più 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 è richiesta una password. Se viene specificata una hashFunction, la password deve essere una chiave hash valida. Se non viene specificata, la password deve essere in dati in chiaro e contenere tra 8 e 100 caratteri ASCII. Per saperne di più, consulta il Riferimento API.
  • Per gli utenti con un piano flessibile per Google Workspace, la creazione di utenti tramite questa API avrà un impatto monetario e comporterà addebiti sull'account di fatturazione del cliente. Per saperne di più, consulta i dati 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 sull'API per più domini.
  • Potrebbero esserci account in conflitto. Controlla se qualche utente che intendi aggiungere ha già un Account Google, quindi segui i passaggi per evitare i conflitti con questi account. Vedi Individuare e gestire gli account in conflitto.
  • Potrebbero esserci account visitatore. Se gli utenti invitano a collaborare su Drive persone esterne all'organizzazione che non hanno un Account Google, a queste ultime verranno assegnati account visitatore con il formato visitor's_username@your_domain.com. Se aggiungi una persona che ha lo stesso nome utente di un account visitatore, l'account viene convertito in un account Google Workspace completo. L'account conserva 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.

Aggiorna un account utente

Per aggiornare un account utente, utilizza la seguente PUT richiesta e includi l' autorizzazione descritta in Autorizzare le richieste. La userKey può essere l'indirizzo email principale dell'utente, l'id utente univoco o uno degli indirizzi email alias dell'utente.

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

Sia il corpo della richiesta sia 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" 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 seguente richiesta aggiorna givenName da "Elizabeth" a "Liz" e aggiunge anche un indirizzo email di casa. Tieni presente che entrambi gli indirizzi email vengono forniti per intero 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 riuscita restituisce un HTTP 200 codice di stato e una User risorsa 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 dell'utente. Prima di rinominare un utente, ti consigliamo di disconnetterlo da tutte le sessioni e i servizi del browser.
  • La propagazione del processo di ridenominazione di un account utente in 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 in caso di impostazioni di inoltro email e non è disponibile come nuovo nome utente.
  • In generale, ti consigliamo anche 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 l'amministrazione.

Imposta un utente come amministratore

Per impostare un utente come super amministratore, utilizza la seguente POST richiesta e includi l'autorizzazione descritta in Autorizzare le richieste. La userKey può essere l'indirizzo email principale dell'utente, l'id utente univoco o uno degli indirizzi email alias dell'utente. Per le proprietà di richiesta e risposta, consulta Riferimento API. Per saperne di più su un super amministratore, consulta il Centro assistenza per l'amministrazione.

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

L'utente deve esistere prima di poter essere impostato come super amministratore. Questa operazione può essere eseguita solo dal super amministratore di un account; gli amministratori delegati non possono promuovere gli utenti a ruoli amministrativi. Per informazioni su come utilizzare la Console di amministrazione Google per modificare il ruolo di un amministratore, consulta il Centro assistenza per l'amministrazione.

Richiesta JSON

In questo esempio, l'utente la 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 riuscita restituisce un codice di stato HTTP 200.

Gestisci le relazioni utente

L'API Directory utilizza il campo relations per definire diversi tipi di relazioni tra gli utenti. In un contesto aziendale, le persone utilizzano comunemente questo campo per le relazioni tra manager e dipendenti e tra 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 supporti la scheda. Per esempi di dove è visibile la scheda, vedi Aggiungere informazioni al profilo della directory di un utente.

Crea 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. Il type descrive la relazione dell'altra persona con l'utente proprietario. Ad esempio, in una relazione tra manager e dipendente, il dipendente è l'utente proprietario e devi aggiungere 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 include il campo relations. Puoi creare più relazioni in un'unica richiesta.

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

Aggiorna o elimina 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 precedente, per rimuovere la relazione di gestione esistente e impostare il manager con la linea tratteggiata come manager dell'utente proprietario, aggiorna l'account dell'utente proprietario con tutti i valori del campo come li vuoi ora.

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

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

{
  "relations": []
}

Recupera un utente

Per recuperare un utente, utilizza la seguente GET richiesta e includi l' autorizzazione descritta in Autorizzare le richieste. La userKey può essere l'indirizzo email principale dell'utente, l'id utente univoco 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 è liz@example.com:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

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": "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 GET richiesta e includi l'autorizzazione descritta in Autorizzare le 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 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 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": "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",
   "suspensionTime": "2013-02-05T10:30:03.325Z",
   "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, utilizza la seguente GET richiesta e includi l'autorizzazione descritta in Autorizzare le 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 rivenditore, utilizza il customerId del cliente rivenduto. Per il customerId, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupera 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 di un profilo utente, inclusi i campi principali e personalizzati. Per esempi, vedi 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. Il 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 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"
}

Recupera 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 GET richieste e includi l'autorizzazione descritta in Autorizzare le 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 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 rivenditore, utilizza il customerId del cliente rivenduto. Per il customerId, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupera 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": "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 una miniatura della foto, l'ultima foto del profilo Google. Per recuperare l'ultima foto dell'utente, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste. La userKey può essere l'indirizzo email principale dell'utente, l'id utente 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 liz@example.com:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail

Risposta JSON

Una risposta riuscita 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 sicura per il web delle tue foto dell'API è simile a RFC 4648 "base64url". Ciò significa che:

  • Il carattere barra (/) viene sostituito dal carattere trattino basso (_).
  • Il carattere segno più (+) viene sostituito dal carattere trattino (-).
  • Il carattere segno uguale (=) viene sostituito dall'asterisco (*).
  • Per il padding, viene utilizzato il carattere punto (.) anziché la definizione baseURL RFC-4648, che utilizza il segno uguale (=) per il padding. Questa operazione viene eseguita per semplificare l'analisi degli 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 con licenza Apache.

Recupera un utente come non amministratore

Sebbene gli account utente possano 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 visualizzazione 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.

Aggiorna 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. La userKey può essere l'indirizzo email principale dell'utente, l'id utente o uno degli indirizzi email 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 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, 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": "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"
}

Elimina 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. La userKey può essere l'indirizzo email principale dell'utente, l'id utente 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/photos/thumbnail

Una volta eliminata, la foto dell'utente non viene visualizzata. Ovunque sia richiesta la foto di un utente, viene visualizzata una silhouette.

Elimina un account utente

Per eliminare un account utente, utilizza la seguente DELETE richiesta e includi l' autorizzazione descritta in Autorizzare le richieste. La userKey può essere l'indirizzo email principale dell'utente, l'id utente univoco 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 liz@example.com viene eliminato:

DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

Una risposta riuscita restituisce un codice di stato HTTP 200.

Prima di eliminare un utente, tieni presente quanto segue:

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 POST richiesta e includi l' autorizzazione descritta in Autorizzare le richieste. Il userKey è l'utente univoco id che si trova nella risposta dell' 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 nella 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'eliminazione dell'utente liz@example.com viene annullata. Vengono ripristinate tutte le proprietà dell'account precedente di questo utente:

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

Una risposta riuscita restituisce un codice di stato HTTP 204. Per visualizzare l'account dell'utente di cui è stata annullata l'eliminazione, utilizza l'operazione Recupera un utente.