Definire query di base utilizzando OData Analytics

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Usare le query OData di Analisi per recuperare i dati di rilevamento del lavoro da Azure DevOps nel browser o in strumenti client come Excel e Power BI. Questo articolo illustra il conteggio degli elementi, la selezione di campi specifici con $select, il filtro con $filter, l'espansione delle proprietà di navigazione con , l'esecuzione $expanddi query sugli intervalli di date e l'ordinamento con $orderby.

Gli esempi si concentrano sui set di entità di rilevamento del lavoro di Azure Boards, ma gli stessi principi si applicano ad altri set di entità. Per altre informazioni, vedere Creare query OData per Analisi e metadati di riferimento per Analisi di Azure Boards.

Prerequisiti

Ottenere un conteggio degli elementi

Per restituire solo un conteggio senza altri dati, aggiungere $apply=aggregate($count as Count) a qualsiasi URL del set di entità. Ad esempio, le query seguenti contano progetti, elementi di lavoro, percorsi di area e utenti in 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)

La Projects query per l'organizzazione fabrikam restituisce:

{
  "value": [
    {
      "Count": 16
    }
  ]
}

Ottenere un conteggio degli elementi e dei relativi dati

Per restituire un conteggio insieme ai dati, aggiungere $count=true a una query che include una $select clausola . Le query seguenti restituiscono un conteggio più le proprietà selezionate per elementi di lavoro, percorsi di area e utenti in un progetto:

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

Per i nomi di proprietà validi, vedere Informazioni di riferimento sui metadati per Analisi di Azure Boards e Data calendario, Progetto e Informazioni di riferimento sui metadati utente.

Ad esempio, la query seguente restituisce il conteggio e i nomi utente nel progetto Fabrikam Fiber :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

La risposta include il conteggio totale in @odata.count e i record corrispondenti in value:

{
  "@odata.count": 5,
  "value": [
    { "UserName": "Microsoft.VisualStudio.Services.TFS" },
    { "UserName": "fabrikamfiber1@hotmail.com" },
    { "UserName": "Jamal Hartnett" },
    { "UserName": "fabrikamfiber5@hotmail.com" },
    { "UserName": "fabrikamfiber2@hotmail.com" }
  ]
}

Selezionare proprietà o campi specifici

Aggiungere una $select clausola per restituire solo le proprietà necessarie. I nomi delle proprietà fanno distinzione tra maiuscole e minuscole, non possono contenere spazi e corrispondono ai nomi dei campi dell'elemento di lavoro. Ad esempio, restituisce $select=WorkItemId,WorkItemType,Title,State questi quattro campi.

Per le ricerche dei nomi di proprietà, inclusi i campi personalizzati, vedere Informazioni di riferimento sui metadati per Azure Boards.

La query seguente restituisce l'ID, il tipo, il titolo e lo stato per i tre elementi di lavoro principali del progetto Fabrikam Fiber:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

{
  "value": [
    { "WorkItemId": 31, "Title": "About screen", "WorkItemType": "Task", "State": "New" },
    { "WorkItemId": 30, "Title": "Change background color", "WorkItemType": "Task", "State": "Active" },
    { "WorkItemId": 32, "Title": "Standardize on form factors", "WorkItemType": "Task", "State": "Active" }
  ]
}

Filtrare i dati

Aggiungere una $filter clausola per restituire solo gli elementi che corrispondono a criteri specifici. Usare operatori di confronto come eq, negt, ltge, e lee combinare le condizioni con and e or. Ad esempio, la query seguente restituisce funzionalità in corso:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

Combinare più condizioni di filtro

Usare le parentesi per raggruppare or le condizioni all'interno di un filtro più and ampio. La query seguente restituisce storie utente, bug e un tipo personalizzato in stati specifici:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

È anche possibile usare funzioni stringa come contains, startswithe endswith nelle espressioni di filtro. Per altre informazioni, vedere Funzioni supportate.

