Definire query di base utilizzando OData Analytics

Articolo
2025-04-08

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 monitoraggio del lavoro, ma i principi valgono anche per 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
Interrogare un intervallo di date
Annidare le istruzioni di espansione
Ordinare i risultati, opzione ordina per

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.0e 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.0e la versione di anteprima più recente è v4.0-preview. Per altre informazioni, vedere Controllo delle versioni dell'API OData.

Prerequisiti

Categoria	Requisiti
Livelli di accesso	- membro del progetto. - Accesso almeno di livello di base.
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 delle attività lavorative

@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 Riferimento ai metadati per Azure Boards Analytics e Data del calendario, Project e Riferimento ai 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

Proprietà delle aree o iterazioni

Per cercare la AreaSK o la IterationSK, o un'altra proprietà di un percorso di area o di un percorso di 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\InternetArea Path. Per specificare altre proprietà definite per l'insieme di entità Areas, vedere Informazioni di riferimento sui metadati per l'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"
    }
  ]
}

Restituisce l'IterationSK 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. La tua query fallirà se aggiungi spazi. Le query OData richiedono attenzione sia alla spaziatura che all'uso delle 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"

Filtra i tuoi 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 come contains, startswith, endswith e altro ancora. Consulta 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à.

Tipi di campi	Proprietà di riferimento	Clausole di esempio da includere
Data e 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)

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 di quanto desideri.

Per restituire meno dati, aggiungere anche un'istruzione $select relativa all'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"
      }
    }
  ]
}

Interrogare 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 dichiarazioni di espansione

In OData, è possibile annidare istruzioni $expand. 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 le istruzioni $expand 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 dell'elemento di lavoro	`/WorkItems?$orderby=WorkItemId`
ID dell'elemento di lavoro in ordine decrescente	`/WorkItems?$orderby=WorkItemId desc`
Tipo di elemento di lavoro e stato	`/WorkItems?$orderby=WorkItemType,State`

Passaggi successivi

Query con ambito progetto e organizzazione

Condividi tramite

Definire query di base utilizzando OData Analytics

Prerequisiti

Restituisce un conteggio degli elementi (nessun altro dato)

Conteggio progetti

Conteggio delle attività lavorative

Numero di aree

Numero di utenti

Restituisce un conteggio di elementi e dati

Proprietà delle aree o iterazioni

Restituire l'areaSK per un percorso di area specifico

Restituisce l'IterationSK per un percorso di iterazione specifico

Restituire proprietà o campi specifici

Filtra i tuoi dati

Specificare diverse clausole di filtro

Restituire i dati per i campi Identity, Area Path e Iteration Path

Filtrare in base a una proprietà di navigazione

Interrogare un intervallo di date

Annidare le dichiarazioni di espansione

Ordinare i risultati, orderby opzione

Passaggi successivi

Articoli correlati

Commenti e suggerimenti

Risorse aggiuntive

Ordinare i risultati, `orderby` opzione