Costruire query OData per Analytics in Azure DevOps

  • Articolo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

L'analisi, la piattaforma di creazione di report per Azure DevOps, può rispondere a domande quantitative sullo stato passato o attuale dei progetti. Analytics supporta le query OData dei metadati e dei dati del set di entità. Esercitando query semplici dal Web browser, è possibile acquisire familiarità con il modello di dati e il processo di query.

In questo articolo si apprenderà quanto segue:

  • Come costruire una query OData di Analisi per il cloud o l'ambiente locale
  • Come eseguire query sui metadati di Analytics
  • Come eseguire query su OData di Analisi per un set di entità
  • Quali opzioni di query sono supportate e la sequenza consigliata
  • Quando viene applicato il paging sul lato server

È possibile eseguire query su Analytics da qualsiasi Web browser supportato. Per altri strumenti che è possibile usare per eseguire query su Analytics, vedere Strumenti di query di Analisi.

Nota

OData, un protocollo a livello di applicazione per interagire con i dati tramite LE INTERFACCE RESTful (dove REST=Representational State Transfer) supporta la descrizione dei modelli di dati, nonché la modifica e l'esecuzione di query sui dati in base a tali modelli. I metadati o Entity Data Model (EDM) descrivono le informazioni disponibili in Analisi, incluse le entità, i tipi di entità, le proprietà, le relazioni e le enumerazioni usate per eseguire query sui dati per compilare report. Per una panoramica di OData, vedere Introduzione a OData.

Prerequisiti

  • Per visualizzare i dati di Analisi ed eseguire query sul servizio, è necessario essere membri di un progetto con accesso basic o superiore. Per impostazione predefinita, a tutti i membri del progetto vengono concesse le autorizzazioni per eseguire query su Analisi e definire le visualizzazioni di Analisi.
  • 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.

Componenti URL per eseguire query sui metadati

Analytics espone il modello di entità nell'URL dei metadati, formato dall'aggiunta $metadata all'URL radice del servizio. Analisi fornisce radici del servizio per un progetto o un'intera organizzazione in Azure DevOps.

È possibile cercare uno degli elementi di dati seguenti eseguendo una query sui metadati.

  • Tipi di entità e set di entità
  • Proprietà e proprietà di navigazione
  • Chiavi surrogate
  • Elenchi enumerati
  • EntitySet
  • Contenitori
  • Funzioni di filtro (Org.OData.Capabilities.V1.FilterFunctions)
  • Aggregazioni supportate (Org.OData.Aggregation.V1.ApplySupported)
  • Supporto batch (Org.OData.Capabilities.V1.BatchSupportType)

L'URL usato dipende dal fatto che si eseseguono query sui dati per Azure DevOps Services (cloud) o un server Azure DevOps locale.

Per eseguire una query sui metadati per un'organizzazione o un progetto ospitato nel cloud, immettere la sintassi dell'URL, come illustrato di seguito in un Web browser. Sostituire {OrganizationName} e {ProjectName} con il nome dell'organizzazione e il nome del progetto su cui eseguire la query. Per restituire tutti i metadati per l'organizzazione, non specificare il nome del progetto.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/version/$metadata 
\______________________________/\______________________________/\______________/\_________/
               |                                 |                       |           |
    Analytics service root URL         Organization/Project        OData version  return metadata

Nota

La versione più recente di Analytics OData è v4.0-preview. È possibile usare questa versione per tutte le query sul servizio ospitato. Per altre informazioni sulle versioni di Analytics e sui dati disponibili, vedere Modello di dati per Analisi.

Ecco un esempio per l'organizzazione fabrikam ospitata in Azure DevOps Services.

https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata

Interpretare la risposta ai metadati

Analytics restituisce un file XML del modello di dati. Usare la funzione di ricerca del browser per trovare informazioni specifiche per l'entità di interesse.

Suggerimento

A seconda del browser in uso, questo file potrebbe essere formattato o meno in modo leggibile. Se non è formattato, è possibile trovare un formattatore XML online gratuito tramite una ricerca nel Web browser.

I due schemi principali definiti nei metadati di Analytics sono Microsoft.VisualStudio.Services.Analytics.Model, che definisce i tipi di entità e i tipi enumerati e i relativi membri e lo Default schema, che definisce i contenitori di entità e i set di entità e le funzioni di filtro OData supportate, trasformazione e aggregazione personalizzata. Per altre informazioni, vedere Metadati OData di Analisi.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Tutti i tipi di entità sono associati alle proprietà e alle proprietà di navigazione. È possibile filtrare le query dei set di entità usando entrambi questi tipi di proprietà. Questi sono elencati nei metadati EntityType in come Property o NavigationalProperty. Le entità correlate vengono usate per specificare filtri aggiuntivi, ad esempio Percorsi iterazione, Percorsi area o Teams.