Proprietà del Percorso dell'Area di Query o del Percorso dell'Iterazione

Alcune query richiedono la chiave surrogata (AreaSK o IterationSK) anziché la stringa di percorso. Usare i set di entità Aree o Iterazioni per cercare la chiave per un percorso specifico.

Restituisci l'AreaSK per un percorso di area specifico

La query seguente restituisce l'oggetto per il percorso dell'area AreaSKFabrikam Fiber\Production Planning\Web . Per altre proprietà disponibili, vedere Aree.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Production Planning\Web'&$select=AreaSK

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

Restituisci IterationSK per un determinato percorso di iterazione

La query seguente restituisce l'oggetto IterationSK per il Fabrikam Fiber\Release 1\Sprint 3 percorso di iterazione. Per altre proprietà disponibili, vedere 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

Filtrare in base alle proprietà di navigazione

Le proprietà di navigazione come Iteration, Areae AssignedTo rappresentano le relazioni con altre entità. Per filtrare in base a un campo da un'entità correlata, usare il percorso completo nel formato NavigationProperty/Field. Ad esempio, Iteration/IterationPath fa riferimento al IterationPath campo tramite la proprietà di Iteration navigazione:

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

La query seguente restituisce i primi cinque elementi di lavoro in un'iterazione specifica, usando il percorso di spostamento completo:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId,WorkItemType,Title,State&$orderby=WorkItemId asc

Espandere i dati dalle entità correlate

Il filtro in base a una proprietà di navigazione non include i relativi dati nella risposta. Per restituire campi da un'entità correlata, usare $expand. Senza $expand, non è possibile accedere ai campi delle proprietà di navigazione tramite $select.

La query seguente restituisce l'elemento di 480 lavoro con tutti i campi dell'entità espansa Iteration :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

Poiché non $select viene applicato all'espansione Iteration , la risposta include ogni Iteration campo:

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

Usare select nelle istruzioni expand

Per limitare i campi restituiti da un'entità espansa, aggiungere una $select clausola all'interno $expand di usando la sintassi $expand=Entity($select=Field1,Field2). La query seguente si espande ma restituisce Iteration solo IterationName e IterationPath:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

La tabella seguente illustra $expand esempi $select per i tipi comuni di proprietà di navigazione:

Per espandere più proprietà di navigazione in una singola query, usare un elenco delimitato da virgole:

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Usare istruzioni di espansione annidate

Per espandere una proprietà di navigazione all'interno di un'entità già espansa, annidarne una $expand all'interno di un'altra. La query seguente si espande e quindi si espande IterationProject all'interno Iteration per mostrare a quale progetto appartiene l'iterazione:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

Per combinare l'espansione annidata con $select, usare un punto e virgola (;) per separare $select le $expand parentesi. Senza il punto e virgola, la query restituisce un errore. La query seguente restituisce solo IterationName e IterationPath da Iteration, più l'oggetto annidato Project:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

Interrogare un intervallo di date

La query di esempio seguente restituisce elementi di lavoro il cui ultimo valore di Data modifica è maggiore o uguale al 1° gennaio 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

La query di esempio seguente restituisce gli elementi di lavoro la cui ultima data modificata è avvenuta durante la settimana dal 31 ottobre al 7 novembre 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z and ChangedDate le 2025-11-07Z

Ordinare i risultati

Aggiungere $orderby per ordinare i risultati in base a una o più proprietà. I risultati sono ordinati in ordine crescente per impostazione predefinita; accodamento desc per decrescente. Separare più campi di ordinamento con virgole.

Passo successivo

Contenuti correlati

• Creazione di query OData per l'analisi dati
• Aggregare i dati con Analytics
• Riferimenti ai metadati per Azure Boards Analytics
• Procedure consigliate da usare per l'esecuzione di query in Analisi
• Funzionalità supportate di OData
• OData v4.0 Part 2: URL Conventions Plus Errata 02