Questo documento descrive come utilizzare le notifiche push che informano la tua applicazione quando una risorsa cambia.
Panoramica
L'API Admin SDK fornisce notifiche push che ti consentono di monitorare le modifiche nelle risorse. Puoi utilizzare questa funzionalità per migliorare il rendimento della tua applicazione. Ti consente di eliminare i costi aggiuntivi di rete e di calcolo associati al polling delle risorse per determinare se sono cambiate. Ogni volta che una risorsa monitorata cambia, l'API Admin SDK invia una notifica alla tua applicazione.
Per utilizzare le notifiche push, devi fare due cose:
Imposta l'URL di destinazione o il ricevitore di callback "webhook".
Si tratta di un server HTTPS che gestisce i messaggi di notifica dell'API attivati quando una risorsa cambia.
Configura un canale di notifica per ogni endpoint della risorsa che vuoi monitorare.
Un canale specifica le informazioni di instradamento per i messaggi di notifica. Durante la configurazione del canale, devi identificare l'URL specifico su cui vuoi ricevere le notifiche. Ogni volta che la risorsa di un canale cambia, l'API Admin SDK invia un messaggio di notifica come richiesta
POST
a quell'URL.
Al momento, l'API SDK Admin supporta le notifiche per le modifiche alla risorsa Attività.
Creare canali di notifica
Per richiedere notifiche push, devi configurare un canale di notifica per ogni risorsa che vuoi monitorare. Una volta configurati i canali di notifica, l'API Admin SDK informa l'applicazione quando una risorsa monitorata cambia.
Inviare richieste per gli smartwatch
A ogni risorsa dell'API Admin SDK visibile è associato un metodo watch
in un URI del seguente formato:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Per configurare un canale di notifica per i messaggi relativi alle modifiche apportate a una
determinata risorsa, invia una richiesta POST
al metodo
watch
della risorsa.
Ogni canale di notifica è associato sia a un determinato utente sia a una particolare risorsa (o insieme di risorse). Una richiesta watch
non andrà a buon fine a meno che l'utente corrente
o l'account di servizio
non sia proprietario di questa risorsa o non disponga dell'autorizzazione per accedervi.
Esempi
Tutte le richieste di visualizzazione per la risorsa Attività hanno il seguente formato generale:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch Authorization: Bearer auth_token_for_current_user Content-Type: application/json { "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
Puoi utilizzare i parametri userKey, applicationName, eventName
e filters
per ricevere notifiche solo per eventi, utenti o applicazioni specifici.
Nota:per chiarezza, nei seguenti esempi viene omesso il corpo della richiesta.
Tieni d'occhio tutte le attività di amministrazione:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Tieni d'occhio tutte le attività relative ai documenti:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Tieni d'occhio le attività di amministrazione di un utente specifico:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Tieni d'occhio un evento specifico, ad esempio la modifica della password di un utente:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
Controlla le modifiche a un documento specifico:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
Proprietà obbligatorie
Per ogni richiesta di tipo watch
, devi fornire i seguenti campi:
-
Una stringa di proprietà
id
che identifica in modo univoco questo nuovo canale di notifica all'interno del progetto. Ti consigliamo di utilizzare un identificatore univoco universale (UUID) o qualsiasi stringa univoca simile. Lunghezza massima: 64 caratteri.Il valore ID impostato viene riportato nell'
X-Goog-Channel-Id
intestazione HTTP di ogni messaggio di notifica che ricevi per questo canale. -
Una stringa di proprietà
type
impostata sul valoreweb_hook
. -
Una stringa di proprietà
address
impostata sull'URL che ascolta e risponde alle notifiche per questo canale di notifica. Questo è l'URL di callback del webhook e deve utilizzare HTTPS.Tieni presente che l'API Admin SDK è in grado di inviare notifiche a questo indirizzo HTTPS solo se sul tuo server web è installato un certificato SSL valido. I certificati non validi includono:
- Certificati autofirmati.
- Certificati firmati da una fonte non attendibile.
- Certificati revocati.
- Certificati con un oggetto che non corrisponde al nome host di destinazione.
Proprietà facoltative
Puoi anche specificare questi campi facoltativi con la richiesta
watch
:
-
Una proprietà
token
che specifica un valore di stringa arbitrario da utilizzare come token del canale. Puoi utilizzare i token del canale di notifica per vari scopi. Ad esempio, puoi utilizzare il token per verificare che ogni messaggio in arrivo sia per un canale creato dall'applicazione (per garantire che la notifica non sia oggetto di spoofing) o per indirizzare il messaggio alla destinazione corretta all'interno dell'applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.Il token è incluso nell'
X-Goog-Channel-Token
intestazione HTTP di ogni messaggio di notifica che la tua applicazione riceve per questo canale.Se utilizzi token dei canali di notifica, ti consigliamo di:
Utilizza un formato di codifica estensibile, ad esempio i parametri di query dell'URL. Esempio:
forwardTo=hr&createdBy=mobile
Non includere dati sensibili come token OAuth.
-
Una stringa di proprietà
expiration
impostata su un timestamp Unix (in millisecondi) della data e dell'ora in cui vuoi che l'API SDK Admin smetta di inviare messaggi per questo canale di notifica.Se un canale ha una scadenza, questa viene inclusa come valore dell'intestazione HTTP
X-Goog-Channel-Expiration
(in formato leggibile) in ogni messaggio di notifica che l'applicazione riceve per questo canale.
Per ulteriori dettagli sulla richiesta, consulta il metodo watch
per la risorsa Attività nel riferimento all'API.
Risposta dall'orologio
Se la richiesta watch
crea correttamente un canale di notifica, viene restituito un codice di stato HTTP 200 OK
.
Il corpo del messaggio della risposta dello smartwatch fornisce informazioni sul canale di notifica che hai appena creato, come mostrato nell'esempio seguente.
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
Oltre alle proprietà inviate nell'ambito della richiesta, le informazioni restituite includono anche resourceId
e resourceUri
per identificare la risorsa guardata su questo canale di notifica.
Puoi passare le informazioni restituite ad altre operazioni del canale di notifica, ad esempio quando vuoi interrompere la ricezione delle notifiche.
Per ulteriori dettagli sulla risposta, consulta il metodo watch
per la risorsa Attività nel riferimento all'API.
Sincronizza messaggio
Dopo aver creato un canale di notifica per monitorare una risorsa, l'API Admin SDK invia un messaggio sync
per indicare che le notifiche stanno iniziando. Il valore dell'intestazione HTTP X-Goog-Resource-State
per questi messaggi è sync
. A causa di problemi di temporizzazione della rete, è possibile ricevere il messaggio sync
anche prima di ricevere la risposta del metodo watch
.
Puoi ignorare la notifica sync
, ma puoi anche usarla. Ad esempio, se decidi di non mantenere
il canale, puoi utilizzare i valori X-Goog-Channel-ID
e
X-Goog-Resource-ID
in una chiamata per
smettere di ricevere notifiche. Puoi anche utilizzare la notifica sync
per eseguire alcune operazioni di inizializzazione e prepararti per gli eventi successivi.
Di seguito è riportato il formato dei messaggi sync
inviati dall'API SDK Admin al tuo URL di ricezione.
POST https://mydomain.com/notifications // Your receiving URL. X-Goog-Channel-ID: channel-ID-value X-Goog-Channel-Token: channel-token-value X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires. X-Goog-Resource-ID: identifier-for-the-watched-resource X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource X-Goog-Resource-State: sync X-Goog-Message-Number: 1
I messaggi di sincronizzazione hanno sempre un valore dell'intestazione HTTP X-Goog-Message-Number
uguale a 1
. Ogni notifica successiva per questo canale ha un numero di messaggio maggiore di quello precedente, anche se i numeri dei messaggi non saranno sequenziali.
Rinnova i canali di notifica
Un canale di notifica può avere una data e un'ora di scadenza, con un valore determinato dalla tua richiesta o da eventuali limiti o valori predefiniti interni dell'API Admin SDK (viene utilizzato il valore più restrittivo). La data e l'ora di scadenza del canale, se esistenti, sono incluse come timestamp Unix (in millisecondi) nelle informazioni restituite dal metodo watch
. Inoltre, la data e l'ora di scadenza sono incluse (in un formato leggibile) in ogni messaggio di notifica che la tua applicazione riceve per questo canale nell'intestazione HTTP X-Goog-Channel-Expiration
.
Al momento non esiste un modo automatico per rinnovare un canale di notifica. Quando
un canale è prossimo alla scadenza, devi sostituirlo con uno nuovo chiamando
il metodo watch
. Come sempre, devi utilizzare un valore univoco per la proprietà id
del nuovo canale. Tieni presente che è probabile che ci sia un periodo di "sovrapposizione" in cui sono attivi i due canali di notifica per la stessa risorsa.
Ricevere notifiche
Ogni volta che una risorsa controllata cambia, l'applicazione riceve un messaggio di notifica che descrive la modifica. L'API SDK Admin invia questi messaggi come richieste POST
HTTPS all'URL specificato come proprietà address
per questo canale di notifica.
Interpreta il formato del messaggio di notifica
Tutti i messaggi di notifica includono un insieme di intestazioni HTTP con prefisso X-Goog-
.
Alcuni tipi di notifiche possono anche includere un corpo del messaggio.
Intestazioni
I messaggi di notifica pubblicati dall'API Admin SDK nell'URL di destinazione includono le seguenti intestazioni HTTP:
Intestazione | Descrizione |
---|---|
Sempre presente | |
|
UUID o altra stringa univoca che hai fornito per identificare questo canale di notifica. |
|
Numero intero che identifica questo messaggio per questo canale di notifica. Il valore è sempre 1 per i messaggi sync . I numeri dei messaggi
aumentano per ogni messaggio successivo sul canale, ma non sono
sequenziali. |
|
Un valore opaco che identifica la risorsa monitorata. Questo ID è stabile nelle varie versioni dell'API. |
|
Il nuovo stato della risorsa che ha attivato la notifica.
Valori possibili:
sync o un nome evento.
|
|
Un identificatore della versione dell'API specifico per la risorsa controllata. |
A volte presente | |
|
Data e ora di scadenza del canale di notifica, espresse in formato leggibile. Presente solo se definito. |
|
Il token del canale di notifica impostato dalla tua applicazione e che puoi utilizzare per verificare l'origine della notifica. Presente solo se definito. |
I messaggi di notifica per le attività contengono le seguenti informazioni nel corpo della richiesta:
Proprietà | Descrizione |
---|---|
kind |
Identifica come risorsa attività. Valore: la stringa fissa "admin#reports#activity ". |
id |
Identificatore univoco del record dell'attività. |
id.time |
Ora di occorrenza dell'attività. Il valore è nel formato della data e dell'ora ISO 8601. L'ora corrisponde alla data completa più ore, minuti e secondi nel formato AAAA-MM-GGThh:mm:ssTZD. Ad esempio, 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
Qualificatore univoco se più eventi hanno lo stesso orario. |
id.applicationName |
Nome dell'applicazione a cui appartiene l'evento. I valori possibili sono: |
id.customerId |
L'identificatore univoco di un account Google Workspace. |
actor |
Utente che esegue l'azione. |
actor.callerType |
Il tipo di autore che ha eseguito l'attività elencata nel report. In questa versione dell'API, callerType è la richiesta dell'entità USER o OAuth 2LO che ha eseguito l'azione elencata nel report . |
actor.email |
L'indirizzo email principale dell'utente di cui vengono segnalate le attività. |
actor.profileId |
L'ID profilo Google Workspace univoco dell'utente. |
ownerDomain |
Dominio della Console di amministrazione o proprietario dei documenti dell'applicazione Documenti. Si tratta del dominio interessato dall'evento del report. |
ipAddress |
Indirizzo IP dell'utente che esegue l'azione. Si tratta dell'indirizzo IP (Internet Protocol) dell'utente quando accede a Google Workspace, che può riflettere o meno la posizione fisica dell'utente. Ad esempio, l'indirizzo IP può essere l'indirizzo del server proxy dell'utente o un indirizzo di rete privata virtuale (VPN). L'API supporta IPv4 e IPv6. |
events[] |
Eventi di attività nel report. |
events[].type |
Tipo di evento. Il servizio o la funzionalità di Google Workspace modificati da un amministratore viene identificato nella proprietà type che identifica un evento utilizzando la proprietà eventName . |
events[].name |
Nome dell'evento. Si tratta del nome specifico dell'attività registrata dall'API. Inoltre, ogni eventName è correlato a una funzionalità o a un servizio Google Workspace specifico che l'API organizza in tipi di eventi.
Per i parametri di richiesta eventName in generale:
|
events[].parameters[] |
Coppie di valori parametro per varie applicazioni. |
events[].parameters[].name |
Il nome del parametro. |
events[].parameters[].value |
Valore stringa del parametro. |
events[].parameters[].intValue |
Valore intero del parametro. |
events[].parameters[].boolValue |
Valore booleano del parametro. |
Esempi
I messaggi di notifica per gli eventi della risorsa Attività hanno la forma generale:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
Un esempio di evento di attività di amministrazione:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.com" } ] } ] }
Risposta alle notifiche
Per indicare il successo, puoi restituire uno dei seguenti codici di stato:
200
, 201
, 202
, 204
o
102
.
Se il tuo servizio utilizza la libreria client dell'API di Google
e restituisce 500
, 502
, 503
o 504
, l'API SDK Admin
riprova con il backoff esponenziale.
Ogni altro codice di stato del reso è considerato un errore del messaggio.
Informazioni sugli eventi di notifica dell'API SDK Admin
Questa sezione fornisce dettagli sui messaggi di notifica che puoi ricevere quando utilizzi le notifiche push con l'API SDK Admin.
Le notifiche push dell'API Reports contengono due tipi di messaggi: messaggi di sincronizzazione e notifiche di eventi. Il tipo di messaggio è indicato nell'intestazione HTTP X-Goog-Resource-State
. I possibili valori per le notifiche di eventi sono gli stessi del metodo activities.list
. Ogni applicazione ha eventi unici:
Interrompi la ricezione di notifiche
La proprietà expiration
controlla quando le notifiche si interrompono automaticamente. Puoi scegliere di interrompere la ricezione delle notifiche per un determinato canale prima che scada chiamando il metodo stop
al seguente URI:
https://www.googleapis.com/admin/reports_v1/channels/stop
Questo metodo richiede che tu fornisca almeno le proprietà id
e resourceId
del canale, come mostrato nell'esempio riportato di seguito. Tieni presente che se l'API SDK Admin ha diversi tipi di risorse con metodi watch
, esiste un solo metodo watch
.stop
Solo gli utenti che dispongono dell'autorizzazione appropriata possono interrompere un canale. In particolare:
- Se il canale è stato creato da un account utente normale, solo lo stesso utente dello stesso client (identificato dagli ID client OAuth 2.0 dei token di autenticazione) che ha creato il canale può interromperlo.
- Se il canale è stato creato da un account di servizio, qualsiasi utente dello stesso client può interromperlo.
Il seguente esempio di codice mostra come interrompere la ricezione delle notifiche:
POST https://www.googleapis.com/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }