REGIONE TOSCANA RT MESSENGER - DOCUMENTO TECNICO
←
→
Trascrizione del contenuto della pagina
Se il tuo browser non visualizza correttamente la pagina, ti preghiamo di leggere il contenuto della pagina quaggiù
REGIONE TOSCANA
SPECIFICHE TECNICHE SISTEMA NOTIFICHE
RT MESSENGER
DOCUMENTO TECNICOSPECIFICHE TECNICHE RT MESSENGER
Controllo del Documento
Numero di Versione 1.5
Data del Documento 19/02/2020
Autori Redatto da C.Simonelli, A. Di Maria, F.Fornasari, M.
Basile (TAI)
Revisionato da F.Fornasari (TAI)
Approvato da
Stato Proposto per approvazione
Storia del documento
Versione Data Descrizione
1.0 22/01/2019 Prima Versione
1.1 25/02/2019 Modificate API
1.2 09/05/2019 Aggiunti Parametro App
1.3 11/12/2019 Aggiunto capitolo Client Rest API
1.4 05/02/2020 Aggiornati gli endpoint e le info sugli scope
1.5 19/02/2020 Aggiornati gli endpoint di Staging (Gateway)
2SPECIFICHE TECNICHE RT MESSENGER
Indice del documento
Controllo del Documento ................................................................................................ 2
Storia del documento ...................................................................................................... 2
1. Introduzione ............................................................................................................ 5
2. Applicazione Server ............................................................................................... 5
2.1. Ciclo di vita del messaggio ..................................................................................................................... 6
3. Utilizzo delle Admin REST API .............................................................................. 7
3.1. Autorizzazione ....................................................................................................................................... 7
3.2. Paginazione............................................................................................................................................ 8
3.3. Servizi per la gestione dei messaggi ...................................................................................................... 8
3.3.1. Creazione di un nuovo messaggio ........................................................................................................... 8
3.3.2. Dettaglio messaggio ................................................................................................................................ 10
3.3.3. Dettaglio destinatario di un messaggio.................................................................................................. 11
3.3.4. Lista destinatari di un messaggio ............................................................................................................ 12
4. Utilizzo delle Client REST API ............................................................................. 14
4.1. Enrollment ........................................................................................................................................... 14
4.2. Gestione Messaggi............................................................................................................................... 15
4.2.1. Recupero lista messaggi .......................................................................................................................... 15
4.2.2. Recupero dettaglio del messaggio ........................................................................................................ 17
4.2.3. Statistiche messaggi ................................................................................................................................. 18
3SPECIFICHE TECNICHE RT MESSENGER
Indice delle tabelle
Tabella 1: Codici di errore.................................................................................................................................. 7
Tabella 2: Parametri creazione di un nuovo messaggio .................................................................................... 9
Tabella 3: Possibili codici di risposta per il servizio di creazione di un nuovo messaggio ............................... 10
Tabella 4: Parametri servizio di recupero dettaglio di un messaggio ............................................................. 10
Tabella 5: Possibili codici di risposta per il servizio di recupero del dettaglio di un messaggio...................... 11
Tabella 6: parametri per il servizio di recupero dettaglio di un destinatario .................................................. 11
Tabella 7: attribuiti presenti nello schema JSON con la lista dei destinatari di un messaggio. ...................... 12
Tabella 8: possibili codici di risposta per il servizio di recupero dettaglio di un destinatario ......................... 12
Tabella 9: parametri per la chiamata al servizio di recupero lista dei destinatari di un messaggio ............... 12
Tabella 10: parametri servizio di recupero lista dei destinatari di un messaggio in caso di paginazione. ...... 13
Tabella 11: attribuiti presenti nello schema JSON con la lista dei destinatari di un messaggio. .................... 13
Tabella 12: possibili codici di risposta per il servizio lista dei destinatari di un messaggio............................. 14
4SPECIFICHE TECNICHE RT MESSENGER
1. Introduzione
L’obiettivo del documento è fornire le specifiche tecniche per l’utilizzo del sistema di notifiche, realizzato in
ambito del progetto App OpenToscana, da parte di sistemi terzi.
Nel documento verranno inoltre descritti i servizi REST esposti con cui le applicazioni client potranno
integrarsi per le operazioni di gestione ed invio di messaggi verso i destinatari desiderati. Le immagini
mostrate nel documento sono d’esempio e potrebbero differire dal sistema finale.
2. Applicazione Server
Message Service è una Web application J2EE che permette la gestione del ciclo di vita dei messaggi e il routing
ai client registrati.
Il sistema mette a disposizione tre interfacce di accesso entrambe basate su Rest:
1. Admin Rest Api – Per permettere la creazione di messaggi e la visualizzazione dello stato di ricezione
degli stessi da parte del client registrati
2. Client Rest Api – Consente la registrazione dei Client e la sincronizzazione bidirezionale dei messaggi
e relative azioni
3. Oauth2 Rest Api – Consente la generazione di token oauth2 utilizzabili per l’invocazione delle Admin
e Client Rest Api
5SPECIFICHE TECNICHE RT MESSENGER
Applicazioni di Console di amministrazione e operatore Mobile Clients Apps
terze parti
Web-Application Android, iOS
Message Service Admin Rest Api Oauth2 Rest Api Client Rest Api
Domain & Permission Service
Repository Service Mobile Notification Service
Figura 1: Architettura logica del sistema Message Service
Internamente il sistema Message Service utilizza un database relazionale per la memorizzazione dei
messaggi, utenti, token accesso ed eventi; inoltre si interfaccia al Mobile Notification Service per segnalare
ai client registrati la presenza di nuovi messaggi oppure eventi. Il Permission Service si occupa di generare e
verificare i token oauth2.
2.1. Ciclo di vita del messaggio
Ogni messaggio inviato contiene almeno le seguenti informazioni:
- body: Il testo del messaggio
- recipients: I destinatari del messaggio
- validUntil: La data entro la quale il messaggio è da considerarsi valido
Un messaggio viene recapitato ad un utente registrato se è presente nella lista dei recipients dello stesso,
se non è mai stato ricevuto e validUntil è successivo o uguale alla data della richiesta.
6SPECIFICHE TECNICHE RT MESSENGER
L’amministratore che cancella un messaggio è come se impostasse il validUntil all’ora attuale. Il risultato è
che tutti gli utenti che hanno già ricevuto il messaggio continueranno a vederlo mentre gli altri non lo
riceveranno mai.
3. Utilizzo delle Admin REST API
Di seguito sono disponibili le Api che permettono, ad una applicazione terza, la creazione, eliminazione di
messaggi e la visualizzazione degli eventi nei confronti dei client. Per convenzione i parametri indicati in
grassetto sono da considerarsi obbligatori.
Per tutti i servizi elencati di seguito vengono utilizzati i seguenti codici di errore:
Codice Descrizione
404 Servizio o messaggio non trovato.
401 / 403 Accesso non autorizzato o consentito.
500 Errore interno.
Tabella 1: Codici di errore
3.1. Autorizzazione
L’autorizzazione deve avvenire attraverso clientId e secret ricevuti da Arpa ed utilizzando client credential
con due scope specifici: uno dei due è sempre “open-toscana-rs/client”, l’altro è uno tra “rtmessenger-
device/audience” e “rtmessenger-device/audience” in base al sub-set di API che si ha intenzione di
utilizzare (rispettivamente endpoint che rispondono a api/device/* e api/sender/*). Questa procedura
genera un access token attraverso il quale invocare le API.
Le API sono attualmente protette dall’API-GATEWAY, quindi per ottenere le credenziali necessarie per
fruire dei servizi descritti in questo documento, la richiesta deve essere inviata sia al supporto ARPA sia al
supporto CART.
L’attuale base URL per le API di STAGING è:
• Device API base URL: https://apistage.regione.toscana.it/C02/rtmessenger-device/v1
• Sender API base URL: https://apistage.regione.toscana.it/C01/rtmessenger-sender/v1
7SPECIFICHE TECNICHE RT MESSENGER
L’attuale base URL per le API di PRODUZIONE è:
• Device API base URL: https://api.regione.toscana.it/C02/rtmessenger-device/v1
• Sender API base URL: https://api.regione.toscana.it/C01/rtmessenger-sender/v1
3.2. Paginazione
Le richieste che restituiscono più risultati vengono paginate (con default = 100). E’ possibile modificare tale
parametro aggiungendo nella query string dell’url il parametro size.
$ curl 'https://host:port/context/api?page=2&size=100'
Se il parametro page viene omesso viene restituita la prima pagina.
3.3. Servizi per la gestione dei messaggi
Di seguito verranno definite in dettaglio le specifiche per ciascuno dei servizi per la gestione completa dei
messaggi del sistema di messaggistica istantanea.
3.3.1.Creazione di un nuovo messaggio
È possibile creare un nuovo messaggio attraverso la chiamata al seguente servizio:
/api/sender/messages
Il servizio può esser invocato passato i seguenti parametri obbligatori tramite il metodo POST:
Parametro Obbligatorio Descrizione
body SI Corpo del messaggio che verrà visualizzato
subject SI Il titolo del messaggio
NO Body da visualizzare nella notifica. Se non indicato verrà
utilizzato il campo body. Da utilizzare quando ci sono
altBody
informazioni di privacy che non devono essere
visualizzate nel campo notifica.
altSubject NO Subject da visualizzare nella notifica. Se non indicato
verrà utilizzato il campo subject. Da utilizzare quando ci
8SPECIFICHE TECNICHE RT MESSENGER
sono informazioni di privacy che non devono essere
visualizzate nel campo notifica.
NO È la modalità attraverso la quale visualizzare la notifica
all’interno dell’applicazione. Se non indicata verrà
template
utilizzata quella standard. I template devono essere
concordati tra mittente e destinatario
SI È la modalità di invio della notifica. Valori ammessi:
mode
ByTopic, ByIdentity, ByRole
recipients SI La lista dei destinatari in base al mode selezionato
NO Data ed ora, in formato UTC, entro la quale il messaggio
expiration
risulterà essere valido. Se non indicato il sistema
NO Data ed ora, in formato UTC, dopo il quale inviare il
notBefore messaggio. Se non indicato il messaggio verrà
notificato immediatamente.
meta NO Attributi opzionali
SI Nome della App a cui inviare il messaggio, per esempio
app
“open-toscana”
Tabella 2: Parametri creazione di un nuovo messaggio
Di seguito un esempio di modello JSON di creazione di un nuovo messaggio:
{
"body": "Prima prova di messaggio",
"subject": "L’oggetto del messaggio",
"expiration": "2019-01-16T22:00:00Z",
"app": "open-toscana",
"mode": "ByIdentity",
"recipients": [
" TINIT-cf1"," TINIT-cf2"
]
}
9SPECIFICHE TECNICHE RT MESSENGER
I possibili codici di risposta per questa chiamata sono i seguenti:
Codice Descrizione
201 Messaggio creato con successo.
Tabella 3: Possibili codici di risposta per il servizio di creazione di un nuovo messaggio
Il tracciato JSON di risposta assume la seguente forma:
{
"messageId": 100
}
3.3.2.Dettaglio messaggio
Attraverso la seguente chiamata è possibile ottenere il dettaglio di uno specifico messaggio:
/api/sender/messages/{messageId}
Il servizio può esser invocato utilizzando il metodo GET secondo la seguente codifica del path:
Parametro Descrizione
messageId Identificativo del messaggio.
Tabella 4: Parametri servizio di recupero dettaglio di un messaggio
Il tracciato JSON è lo stesso dell’invio del messaggio
I possibili codici di risposta per questa chiamata sono i seguenti:
Codice Descrizione
404 Messaggio non trovato
403 Messaggio non visibile per mancanza di diritti
10SPECIFICHE TECNICHE RT MESSENGER
200 Ok.
Tabella 5: Possibili codici di risposta per il servizio di recupero del dettaglio di un messaggio
3.3.3.Dettaglio destinatario di un messaggio
Attraverso la seguente chiamata è possibile ottenere il dettaglio di uno specifico destinatario per
un determinato messaggio:
/api/sender/messages/{messageId}/recipients/{login}
Il servizio può esser invocato utilizzando il metodo GET secondo la seguente codifica del path:
Parametro Descrizione
messageId Identificativo del messaggio.
login Codice del fiscale del destinatario.
Tabella 6: parametri per il servizio di recupero dettaglio di un destinatario
Il tracciato JSON di risposta assume la seguente forma:
{
"recipientId": "TINIT-cf1",
"read": {
"eventTime": "2015-03-12T14:57:50Z"
},
"received": {
"eventTime": "2015-03-05T14:57:50Z"
}
}
Gli attributi presenti per ciascun destinatario restituito sono i seguenti:
11SPECIFICHE TECNICHE RT MESSENGER
Attributo Descrizione
recipientId Identificativo del destinatario.
Contiene data di lettura del messaggio e l’identificativo del device
read destinatario. Se il messaggio non è ancora stato letto l’attribuito
assume valore null oppure non presente.
Contiene data di ricezione del messaggio e l’identificativo del device
received destinatario. Se il messaggio non è stato ancora ricevuto l’attribuito
assume valore null oppure non presente.
Tabella 7: attribuiti presenti nello schema JSON con la lista dei destinatari di un messaggio.
I possibili codici di risposta per questa chiamata sono i seguenti:
Codice Descrizione
200 Ok.
Tabella 8: possibili codici di risposta per il servizio di recupero dettaglio di un destinatario
3.3.4.Lista destinatari di un messaggio
Dato un codice identificativo di un messaggio, la seguente chiamata restituisce la lista dei relativi
destinatari paginata ed il dettaglio dello stato per ciascuno di essi in merito allo specifico
messaggio:
/api/sender/messages/{messageId}/recipients
Il servizio può esser invocato utilizzando il metodo GET secondo la seguente codifica del path:
Parametro Descrizione
messageId Identificativo del messaggio.
Tabella 9: parametri per la chiamata al servizio di recupero lista dei destinatari di un messaggio
I seguenti parametri opzionali, necessari in caso di paginazione, possono essere inviati alla chiamata
utilizzando il metodo GET:
Parametro Descrizione
12SPECIFICHE TECNICHE RT MESSENGER
size Numero di elementi per pagina (default 100).
page Numero di pagina (default 0).
Tabella 10: parametri servizio di recupero lista dei destinatari di un messaggio in caso di paginazione.
Il tracciato JSON di risposta assume la seguente forma:
[{
"recipientId": "TINIT-cf1",
"read": {
"eventTime": "2015-03-12T14:57:50Z"
},
"received": {
"eventTime": "2015-03-05T14:57:50Z"
}
}]
Gli attributi presenti per ciascun destinatario restituito sono i seguenti:
Attributo Descrizione
recipientId Identificativo del destinatario.
Contiene data di lettura del messaggio e l’identificativo del device
read destinatario. Se il messaggio non è ancora stato letto l’attribuito
assume valore null oppure non presente.
Contiene data di cancellazione del messaggio e l’identificativo del device
deleted destinatario. Se il messaggio non è stato cancellato l’attribuito assume
valore null oppure non presente.
Contiene data di ricezione del messaggio e l’identificativo del device
received destinatario. Se il messaggio non è stato ancora ricevuto l’attribuito
assume valore null oppure non presente.
Tabella 11: attribuiti presenti nello schema JSON con la lista dei destinatari di un messaggio.
13SPECIFICHE TECNICHE RT MESSENGER
I possibili codici di risposta per questa chiamata sono i seguenti:
Codice Descrizione
200 Ok.
Tabella 12: possibili codici di risposta per il servizio lista dei destinatari di un messaggio
4. Utilizzo delle Client REST API
Di seguito è riportata la lista delle API che permettono ad un’app (client) di interagire con il sistema di notifica
per le seguenti operazioni:
• Enrollment: ovvero la fase di registrazione del device fisico dell’utente.
• Gestione Messaggi: la gestione va vista in termini di recupero della lista messaggi per l’utente, lo
stato del messaggio (letto o non letto), la visualizzazione del messaggio.
Per l’autorizzazione dovrà essere creato sul sistema ARPA un client OAuth2.0 di tipo public e con scope
assegnato open-toscana-rs/app.
4.1. Enrollment
Per la fase di registrazione, il sistema prevede l’esecuzione di una PUT all’API seguente:
/api/device/register
Il body strutturato in formato application/json dovrà contenere i seguenti parametri:
Parametro Descrizione
Package ID dell’applicativo, ovvero l’identificativo di package sugli store
appId
Apple o Google; per esempio it.toscana.regione.opentoscana
Identificativo dell’applicazione, ovvero deve essere corrispondente al
appName
nome configurato sul sistema di notifica che è multi applicazione.
appVersion Versione dell’applicazione
deviceKind Piattaforma di riferimento: Android o IOs
messagingKind Canale di distribuzione: FirebaseFCM o AppleAPNS
14SPECIFICHE TECNICHE RT MESSENGER
Token di autenticazione sul canale di distribuzione della piattaforma di
messagingToken riferimento per il device, generato nel momento in cui l’app viene
installata.
name Modello del device
osVersion Versione del sistema operativo
Questa fase prevede una prima chiamata senza gli Headers Secret e Authentication di cui al punto ma con il
campo messaggingToken popolato con il token Firebase o APNS. L'RT Messenger risponde con il valore Secret
che dovrà essere utilizzato nelle successive registrazioni (con o senza accessToken) e nelle chiamate agli altri
endpoint. È importante utilizzare sempre il Secret più recente.
Nel caso in cui l'RT Messenger risponda con 401 a una delle chiamate effettuate con l'ultimo Secret posseduto
dal device, è necessario che esso rieffettui la registrazione per ottenere un nuovo Secret.
4.2. Gestione Messaggi
Le API client per la gestione messaggi sono le seguenti.
4.2.1.Recupero lista messaggi
Per recuperare la lista messaggi specifica per il device registrato, il sistema prevede una GET all’API
seguente:
/api/device/messages
Con i seguenti parametri:
Parametro Descrizione
count Numero di messaggi richiesti
Data fino alla quale si richiedono i messaggi. Se non viene passato, verrà
to
presa la data attuale.
Il tracciato JSON di risposta ha la seguente forma:
[
{
"id": 336,
15SPECIFICHE TECNICHE RT MESSENGER
"body": "app background token scaduto\n",
"subject": "monica 2222",
"creation": "2019-11-15T18:02:29.302Z",
"expiration": "2029-11-12T18:02:29.302Z",
"updated": "2019-11-15T18:02:29.302Z",
"template": "default",
"topic": {
"id": 1,
"name": "default",
"description": "Topic di default",
"subscribed": false
},
"status": "Received",
"meta": {},
"new": true
},
{
"id": 335,
"body": "app aperta token scaduto",
"subject": "test monica 3333",
"creation": "2019-11-15T17:55:05.995Z",
"expiration": "2029-11-12T17:55:05.995Z",
"updated": "2019-11-15T17:55:05.995Z",
"template": "default",
"topic": {
"id": 1,
"name": "default",
"description": "Topic di default",
16SPECIFICHE TECNICHE RT MESSENGER
"subscribed": false
},
"status": "Received",
"meta": {},
"new": true
},
{
"id": 334,
"body": "app non accesa",
"subject": "Test monica",
"creation": "2019-11-15T17:49:31.397Z",
"expiration": "2029-11-12T17:49:31.397Z",
"updated": "2019-11-15T17:49:31.397Z",
"template": "default",
"topic": {
"id": 1,
"name": "default",
"description": "Topic di default",
"subscribed": false
},
"status": "Viewed",
"meta": {},
"new": false
}
]
4.2.2.Recupero dettaglio del messaggio
Per leggere il messaggio, è necessario effettuare una GET alla seguente API:
17SPECIFICHE TECNICHE RT MESSENGER
/api/device/messages/viewd/{messageId}
Il formato JSON di risposta ha la forma seguente:
[
{
"id": 43,
"body": "test test test",
"subject": "test pubblico 3",
"creation": "2019-10-03T13:58:52.823Z",
"expiration": "2029-09-30T13:58:52.823Z",
"updated": "2019-10-03T13:58:52.823Z",
"template": "default",
"topic": {
"id": 1,
"name": "default",
"description": "Topic di default",
"subscribed": false
},
"status": "Viewed",
"meta": {},
"new": false
}
]
4.2.3. Statistiche messaggi
Il sistema espone un API in GET per estrarre informazioni, per lo specific device, riguardo:
18SPECIFICHE TECNICHE RT MESSENGER
• numero di tutti i messaggi a cui l’utente ha diritto di accesso
• numero messaggi da leggere
• data dell’ultimo messaggio inviato che l’utente può leggere
/api/device/messages/stat
Il formato JSON di risposta ha la forma seguente:
{
"globalCount": 17,
"newCount": 10,
"lastReceivedOn": "2019-11-15T18:02:29.351Z"
}
19Puoi anche leggere
