Notifiche push

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 alle risorse. Puoi utilizzare questa funzionalità per migliorare le prestazioni della tua applicazione. 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:

• Configura l'URL di ricezione o il ricevitore di callback "webhook".

  Si tratta di un server HTTPS che gestisce i messaggi di notifica API attivati quando una risorsa cambia.

• Configura un (canale di notifica) per ogni endpoint risorsa che vuoi monitorare.

  Un canale specifica le informazioni di routing per i messaggi di notifica. Nell'ambito della configurazione del canale, devi identificare l'URL specifico in cui vuoi ricevere le notifiche. Ogni volta che le risorse di un canale cambiano, l'API Admin SDK invia un messaggio di notifica come richiesta POST a quell'URL.

Nota:il termine "canale" utilizzato in questo documento si riferisce specificamente a un canale di notifica e non a qualsiasi altro tipo di canale utilizzato in questa API o servizio. È possibile attivare più canali di notifica contemporaneamente per la stessa risorsa.

Al momento, l'API Admin SDK 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 comunica alla tua applicazione quando una risorsa monitorata cambia.

Effettuare richieste di visualizzazione

Ogni risorsa API SDK Admin osservabile ha un metodo watch associato a 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 a una risorsa specifica, invia una richiesta POST al metodo watch per la risorsa.

Ogni canale di notifica è associato sia a un utente specifico sia a una risorsa (o a un insieme di risorse) specifica. Una richiesta watch non andrà a buon fine a meno che l'utente attuale o l'account di servizio non possieda o non disponga dell'autorizzazione per accedere a questa risorsa.

Esempi

Tutte le richieste di visualizzazione per la risorsa Attività hanno la forma 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

Il corpo della richiesta ha le seguenti proprietà:

• id: un UUID o una stringa univoca simile che identifica questo canale.
• type: Il tipo di meccanismo di distribuzione. Il valore di questo campo deve essere web_hook.
• address: l'URL a cui vengono inviate le notifiche.
• token: una stringa arbitraria inviata all'indirizzo di destinazione con ogni notifica, allo scopo di verificare che la notifica provenga da una fonte attendibile.
• payload: un flag booleano che indica se il payload deve essere incluso nella notifica.
• expiration: il tempo di permanenza in secondi per il canale di notifica.

Puoi utilizzare i parametri userKey, applicationName, eventName e filters per ricevere notifiche solo per eventi, utenti o applicazioni specifici.

Nota:i seguenti esempi omettono il corpo della richiesta per chiarezza.

Tieni d'occhio tutte le attività di amministrazione:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Monitora tutte le attività relative ai documenti:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Per monitorare l'attività amministrativa di un utente specifico:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/[e-mail]/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

Monitora 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 watch, devi fornire questi campi:

• Una stringa di proprietà id che identifica in modo univoco questo nuovo canale di notifica all'interno del tuo progetto. Ti consigliamo di utilizzare un identificatore univoco universale (UUID) o qualsiasi stringa univoca simile. Lunghezza massima: 64 caratteri.

  Il valore dell'ID che hai impostato viene restituito nell'intestazione HTTP X-Goog-Channel-Id di ogni messaggio di notifica che ricevi per questo canale.

• Una stringa di proprietà type impostata sul valore web_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 Admin SDK può 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 soggetto che non corrisponde al nome host di destinazione.

Proprietà facoltative

Puoi anche specificare questi campi facoltativi con la tua richiesta watch:

• Una proprietà token che specifica un valore 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 destinato a un canale creato dalla tua applicazione, per assicurarti che la notifica non sia falsificata o per indirizzare il messaggio alla destinazione corretta all'interno della tua applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.

  Il token è incluso nell'intestazione HTTP X-Goog-Channel-Token in ogni messaggio di notifica che la tua applicazione riceve per questo canale.

  Se utilizzi i token dei canali di notifica, ti consigliamo di:

  • Utilizza un formato di codifica estensibile, ad esempio i parametri di query URL. Esempio: forwardTo=hr&createdBy=mobile

  • Non includere dati sensibili come i token OAuth.

  Nota: se devi inviare dati altamente sensibili, assicurati che siano criptati prima di aggiungerli al token.

