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 usare questa funzione per migliorare le prestazioni di la 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:

  • Configura l'URL di ricezione o il "webhook" ricevitore 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. Durante la configurazione del canale, devi identificare l'URL specifico su cui vuoi ricevere le notifiche. Ogni volta che una risorsa del canale cambia, l'API SDK Admin invia un messaggio di notifica come POST richiesta a quell'URL.

Al momento, l'API SDK Admin supporta le notifiche per le modifiche alla risorsa Attività.

Crea 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.

Effettua richieste di orologio

A ogni risorsa dell'API Admin SDK visibile è associata una risorsa 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 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: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

Tieni d'occhio 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

Tieni d'occhio 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 simile stringa univoca. 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 valore web_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 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 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 stata falsificata, oppure per inoltrare il messaggio alla destinazione corretta all'interno della tua applicazione in base allo scopo del canale. Lunghezza massima: 256 caratteri.

    Il token è incluso nel Intestazione HTTP X-Goog-Channel-Token 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, ad esempio i parametri di query dell'URL. Esempio: forwardTo=hr&createdBy=mobile

    • Non includere dati sensibili come 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 data di scadenza, questa è inclusa come valore dell'intestazione HTTP X-Goog-Channel-Expiration (in formato leggibile da persone) in ogni messaggio di notifica ricevuto dalla tua applicazione per questo canale.

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

Guardare la risposta

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, 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 ad altre operazioni del canale di notifica, ad esempio quando vuoi interrompere la ricezione delle notifiche.

Per ulteriori dettagli sulla risposta, consulta watch per la risorsa Activities nel riferimento API.

Messaggio di sincronizzazione

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. Il valore dell'intestazione HTTP X-Goog-Resource-State 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 anche utilizzare la sync notifica per eseguire alcune operazioni di inizializzazione in preparazione agli 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 contiene un numero di messaggio maggiore del precedente, sebbene il messaggio i numeri non saranno sequenziali.

Rinnova i 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 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 richiamando 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" quando i due canali di notifica per la stessa risorsa sono attivi.

Ricevere 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.

.

Interpreta il formato del messaggio 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
X-Goog-Channel-ID UUID o un'altra stringa univoca che hai fornito per identificarla 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. Messaggio aumentano per ogni messaggio successivo sul canale, ma non sequenziali.
X-Goog-Resource-ID Un valore opaco che identifica la risorsa controllata. Questo ID è sono stabili tra le 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 per la versione API della risorsa guardata.
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 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 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 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 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 del proprietario del documento 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 del protocollo internet (IP) dell'utente quando accede a Google Workspace, che può o meno riflettere 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 è 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 Google Workspace specifico che l'API organizza in tipi di eventi.
Per i parametri della richiesta eventName in generale:
  • Se eventName non viene specificato, 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 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 di 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 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 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 controlla quando le notifiche si interrompono automaticamente. Puoi scegliere di interrompere la ricezione delle notifiche per un determinato canale prima della scadenza chiamando il metodo stop al 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 Admin SDK ha diversi tipi di risorse con metodi watch, esiste un solo metodo watch.

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 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"
}