Il blog di Giuseppe Marchi - SharePoint MVP
NAVIGATION - SEARCH

Rilasciata la developer preview degli SharePoint WebHooks

A seguito del rilascio della prima preview dello SharePoint Framework, il team di prodotto di Microsoft rilascia gli SharePoint WebHooks, sempre all'interno dei "Developer tenant" di Office 365.

Di che si tratta?
Un WebHook è una modalità in cui una propria applicazione client, può essere notificata da un'applicazione server-side di terze parti, allo scatenarsi di uno o più particolari eventi. E' un concetto che è ormai noto nel web e che è stato il seguito delle tematiche di sviluppo di API. Fondamentalmente, le API forniscono dati a chi li ha richiesti, i WebHook forniscono a chi si è sottoscritto e allo scatenarsi di un evento.
Tecnicamente, un WebHook è una chiamata in POST verso le varie applicazioni client che si sono sottoscritte ad un particolare evento. Questa chiamata, ha come corpo della chiamata un oggetto JSON contenente tutte le informazioni che l'applicazione server-side decide di fornire legate all'evento scatenato.
Per farvi un esempio:
- Una API può rispondere alla richiesta "Dammi l'elenco delle fatture del mese".
- Un WebHook può rispondere alla richiesta "Avvisami quando viene inserita una nuova fattura".
Il concetto dei WebHook ha sicuramente aiutato ad implementare tutte le nuove applicazioni real-time che sono in voga in questo momento.
Con questo rilascio il team di prodotto di SharePoint integra il concetto dei WebHook all'interno di parte della sua architettura. Sì perchè ad ora sono stati aggiunti solamente ai principali eventi legati alle liste e librerie di documenti.

Dov'è la novità?
Se ci pensate bene, il concetto di base è lo stesso che sta dietro agli Event Receiver (per lo sviluppo server-side su installazioni on-premise) e ai Remote Event Receivers (per lo sviluppo sul cloud, tramite il modello ad Add-in).
La novità sta nella tecnologia utilizzata.
Le notifiche vengono generate da un modello veramente robusto per quanto riguarda l'affidabilità sulla ricezione dei messaggi. Modello, basato su HTTP, in grado quindi di utilizzare quindi tutti i codici di stato standard del protocollo per determinare come e quando effettuare le richieste di "retry", così da non perdere nessun messaggio. Funzionalità che su piattaforme cloud come quella di Office 365 (cioè dove non avete alcun controllo server-side) è sicuramente indispensabile.
In aggiunta, se seguite quello che accade per gli altri prodotti Office 365, neanche in questo caso sarete rimasti sorpresi da questo annuncio. Le WebHook sono già state applicate con successo all'interno delle API di Outlook Online.

Come utilizzare le nuove API di notifica
Per utilizzare le API di notifica è necessario prima sottoscriversi. Per farlo, basta fare una chiamata alle API REST di SharePoint Online e specificare queste tre informazioni necessarie a ricevere le notifiche:

  1. La risorsa su cui si vuole ricevere le notifiche (es: l'URL di una lista SharePoint)
  2. L'indirizzo della vostra applicazione client (cioè esterna al contesto di SharePoint) a cui SharePoint deve mandare la chiamata in POST allo scatenarsi di un evento sulla lista
  3. La data di scadenza della sottoscrizione (come limite, non ci possono essere sottoscrizioni con scadenze più lunghe di 6 mesi)
A queste tre informazioni è possibile aggiungere un quarto parametro, opzionale, che può essere utilizzato per scopi vari.
Vi lascio qui un pò di codice d'esempio.

URL richiesta: https://dev4side.sharepoint.com/_api/web/lists('Test')/subscriptions
Tipo di richiesta: POST
ContentType: application/json
Corpo del messaggio:

{
"resource":"https://dev4side.sharepoint.com/_api/web/lists('Test')",
"notificationUrl":"https://apps.dev4side.com/realtimeapp/service",
"expirationDateTime":"2016-09-15T12:00:00+00:00"
}

A seguito di questa chiamata, SharePoint Online verifica che l'endpoint che è stato specificato, sia in grado di ricevere le notifiche. Questa verifica viene effettuata con una prima chiamata in POST a cui l'endpoint deve rispondere con uno stato HTTP 200 assieme ad un token di validazione nel corpo della richiesta, il tutto nel minor tempo possibile. Non verranno create sottoscrizioni se l'endpoint non risponde subito alla richiesta di verifica (la documentazione dice che il tempo di risposta deve essere inferiore a 5 secondi).
Fatto questo, il vostro endpoint è pronto per ricevere notifiche.



Come avete potuto capire, dall'altra parte ci deve essere un'applicazione esterna al contesto di SharePoint Online che dovrà essere in grado di ricevere la richiesta in POST e gestirla. Ovviamente non c'è limite riguardo la tecnologia che può essere utilizzata per questa applicazione.

E' la morte dei Remote Event Receiver?
Sicuramente NO.
Microsoft continuerà a mantenere entrambe le possibilità (WebHook e Remote Event Receiver) per lasciare allo sviluppatore la più ampia scelta possibile. I Remote Event Receiver risultano ancora l'unica possibilità per eseguire delle azioni personalizzate su eventi sincroni generati da SharePoint (es: ItemAdding) che invece NON sono supportati dalle nuove API di notifiche (con i WebHook ci si può sottoscrivere all'evento ItemAdded per intederci).

Conclusioni
Potete accedere alla documentazione iniziale di queste nuove API a questo indirizzo: https://aka.ms/spwebhooks
Su GitHub è già presente un repository con del codice d'esempio a questo indirizzo: https://aka.ms/spwebhooksample
Se volete vedere i WebHook in azione, vi consiglio di vedere la registrazione di questo webcast.
Come vi dicevo, per ora queste nuove API sono in preview e coprono solamente alcuni degli eventi di liste e librerie di documenti. Non ci sono ancora informazioni riguardo la lista completa di eventi che verrà implementata, ne se e quando questa funzionalità entrerà a far parte della versione on-premise di SharePoint.

blog comments powered by Disqus