Questa pagina è stata tradotta dall'API Cloud Translation.

Notifiche push

Questo documento descrive come utilizzare le notifiche push che informano la tua applicazione quando una risorsa viene modificata.

Panoramica

L'API Admin SDK fornisce notifiche push che 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 alle risorse di polling per determinare se sono cambiate. Ogni volta che una risorsa controllata viene modificata, l'API SDK Admin invia una notifica all'applicazione.

Per utilizzare le notifiche push, devi fare due cose:

Configura l'URL di ricezione o il destinatario di callback "webhook".
Questo è un server HTTPS che gestisce i messaggi di notifica dell'API che vengono attivati quando una risorsa viene modificata.
Configura un (canale di notifica) per ogni endpoint delle risorse che vuoi guardare.
Un canale specifica le informazioni di routing per i messaggi di notifica. Come parte della configurazione del canale, devi identificare l'URL specifico in cui vuoi ricevere le notifiche. Ogni volta che la risorsa di un canale viene modificata, l'API SDK Admin invia un messaggio di notifica come richiesta POST all'URL.

Attualmente, l'API Admin SDK 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. Dopo aver configurato i canali di notifica, l'API Admin SDK informa la tua applicazione in caso di modifiche alle risorse guardate.

Inviare richieste di visualizzazione

A ogni risorsa dell'API SDK Admin guardabile è associato un metodo watch in un URI nel 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 per la risorsa.

Ogni canale di notifica è associato a un determinato utente e a una determinata risorsa (o insieme di risorse). Una richiesta watch non avrà esito positivo se l'utente o l'account di servizio attuale non 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 solo notifiche relative a specifici eventi, utenti o applicazioni.

Nota:per chiarezza, nei seguenti esempi viene omesso il corpo della richiesta.

Controlla tutte le attività di amministrazione:

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

Guarda tutte le attività relative ai documenti:

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

Controlla l'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 watch, devi compilare i seguenti campi:

Una stringa della 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 una stringa univoca simile. Lunghezza massima: 64 caratteri.

Il valore ID impostato viene riportato nell'intestazione HTTP X-Goog-Channel-Id di ogni messaggio di notifica che ricevi per questo canale.
Una stringa della 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 è 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 tua richiesta watch:

Una proprietà token che specifica un valore stringa arbitrario da utilizzare come token di 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 assicurarti che la notifica non sia oggetto di spoofing, oppure 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 di ogni messaggio di notifica che la tua applicazione riceve per questo 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.
Nota: se devi inviare dati altamente sensibili, assicurati che siano criptati prima di aggiungerli al token.
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 interrompa l'invio di messaggi per questo canale di notifica.

Se un canale ha una data di scadenza, viene incluso come valore dell'intestazione HTTP X-Goog-Channel-Expiration (in formato leggibile) in ogni messaggio di notifica ricevuto dall'applicazione per questo canale.

Nota: per l'API SDK Admin, la scadenza massima è 21.600 secondi. Se non imposti la proprietà expiration nella richiesta, la data di scadenza predefinita sarà 21.600 secondi dopo l'ora attuale.

Per maggiori dettagli sulla richiesta, consulta il metodo watch per la risorsa Activities nel riferimento API.

Guarda 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 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à che hai inviato nell'ambito della richiesta, le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa guardata su questo canale di notifica.

Nota: la proprietà resourceId è un identificatore stabile e indipendente dalla versione per la risorsa. La proprietà resourceUri è l'URI canonico della risorsa monitorata nel contesto della versione corrente dell'API, quindi è 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 maggiori dettagli sulla risposta, consulta il metodo watch per la risorsa Activities nel riferimento API.

Sincronizza messaggio

Dopo aver creato un canale di notifica per guardare una risorsa, l'API Admin SDK 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 di problemi di rete, è possibile ricevere il messaggio sync anche prima di ricevere la risposta del metodo watch.

Puoi ignorare la notifica sync, ma puoi usarla. 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 inizializzazioni e prepararti per gli eventi successivi.

Di seguito è mostrato il formato dei messaggi sync che l'API Admin SDK invia all'URL di destinazione.

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 di intestazione HTTP X-Goog-Message-Number pari a 1. Ogni notifica successiva per questo canale ha un numero di messaggi maggiore della precedente, anche se i numeri dei messaggi 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 o predefiniti dell'API Admin SDK (viene utilizzato il valore più restrittivo). La data di scadenza del canale, se presente, viene inclusa come timestamp Unix (in millisecondi) nelle informazioni restituite dal metodo watch. Inoltre, la data e l'ora di scadenza sono incluse (in formato leggibile) in ogni messaggio di notifica ricevuto dall'applicazione 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 richiamando il metodo watch. Come sempre, devi utilizzare un valore univoco per la proprietà id del nuovo canale. Tieni presente che potrebbe verificarsi un periodo di tempo di "sovrapposizione" in cui i due canali di notifica per la stessa risorsa sono attivi.

Ricezione notifiche

Ogni volta che una risorsa controllata viene modificata, 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.

Nota: le richieste HTTPS per la consegna delle notifiche specificano uno user agent pari a APIs-Google e rispettano le istruzioni del file robots.txt, come descritto nella sezione API Google User agent.

Interpretare il formato dei messaggi 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 SDK Admin nell'URL di destinazione includono le seguenti intestazioni HTTP:

Titolo	Descrizione
Sempre presente
`X-Goog-Channel-ID`	UUID o altra stringa univoca che hai fornito 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`. Il numero dei messaggi aumenta per ogni messaggio successivo sul canale, ma non è sequenziale.
`X-Goog-Resource-ID`	Un valore opaco che identifica la risorsa controllata. Questo ID è stabile in tutte 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 della versione dell'API per la risorsa monitorata.
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`	La identifica come risorsa di attività. Valore: la stringa fissa "`admin#reports#activity`".
`id`	Identificatore univoco del record dell'attività.
`id.time`	Ora in cui si è verificata l'attività. Il valore è nel formato di data e 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 tempo.
`id.applicationName`	Nome dell'applicazione a cui appartiene l'evento. I valori possibili includono: admin calendario guida gruppi groups_enterprise login dispositivo mobile saml token user_accounts
`id.customerId`	L'identificatore univoco di un account Google Workspace.
`actor`	L'utente esegue l'azione.
`actor.callerType`	Il tipo di autore che ha eseguito l'attività indicata nel report. In questa versione dell'API, `callerType` rappresenta la richiesta dell'entità `USER` o OAuth 2LO che ha eseguito l'azione indicata nel report .
`actor.email`	L'indirizzo email principale dell'utente di cui vengono registrate 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ò indicare 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. La funzionalità o il servizio di Google Workspace modificato da un amministratore viene identificato nella proprietà `type`, che identifica un evento utilizzando la proprietà `eventName`.
`events[].name`	Il nome dell'evento. Si tratta del 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 di richiesta `eventName` in generale: Se non viene fornito alcun valore `eventName`, il report restituisce tutte le possibili istanze di un elemento `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 delle risorse di 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 a un'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 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 SDK Admin esegue un nuovo tentativo con un backoff esponenziale. Ogni altro codice di stato restituito è considerato un messaggio non riuscito.

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

Notifiche di arresto

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

Solo gli utenti con l'autorizzazione appropriata possono interrompere un canale. In particolare:

Se il canale è stato creato da un normale account utente, solo lo stesso utente dello stesso client (identificato dagli ID client OAuth 2.0 dei token di autorizzazione) che ha creato il canale può arrestare il canale.
Se il canale è stato creato da un account di servizio, qualsiasi utente dello stesso client può arrestare 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"
}