API dati di riferimento Azure Time Series Insights Gen1
Attenzione
È un articolo di Gen1.
Questo articolo descrive l'API di riferimento Gestione dati di Azure Time Series Insights Gen1 usata per gestire gli elementi all'interno di un set di dati di riferimento. Si presuppone che il set di dati di riferimento sia già stato creato all'interno dell'ambiente.
I dati di riferimento includono i dati del produttore o della posizione che cambiano raramente. I dati di riferimento vengono usati per contestualizzare i dati di telemetria e servono per confrontare i dati di telemetria.
Suggerimento
- Per creare un set di dati di riferimento, vedere Come creare un set di dati di riferimento.
Poiché i set di dati sono preesistenti e fissi, ogni pacchetto di dati inviato da un dispositivo contiene informazioni identiche. Di conseguenza, i dati di riferimento non vengono inviati dai dispositivi e si gestiscono i dati usando l'API Di riferimento Gestione dati o l'portale di Azure.
Panoramica delle API
L'API Reference Gestione dati è un'API batch.
Importante
- Tutte le operazioni relative a questa API sono operazioni HTTP POST.
- Ogni operazione accetta oggetti JSON come payload della richiesta.
- Gli oggetti JSON della richiesta HTTP definiscono un singolo nome di proprietà che specifica l'operazione da eseguire dall'API.
I nomi delle proprietà delle richieste JSON validi sono:
Importante
- Il valore della proprietà è una matrice di elementi di dati di riferimento su cui deve essere applicata l'operazione.
- Ogni elemento viene elaborato singolarmente e un errore con un elemento non impedisce che gli altri vengano scritti correttamente. Ad esempio, se la richiesta ha 100 elementi e un elemento ha un errore, vengono scritti 99 elementi e uno viene rifiutato.
- Gli elementi di dati di riferimento vengono sottoposti a query usando le proprietà della chiave completamente enumerate.
Nota
Tutti gli esempi di corpo JSON seguenti presuppongono un set di dati di riferimento con una singola chiave di proprietà con nome deviceId e tipo String.
Inserire elementi di dati di riferimento
Inserisce o sostituisce l'intero elemento $.put[i] dati di riferimento ( l'elementoith nella matrice con la chiave inserita). L'unità di commit è $.put[i]. l'operazione idempotente.
Endpoint e operazione:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Esempio di corpo della richiesta:
{ "put": [{ "deviceId": "Fan1", "color": "Red", "maxSpeed": 5 }, { "deviceId": "Fan2", "color": "White", "floor": 2 }] }Esempio di risposta:
{ "put": [ null, null ] }
Elementi di dati di riferimento delle patch
Aggiornamenti e inserisce proprietà specifiche per l'elemento $.patch[i]di dati di riferimento.
Endpoint e operazione:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Esempio di corpo della richiesta:
{ "patch": [ { "deviceId": "Fan1", "maxSpeed": 108 }, { "deviceId": "Fan2", "floor": 18 } ] }Esempio di corpo della risposta:
{ "patch": [ null, null ] }
Eliminare le proprietà negli elementi di dati di riferimento
Elimina le proprietà specificate dall'elemento di $.deleteproperties[i]dati di riferimento .
Endpoint e operazione:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Esempio di corpo della richiesta:
{ "deleteProperties":[ { "key":{ "deviceId":"Fan2" }, "properties":[ "floor" ] } ] }Esempio di corpo della risposta:
{ "deleteProperties": [ null ] }
Eliminare elementi di dati di riferimento
Elimina l'intero elemento dati di riferimento identificato dai valori delle proprietà chiave specificati in ogni $.delete[i]oggetto .
Endpoint e operazione:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Esempio di corpo della richiesta:
{ "delete": [{ "deviceId": "Fan1" }] }Esempio di corpo della risposta:
{ "delete": [ null ] }
Ottenere elementi di dati di riferimento
Ottiene l'intero elemento di dati di riferimento identificato dai valori delle proprietà chiave specificati in ogni $.get[i]oggetto .
Endpoint e operazione:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Esempio di corpo della richiesta:
{ "get": [{ "deviceId": "Fan1" }, { "deviceId": "Fan2" }] }Esempio di corpo della risposta:
{ "get": [ { "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }, { "id": "Fan2", "floor": 18 } ] }
Convalida e gestione degli errori
L'API Reference Gestione dati elabora singolarmente ogni elemento e un errore con un elemento non impedisce agli altri di essere scritti correttamente. Ad esempio, se la richiesta ha 100 elementi e un elemento ha un errore, vengono scritti 99 elementi e uno viene rifiutato.
Codici di errore dell'elemento
I codici di errore dell'elemento si verificano all'interno di un corpo di risposta JSON riuscito con il codice di stato HTTP 200.
InvalidInput: chiave non trovata. Indica che l'elemento sottoposto a query non è disponibile nel set di dati di riferimento.
{ "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }InvalidInput: la chiave payload non deve contenere alcuna proprietà non chiave. Indica che gli elementi di query del corpo della richiesta JSON non devono contenere proprietà non chiave, ovvero proprietà specificate nello schema del set di riferimenti. Le proprietà delle chiavi sono disponibili nella portale di Azure.
{ "code": "InvalidInput", "message": "Payload key should not contain any non-key property.", "target": null, "details": null, "innerError": null }InvalidInput: l'elemento payload deve contenere tutte le proprietà chiave. Indica che gli elementi di query del corpo della richiesta JSON devono includere tutte le proprietà chiave, ovvero le proprietà specificate nello schema del set di riferimenti. Le proprietà delle chiavi sono disponibili in portale di Azure.
{ "code": "InvalidInput", "message": "Payload item should contain all key properties.", "target": null, "details": null, "innerError": null }
Esempio di join dati di riferimento
Prendere in considerazione un messaggio dell'hub eventi con la struttura seguente:
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z"
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z"
}
]
Si consideri un elemento di dati di riferimento impostato con il nome contoso e il tasto deviceId di tipo String e che ha la struttura seguente:
| deviceId | color | Maxspeed | floor |
|---|---|---|---|
| Fan1 | Red | 5 | |
| Fan2 | White | 2 |
Quando i due eventi nel messaggio dell'hub eventi vengono elaborati da Azure Time Series Insights motore di ingresso Gen1, vengono aggiunti con l'elemento di dati di riferimento corretto. L'output degli eventi ha la struttura seguente:
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z",
"color":"Red",
"maxSpeed":5
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z",
"color":"White",
"floor":2
}
]
Regole di join e semantica
Quando si unisce i dati di riferimento, rispettare i vincoli seguenti:
- Il confronto tra nomi chiave è distinzione tra maiuscole e minuscole.
- Il confronto tra valori chiave è distinzione tra maiuscole e minuscole per le proprietà stringa.
Per gli ambienti con più set di dati di riferimento, vengono applicati tre vincoli aggiuntivi durante i join:
- Ogni elemento in un set di dati di riferimento può specificare il proprio elenco di proprietà non chiave.
- Per i due set di dati di riferimento A e B, le proprietà non chiave non devono intersecarsi.
- I set di dati di riferimento vengono aggiunti direttamente agli eventi, non ad altri set di dati a cui si fa riferimento e quindi agli eventi. Per aggiungere un elemento dati di riferimento a un evento, tutte le proprietà chiave usate nell'elemento dati di riferimento devono essere presenti nell'evento. Inoltre, le proprietà chiave non devono venire dalle proprietà non chiave unite a un evento tramite altri elementi dati di riferimento.
Dato questi vincoli, il motore di join può applicare il join in qualsiasi ordine per un determinato evento. La gerarchia e l'ordinamento non vengono considerati.
Limiti correnti
È possibile aggiungere fino a due set di dati di riferimento per ogni ambiente Azure Time Series Insights Gen1. Le limitazioni aggiuntive associate ai dati di riferimento di Azure Time Series Insights Gen1 sono elencate nella tabella seguente:
| Nome limite | Valore limite | SKU interessati | Note |
|---|---|---|---|
| Conteggio delle proprietà chiave | 3 | S1, S2 | Per set di dati di riferimento; Azure Resource Manager e solo portale di Azure |
| Dimensioni delle proprietà chiave | 1 KB | S1, S2 | Per set di dati di riferimento |
| Conteggio degli elementi di dati di riferimento | 2.000/20.000 (S1/S2) | S1, S2 | Per unità; ad esempio, 4 SKU S1 unità = 8.000 elementi (4 x 2.000) |
| Numero massimo di transazioni simultanee | 2/10 (S1/S2) | S1, S2 | |
| Numero massimo di transazioni di dati di riferimento | 120/600 (S1/S2) | S1, S2 | All'ora |
| Numero massimo di elementi di dati di riferimento | 1\.000 | S1, S2 | Per transazione |
| Dimensioni massime dell'elemento dati di riferimento | 8,192 KB | S1, S2 | Per transazione |
Vedi anche
Per altre informazioni sulla registrazione dell'applicazione e sul modello di programmazione di Azure Active Directory, vedere Azure Active Directory per gli sviluppatori.
Per informazioni sui parametri di richiesta e autenticazione, vedere Autenticazione e autorizzazione.
Gli strumenti che consentono di testare le richieste e le risposte HTTP includono:
- Fiddler. Questo proxy di debug Web gratuito può intercettare le richieste REST, in modo da poter diagnosticare i messaggi di richiesta e risposta HTTP.
- JWT.io. È possibile usare questo strumento per eseguire rapidamente il dump delle attestazioni nel token di connessione e quindi convalidarne il contenuto.
- Postman. Si tratta di uno strumento gratuito di test di richiesta HTTP e risposta per il debug delle API REST.
Altre informazioni su Azure Time Series Insights Gen1 esaminando la documentazione di Gen1.