Gestisci gruppi

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

  • Crea un gruppo
  • Aggiornare un gruppo
  • Aggiungere un alias di gruppo
  • Recuperare un gruppo
  • Recuperare tutti i gruppi per un dominio o l'account
  • Recupera tutti i gruppi di un membro
  • 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 nell'articolo relativo all'autorizzazione delle 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 Autorizzare le richieste. Il groupKey è l'indirizzo email del gruppo, uno qualsiasi degli indirizzi email 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, consigliamo di non utilizzare l'indirizzo email del gruppo come chiave per i dati persistenti, perché l'indirizzo email è soggetto a modifiche.

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

Nell'esempio seguente, l'groupKey univoco è nnn e il nome del gruppo è Gruppo vendite APAC: 

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 nella richiesta. 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. Il groupKey è l'indirizzo email del gruppo, uno qualsiasi degli indirizzi email alias del gruppo o l'id univoco del gruppo. Per le proprietà delle stringhe 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 persistenti 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 di gruppo.

Recuperare un gruppo

Per recuperare un gruppo, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. Il groupKey è l'indirizzo email del gruppo, uno qualsiasi degli indirizzi email alias del gruppo o l'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 persistenti perché l'indirizzo email è soggetto a modifiche.

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

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

Una risposta riuscita restituisce un codice di stato 200 HTTP 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"
     }
    ]
}

Recuperare tutti i gruppi per un dominio o l'account

Per recuperare tutti i gruppi per un dominio o l'account specifico, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzazione delle 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 per 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 il valore customerId dell'account. In qualità di amministratore dell'account, utilizza la stringa my_customer per rappresentare il customerId del tuo account. Se sei un rivenditore che accede all'account di un cliente rivenduto, utilizza il customerId dell'account rivenduto. Per il valore customerId, utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupera tutti gli utenti di un dominio. La risposta risultante ha il valore customerId.
  • Utilizzando sia gli argomenti domain che 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. Questo è l'account customerId dell'amministratore che effettua la richiesta.
  • Utilizzando 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. Esiste un nextPageToken per l'elenco successivo di utenti in questa risposta: 

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 in 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 un membro

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 l'id univoco dell'utente, che può essere trovato utilizzando l'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.
  • Utilizzando 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 riuscita restituisce un codice di stato HTTP 200 e l'elenco delle informazioni sui membri:

  • Vengono restituiti tutti i gruppi per i quali un membro ha un abbonamento, inclusi i gruppi al di fuori del dominio dell'utente.
  • I gruppi vengono restituiti in ordine alfabetico in base all'indirizzo email di ciascun gruppo.
  • Nel corpo della risposta, id è l'ID univoco del gruppo.
  • Nella risposta, l'elenco 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"
     }
  ],
   "nextPageToken": "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 in Autorizzare le richieste. L'groupKey può essere l'indirizzo email principale del gruppo, l'id univoco del gruppo o uno qualsiasi degli indirizzi email 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. L'groupKey può essere l'indirizzo email principale del gruppo, l'id univoco del gruppo o uno qualsiasi degli indirizzi email 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 nell'articolo relativo all'autorizzazione delle richieste. groupKey è l'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. ma il mittente riceve un avviso di mancato recapito.