Query con ambito progetto e organizzazione

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

Usando Analytics per Azure DevOps, è possibile costruire query con ambito un progetto o un'organizzazione o una raccolta. È possibile eseguire queste query direttamente nel browser o all'interno di Power BI.

Le query con ambito progetto consentono di rispondere a domande su un singolo progetto, mentre le query con ambito organizzazione e raccolta consentono di rispondere a domande che superano i limiti del progetto. Le query con ambito organizzazione e raccolta richiedono autorizzazioni utente più ampie o restrizioni di ambito più ampie per assicurarsi che la query non venga bloccata a causa di una mancanza di autorizzazioni.

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.

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.

Importante

Se non si ha accesso a tutti i progetti di un'organizzazione, è consigliabile applicare un filtro di progetto a tutte le query. Quando si estraggono dati in strumenti client come Power BI o Excel, l'uso della sintassi del percorso del progetto è il modo migliore per garantire che tutti i dati siano vincolati dal progetto specificato. È consigliabile usare query con ambito organizzazione o con ambito raccolta solo quando è necessario creare report su due o più progetti.

Query con ambito progetto

Per creare una query, immettere l'URL OData in un Web browser supportato.

L'URL di base per una query OData a livello di progetto è come illustrato nella sintassi seguente.

Cloud (Azure DevOps Services)

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/

Negli esempi forniti sostituire {OrganizationName} e {ProjectName} con i nomi dell'organizzazione e del progetto su cui eseguire una query.

Locale (Azure DevOps Server)

https://{servername}:{port}/tfs/{CollectionName}/{ProjectName}/_odata/{version}/

Negli esempi forniti effettuare le sostituzioni seguenti:

• analytics.dev.azure.com con {ServerName}:{Port}/tfs/
• {CollectionName} con il nome della raccolta di progetti (il valore predefinito è DefaultCollection)
• {ProjectName} con il nome del progetto di cui si desidera eseguire una query.

Nota

Gli esempi rimanenti forniti in questo articolo si basano su un URL di Azure DevOps Services. È necessario sostituire nell'URL del server Azure DevOps per eseguire gli esempi.

Restituisce un conteggio degli elementi di lavoro

Ad esempio, la query con ambito progetto seguente restituisce il numero di elementi di lavoro per un progetto specifico.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems/$count

Ad esempio, una query del progetto Fabrikam Fiber restituisce un conteggio di 7126 elementi di lavoro. Gli elementi di lavoro eliminati non sono inclusi nel conteggio.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/WorkItems/$count

7126

Restituire i percorsi dell'area del progetto

Analogamente, la stringa di query seguente restituirà le aree per un progetto specifico:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/Areas

Equivale al filtro seguente per una query con ambito organizzazione:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/Areas?
  $filter=Project/ProjectName eq '{ProjectName}'

Ad esempio, una query del progetto Fabrikam Fiber restituisce tutte le proprietà definite per un percorso di area perché nella query non viene applicato alcun $select operatore.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v1.0/Areas

L'esempio seguente mostra i dati restituiti per un singolo percorso area.

ProjectSK	"56af920d-393b-4236-9a07-24439ccaa85c"
AreaSK	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaId	"26be05fd-e68a-4fcb-833f-497f6bee45f2"
AreaName	"Service Delivery"
Number	55373
AreaPath	"Fabrikam Fiber\\Service Delivery"
AreaLevel1	"Fabrikam Fiber"
AreaLevel2	"Service Delivery"
AreaLevel3	null
AreaLevel4	null
AreaLevel5	null
AreaLevel6	null
AreaLevel7	null
AreaLevel8	null
AreaLevel9	null
AreaLevel10	null
AreaLevel11	null
AreaLevel12	null
AreaLevel13	null
AreaLevel14	null
Depth	1

Uso dell'opzione $expand

Quando si usa una query con ambito progetto con un'opzione $expand , non è necessario fornire altri filtri.

Ad esempio, il filtro con ambito progetto seguente:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v1.0/WorkItems?
  $expand=Parent

viene filtrato automaticamente per applicare la sicurezza:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=ProjectName eq '{ProjectName}')

Query con ambito organizzazione

L'URL di base per le query a livello di organizzazione è come illustrato:

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0

Quando si usa una query con ambito organizzazione con un'opzione $expand , è necessario fornire un altro filtro.

Ad esempio, la query con ambito organizzazione seguente, che usa un $expand oggetto per recuperare gli elementi figlio di tutti gli elementi di lavoro.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children

Richiede un altro filtro per verificare che gli elementi figlio siano limitati al progetto specificato:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Restituisce l'elemento padre di tutti gli elementi di lavoro

La query seguente, che usa un'opzione $expand per recuperare l'elemento padre di tutti gli elementi di lavoro.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent

Richiede un altro filtro per verificare che l'elemento padre sia limitato al progetto specificato:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Project/ProjectName eq '{ProjectName}'
  &$expand=Parent($filter=Project/ProjectName eq '{ProjectName}')

Senza l'altro filtro, la richiesta avrà esito negativo se l'elemento padre di qualsiasi elemento di lavoro fa riferimento agli elementi di lavoro in un progetto a cui non si ha accesso in lettura.

Restrizioni di sicurezza a livello di progetto

Analisi presenta altre restrizioni sulla sintassi delle query correlate alla sicurezza a livello di progetto.

I any filtri o all si applicano all'entità di base in un oggetto $expand. Per i filtri basati su un progetto, il filtro viene ignorato in modo esplicito quando si usa un oggetto $expand:

Ad esempio, la query seguente:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children($filter=Project/ProjectName eq '{ProjectName}')

Viene interpretato come:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}'
  &$expand=Children

e avrà esito negativo se non si ha accesso a tutti i progetti.

Per aggirare la restrizione, è necessario aggiungere un'espressione aggiuntiva in $filter:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectName eq '{ProjectName}' and Children/any(r: r/ProjectName eq '{ProjectName}')
  &$expand=Children

L'uso $level di è supportato solo se si ha accesso a tutti i progetti nella raccolta o quando si usa una query con ambito progetto:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Children($levels=2;$filter=ProjectName eq '{ProjectName}')

Analytics non supporta riferimenti di livello incrociato per i progetti che usano la $it clausola . Ad esempio, la query seguente fa riferimento all'alias dell'elemento di ProjectName$it lavoro radice, che non è supportato:

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $expand=Links(
    $expand=TargetWorkItem;
    $filter=TargetWorkItem/Project/ProjectName eq $it/Project/ProjectName)

Passaggio successivo

Eseguire query sui dati aggregati

Articoli correlati

• Linee guida per le query