Query a livello di 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

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.

Importante

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

Query con ambito di 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 in questo articolo si basano su un URL di Azure DevOps Services. Sostituire l'URL del server Azure DevOps per usare 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 7.126 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 restituisce le aree per un progetto specifico:

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

Equivale al filtro seguente su una query a livello di 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 Area Path poiché nella query non viene applicato alcun operatore $select.

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 seguente filtro con ambito di progetto:

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 organizzativo

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

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

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

Ad esempio, la seguente query con ambito organizzativo, che utilizza un $expand 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 utilizza l'opzione $expand per recuperare il padre di tutti gli elementi di lavoro.

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

È necessario un altro filtro per verificare che i genitori siano limitati 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 il filtro aggiuntivo, la richiesta ha 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 lettura.

Restrizioni di sicurezza a livello di progetto

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

I filtri any o all si applicano all'entità base di un $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 ha 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, nella query seguente, l'elemento di lavoro radice ProjectName viene utilizzato con l'alias $it, 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