Gestisci gruppi

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

  • Crea un gruppo
  • Aggiorna un gruppo
  • Aggiungi un alias di gruppo
  • Recupera un gruppo
  • Recuperare tutti i gruppi per un dominio o per l'account
  • Recupera tutti i gruppi per 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 in Autorizzare richieste. Puoi creare un gruppo per qualsiasi dominio associato all'account. Per le stringhe di query, le proprietà delle richieste e delle risposte, 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 è gruppo_vendite@example.com: 

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

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

Aggiorna un gruppo

Per aggiornare le impostazioni di un gruppo, utilizza la seguente richiesta PUT e includi l'autorizzazione descritta in Autorizzare richieste. groupKey è l'indirizzo email del gruppo, l'indirizzo email di qualsiasi alias del gruppo o l'indirizzo email id univoco del gruppo. Per le stringhe di query, le proprietà delle richieste e delle risposte, 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, in quanto l'indirizzo email è soggetto a modifiche.

Nell'esempio seguente, l'unico groupKey è 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 nella richiesta. Non è necessario inserire tutte le proprietà del gruppo nella richiesta.

Una risposta corretta 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"
     }
    ]
}

Aggiungi un alias di gruppo

Per aggiungere un alias di gruppo, utilizza la seguente richiesta POST e includi l'autorizzazione descritta in Autorizzare le richieste. groupKey è l'indirizzo email del gruppo, l'indirizzo email di qualsiasi alias del gruppo o l'indirizzo email univoco del gruppo id. Per le stringhe di query, le proprietà 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, in quanto l'indirizzo email è soggetto a modifiche.

La seguente richiesta JSON mostra una richiesta di esempio per creare l'alias di un gruppo. groupKey è il valore 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 corretta restituisce un codice di stato HTTP 201 e le proprietà del nuovo alias di gruppo.

Recupera un gruppo

Per recuperare un gruppo, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizza richieste. groupKey è l'indirizzo email del gruppo, l'indirizzo email di qualsiasi alias del gruppo o l'indirizzo email univoco del gruppo id. Per le stringhe di query, le proprietà delle richieste e delle risposte, vedi 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, in quanto l'indirizzo email è soggetto a modifiche.

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

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

Una risposta corretta 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"
     }
    ]
}

Recuperare tutti i gruppi per un dominio o per l'account

Per recuperare tutti i gruppi per un dominio o l'account specifici, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste. Per le stringhe di query, le proprietà di richiesta e risposta, consulta il metodo groups.list. Per la leggibilità, in questo esempio vengono utilizzati i ritorni a riga: 

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, considera 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 il valore customerId dell'account. In qualità di amministratore di account, utilizza la stringa my_customer per rappresentare customerId del tuo account. Se sei un rivenditore che ha accesso all'account di un suo cliente, utilizza il customerId dell'account del rivenditore. Per il valore 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.
  • Utilizzo di entrambi gli argomenti domain e customer: l'API Directory restituisce tutti i gruppi per domain.
  • Mancato utilizzo degli 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 ha effettuato 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 di 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 di utenti successivi: 

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

Una risposta corretta 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 per un membro

Per recuperare tutti i gruppi per cui un membro dispone di una sottoscrizione, usa la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste. Per la leggibilità, in questo esempio vengono utilizzati i ritorni a riga: 

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'indirizzo email id univoco dell'utente, che puoi trovare utilizzando l'operazione di recupero di 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. In caso di impaginazione, la risposta restituisce la proprietà nextPageToken che fornisce un token per la pagina successiva dei risultati della risposta. La prossima richiesta utilizzerà 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à di richiesta e risposta, consulta il metodo groups.list.

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

  • Vengono restituiti tutti i gruppi per i quali un membro ha un abbonamento, inclusi quelli esterni al dominio dell'utente.
  • I gruppi vengono restituiti in ordine alfabetico dall'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"
     }
  ],
   "nextPakeToken": "NNNNN"
}

Recupera tutti gli alias di gruppo

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

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

Una risposta corretta 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 in Autorizzare le richieste. groupKey può essere l'indirizzo email principale del gruppo, l'indirizzo email univoco del gruppo id o gli indirizzi email di uno degli alias di gruppo. aliasId è l'alias che viene eliminato. Per le proprietà richiesta e risposta, consulta la risorsa groups: 

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

Una risposta corretta 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 richieste. groupKey è il valore 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 corretta 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 dei membri non vengono eliminati.
  • L'archivio del gruppo è stato eliminato.
  • I messaggi inviati all'indirizzo del gruppo eliminato non vengono recapitati. Il mittente riceve invece un avviso di mancato recapito.