Project- en organisatiequery's

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

Met behulp van Analytics voor Azure DevOps kunt u query's maken die zijn gericht op een project of een organisatie of verzameling. U kunt deze query's rechtstreeks uitvoeren in uw browser of in Power BI.

Met query's binnen projectbereik kunt u vragen beantwoorden over één project, terwijl query's met organisatie- en verzamelingsbereiken u in staat stellen vragen te beantwoorden die grenzen van projecten overschrijden. Voor query's met organisatie- en verzamelingsbereiken zijn bredere gebruikersmachtigingen of zorgvuldige bereikbeperkingen vereist om ervoor te zorgen dat uw query niet wordt geblokkeerd vanwege een gebrek aan machtigingen.

Notitie

De Analytics-service wordt automatisch ingeschakeld en ondersteund in productie voor alle Azure DevOps-services. Power BI-integratie en -toegang tot de OData-feed van de Analytics-service zijn algemeen beschikbaar. We raden u aan deze te gebruiken en ons feedback te geven. Beschikbare gegevens zijn afhankelijk van versie. De meest recente ondersteunde versie is v2.0en de nieuwste preview-versie is v4.0-preview. Zie OData API-versiebeheer voor meer informatie.

Vereisten

• Toegang: Wees lid van een project met ten minste basistoegang .
• Machtigingen: projectleden zijn standaard gemachtigd om query's uit te voeren op Analytics en weergaven te maken.
• Zie Machtigingen en vereisten voor toegang tot Analyse voor meer informatie over andere vereisten met betrekking tot het inschakelen van services en functies en algemene activiteiten voor het bijhouden van gegevens.

Belangrijk

Als u geen toegang hebt tot alle projecten in een organisatie, wordt u aangeraden een projectfilter toe te passen op al uw query's. Wanneer u gegevens ophaalt in clienthulpprogramma's zoals Power BI of Excel, is het gebruik van de syntaxis van het projectpad de beste manier om ervoor te zorgen dat al uw gegevens worden beperkt door het opgegeven project. U wordt aangeraden alleen query's binnen het bereik van de organisatie of verzameling te gebruiken wanneer u over twee of meer projecten moet rapporteren.

Query's met projectbereik

U maakt een query door de OData-URL in te voeren in een ondersteunde webbrowser.

De basis-URL voor een OData-query op projectniveau wordt weergegeven in de volgende syntaxis.

Cloud (Azure DevOps Services)

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

Vervang in de opgegeven {OrganizationName} voorbeelden uw {ProjectName} namen van uw organisatie en project die u wilt opvragen.

On-premises (Azure DevOps-server)

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

Voer in de opgegeven voorbeelden de volgende vervangingen uit:

• analytics.dev.azure.com met {ServerName}:{Port}/tfs/
• {CollectionName} met de naam van uw projectverzameling (standaard is DefaultCollection)
• {ProjectName} met de naam van het project waarop u een query wilt uitvoeren.

Notitie

De overige voorbeelden in dit artikel zijn gebaseerd op een Azure DevOps Services-URL. U moet de URL van uw Azure DevOps Server vervangen door de voorbeelden uit te oefenen.

Een aantal werkitems retourneren

De volgende query met projectbereik retourneert bijvoorbeeld het aantal werkitems voor een specifiek project.

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

Een query van het Fabrikam Fiber-project retourneert bijvoorbeeld een telling van 7126 werkitems. Verwijderde werkitems zijn niet opgenomen in het aantal.

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

7126

Projectgebiedpaden retourneren

Op dezelfde manier retourneert de volgende queryreeks de gebieden voor een specifiek project:

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

Dit is gelijk aan het volgende filter voor een query binnen het bereik van de organisatie:

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

Een query van het Fabrikam Fiber-project retourneert bijvoorbeeld alle eigenschappen die zijn gedefinieerd voor een gebiedspad, omdat er geen $select operator wordt toegepast in de query.

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

In het volgende voorbeeld ziet u de gegevens die worden geretourneerd voor één vlakpad.

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

Gebruik van de optie $expand

Wanneer u een query met projectbereik gebruikt met een $expand optie, hoeft u geen andere filters op te geven.

Bijvoorbeeld het volgende filter voor projectbereik:

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

wordt automatisch gefilterd om beveiliging af te dwingen:

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

Query's binnen organisatiebereik

De basis-URL voor query's op organisatieniveau is zoals weergegeven:

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

Wanneer u een query binnen het bereik van de organisatie gebruikt met een $expand optie, moet u een ander filter opgeven.

De volgende query met organisatiebereik, die bijvoorbeeld gebruikmaakt van een $expand query om de onderliggende items van alle werkitems op te halen.

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

Er is een ander filter vereist om te controleren of de onderliggende items beperkt zijn tot het opgegeven project:

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

Het bovenliggende item van alle werkitems retourneren

De volgende query, die gebruikmaakt van een $expand optie voor het ophalen van het bovenliggende item van alle werkitems.

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

Er is een ander filter vereist om te controleren of het bovenliggende item beperkt is tot het opgegeven project:

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

Zonder het andere filter mislukt de aanvraag als het bovenliggende item verwijst naar werkitems in een project waartoe u geen leestoegang hebt.

Beveiligingsbeperkingen op projectniveau

Analytics heeft nog enkele beperkingen voor querysyntaxis met betrekking tot beveiliging op projectniveau.

De any of all filters zijn van toepassing op de basisentiteit op een $expand. Voor filters op basis van een project negeren we het filter expliciet wanneer u een $expand:

Bijvoorbeeld de volgende query:

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

Wordt geïnterpreteerd als:

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

en mislukt als u geen toegang hebt tot alle projecten.

Als u de beperking wilt omzeilen, moet u een extra expressie toevoegen in het $filtervolgende:

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

Het gebruik $level wordt alleen ondersteund als u toegang hebt tot alle projecten in de verzameling of wanneer u een query met projectbereik gebruikt:

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

Analytics biedt geen ondersteuning voor verwijzingen op meerdere niveaus voor projecten die gebruikmaken van de $it component. De volgende query verwijst bijvoorbeeld naar de alias $it van ProjectName het hoofdwerkitem. Dit wordt niet ondersteund:

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

Volgende stap

Statistische gegevens opvragen

Verwante artikelen:

• Queryrichtlijnen