Definire query di base con OData Analytics
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Usando Analytics per Azure DevOps, è possibile creare query di base e filtrate per restituire i dati di interesse. È possibile eseguire queste query direttamente nel browser o all'interno di Power BI.
Questo articolo contiene informazioni fornite in Costruire query OData per analisi e informazioni di riferimento sui metadati per Analisi di Azure Boards. Inoltre, le query in questo articolo sono incentrate sul recupero di set di entità di rilevamento del lavoro, ma i principi si applicano per l'esecuzione di query su altri set di entità.
In questo articolo si apprenderà come definire query che restituiscono i dati seguenti:
- Numero di elementi (nessun altro dato)
- Numero di elementi e dati
- Proprietà definite per aree o percorsi di iterazione
- Colonne o campi selezionati
- Dati filtrati
- Restituire i dati per i campi Identity, Area Path e Iteration Path
- Filtrare in base a una proprietà di navigazione
- Eseguire una query su un intervallo di date
- Annidare le istruzioni di espansione
- Ordinare i risultati, opzione orderby
Nota
Il servizio Analytics viene abilitato e supportato automaticamente nell'ambiente di produzione per tutti i Servizi DevOps di Azure. L'integrazione di Power BI e l'accesso al feed OData del servizio di analisi sono disponibili a livello generale. Ti invitiamo a usarlo e a inviare commenti e suggerimenti.
I dati disponibili dipendono dalla versione. La versione supportata più recente è v2.0
e la versione di anteprima più recente è v4.0-preview
. Per altre informazioni, vedere Controllo delle versioni dell'API OData.
Nota
Il servizio Analytics viene installato e supportato automaticamente nell'ambiente di produzione per tutte le nuove raccolte di progetti per Azure DevOps Server 2020 e versioni successive. L'integrazione di Power BI e l'accesso al feed OData del servizio di analisi sono disponibili a livello generale. Ti invitiamo a usarlo e a inviare commenti e suggerimenti. Se è stato eseguito l'aggiornamento da Azure DevOps Server 2019, è possibile installare il servizio Analytics durante l'aggiornamento.
I dati disponibili dipendono dalla versione. La versione supportata più recente è v2.0
e la versione di anteprima più recente è v4.0-preview
. Per altre informazioni, vedere Controllo delle versioni dell'API OData.
Nota
Il servizio Analytics è disponibile in anteprima per Azure DevOps Server 2019. È possibile abilitarlo o installarlo per una raccolta di progetti. L'integrazione di Power BI e l'accesso al feed OData del servizio di analisi sono disponibili in anteprima. Ti invitiamo a usarlo e a inviare commenti e suggerimenti.
I dati disponibili dipendono dalla versione. La versione supportata più recente è v2.0
e la versione di anteprima più recente è v4.0-preview
. Per altre informazioni, vedere Controllo delle versioni dell'API OData.
Prerequisiti
- Accesso: essere un membro di un progetto con almeno l'accesso Basic .
- Autorizzazioni: per impostazione predefinita, i membri del progetto dispongono dell'autorizzazione per eseguire query su Analisi e creare viste.
- Per altre informazioni sugli altri prerequisiti relativi all'abilitazione di servizi e funzionalità e alle attività generali di rilevamento dei dati, vedere Autorizzazioni e prerequisiti per l'accesso ad Analytics.
Nota
In questo articolo viene definito l'URL della query OData per Azure DevOps Services. Per creare una query simile per un server locale, vedere le indicazioni fornite in Costruire query OData per Analytics. È consigliabile modificare le query fornite per l'organizzazione e il progetto per acquisire familiarità con l'esecuzione di query su OData tramite il browser.
Restituisce un conteggio degli elementi (nessun altro dato)
Per informazioni sul numero di elementi o entità definiti in un'organizzazione o in un progetto, specificare $apply=aggregate($count as Count)
l'opzione di query. Ad esempio, le query seguenti restituiscono il numero di progetti, elementi di lavoro, percorsi di area e utenti definiti per un'organizzazione.
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)
Suggerimento
Le query tra progetti hanno esito negativo quando l'utente che esegue la query non ha accesso a tutti i progetti. Altre informazioni sui requisiti nelle query con ambito di progetto e organizzazione.
Conteggio progetti
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value
0
@odata.id null
Count 28
Conteggio elementi di lavoro
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value
0
@odata.id null
Count 1166
Numero di aree
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 70
Numero di utenti
@odata.context "https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value
0
@odata.id null
Count 16
Restituisce un conteggio di elementi e dati
Per restituire un conteggio degli elementi insieme ai dati selezionati per gli elementi, specificare l'opzione $count=true
di query. Ad esempio, le query seguenti restituiscono un conteggio di elementi di lavoro, percorsi di area e utenti definiti per un progetto insieme alle proprietà specificate. Per le proprietà valide, vedere Informazioni di riferimento sui metadati per Analisi di Azure Boards e Data calendario, Project e Informazioni di riferimento sui metadati utente per Azure DevOps Analytics.
Suggerimento
Se non si specificano le proprietà da restituire, Analytics restituirà tutte le proprietà definite per il tipo di entità specificato.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail
Aree o iterazioni
Per cercare la AreaSK
proprietà o IterationSK
o di un percorso di area o iterazione, usare le query seguenti.
Restituire l'areaSK per un percorso di area specifico
La query seguente specifica di restituire la AreaSK
proprietà definita per Fabrikam Fiber\Service Delivery\Internet Area Path. Per specificare altre proprietà definite per il Areas
set di entità, vedere Informazioni di riferimento sui metadati per Analisi di Azure Boards, Aree.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK
La query restituisce i dati seguenti.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
"value": [
{
"AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
}
]
}
Restituire iterazioneSK per un percorso di iterazione specifico
La query seguente specifica di restituire la IterationSK
proprietà definita per il percorso di iterazione Fabrikam Fiber\Release 1\Sprint 3. Per specificare altre proprietà definite per il Iterations
set di entità, vedere Informazioni di riferimento sui metadati per Analisi di Azure Boards, Iterazioni.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK
La query restituisce i dati seguenti.
{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
"value": [
{
"IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
}
]
}
Restituire proprietà o campi specifici
Per restituire proprietà specifiche o campi dell'elemento di lavoro, aggiungere una $select
clausola che specifica i nomi delle proprietà.
Ad esempio, per restituire l'ID elemento di lavoro, tipo di elemento di lavoro, titolo e stato degli elementi di lavoro, aggiungere la clausola seguente alla query. Questa clausola specifica le proprietà che corrispondono ai campi denominati.
Nota
I nomi delle proprietà non contengono spazi. Se si aggiungono spazi, la query avrà esito negativo. Le query OData richiedono attenzione sia alla spaziatura che alla combinazione di maiuscole e minuscole. Per informazioni su come vengono etichettate le proprietà dei campi personalizzate, vedere Informazioni di riferimento sui metadati per Azure Boards, Proprietà personalizzate.
Qui si specifica di restituire i primi tre elementi di lavoro.
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3
Analytics restituisce i dati seguenti.
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value
0
WorkItemId 462
Title "Test case"
WorkItemType "Test Case"
State "Design"
1
WorkItemId 491
Title "Change color settings"
WorkItemType "Shared Steps"
State "Active"
2
WorkItemId 461
Title "Test impediment"
WorkItemType "Impediment"
State "Open"
.
Applicare i filtri ai dati
Per filtrare un set di entità per restituire gli elementi di selezione, specificare una $filter
clausola che specifica i criteri che gli elementi devono soddisfare. Basandosi sull'ultima query, in questo caso viene aggiunta una clausola di filtro per restituire solo i tipi di elemento di lavoro Feature presenti nello stato In corso .
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'
https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State
Analytics restituisce i dati seguenti.
@odata.context "https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value
0
WorkItemId 380
Title "Refresh web look, feel, performance factors"
State "In Progress"
1
WorkItemId 480
Title "Customer Phone - Phase 1"
State "In Progress"
2
WorkItemId 493
Title "Change initial view"
State "In Progress"
3
WorkItemId 479
Title "Customer Web - Phase 1"
State "In Progress"
4
WorkItemId 551
Title "Mobile feedback"
State "In Progress"
Specificare diverse clausole di filtro
È possibile usare AND
e OR
per specificare diverse clausole di filtro.
Ad esempio, la query seguente specifica di restituire elementi di lavoro di tipo User Story, Bug e Backlog Work (un tipo di elemento di lavoro personalizzato) inclusi negli stati New, Committed o Active . Usare le parentesi per raggruppare le clausole di filtro in base alle esigenze.
Inoltre, è possibile applicare varie funzioni, ad contains
esempio , startswith
endswith
e altro ancora. Vedere le funzionalità e le clausole OData supportate, Funzioni supportate.
Restituire i dati per i campi Identity, Area Path e Iteration Path
Le proprietà di selezione sono associate alle proprietà di navigazione e non sono direttamente accessibili tramite l'istruzione $select
. È necessario usare un'istruzione $expand
per restituire i dati di interesse. Queste proprietà sono spesso associate a diverse proprietà proprie. Ad esempio, con i campi Identity è possibile specificare per restituire il nome utente o il messaggio di posta elettronica dell'utente.
Nella tabella seguente vengono forniti esempi di come espandere diverse di queste proprietà.
Campi tipo | Proprietà di riferimento | Clausole di esempio da includere |
---|---|---|
Data/Ora | DateSK |
$expand=CreatedDate($select=Date) oppure$expand=CreatedDate($select=WeekStartingDate) |
Identità | UserSK |
$expand=AssignedTo($select=UserName) oppure$expand=AssignedTo($select=UserEmail) |
Area | AreaSK |
$expand=Area($select=AreaName) oppure$expand=Area($select=AreaPath) |
Iterazione | IterationSK |
$expand=Iteration($select=IterationName) oppure$expand=Iteration($select=IterationPath) oppure$expand=Iteration($select=StartDate) |
Project | ProjectSK |
$expand=Project($select=ProjectName) |
Team | TeamSK |
$expand=Teams($select=TeamName) |
Per specificare diverse proprietà che devono essere espanse, è necessario specificarle in una singola clausola di espansione all'interno di un elenco delimitato da virgole.
$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)
Filtrare in base a una proprietà di navigazione
Quando si specifica una proprietà di navigazione come parte dei criteri di filtro, è necessario specificarla nel formato richiesto.
Ad esempio, la clausola seguente specifica di filtrare gli elementi di lavoro in base all'iterazione 1 definita per il progetto.
/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
In questo esempio, Iteration
è il nome della proprietà di navigazione e IterationPath
corrisponde al percorso completo per l'iterazione. Per usare un'altra entità come filtro, inserire la proprietà di navigazione seguita da una barra seguita dal nome del campo per filtrare.
Ed ecco la query OData completa:
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'
Ecco un altro esempio che richiede i primi cinque elementi di lavoro nel percorso Fabrikam Fiber\Service Delivery\Voice Area Path.Here's another example that requests the top five work items under the Fabrikam Fiber\Service Delivery\Voice Area Path are returned.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value
0
WorkItemId 361
Title "Hello World Web Site"
WorkItemType "Product Backlog Item"
State "Removed"
1
WorkItemId 362
Title "Resume"
WorkItemType "Product Backlog Item"
State "New"
2
WorkItemId 363
Title "Welcome back page"
WorkItemType "Product Backlog Item"
State "Done"
3
WorkItemId 365
Title "Pause"
WorkItemType "Feature"
State "New"
4
WorkItemId 374
Title "Fix performance issues"
WorkItemType "Task"
State "To Do"
Suggerimento
Non è possibile usare la proprietà di navigazione direttamente in un'istruzione $select
. È invece necessario usare $expand
.
L'esempio di filtro precedente per il percorso di iterazione non restituisce il percorso di iterazione perché è contenuto in un'entità correlata. Per restituire dati in un'entità correlata, aggiungere un'istruzione $expand
:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration
Ecco un esempio che restituisce informazioni assegnate all'ID elemento di lavoro 480.
https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
@odata.context "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value
0
WorkItemId 480
Title "Customer Phone - Phase 1"
WorkItemType "Feature"
State "In Progress"
Iteration
ProjectSK "56af920d-393b-4236-9a07-24439ccaa85c"
IterationSK "c7063041-ff3a-4d7f-bb46-c433c7030d59"
IterationId "c7063041-ff3a-4d7f-bb46-c433c7030d59"
IterationName "Sprint 1"
Number 55297
IterationPath "Fabrikam Fiber\\Release 1\\Sprint 1"
StartDate "2022-01-17T00:00:00-08:00"
EndDate "2022-02-04T23:59:59.999-08:00"
IterationLevel1 "Fabrikam Fiber"
IterationLevel2 "Release 1"
IterationLevel3 "Sprint 1"
IterationLevel4 null
IterationLevel5 null
IterationLevel6 null
IterationLevel7 null
IterationLevel8 null
IterationLevel9 null
IterationLevel10 null
IterationLevel11 null
IterationLevel12 null
IterationLevel13 null
IterationLevel14 null
Depth 2
IsEnded true
AnalyticsUpdatedDate "2022-01-18T22:18:58.17Z"
Come si può notare, il percorso di iterazione viene espanso nel risultato e tutti i dati di iterazione vengono restituiti. Probabilmente sono più dati che desiderati.
Per restituire meno dati, aggiungere anche un'istruzione $select
per l'iterazione:
/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)
Restituisce quindi i dati seguenti.
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
"value":[
{
"WorkItemId":10000,
"WorkItemType":"Task",
"Title":"Some title",
"State":"Completed",
"Iteration":{
"Name":"Sprint 55",
"IterationPath":"Fabrikam\\Sprints\\Sprint 55"
}
}
]
}
Eseguire una query su un intervallo di date
Nell'esempio seguente vengono restituiti elementi di lavoro la cui data di modifica è maggiore di quella del 1° gennaio 2021.
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z
Nell'esempio seguente vengono restituiti elementi di lavoro la cui data di modifica viene eseguita durante la settimana dal 26 aprile al 30 aprile 2021.
https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z
Annidare le istruzioni di espansione
In OData è possibile annidare $expand
le istruzioni. Ad esempio, è possibile scrivere l'istruzione query precedente per visualizzare il progetto di cui fa parte l'iterazione:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)
Restituisce il codice JSON seguente:
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
"value":[
{
"WorkItemId":10000,
"Revision":3,
"Watermark":283397,
"Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
"WorkItemType":"Task",
"ChangedDate":"2014-07-10T19:29:58.41Z",
"CreatedDate":"2014-04-19T22:44:58.31Z",
"State":"Completed",
"Reason":"Completed",
"Priority":2,
"CompletedWork":10.0,
"OriginalEstimate":20.0,
"Count":1,
"Iteration":{
"IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
"Name":"Sprint 55",
"Number":13021,
"IterationPath":"Fabrikam\\Sprints\\Sprint 55",
"StartDate":"2013-09-23T00:00:00Z",
"EndDate":"2013-10-11T00:00:00Z",
"IterationLevel1":"Fabrikam",
"IterationLevel2":" Sprints",
"IterationLevel3":"Sprint 55",
"Level":2,
"IsDeleted":false,
"Project":{
"ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
"ProjectName":"Fabrikam",
"IsDeleted":false
}
}
}
]
}
È anche possibile combinare $expand
istruzioni e $select
. Ad esempio, è possibile modificare la query precedente in modo da restituire solo il nome dell'iterazione e il percorso di iterazione:
/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)
Restituisce il codice JSON seguente:
{
"@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
"value":[
{
"WorkItemId":10000,
"Revision":3,
"Watermark":283397,
"Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
"ChangedDate":"2014-07-10T19:29:58.41Z",
"CreatedDate":"2014-04-19T22:44:58.31Z",
"State":"Completed",
"Reason":"Completed",
"Priority":2,
"CompletedWork":10.0,
"OriginalEstimate":20.0,
"Count":1,
"Iteration":{
"IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
"Project":{
"ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
"ProjectName":"Fabrikam",
"IsDeleted":false
}
}
}
]
}
Si noti che il risultato qui mostra solo IterationId e IterationPath e che Project è un oggetto annidato all'interno del risultato JSON. Un altro elemento chiave da notare è l'URL stesso. Quando si usa un'istruzione $select
e una $expand
clausola , è necessario usare un punto e virgola (;) prima di $expand
. Qualsiasi altra operazione genererà un errore.
Ordinare i risultati, orderby
opzione
Specificare l'opzione $orderby
per ordinare i risultati o specificare la sequenza in cui vengono restituiti i risultati. È possibile ordinare in ordine crescente o decrescente usando rispettivamente parole asc
chiave o desc
. Alcuni esempi sono visualizzati
Ordina per | Clausola da includere |
---|---|
ID elemento di lavoro | /WorkItems?$orderby=WorkItemId |
ID elemento di lavoro decrescente | /WorkItems?$orderby=WorkItemId desc |
Tipo di elemento di lavoro e stato | /WorkItems?$orderby=WorkItemType,State |