Notifiche push

Questo documento descrive come utilizzare le notifiche push per informare i tuoi quando una risorsa cambia.

Panoramica

L'API Directory fornisce notifiche push che ti consentono di monitorare le modifiche alle 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 Directory invia una notifica alla tua applicazione.

Per utilizzare le notifiche push, devi fare due cose:

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

    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 la risorsa di un canale cambia, l'API Directory invia un messaggio di notifica come richiesta POST a quell'URL.

Al momento, l'API Directory supporta le notifiche per le modifiche alla risorsa Users.

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 Directory informa l'applicazione quando una risorsa monitorata cambia.

Effettua richieste di orologio

A ogni risorsa dell'API Directory disponibile è 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 andrà a buon fine a meno che l'account di servizio o l'utente corrente non sia proprietario di questa risorsa o non disponga dell'autorizzazione per accedervi.

Esempi

Tutte le richieste di visualizzazione per la risorsa User per un singolo dominio hanno il formato generale:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Utilizza i parametri domain e event per specificare il dominio e il tipo di evento per cui vuoi ricevere le notifiche.

Tutte le richieste di orologi per la risorsa Utente di un cliente hanno la forma generale:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Utilizza i parametri customer e event per specificare l'ID univoco dell'Account Google del cliente e il tipo di evento per cui vuoi ricevere notifiche.

I valori possibili per event sono:

  • add: evento creato dall'utente
  • delete: evento eliminato dall'utente
  • makeAdmin: evento di modifica dello stato dell'amministratore utenti
  • undelete: evento di annullamento dell'eliminazione dell'utente
  • update: evento di aggiornamento utente

Nota: nei seguenti esempi, il corpo della richiesta omette il corpo della richiesta per maggiore chiarezza.

Cerca gli eventi creati dall'utente per il dominio mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Cerca gli eventi creati dall'utente per il cliente my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

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 dell'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 valore web_hook.

  • Una stringa di proprietà address impostata sull'URL che ascolta e risponde alle notifiche per questo canale di notifica. Si tratta del tuo URL di callback webhook e deve utilizzare HTTPS.

    Tieni presente che l'API Directory è 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 con la richiesta 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 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 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 Directory 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 ricevute dall'applicazione per questo canale.

Per maggiori dettagli sulla richiesta, fai riferimento al metodo watch per la risorsa Users in Riferimento API.

Guardare 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": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // 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 Users nel riferimento all'API.

Messaggio di sincronizzazione

Dopo aver creato un canale di notifica per monitorare una risorsa, l'API Directory invia un messaggio sync per indicare che le notifiche stanno iniziando. 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 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 utilizzare anche Notifica sync per eseguire alcune operazioni di inizializzazione per prepararsi per gli eventi successivi.

Il formato dei messaggi sync a cui l'API Directory invia 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 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 Directory (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, 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 in modo che sia una "sovrapposizione" periodo di tempo in cui i due canali di notifica sono attive nella stessa risorsa.

Ricevere notifiche

Ogni volta che una risorsa controllata cambia, l'applicazione riceve messaggio di notifica che descrive la modifica. L'API Directory 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 testo.

Intestazioni

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

Intestazione Descrizione
Sempre presente
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. 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 guardata. 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 della versione dell'API specifico per la risorsa controllata.
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 gli utenti contengono le seguenti informazioni nel corpo della richiesta:

Proprietà Descrizione
kind Identifica questa risorsa come utente. Valore: la stringa fissa "admin#directory#user".
id Identificatore univoco della risorsa utente.
etag ETag del messaggio di notifica. Diverso dall'ETag della risorsa Utente.
primaryEmail L'indirizzo email principale dell'utente.

Esempi

I messaggi di notifica per gli eventi delle risorse User 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: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Un esempio di evento eliminato da un utente:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.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 Directory nuovi tentativi con backoff esponenziale. Tutti gli altri codici di stato di ritorno sono considerati errori di messaggio.

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 della scadenza chiamando il metodo stop al seguente URI:

https://www.googleapis.com/admin/directory_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 Directory ha diversi tipi di con watch metodi, ce n'è solo uno 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 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/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}