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 richiestaGET
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
conmy_customer
o il valorecustomerId
dell'account. In qualità di amministratore di account, utilizza la stringamy_customer
per rappresentarecustomerId
del tuo account. Se sei un rivenditore che ha accesso all'account di un suo cliente, utilizza ilcustomerId
dell'account del rivenditore. Per il valorecustomerId
utilizza il nome di dominio principale dell'account nella richiesta dell'operazione Recupera tutti gli utenti in un dominio. La risposta risultante ha il valorecustomerId
. - Utilizzo di entrambi gli argomenti
domain
ecustomer
: l'API Directory restituisce tutti i gruppi perdomain
. - Mancato utilizzo degli argomenti
domain
ecustomer
: l'API Directory restituisce tutti i gruppi per l'account associato amy_customer
. Questo è l'accountcustomerId
dell'amministratore che ha effettuato la richiesta. - Utilizzo di entrambi gli argomenti
customer
euserKey
: 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 emailid
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 querypageToken
. - Utilizzo di entrambi gli argomenti
customer
euserKey
: 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 richiestaGET
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 richiestaDELETE
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.