Ho appena bloggato sul mio Blog Inglese riguardo alle REST APIs ed operatore asOf, ma ritengo l’argomento interessante, per cui voglio postare qui velocemente alcune riflessioni.
Le REST APIs sono molto comode perché permettono di interagire con TFS, soprattutto per quanto riguarda il “prelevare dati” in maniera semplice e veloce. Se siete curiosi riguardo le REST APIs, vi consiglio prima di tutto di guardare l’endpoint che vi permette di eseguire una query con il Work Item Query Language.
Il Work Item Query Language è una sintassi Sql Like che permette di interrogare il Work Item Store per recuperare le informazioni di cui avete bisogno. Questa funzionalità è FONDAMENTALE se volete recuperare dati sull’andamento del team per fare grafici, report o quant’altro.
Basta effettuare un post a questo endpoint
https://gianmariaricci.visualstudio.com/defaultcollection/_apis/wit/queryresults?api-version=1.0-preview
Utlizzando un Content-Type header di application/json (non lo dimenticate altrimenti le APIs vi restuitiranno errori del tipo “avete dimenticato il parametro QueryId” che difficilmente vi faranno capire dove sta l’errore), potete inviare questa query al Work Item Store.
{ "wiql": "Select [System.Id] FROM WorkItems where
[System.TeamProject] = 'Experiments' AND
[System.WorkItemType] = 'Bug' AND
[System.State] = 'Proposed'" }
Il risultato è una serie di Work Item Id, ovvero la lista degli id che soddisfano la query. In questo caso io potrei semplicemente essere interessato al conteggio dell’array Json, per capire che ho 13 bug ins tato Proposed nel progetto Experiments.
{
asOf: "2014-07-05T09:52:39.447Z"
query: {
type: "query"
columns: [1]
0: "System.Id"
-
queryType: "flat"
sortOptions: [0]
wiql: "Select [System.Id] FROM WorkItems where [System.TeamProject] = 'Experiments' AND [System.WorkItemType] = 'Bug' AND [System.State] = 'Proposed'"
url: null
}-
results: [13]
0: {
sourceId: 108
}-
1: {
sourceId: 270
Se faccio una query per ogni stato posso creare un grafico, cosa che però mi è permessa nativamente da VSO, per cui dove sta il vantaggio??
Figure 1: Count of Bugs grouped by state
Il reale vantaggio è il fatto di poter interrogare il Work Item Store in precisi istanti di tempo, infatti la risposta contiene come prima riga il timestamp del momento in cui è stata eseguita la query, che indica il timestamp per cui il risultato è valido.
asOf: “2014-07-05T09:52:39.447Z”
Molti non lo sanno, ma potete usare l’operatore asOf nella query per eseguire la query in un preciso istante temporale, ovvero conoscere il risultato in un determinato momento nel passato. Ecco come fare:
{ "wiql": "Select [System.Id] FROM WorkItems where
[System.TeamProject] = 'Experiments' AND
[System.WorkItemType] = 'Bug' AND
[System.State] = 'Proposed'
asof '2014-07-04T10:00:00.000Z'
" }
Come si può vedere dalla risposta sottostante, il risultato è cambiato e la query è stata eseguita in quel particolare timestamp, permettendoci di interrogare il Work Item Store per dirci il suo contenuto in qualsiasi istante di tempo nel passato.
{
asOf: "2014-07-04T10:00:00Z"
query: {
type: "query"
columns: [1]
0: "System.Id"
-
queryType: "flat"
sortOptions: [0]
wiql: "Select [System.Id] FROM WorkItems where [System.TeamProject] = 'Experiments' AND [System.WorkItemType] = 'Bug' AND [System.State] = 'Proposed' asof '2014-07-04T10:00:00.000Z' "
url: null
}-
results: [16]
0: {
sourceId: 108
A questo punto potete fare una semplice routine che esegue una serie di query utilizzando asOf per costruire grafici di trend, che non sono ancora disponibili su VSO, o per fare analisi personalizzate sui propri dati.
Il consiglio in questo caso è di creare una routine che interroga VSO per i dati storici e poi salva il risultato in una cache locale, per non dover ogni volta rifare decine di query al vostro account.
Gian Maria.
Login