Il frammento di codice seguente fornisce una visualizzazione parziale dei metadati per l'entità WorkItem . Le proprietà corrispondono a un campo dell'elemento di lavoro e a dati specifici acquisiti da Analytics, ad esempio LeadTimeDays e CycleTimeDays. Le proprietà di navigazione corrispondono ad altri set di entità o a dati di Analisi specifici acquisiti per il tipo di entità, ad esempio Revisions, LinksChildren, e Parent.

<Key>
   <PropertyRef Name="WorkItemId"/>
</Key>
<Property Name="WorkItemId" Type="Edm.Int32" Nullable="false">
   <Annotation Term="Ref.ReferenceName" String="System.Id"/>
   <Annotation Term="Display.DisplayName" String="Work Item Id"/>
</Property>
<Property Name="InProgressDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="InProgress Date"/>
   </Property>
<Property Name="CompletedDate" Type="Edm.DateTimeOffset">
   <Annotation Term="Display.DisplayName" String="Completed Date"/>
   </Property>
<Property Name="LeadTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Lead Time Days"/>
</Property>
<Property Name="CycleTimeDays" Type="Edm.Double">
   <Annotation Term="Display.DisplayName" String="Cycle Time Days"/>
</Property>
<Property Name="InProgressDateSK" Type="Edm.Int32"/>
<Property Name="CompletedDateSK" Type="Edm.Int32"/>
<Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
<Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
<Property Name="WorkItemRevisionSK" Type="Edm.Int32" Nullable="false"/>
...
<NavigationProperty Name="BoardLocations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.BoardLocation)"/>
<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
<NavigationProperty Name="InProgressOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="InProgressDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="CompletedOn" Type="Microsoft.VisualStudio.Services.Analytics.Model.CalendarDate">
<ReferentialConstraint Property="CompletedDateSK" ReferencedProperty="DateSK"/>
</NavigationProperty>
<NavigationProperty Name="Revisions" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemRevision)"/>
<NavigationProperty Name="Links" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItemLink)"/>
<NavigationProperty Name="Children" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Parent" Type="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
<ReferentialConstraint Property="ParentWorkItemId" ReferencedProperty="WorkItemId"/>
</NavigationProperty>
<NavigationProperty Name="Processes" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Process)"/>
<NavigationProperty Name="Descendants" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.WorkItem)"/>
<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project" Nullable="false">
<ReferentialConstraint Property="ProjectSK" ReferencedProperty="ProjectSK"/>
<Annotation Term="Display.DisplayName" String="Project"/>
...

Componenti URL per eseguire query sulle entità

Per eseguire query sui dati di Analisi e compilare report, in genere si esegue una query su un set di entità. Per una panoramica delle entità supportate, vedere Analisi dei metadati OData.

L'URL seguente viene usato per eseguire query su un oggetto specifico EntitySet, ad esempio WorkItems, WorkItemSnapshote PipelineRuns.

https://analytics.dev.azure.com/OrganizationName/ProjectName/_odata/version/EntityType?{Query-options}
\______________________________/\__________________________/ \____________/\_________/\_____________/
               |                             |                    |               |          |
    Analytics service root URL     Organization/Project      OData version    Entity   Query parts

Ecco un esempio per l'organizzazione fabrikam che restituisce il numero di elementi di lavoro definiti per il progetto Fabrikam Fiber.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?%20$apply=aggregate($count%20as%20Count)

L'esempio restituisce 1399 elementi di lavoro.

{
"@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(Count)",
"value": [
   {
   "@odata.id": null,
   "Count": 1399
   }
 ]
}

Nota

Se non si include una $select clausola o $apply , si riceverà un avviso, ad esempio "VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060." Equivale a eseguire un'istruzione select nel set di entità e restituire tutti gli elementi, tutte le colonne e tutte le righe. Se si dispone di un numero elevato di record, potrebbero essere necessari alcuni secondi. Se sono presenti più di 10.000 elementi di lavoro, viene applicato il paging basato su server.

Per evitare di incorrere nei limiti di utilizzo, includere sempre una $select clausola o $apply .

Per informazioni sulle proprietà e sulle relazioni dei metadati delle entità, vedere gli articoli seguenti:

Esempio: Eseguire una query su un set di entità specifico

Per eseguire query su un set di entità specifico, ad esempio WorkItems, Areaso Projects, aggiungere il nome del set di entità: /WorkItems, /Areaso /Projects. Per un elenco completo dei set di entità, vedere Modello di dati per Analisi.

Ad esempio, è possibile ottenere un elenco di progetti definiti per l'organizzazione eseguendo /Projects una query e selezionando per restituire la ProjectName proprietà . Per l'organizzazione fabrikam, l'URL è illustrato di seguito.

  https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/Projects?$select=ProjectName

Analytics restituisce i nomi dei progetti definiti per l'organizzazione fabrikam .

{
@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(ProjectName)",

"value": [
   {
      "ProjectName": "Basic Fabrikam"
   },
   {
      "ProjectName": "Fabrikam Fiber"
   },
   {
      "ProjectName": "MyFirstProject"
   },
   {
      "ProjectName": "Fabrikam Test"
   },
   {
      "ProjectName": "MyPublicProject"
   }
 ]
}

Opzioni di query

Un'opzione di query è un set di parametri della stringa di query applicati a una risorsa che consente di controllare la quantità di dati restituiti per la risorsa nell'URL.

Le opzioni di query devono essere specificate nell'ordine elencato nella tabella seguente.

Opzione query Note
$apply Set di trasformazioni che è possibile applicare a una query, ad esempio: filter, groupby, aggregate, computeexpand,concat
Per esempi, vedere Aggregare i dati di rilevamento del lavoro con Analytics.
$compute Funzione OData supportata che è possibile specificare per definire le proprietà calcolate che possono essere usate in un'espressione $selecto $orderby$filter.
$filter Usare per filtrare l'elenco di risorse restituite. L'espressione specificata con $filter viene valutata per ogni risorsa nella raccolta e solo gli elementi in cui l'espressione restituisce true vengono inclusi nella risposta. Le risorse per le quali l'espressione restituisce false o null o le proprietà di riferimento non disponibili a causa delle autorizzazioni vengono omesse dalla risposta.
Per esempi, vedere Eseguire query sui dati di rilevamento del lavoro usando Analytics .
$orderby Utilizzare per specificare la sequenza in cui devono essere restituiti i record.
Per esempi, vedere Eseguire query sui dati di rilevamento del lavoro con Analytics.
$top/$skip Utilizzare per limitare il numero di record restituiti.
Per esempi, vedere Query con ambito di progetto e organizzazione.
$select/$expand Usare $select per specificare le colonne necessarie per compilare il report. Usare $expand per annidare altre opzioni di query. Ogni expandItem oggetto viene valutato in relazione all'entità contenente la proprietà di navigazione o flusso espansa.

Elenco delimitato da punto e virgola delle opzioni di query, racchiuso tra parentesi, con il nome della proprietà di navigazione. Le opzioni di query di sistema consentite sono $filter, $select, $orderby$skip, $top, $count, $search, e $expand.
Per esempi, vedere Eseguire query sui dati di rilevamento del lavoro con Analytics.
$skiptoken Utilizzare per ignorare un numero specificato di record.
$count oppure $count=true Immettere $count per restituire solo il numero di record. Immettere $count=trueper restituire sia un conteggio del record che i dati sottoposti a query.
Per esempi, vedere Aggregare i dati di rilevamento del lavoro con Analytics.

Suggerimento

Evitare di combinare $apply le clausole e $filter in una singola query. Per filtrare la query, sono disponibili due opzioni: (1) usare una $filter clausola o (2) usare una clausola di $apply=filter() combinazione. Ognuna di queste opzioni funziona in modo ottimale da solo, ma combinandole insieme potrebbe portare ad alcuni risultati imprevisti.

Imponi paging lato server

L'analisi forza il paging quando i risultati della query superano i 10000 record. In tal caso, si otterrà la prima pagina di dati e il collegamento da seguire per ottenere la pagina successiva. Il collegamento (@odata.nextLink) è disponibile alla fine dell'output JSON. Sarà simile a una query originale seguita da $skip o $skiptoken. Ad esempio:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
   // 10000 values here
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$skiptoken=10000"
}

Nota

Quando si esegue il pull dei dati in strumenti client come Power BI Desktop o Excel, gli strumenti seguiranno automaticamente il collegamento successivo e caricheranno tutti i record necessari.

Passaggi successivi

Creare query di base con OData Analytics