Template HTTP

Configurazione template HTTP

Il template HTTP non necessita di ulteriori configurazioni. Una volta selezionato il tipo di template HTTP e aggiunto i segnali, è possibile iniziare la trasmissione. 

Trasmettere ad un template

I dati vanno inoltrati all'indirizzo https://api.databoom.com/v1/signals/push/<valore unico arbitrario>. 

Il valore unico arbitrario è un valore scelto a piacere dall'utente per identificare in maniera univoca il dispositivo. Verrà utilizzato, insieme al token del template, come token e descrizione del dispositivo generato seguendo la struttura <token template>-<valore unico arbitrario>.

Per autenticare la richiesta è necessario utilizzare un OAuth token generato in Databoom con permessi di Pubblicazione e Creazione

• Nel menù laterale Impostazioni -> Credenziali, cliccare il pulsante Aggiungi OAuth nel riquadro Chiavi OAuth
• Per garantire una sicurezza ottimale, si consiglia di generare un OAuth token diverso per ogni istanza del template che si vuole configurare

Il formato dei dati da inoltrare è il seguente:

{
    "type": "data",
    "message":  [
      {
        "template": "<token template HTTP>",
        "date": "2018-04-12T15:00:00.000Z",
        "signals": [
          {
            "name": "<token segnale 1>",
            "value": <valore segnale 1>
          },
          {
            "name": "<token segnale 2>",
            "value": <valore segnale 2>
          }
        ]
      }
    ]
}

Il <token template HTTP> è disponibile nel riquadro informazioni all'interno del dispositivo.

Il campo date non è obbligatorio, se non viene inserito viene memorizzata la data al momento della ricezione.

I token dei segnali, nell'esempio <token segnale 1> e <token segnale 2>, possono essere copiati direttamente dalla pagina del dispositivo cliccando l'icona di copia all'interno dell'etichetta corrispondente.

La pubblicazione di questo payload comporta:

• Se precedentemente non è avvenuta alcuna comunicazione:
  • la generazione di un nuovo dispositivo con token <token template HTTP>-<valore unico arbitrario>. Il dispositivo verrà popolato con gli stessi segnali associati al template (nuovi segnali con lo stesso token), indipendentemente dal fatto che vengano inviati o meno loro valori. I segnali saranno già validati e pronti a comunicare. Se in signals vengono inseriti segnali non previsti dal template, vengono creati nel nuovo dispositivo in attesa di validazione
• Se precedentemente sono già avvenute comunicazioni:
  • l'aggiornamento del dispositivo <token template HTTP>-<valore unico arbitrario> con i valori in signals. Se al template è stato associato un nuovo segnale, viene creato anche nel dispositivo

message è un array, è pertanto possibile creare/comunicare con più dispositivi a pubblicazione, a patto che facciano riferimento a template diversi.

Funzione di trasformazione per dati pubblicati

Nel caso non sia possibile personalizzare il contenuto dei dati da inoltrare nel formato compatibile con Databoom (formato del punto precedente), è possibile specificare, nella pagina di modifica dei singoli segnali, una funzione di trasformazione per elaborare il payload inoltrato e renderlo interpretabile dalla piattaforma.

La funzione deve ritornare uno o più valori (array []) nel formato:

{
    'date': <DATA>,
    'value': <VALORE>
}

o

{
    'value': <VALORE>
}

o

<VALORE>

Nel caso si utilizzi un array, è possibile utilizzare formati diversi per le diverse componenti.

Nell'esempio si può notare la funzione doIt 

function doIt(payload) {    
    return {
        'date': new Date(),
        'value': (payload[1].charCodeAt(0) - 97)
    };
}

Il parametro payload permette di accedere ai dati pubblicati e di elaborarli in modo da restituirli nel formato compatibile. Nell'esempio il valore viene ricavato sottraendo 97 al codice del primo carattere della prima componente del payload.