• Una stringa di proprietà expiration impostata su un timestamp Unix (in millisecondi) della data e dell'ora in cui vuoi che l'API Admin SDK interrompa l'invio di messaggi per questo canale di notifica.

  Se un canale ha un tempo di scadenza, questo viene incluso come valore dell'intestazione HTTP X-Goog-Channel-Expiration (in formato leggibile) in ogni messaggio di notifica che la tua applicazione riceve per questo canale.

Nota:per l'API Admin SDK, il tempo di scadenza massimo è 21600 secondi. Se non imposti la proprietà expiration nella richiesta, il tempo di scadenza è impostato per impostazione predefinita su 21600 secondi dopo l'ora corrente.

Per ulteriori dettagli sulla richiesta, consulta il metodo watch per la risorsa Attività nel riferimento API.

Guarda la risposta

Se la richiesta watch crea correttamente un canale di notifica, restituisce 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",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

Oltre alle proprietà inviate nell'ambito della richiesta, le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa visualizzata su questo canale di notifica.

Nota:la proprietà resourceId è un identificatore stabile e indipendente dalla versione della risorsa. La proprietà resourceUri è l'URI canonico della risorsa osservata nel contesto della versione attuale dell'API, pertanto è specifica per la versione.

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 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 per iniziare. Il valore dell'intestazione HTTP X-Goog-Resource-State per questi messaggi è sync. A causa di problemi di sincronizzazione della rete, è possibile ricevere il messaggio sync anche prima di ricevere la risposta del metodo watch.

Puoi ignorare la notifica sync in tutta sicurezza, ma puoi anche utilizzarla. Ad esempio, se decidi di non voler mantenere il canale, puoi utilizzare i valori X-Goog-Channel-ID e X-Goog-Resource-ID in una chiamata per interrompere la ricezione delle notifiche. Puoi anche utilizzare la notifica sync per eseguire alcune operazioni di inizializzazione in preparazione a eventi successivi.

Il formato dei messaggi sync che l'API SDK Admin invia al tuo URL di ricezione è mostrato 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 valore dell'intestazione HTTP X-Goog-Message-Number pari 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 canali di notifica

Un canale di notifica può avere un tempo 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). L'eventuale ora di scadenza del canale è inclusa come timestamp Unix (in millisecondi) nelle informazioni restituite dal metodo watch. Inoltre, la data e l'ora di scadenza (in formato leggibile) sono incluse 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 è vicino 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 si verifichi un periodo di "sovrapposizione" di tempo in cui i due canali di notifica per la stessa risorsa sono attivi.

Ricevere notifiche

Ogni volta che una risorsa monitorata cambia, la tua applicazione riceve un messaggio di notifica che descrive la modifica. L'API Admin SDK invia questi messaggi come richieste HTTPS POST all'URL specificato come proprietà address per questo canale di notifica.

Nota:le richieste HTTPS di distribuzione delle notifiche specificano uno user agent di APIs-Google e rispettano le direttive del file robots.txt, come descritto in User agent APIs Google.

Interpretare il formato del messaggio di notifica

Tutti i messaggi di notifica includono un insieme di intestazioni HTTP con prefissi X-Goog-. Alcuni tipi di notifiche possono includere anche un corpo del messaggio.

Intestazioni

I messaggi di notifica pubblicati dall'API Admin SDK nell'URL di ricezione includono le seguenti intestazioni HTTP:

