Gestisci gruppi

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

  • Crea un gruppo
  • Aggiorna un gruppo
  • Aggiungere un alias di gruppo
  • Recupera un gruppo
  • Recupera tutti i gruppi per un dominio o per l'account
  • Recupera tutti i gruppi per un membro
  • Recuperare 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 descritti in Autorizzare le richieste. Puoi creare un gruppo per qualsiasi dominio associato all'account. Per le stringhe di query, request, e le proprietà della risposta, consulta le Metodo groups.insert. 

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

La seguente richiesta JSON mostra il corpo di una richiesta di esempio che crea un gruppo. L'indirizzo email del gruppo l'indirizzo è [email protected]: 

{
   "email": "[email protected]",
   "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 il parametro l'autorizzazione descritta in Autorizzare le richieste. groupKey è l'indirizzo email del gruppo, qualsiasi indirizzo email dell'alias di gruppo, o l'elemento id univoco del gruppo. Per le stringhe di query e le proprietà di richiesta e risposta, vedi 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 persistenti perché l'indirizzo email può cambiare.

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

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

{
    "email": "[email protected]",
    "name": "APAC Sales Group"
}

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

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": "[email protected]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[email protected]"
     }
    ],
    "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 descritto in Autorizzare le richieste. groupKey è l'indirizzo email del gruppo, qualsiasi alias del gruppo l'indirizzo email l'elemento id univoco del gruppo. Per le stringhe di query e le proprietà di richiesta e 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 può cambiare.

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

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

{
    "alias": "[email protected]"
}

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 descritti in Autorizzare le richieste. groupKey è l'indirizzo email del gruppo, qualsiasi alias del gruppo l'indirizzo email il valore id univoco del gruppo. Per le stringhe di query e le proprietà di richiesta e 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 può cambiare.

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": "[email protected]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[email protected]"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

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

Per recuperare tutti i gruppi per un dominio o un account specifico, usa GET richiedere e includere l'autorizzazione descritta in Autorizzare le richieste. Per la query le stringhe, le proprietà delle richieste e delle risposte, vedi Metodo groups.list. Per la leggibilità, in questo esempio vengono utilizzati i ritorni a riga di comando: 

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 un account, considera quanto segue:

  • Tutti i gruppi per un sottodominio: utilizza l'argomento domain con il nome del dominio.
  • Tutti i gruppi dell'account: utilizza l'argomento customer con my_customer o il valore customerId dell'account. Come account amministratore, utilizza la stringa my_customer per rappresentare l'account customerId. Se sei un rivenditore che accede all'account di un cliente del rivenditore, utilizza la customerId dell'account del rivenditore. Per il valore customerId utilizza il valore nome di dominio principale dell'account Recuperare tutti gli utenti in un dominio dell'operazione. La risposta risultante ha il valore customerId.
  • Utilizzo di entrambi gli argomenti domain e customer: il L'API Directory restituisce tutti i gruppi per domain.
  • Non vengono utilizzati 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 crea la richiesta.
  • Utilizzo di entrambi gli argomenti customer e userKey: il 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 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 di rivenditore restituisce tutti i gruppi per l'account del rivenditore con customerId C03az79cb. Il numero massimo di risultati restituiti per pagina di risposta è 2. È presente un nextPageToken per l'elenco di utenti successivi in questa risposta: 

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 nell'email del gruppo: 

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "[email protected]",
      "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": "[email protected]",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "[email protected]"
       }
      ],
      "nonEditableAliases: [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

Recupera tutti i gruppi per un membro

Per recuperare tutti i gruppi per i quali un membro è iscritto, usa il seguente GET richiedere e includere l'autorizzazione descritta in Autorizzare le richieste. Per una migliore leggibilità, in questo esempio vengono utilizzati i 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'indirizzo id univoco dell'utente che puoi trovare utilizzando Recupera un'operazione 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. Nella caso di impaginazione, la risposta restituisce la proprietà nextPageToken, che fornisce una per la pagina successiva dei risultati di risposta. La tua prossima richiesta utilizza questo token come Valore della stringa di query pageToken.
  • Utilizzo di entrambi gli argomenti customer e userKey: il L'API Directory restituisce un errore. Devi effettuare due richieste separate con questi argomenti.

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

Una risposta corretta restituisce un Codice di stato HTTP 200 e l'elenco delle informazioni sul membro:

  • Tutti i gruppi a cui un membro è iscritto, inclusi i gruppi esterni a quelli dell'utente dominio, vengono restituiti.
  • I gruppi vengono restituiti in ordine alfabetico dell'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 il campo esterni agli alias del gruppo. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "[email protected]",
      "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"
}

Recuperare tutti gli alias di gruppo

Per recuperare tutti gli alias di un gruppo, utilizza la seguente richiesta GET e includi il parametro l'autorizzazione descritta in Autorizzare le richieste. La groupKey può essere l'indirizzo email principale del gruppo, l'indirizzo univoco id o uno qualsiasi degli alias di gruppo email. Per le proprietà di 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 il parametro l'autorizzazione descritta in Autorizzare le richieste. groupKey può essere l'indirizzo email principale del gruppo, l'indirizzo univoco id o uno qualsiasi degli alias di gruppo email. aliasId è l'alias eliminati. Per le proprietà di 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 descritti in Autorizzare le richieste. groupKey è l'elemento id univoco del gruppo: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
 Ad esempio, questa richiesta DELETE elimina il gruppo che contiene 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 del membro non vengono eliminati.
  • L'archivio del gruppo è stato eliminato.
  • I messaggi inviati all'indirizzo del gruppo eliminato non vengono recapitati. Al contrario, il mittente riceve messaggio rispedito al mittente.