Gestisci gruppi

Questa pagina spiega come gestire Google Gruppi con l'API Directory:

  • Crea un gruppo
  • Aggiornare un gruppo
  • Aggiungere un alias di gruppo
  • Recuperare un gruppo
  • Recupera tutti i gruppi per un dominio o l'account
  • Recupera tutti i gruppi di appartenenza di un utente
  • Recupera tutti gli alias di gruppo
  • Eliminare un alias di gruppo
  • Eliminare un gruppo

Crea un gruppo

Per creare un gruppo, utilizza la seguente richiesta POST e includi l'autorizzazione descritta in Autorizzare le richieste. Puoi creare un gruppo per qualsiasi dominio associato all'account. Per le proprietà della stringa di query, della richiesta e della risposta, consulta il metodo groups.insert. 

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

La seguente richiesta JSON mostra un corpo della richiesta di esempio che crea un gruppo. L'indirizzo email del gruppo è sales_group@example.com: 

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

Una risposta riuscita restituisce un codice di stato HTTP 201 e le proprietà del nuovo gruppo.

Aggiornare un gruppo

Per aggiornare le impostazioni di un gruppo, utilizza la seguente richiesta PUT e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. groupKey è l'indirizzo email del gruppo, uno degli indirizzi email dell'alias del gruppo o il id univoco del gruppo. Per le proprietà della stringa di query, della richiesta e della risposta, consulta il metodo groups.update. 

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

In generale, Google consiglia di non utilizzare l'indirizzo email del gruppo come chiave per i dati permanenti perché l'indirizzo email è soggetto a modifiche.

Nell'esempio seguente, il valore groupKey univoco è nnn e il nome del gruppo è APAC Sales Group: 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

Per una richiesta di aggiornamento, devi solo inviare le informazioni aggiornate. Non è necessario inserire tutte le proprietà del gruppo nella richiesta.

Una risposta riuscita restituisce un codice di stato HTTP 201 e le proprietà del nuovo gruppo: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

Aggiungere un alias di gruppo

Per aggiungere un alias di gruppo, utilizza la seguente richiesta POST e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. groupKey è l'indirizzo email del gruppo, uno degli indirizzi email degli alias del gruppo o il id univoco del gruppo. Per le proprietà della stringa di query, della richiesta e della risposta, consulta la risorsa groups. 

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

In generale, Google consiglia di non utilizzare l'indirizzo email del gruppo come chiave per i dati permanenti perché l'indirizzo email è soggetto a modifiche.

La seguente richiesta JSON mostra una richiesta di esempio per creare l'alias di un gruppo. groupKey è il id univoco del gruppo rappresentato da NNNN

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases

{
    "alias": "best_sales_group@example.com"
}

Una risposta riuscita restituisce un codice di stato HTTP 201 e le proprietà del nuovo alias gruppo.

Recuperare un gruppo

Per recuperare un gruppo, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste. groupKey è l'indirizzo email del gruppo, uno degli indirizzi email degli alias del gruppo o il id univoco del gruppo. Per le proprietà della stringa di query, della richiesta e della risposta, consulta il metodo groups.get. 
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

In generale, Google consiglia di non utilizzare l'indirizzo email del gruppo come chiave per i dati permanenti perché l'indirizzo email è soggetto a modifiche.

Nell'esempio seguente, l'ID groupKey univoco è nnnn: 

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

Una risposta riuscita restituisce un codice di stato HTTP 200 e le impostazioni del gruppo: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

Recupera tutti i gruppi per un dominio o l'account

Per recuperare tutti i gruppi per un dominio o un account specifico, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste. Per le proprietà della stringa di query, della richiesta e della risposta, consulta il metodo groups.list. Per favorire la leggibilità, in questo esempio sono stati inseriti dei ritorni a capo. 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

Quando recuperi tutti i gruppi per un dominio o l'account, tieni presente quanto segue:

  • Tutti i gruppi di un sottodominio: utilizza l'argomento domain con il nome del dominio.
  • Tutti i gruppi per l'account: utilizza l'argomento customer con my_customer o con il valore customerId dell'account. In qualità di amministratore dell'account, utilizza la stringa my_customer per rappresentare il valore customerId del tuo account. Se sei un rivenditore che accede all'account di un cliente a cui è stato rivenduto un prodotto, utilizza customerId dell'account rivenduto. Per il valore customerId, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupero di tutti gli utenti di un dominio. La risposta risultante ha il valore customerId.
  • Utilizzo di entrambi gli argomenti domain e customer: l'API Directory restituisce tutti i gruppi per domain.
  • Non utilizzare gli argomenti domain e customer: l'API Directory restituisce tutti i gruppi per l'account associato a my_customer. Si tratta dell'account customerId dell'amministratore che effettua la richiesta.
  • Utilizzo di entrambi gli argomenti customer e userKey: l'API Directory restituisce un errore. Devi effettuare due richieste separate con questi argomenti.