Intestazione	Descrizione
Sempre presente
X-Goog-Channel-ID	UUID o altra stringa univoca fornita per identificare questo canale di notifica.
X-Goog-Message-Number	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.
X-Goog-Resource-ID	Un valore opaco che identifica la risorsa osservata. Questo ID è stabile nelle varie versioni dell'API.
X-Goog-Resource-State	Il nuovo stato della risorsa che ha attivato la notifica. Valori possibili: sync o un nome evento.
X-Goog-Resource-URI	Un identificatore specifico della versione dell'API per la risorsa osservata.
A volte presente
X-Goog-Channel-Expiration	Data e ora di scadenza del canale di notifica, espresse in formato leggibile. Presente solo se definito.
X-Goog-Channel-Token	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 questa risorsa come un'attività. Valore: la stringa fissa "admin#reports#activity".
id	Identificatore univoco del record di attività.
id.time	Ora in cui si è verificata l'attività. Il valore è nel 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 si svolgono nello stesso momento.
id.applicationName	Il nome dell'applicazione a cui appartiene l'evento. I valori possibili includono: admin calendario drive groups groups_enterprise login dispositivo mobile saml token user_accounts
id.customerId	L'identificatore univoco di un account Google Workspace.
actor	L'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 di entità USER o OAuth 2LO che ha eseguito l'azione elencata nel report .
actor.email	L'indirizzo email principale dell'utente le cui attività vengono segnalate.
actor.profileId	L'ID profilo Google Workspace univoco dell'utente.
ownerDomain	Dominio della Console di amministrazione o proprietario del documento dell'applicazione Documenti. Il dominio interessato dall'evento del report.
ipAddress	L'indirizzo IP dell'utente che esegue l'azione. Si tratta dell'indirizzo del protocollo internet (IP) dell'utente al momento dell'accesso a Google Workspace, che potrebbe o meno riflettere la posizione fisica dell'utente. Ad esempio, l'indirizzo IP può essere l'indirizzo del server proxy dell'utente o 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à Google Workspace modificati da un amministratore sono identificati nella proprietà type, che identifica un evento utilizzando la proprietà eventName.
events[].name	Il nome dell'evento. Questo è il nome specifico dell'attività segnalata dall'API. Ogni eventName è correlato a un servizio o a una funzionalità specifica di Google Workspace che l'API organizza in tipi di eventi. Per i parametri di richiesta eventName in generale: Se non viene fornito alcun eventName, il report restituisce tutte le possibili istanze di un eventName. Quando richiedi un eventName, la risposta dell'API restituisce tutte le attività che contengono quel eventName. È possibile che le attività restituite abbiano altre proprietà eventName oltre a quella richiesta.
events[].parameters[]	Coppie di valori di 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 di attività hanno la forma generale:

POST https://mydomain.com/notifications
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 di attività amministrativa:

POST https://mydomain.com/notifications
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": "[e-mail]",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "[e-mail]"
        }
      ]
    }
  ]
}

Risposta alle notifiche

Per indicare l'esito positivo, 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 Admin SDK ritenta con il backoff esponenziale. Tutti gli altri codici di stato del reso vengono considerati un errore del messaggio.

Informazioni sugli eventi di notifica dell'API Admin SDK

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 valori possibili per le notifiche di eventi sono gli stessi del metodo activities.list. Ogni applicazione ha eventi unici:

• admin
• calendario
• drive
• groups
• login
• dispositivo mobile
• saml
• token
• user_accounts

Nota:nel tempo potrebbero essere aggiunti altri eventi di stato delle risorse. I gestori dei messaggi di notifica devono ignorare in modo controllato eventuali valori imprevisti.

Interrompi la ricezione di notifiche

La proprietà expiration controlla quando le notifiche vengono interrotte automaticamente. Puoi scegliere di interrompere la ricezione delle notifiche per un canale specifico prima della scadenza chiamando il metodo stop all'indirizzo URI seguente:

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 di seguito. Tieni presente che se l'API Admin SDK ha diversi tipi di risorse con metodi watch, esiste un solo metodo stop.

Solo gli utenti con l'autorizzazione corretta 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 service account, qualsiasi utente dello stesso client 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"
}

Considerazioni speciali

Quando lavori con le notifiche push, tieni presente quanto segue:

Le notifiche non sono affidabili al 100%. In condizioni di lavoro normali, è normale che una piccola percentuale di messaggi venga eliminata. Assicurati di gestire questi messaggi mancanti in modo appropriato, in modo che l'applicazione si sincronizzi anche se non vengono ricevuti messaggi push.

Le notifiche potrebbero non essere inviate nell'ordine in cui si verificano gli eventi.