Questo documento descrive come utilizzare le notifiche push per informare i tuoi quando una risorsa cambia.
Panoramica
L'API SDK Admin fornisce notifiche push che ti consentono di monitorare delle modifiche nelle risorse. Puoi usare questa funzione per migliorare le prestazioni di la tua applicazione. Consente di eliminare le risorse di rete e di calcolo aggiuntive relativi ai sondaggi per determinare se sono cambiati. Ogni volta che una risorsa monitorata cambia, l'API SDK Admin ti invia una notifica un'applicazione.
Per utilizzare le notifiche push, devi eseguire due operazioni:
Configura l'URL di ricezione o il "webhook" ricevente di callback.
Questo è un server HTTPS che gestisce i messaggi di notifica delle API in caso di modifica di una risorsa.
Configura un (canale di notifica) per ogni endpoint delle risorse che vuoi smartwatch.
Un canale specifica le informazioni di routing per le notifiche messaggi. Come parte della configurazione del canale, devi identificare l'URL specifico in cui vuoi ricevere notifiche. Ogni volta che una risorsa del canale cambia, l'API SDK Admin invia un messaggio di notifica come
POST
richiesta a quell'URL.
Attualmente, l'API SDK Admin supporta le notifiche per le modifiche a la risorsa Attività.
Crea canali di notifica
Per richiedere notifiche push, devi configurare un canale di notifica per ogni risorsa che vuoi monitorare. Dopo aver impostato i canali di notifica l'API SDK Admin avvisa la tua applicazione quando una risorsa modifiche.
Effettua richieste di orologio
A ogni risorsa dell'API Admin SDK visibile è associata
watch
in un URI nel seguente formato:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Per impostare un canale di notifica per i messaggi relativi alle modifiche a una
risorsa specifica, invia una richiesta POST
Metodo watch
per la risorsa.
Ogni canale di notifica è associato sia a un utente specifico
una particolare risorsa (o un insieme di risorse). Una richiesta watch
non avrà successo a meno che l'utente corrente
o un account di servizio
possiede o dispone dell'autorizzazione per accedere a questa risorsa.
Esempi
Tutte le richieste di visualizzazione per la risorsa Attività hanno il 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: nei seguenti esempi, il corpo della richiesta omette il corpo della richiesta per maggiore chiarezza.
Controlla tutte le attività di amministrazione:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Controlla tutte le attività relative ai documenti:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Controlla le attività di amministrazione di un utente specifico:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Controlla 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 della proprietà
id
che identifica in modo univoco nuovo canale di notifica all'interno del tuo progetto. È consigliabile utilizzare Un identificatore univoco universale (UUID) o simile stringa univoca. Lunghezza massima: 64 caratteri.Il valore ID impostato viene ripreso nel campo Intestazione HTTP
X-Goog-Channel-Id
di ogni notifica che ricevi per questo canale. -
Una stringa della proprietà
type
impostata sul valoreweb_hook
. -
Una stringa della 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 SDK Admin è in grado di inviare notifiche a questo indirizzo HTTPS solo se è installato un certificato SSL valido sul tuo server web. I certificati non validi includono:
- Certificati autofirmati.
- Certificati firmati da una fonte non attendibile.
- Certificati revocati.
- Certificati con un oggetto che non corrisponde alla destinazione dell'host.
Proprietà facoltative
Puoi anche specificare questi campi facoltativi
Richiesta di watch
:
-
Una proprietà
token
che specifica una stringa arbitraria da utilizzare come token del canale. Puoi usare il canale di notifica di token per vari scopi. Ad esempio, puoi utilizzare per verificare che ogni messaggio in arrivo sia destinato a un canale dell'applicazione creata, per assicurarti che la notifica falsificato o per indirizzare il messaggio alla destinazione corretta la tua applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.Il token è incluso nel
X-Goog-Channel-Token
intestazione HTTP in ogni notifica che la tua applicazione riceve per il canale.Se utilizzi i token del canale di notifica, ti consigliamo di:
Utilizza un formato di codifica estensibile, come la query URL parametri. Esempio:
forwardTo=hr&createdBy=mobile
Non includere dati sensibili come i token OAuth.
-
Una stringa della proprietà
expiration
impostata su un Timestamp Unix (in millisecondi) della data e dell'ora in cui vuoi che l'API SDK Admin interrompi l'invio di 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 ricevute dall'applicazione per questo canale.
Per maggiori dettagli sulla richiesta, fai riferimento al metodo watch
per la risorsa Attività nel riferimento API.
Guarda la risposta
Se la richiesta watch
crea correttamente una notifica
viene restituito un codice di stato HTTP 200 OK
.
Il corpo del messaggio della risposta dell'orologio fornisce informazioni sul canale di notifica appena creato, come mostrato nell'esempio riportato di seguito.
{ "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, i campi
le informazioni restituite includono anche resourceId
e
resourceUri
per identificare la risorsa guardata su questo
canale di notifica.
Puoi passare le informazioni restituite a un altro canale di notifica operazioni, come quando interrompi la ricezione notifiche.
Per ulteriori dettagli sulla risposta, consulta watch
per la risorsa Activities nel riferimento API.
Sincronizza messaggio
Dopo aver creato un canale di notifica per osservare una risorsa,
L'API SDK Admin invia un messaggio sync
per indicare che
le notifiche vengono avviate. HTTP X-Goog-Resource-State
il valore dell'intestazione per questi messaggi è sync
. A causa della rete
problemi di tempo, puoi ricevere il messaggio sync
anche prima di ricevere la risposta del metodo watch
.
Puoi ignorare la notifica di sync
, ma puoi
lo usi. Ad esempio, se decidi di non voler più mantenere
il canale, puoi usare X-Goog-Channel-ID
e
Valori di X-Goog-Resource-ID
in una chiamata a
interrompere la ricezione delle notifiche. Puoi utilizzare anche
Notifica sync
per eseguire alcune operazioni di inizializzazione per prepararsi
per gli eventi successivi.
Il formato dei messaggi sync
a cui invia l'API SDK Admin
l'URL di destinazione è riportato di seguito.
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 HTTP X-Goog-Message-Number
valore dell'intestazione 1
. Ogni notifica successiva per questo canale contiene
un numero di messaggio maggiore del precedente, sebbene il messaggio
i numeri non saranno sequenziali.
Rinnova canali di notifica
Un canale di notifica può avere una data di scadenza, con un valore
determinato dalla tua richiesta o da eventuali limiti interni dell'API SDK Admin
o valori predefiniti (più viene utilizzato il valore più restrittivo). La scadenza del canale
l'ora, se disponibile, viene inclusa come timestamp Unix
(in millisecondi) nelle informazioni restituite dal metodo watch
. Inoltre,
data e ora di scadenza sono incluse (in formato leggibile) in ogni
messaggio di notifica ricevuto dall'applicazione per il canale in questione
Intestazione HTTP X-Goog-Channel-Expiration
.
Al momento, non è possibile rinnovare automaticamente un canale di notifica. Quando
un canale è prossimo alla scadenza, devi sostituirlo con uno nuovo richiamando
il metodo watch
. Come sempre, devi utilizzare un valore univoco per
la proprietà id
del nuovo canale. Tieni presente che è probabile
in modo che sia una "sovrapposizione" periodo di tempo in cui i due canali di notifica
sono attive le stesse risorse.
Ricezione notifiche
Ogni volta che una risorsa controllata cambia, l'applicazione riceve
messaggio di notifica che descrive la modifica. L'API Admin SDK invia questi dati
messaggi come richieste HTTPS POST
all'URL specificato come
Proprietà address
per questa notifica
canale.
Interpretare il formato dei messaggi di notifica
Tutti i messaggi di notifica includono un insieme di intestazioni HTTP con
X-Goog-
prefissi.
Alcuni tipi di notifiche possono includere anche un
corpo del messaggio.
Intestazioni
Messaggi di notifica pubblicati dall'API SDK Admin sulla ricezione L'URL include le seguenti intestazioni HTTP:
Intestazione | Descrizione |
---|---|
Presentare sempre | |
|
UUID o un'altra stringa univoca che hai fornito per identificarla canale di notifica. |
|
Numero intero che identifica il messaggio per questa notifica
canale. Il valore per i messaggi sync è sempre 1 . Messaggio
aumentano per ogni messaggio successivo sul canale, ma
non sequenziali. |
|
Un valore opaco che identifica la risorsa controllata. Questo ID è sono stabili tra le 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. |
|
Token del canale di notifica impostato dalla tua applicazione e che puoi utilizzare per verificare la fonte 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 |
L'identificatore univoco del record dell'attività. |
id.time |
L'ora in cui si è verificata l'attività. Il valore è in Formato di data e ora ISO 8601. L'ora è la 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 svolto l'attività elencata nel report. In questa versione dell'API, callerType è la richiesta di entità USER o OAuth 2LO che ha eseguito l'azione indicata 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 l'indirizzo di una 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. Questo è il nome specifico dell'attività riportata dall'API. Inoltre, ogni eventName è correlato a una funzionalità o a un servizio specifico di Google Workspace che l'API organizza in tipi di eventi.
Per i parametri della richiesta eventName in generale:
|
events[].parameters[] |
Coppie di valori dei parametri 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 delle risorse Attività hanno il formato 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 } ] } ] }
Esempio di evento relativo all'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 che l'operazione è andata a buon fine, puoi restituire uno dei seguenti codici di stato:
200
, 201
, 202
, 204
o
102
.
Se il servizio utilizza la libreria client API di Google
e restituisce 500
,502
, 503
o 504
, l'API SDK Admin
nuovi tentativi con backoff esponenziale.
Ogni altro codice di stato del reso è considerato un errore del messaggio.
Informazioni sugli eventi di notifica dell'API Admin SDK
Questa sezione fornisce dettagli sui messaggi di notifica che puoi quando si utilizzano 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 valori possibili per le notifiche di eventi sono gli stessi del metodo activities.list
. Ogni applicazione ha eventi univoci:
Interrompi la ricezione di notifiche
La proprietà expiration
stabilisce quando interrompere automaticamente le notifiche. Puoi
scegliere di interrompere la ricezione delle notifiche per un determinato canale prima che questo
scade chiamando il metodo stop
all'indirizzo
il seguente URI:
https://www.googleapis.com/admin/reports_v1/channels/stop
Questo metodo richiede che tu fornisca almeno i dati del canale
id
e le proprietà resourceId
, come mostrato in
di esempio qui sotto. Tieni presente che, se l'API SDK Admin ha diversi tipi di
con watch
metodi, ce n'è solo uno
Metodo stop
.
Solo gli utenti che dispongono dell'autorizzazione appropriata possono interrompere un canale. In particolare:
- Se il canale è stato creato da un normale account utente, solo lo stesso utente dallo stesso client (come identificato dagli ID client OAuth 2.0 della di autenticazione) che ha creato il canale può interromperlo.
- Se il canale è stato creato da un account di servizio, qualsiasi utente il cliente può interrompere il canale.
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" }