Nell'esempio seguente, un amministratore dell'account utilizza my_customer per richiedere un elenco di tutti i gruppi di un account:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2

Nell'esempio seguente, la richiesta di un amministratore rivenditore restituisce tutti i gruppi per l'account rivenduto con customerId C03az79cb. Il numero massimo di risultati restituiti per pagina di risposta è 2. In questa risposta è presente un nextPageToken per l'elenco successivo di utenti: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

Una risposta riuscita restituisce un codice di stato HTTP 200 e i gruppi nell'ordine alfabetico dell'email del gruppo: 

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support@sales.com",
      "name": "Sales support",
      "directMembersCount": "6",
      "description": "The sales support group",
      "adminCreated": true
     },
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "travel@sales.com",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "best_sales_group@example.com"
       }
      ],
      "nonEditableAliases: [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

Recupera tutti i gruppi di appartenenza di un utente

Per recuperare tutti i gruppi per i quali un membro ha un abbonamento, utilizza la seguente richiesta GET 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/groups?userKey=user key
?pageToken=pagination token
&maxResults=maximum results per response page
  • Un membro può essere un utente o un gruppo.
  • userKey può essere l'indirizzo email principale dell'utente, l'indirizzo email alias dell'utente, l'indirizzo email principale di un gruppo, l'alias email di un gruppo o il id univoco dell'utente che può essere trovato utilizzando la operazione Recupera un utente.
  • L'utente o il gruppo specificato in userKey deve appartenere al tuo dominio.
  • Utilizza la stringa di query pageToken per le risposte con un numero elevato di gruppi. Nel caso della paginazione, la risposta restituisce la proprietà nextPageToken che fornisce un token per la pagina successiva dei risultati della risposta. La richiesta successiva utilizza questo token come valore della stringa di query pageToken.
  • Utilizzo di entrambi gli argomenti customer e userKey: l'API Directory restituisce un errore. Devi effettuare due richieste separate con questi argomenti.

Per le proprietà della richiesta e della risposta, consulta il metodo groups.list.

Una risposta corretta restituisce un codice di stato HTTP 200 e l'elenco delle informazioni sui membri:

  • Vengono restituiti tutti i gruppi a cui un membro ha un abbonamento, inclusi i gruppi esterni al dominio dell'utente.
  • I gruppi vengono restituiti nell'ordine alfabetico dell'indirizzo email di ciascun gruppo.
  • Nel corpo della risposta, id è l'ID univoco del gruppo.
  • Nella risposta, la voce di un gruppo esterno al dominio dell'utente non include gli alias del gruppo esterno. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "sales_group@example.com",
      "name": "sale group",
      "directMembersCount": "5",
      "description": "Sales group"
     },
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support_group.com",
      "name": "support group",
      "directMembersCount": "5",
      "description": "Support group"
     }
  ],
   "nextPakeToken": "NNNNN"
}

Recupera tutti gli alias di gruppo

Per recuperare tutti gli alias di un gruppo, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. groupKey può essere l'indirizzo email principale del gruppo, il id unico del gruppo o uno degli indirizzi email degli alias del gruppo. Per le proprietà della richiesta e della risposta, consulta la risorsa groups. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

Una risposta riuscita restituisce un codice di stato HTTP 201 e un elenco degli alias del gruppo.

Eliminare un alias di gruppo

Per eliminare l'alias di un gruppo, utilizza la seguente richiesta DELETE e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. groupKey può essere l'indirizzo email principale del gruppo, il id unico del gruppo o uno degli indirizzi email degli alias del gruppo. aliasId è l'alias in fase di eliminazione. Per le proprietà della richiesta e della risposta, consulta la risorsa groups: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

Una risposta riuscita restituisce un codice di stato HTTP 201.

Eliminare un gruppo

Per eliminare un gruppo, utilizza la seguente richiesta DELETE e includi l'autorizzazione descritta in Autorizzare le richieste. groupKey è il id univoco del gruppo: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
 Ad esempio, questa richiesta DELETE elimina il gruppo che ha il gruppo nnnn id: 
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

Una risposta riuscita restituisce un codice di stato HTTP 200.

Quando un gruppo viene eliminato, si verifica quanto segue:

  • Tutti i membri del gruppo vengono eliminati. Gli account utente del membro non vengono eliminati.
  • L'archivio del gruppo viene eliminato.
  • I messaggi inviati all'indirizzo del gruppo eliminato non vengono recapitati. Il mittente riceve invece un messaggio di mancata consegna.