OData Analytics-queryrichtlijnen voor Azure DevOps

  • Artikel

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

Ontwikkelaars van extensies kunnen profiteren door de richtlijnen in dit artikel te volgen voor het ontwerpen van efficiënte OData-query's op basis van Analytics voor Azure DevOps. Als u deze richtlijnen volgt, zorgt u ervoor dat de query's goede prestaties hebben voor de uitvoeringstijd en het resourceverbruik. Query's die niet aan deze richtlijnen voldoen, kunnen leiden tot slechte prestaties, met lange wachttijden voor rapporten, query's die het toegestane resourceverbruik overschrijden of serviceblokkeringen.

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.

Notitie

De Analytics-service wordt automatisch geïnstalleerd en ondersteund in productie voor alle nieuwe projectverzamelingen voor Azure DevOps Server 2020 en nieuwere versies. 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. Als u een upgrade hebt uitgevoerd van Azure DevOps Server 2019, kunt u de Analytics-service installeren tijdens de upgrade.

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.

Notitie

De Analytics-service is in preview voor Azure DevOps Server 2019. U kunt deze in- of installeren voor een projectverzameling. Power BI-integratie en toegang tot de OData-feed van de Analytics-service zijn in preview. 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.

Deze richtlijnen zijn onze aanbevelingen voorafgegaan door de termen DO, CONSIDER, AVOID en DON'T. Beperkende regels die door Analytics worden afgedwongen, bevatten het voorvoegsel [BLOCKED] . U moet de afwegingen tussen verschillende oplossingen begrijpen. Onder bepaalde omstandigheden hebt u mogelijk gegevensvereisten die u dwingen een of meer richtlijnen te schenden. Dergelijke gevallen moeten zeldzaam zijn. Wij raden u aan een duidelijke en overtuigende reden voor dergelijke beslissingen te hebben.

Tip

De voorbeelden in dit document zijn gebaseerd op een AZURE DevOps Services-URL. Gebruik vervangingen voor on-premises versies.

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

Fout- en waarschuwingsberichten

✔️ OData-responswaarschuwingen controleren

Elke query die u uitvoert, wordt gecontroleerd op basis van een set vooraf gedefinieerde regels. Schendingen retourneren het OData-antwoord hieronder @vsts.warnings. Bekijk deze waarschuwingen wanneer ze actuele en contextgevoelige informatie bieden over het verbeteren van uw query.

{
  "@odata.context": "https://{OrganizationName}.tfsallin.net/_odata/v1.0/$metadata#WorkItems",
  "@vsts.warnings": [
    "The specified query does not include a $select or $apply clause which is recommended for all queries."
  ],
  ...
}

✔️ OData-foutberichten controleren

Query's die een OData-foutregel schenden, resulteert in een mislukt antwoord met de statuscode 400 (Ongeldige aanvraag). Berichten koppelen worden niet weergegeven in de @vsts.warnings eigenschap. In plaats daarvan genereren ze een foutbericht in de message eigenschap in het JSON-antwoord.

{
  "error": {
  "code": "0",
  "message": "The query specified in the URI is not valid. The Snapshot tables in Analytics are intended to be used only in an aggregation."
  }
}

Beperkingen

Do's

Overwegen

Geblokkeerd

Vermijden

✔️ DO limit the query to the project(s) you have access to

Als uw query is gericht op gegevens van een project waarvoor u geen toegang hebt, retourneert de query het bericht 'Projecttoegang geweigerd'. Om ervoor te zorgen dat u toegang hebt, moet u ervoor zorgen dat de machtiging Analyse weergeven is ingesteld op Toestaan voor alle projecten die u opvraagt. Zie Machtigingen die vereist zijn voor toegang tot Analytics voor meer informatie.

Als u geen toegang hebt tot een project, wordt het volgende bericht weergegeven:

De queryresultaten bevatten gegevens in een of meer projecten waarvoor u geen toegang hebt. Voeg een of meer projectfilters toe om de projecten op te geven waar u toegang toe hebt in de entiteit WorkItems. Als u $expand of navigatie-eigenschappen gebruikt, is het projectfilter vereist voor deze entiteiten.

U kunt dit probleem omzeilen door expliciet een projectfilter toe te voegen of het eindpunt met projectbereik te gebruiken, zoals verderop in dit artikel wordt uitgelegd.

Met de volgende query worden bijvoorbeeld werkitems opgehaald die deel uitmaken van projecten met de naam {projectSK1} en {projectSK2}.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK1} or ProjectSK eq {projectSK2}
  &$select=WorkItemId, Title

✔️ GEEF een projectfilter in de $expand component op als uw uitbreiding gegevens kan bevatten in andere, mogelijk ontoegankelijke projecten

Wanneer u navigatie-eigenschappen uitvouwt, is er een kans dat u verwijst naar gegevens uit andere, ontoegankelijke projecten. Als u verwijst naar ontoegankelijke gegevens, ontvangt u hetzelfde foutbericht dat eerder is vermeld: 'De queryresultaten bevatten gegevens in een of meer projecten...'. Op dezelfde manier kunt u dit probleem oplossen door expliciete projectfilters toe te voegen om de uitgebreide gegevens te beheren.

U kunt dit doen in de reguliere $filter component voor eenvoudige navigatie-eigenschappen. Met de volgende query wordt bijvoorbeeld expliciet gevraagd WorkItemLinks waar zowel de koppeling als het doel zich in hetzelfde project bevinden.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemLinks?
  $filter=ProjectSK eq {projectSK} and TargetWorkItem/ProjectSK eq {projectSK}
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($select=WorkItemId, Title)

In plaats daarvan kunt u het filter verplaatsen om de optie uit te $filter vouwen in de $expand component. Het wijzigt echter de semantische van de query. Met de volgende query worden bijvoorbeeld alle koppelingen uit een bepaald project opgehaald en wordt het doel voorwaardelijk alleen uitgebreid als het in hetzelfde project bestaat. Hoewel deze methode geldig is, kan dit verwarring veroorzaken omdat het lastig kan zijn om te bepalen of een eigenschap niet is uitgevouwen omdat deze is null of omdat deze is gefilterd. Gebruik deze oplossing alleen als u dit specifieke gedrag echt nodig hebt.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemLinks?
  $filter=ProjectSK eq {projectSK}
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title)

De $filter uitvouwoptie is handig wanneer u de eigenschap verzameling uitvouwen, zoals Children in WorkItems de entiteitsset, gebruikt. De volgende query retourneert bijvoorbeeld alle werkitems uit een bepaald project, samen met alle onderliggende items die deel uitmaken van hetzelfde project.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK}
  &$select=WorkItemId, Title
  &$expand=Children($filter=ProjectSK eq {projectSK}; $select=WorkItemId, Title)

Geef het filter op als u een van de volgende eigenschappen uitvouwt:

  • WorkItems entiteitsset: Parent, Children
  • WorkItemLinks entiteitsset: TargetWorkItem.

✔️ OVERWEEG query's uit te voeren met behulp van het eindpunt met projectbereik

Als u geïnteresseerd bent in gegevens uit één project, raden we u aan het OData-eindpunt met projectbereik (/{ProjectName}/_odata/v1.0) te gebruiken. Hiermee voorkomt u de problemen die in de voorgaande twee secties worden beschreven en filtert u impliciet gegevens naar het ene project, de entiteitsset waarnaar wordt verwezen en alle uitgebreide navigatie-eigenschappen.

Met deze vereenvoudiging kunnen de query's uit de vorige sectie worden herschreven naar het volgende formulier. Niet alleen is het filter in de uitvouwcomponent verdwenen, maar er is ook geen filter nodig voor de hoofdentiteitsset.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItemLinks?
  &$select=LinkTypeReferenceName, SourceWorkItemId, TargetWorkItemId
  &$expand=TargetWorkItem($select=WorkItemId, Title)

De query voor werkitem onderliggende items is ook veel korter en eenvoudiger.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}//WorkItems?
  &$select=WorkItemId, Title
  &$expand=Children($select=WorkItemId, Title)

U kunt deze oplossing alleen toepassen wanneer uw focus gegevens uit één project is. Voor rapportage tussen projecten moet u filterstrategieën gebruiken die in de vorige secties zijn beschreven.

✔️ DO wacht of stop de bewerking als uw query de gebruikslimieten overschrijdt

Als u veel query's uitvoert of als voor de query's veel resources nodig zijn om uit te voeren, kunt u de servicelimieten overschrijden en tijdelijk worden geblokkeerd. Als u de servicelimieten overschrijdt, stopt u de bewerking omdat de kans bestaat dat de volgende query die u verzendt, mislukt met hetzelfde foutbericht.

De aanvraag is geblokkeerd vanwege het overschrijden van het gebruik van de resource {resource} in naamruimte {namespace}.

Zie Frequentielimieten voor meer informatie over frequentielimieten. Raadpleeg de prestatierichtlijnen verderop in dit artikel voor meer informatie over het ontwerpen van efficiënte OData-query's.

✔️ WACHT of stop de bewerking als uw query mislukt met een time-out

Net als bij het overschrijden van de gebruikslimieten moet u de bewerking wachten of stoppen als er een time-out optreedt voor uw query. Dit kan duiden op een tijdelijk probleem, dus u kunt het opnieuw proberen om te zien of het probleem wordt opgelost. Permanente time-outs geven echter aan dat de query waarschijnlijk te duur is om uit te voeren. Verdere nieuwe pogingen resulteren alleen in het overschrijden van de gebruikslimieten en u wordt geblokkeerd.

TF400733: De aanvraag is geannuleerd: de aanvraag heeft de time-out van de aanvraag overschreden. Probeer het opnieuw.

Time-outs geven aan dat een query optimalisatie vereist. Zie de prestatierichtlijnen verderop in dit artikel voor meer informatie over het ontwerpen van efficiënte OData-query's.

❌ [GEBLOKKEERD] Gebruik geen momentopname-entiteiten voor iets anders dan aggregaties

Entiteitssets voor momentopnamen met het Snapshot achtervoegsel zijn speciaal omdat ze worden gemodelleerd als dagelijkse momentopnamen. U kunt ze gebruiken om een status van entiteiten op te halen, zoals ze aan het einde van elke dag in het verleden waren. Als u bijvoorbeeld query's hebt uitgevoerd en filtert WorkItemSnapshot op één WorkItemId, krijgt u één record voor elke dag sinds het werkitem is gemaakt. Het rechtstreeks laden van al deze gegevens zou duur zijn en hoogstwaarschijnlijk de gebruikslimieten overschrijden en worden geblokkeerd. Aggregaties op deze entiteiten worden echter zowel toegestaan als aanbevolen. In feite zijn de entiteitssets voor momentopnamen ontworpen met behulp van aggregatiescenario's.

De volgende query haalt bijvoorbeeld het aantal werkitems op zoals op datum om te zien hoe deze in januari 2020 is gegroeid.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemSnapshot?
  $apply=
    filter(DateSK ge 20200101 and DateSK le 20200131)/
    groupby((DateSK), aggregate($count as Count))

Zie Statistische gegevens voor meer informatie over aggregaties.

✔️ DO include or column in component when you aggregate over snapshot tables (DO include DateSK or DateValue column in groupby component when you aggregate over snapshot tables)

Omdat alle momentopname-entiteiten zijn gemodelleerd als dagelijkse momentopnametabellen, moet u altijd een van de dageigenschappen (DateSK of DateValue) opnemen in de groeperingscomponent. Anders kan het resultaat onjuist worden opgepompt.

Als u bijvoorbeeld alleen AssignedTo op eigenschap hebt gegroepeerd WorkItemSnapshot en samengevoegd met het aantal, worden alle aan personen toegewezen werkitems vermenigvuldigd met het aantal dagen waarop elke toewijzing actief was. Hoewel u mogelijk een situatie hebt waarin dit het gewenste resultaat is, zijn dergelijke gevallen zeldzaam.

❌ [GEBLOKKEERD] Gebruik geen entiteitssleutels in resourcepaden voor entiteitsadressering

OData-syntaxis biedt een manier om toegang te krijgen tot een bepaalde entiteit door de sleutels rechtstreeks in de URL-segmenten op te geven. Zie OData-versie 4.0 voor meer informatie. Deel 2: URL-conventies - 4.3 Adresseringsentiteiten. Hoewel OData dergelijke adressering toestaat, blokkeert Analytics deze. Opname in een query resulteert in de volgende fout.

De query die is opgegeven in de URI, is ongeldig. Analytics biedt geen ondersteuning voor sleutel- of eigenschapsnavigatie, zoals WorkItems(Id) of WorkItem(Id)/AssignedTo. Als u deze fout in PowerBI krijgt, moet u de query herschrijven om te voorkomen dat er een onjuist vouwen optreedt dat een N+1-probleem veroorzaakt.

Zoals de foutberichten aangeeft, kunnen bepaalde clienthulpprogramma's directe entiteitsadressering misbruiken. In plaats van alle gegevens in één aanvraag te laden, kunnen dergelijke clients ervoor kiezen om onafhankelijk van elke entiteit een query uit te voeren. Deze praktijk wordt afgeraden omdat dit kan leiden tot een groot aantal aanvragen. In plaats daarvan raden we u aan expliciete entiteitsadressering te gebruiken, zoals wordt uitgelegd in de volgende sectie.

✔️ DO expliciet adresseert entiteiten met filtercomponenten

Als u gegevens voor één entiteit wilt ophalen, moet u dezelfde benadering gebruiken als voor een verzameling entiteiten en expliciet filters in de $filter component definiëren.

De volgende query haalt bijvoorbeeld één werkitem op met de id.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=WorkItemId eq {id}
  &$select=WorkItemId, Title

Als u niet zeker weet welke eigenschappen u in een dergelijk filter moet opnemen, kunt u deze opzoeken in de metagegevens. Zie OData-query's maken voor Analyse, URL-onderdelen om een query uit te voeren op de metagegevens. Eigenschappen bevinden zich in het Key element van de EntityType. Dit zijn bijvoorbeeld WorkItemIdRevision belangrijke kolommen voor de WorkItemRevision entiteit.

<EntityType Name="WorkItemRevision">
  <Key>
    <PropertyRef Name="WorkItemId"/>
    <PropertyRef Name="Revision"/>
  </Key>
  [...]
</EntityType>

❌ [GEBLOKKEERD] Niet uitbreiden Revisions op WorkItem entiteit

Het analysegegevensmodel staat bepaalde typen uitbreidingen niet toe. Een daarvan, wat voor sommigen verrassend kan zijn, is de Revisions verzamelingseigenschap op de WorkItem entiteit. Als u deze eigenschap probeert uit te vouwen, wordt het volgende foutbericht weergegeven.

De query die is opgegeven in de URI, is ongeldig. De eigenschap Revisies kan niet worden gebruikt in de queryoptie $expand.

Deze beperking is ingesteld om iedereen aan te moedigen de aanbevolen oplossing te gebruiken, die revisies ophaalt, WorkItemRevisions zoals wordt uitgelegd in de volgende sectie.

✔️ Do use WorkItemRevisions entity set to load all the revisions for a given work item

Gebruik WorkItemRevisions elke keer dat u de volledige geschiedenis voor een werkitem of een verzameling werkitems wilt ophalen.

De volgende query retourneert bijvoorbeeld alle revisies van een werkitem met de {id} id.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemRevisions?
  $filter=WorkItemId eq {id}
  &$select=WorkItemId, Title

Als u de volledige geschiedenis belangrijk vindt voor alle werkitems die voldoen aan bepaalde criteria, drukt u deze uit met behulp van een filter op de WorkItem navigatie-eigenschap. Met de volgende query worden bijvoorbeeld alle revisies van alle momenteel actieve werkitems weergegeven.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemRevisions?
  $filter=WorkItem/State eq 'Active'
  &$select=WorkItemId, Title

❌ [GEBLOKKEERD] Niet groeperen op afzonderlijke kolommen

U gebruikt een groeperingsbewerking om het aantal records te verminderen. Het gebruik van afzonderlijke kolommen in de groupby component geeft een probleem aan en de query mislukt onmiddellijk. Als deze situatie per ongeluk optreedt, wordt het volgende foutbericht weergegeven.

Een of meer van de kolommen die zijn opgegeven in de groupby-component van deze query, worden niet aanbevolen.

Als u dit probleem wilt oplossen, verwijdert u de afzonderlijke kolom uit de groupby component.

❌ [GEBLOKKEERD] Gebruik geen countdistinct aggregatie

Analytics biedt geen ondersteuning voor de countdistinct functie, ook al wordt OData wel ondersteund. Hoewel we van plan zijn om in de toekomst ondersteuning toe te voegen, is deze momenteel niet beschikbaar. Een query die deze functie bevat, retourneert het volgende foutbericht.

Query's die een aantal afzonderlijk toepassen met een aggregatie, worden niet ondersteund.

❌ Aggregaties VERMIJDEN die kunnen leiden tot rekenkundige overloop

In zeldzame gevallen kan een aggregatiequery problemen ondervinden met rekenkundige overloop. Dit kan bijvoorbeeld gebeuren wanneer u een aantal numerieke eigenschappen optelt die niet zijn bedoeld voor optellen, zoals StackRank in de entiteiten van het werkitem. Omdat de OData-extensie voor gegevensaggregatiestandaard geen manier biedt om een eigenschap naar een ander type te casten, is de enige manier om dit probleem op te lossen de problematische eigenschap uit de aggregatie te verwijderen.

✔️ BATCH-eindpunt gebruiken voor lange query's

U kunt problemen ondervinden met lange query's. In het bijzonder kunnen er problemen optreden wanneer:

  • U kunt een query uitvoeren op een project met veel aangepaste velden.
  • Uw query wordt programmatisch samengesteld.

De huidige limiet van OData-query's die worden verzonden, HTTP GET is 3000 tekens. Als u deze overschrijdt, krijgt u een antwoord '404 Niet gevonden'.

HTTP/1.1 404 Not Found
Content-Length: 0

Als u dit probleem wilt oplossen, gebruikt u het OData-batcheindpunt, zoals uitgelegd in de specificatie, OData versie 4.0. Deel 1: Protocol - 11.7 Batch-aanvragen. Batch-mogelijkheid is voornamelijk ontworpen om meerdere bewerkingen te groeperen in één HTTP nettolading van aanvragen, maar u kunt deze ook gebruiken als tijdelijke oplossing voor de beperking van de querylengte. Door een HTTP POST aanvraag te verzenden, kunt u een query van een willekeurige lengte doorgeven en de service deze correct interpreteert.

❌ [GEBLOKKEERD] Gebruik geen batcheindpunt voor het verzenden van meerdere query's

We beperken het gebruik van het batch-eindpunt voor het verwerken van een batch met meerdere aanvragen. Eén aanvraag kan nog steeds slechts één query hebben. Als u een batch met verschillende query's probeert te verzenden, mislukt de bewerking met het volgende foutbericht. De enige oplossing is het splitsen van query's in meerdere aanvragen.

Analyse biedt geen ondersteuning voor de verwerking van meerdere bewerkingen die het huidige batchbericht bevat. Analytics maakt gebruik van OData-batch om POST-aanvragen te ondersteunen, maar vereist dat u de bewerking beperkt tot één aanvraag.

❌ [GEBLOKKEERD] GEBRUIK GEEN query's die resulteren in meer dan 800 kolommen

We beperken query's die resulteren in meer dan 800 kolommen. Als u niet selectief genoeg bent in welke kolommen uw query retourneert, wordt mogelijk het volgende foutbericht weergegeven.

VS403670: De opgegeven query retourneert N-kolommen die hoger zijn dan de toegestane limiet van 800 kolommen. Gebruik expliciete $select (inclusief binnen de $expand) om het aantal kolommen te beperken.

Voeg een $select-component toe aan uw query en aan $expand bewerkingen in uw query om te voorkomen dat deze limiet wordt overschreden.

❌ VERMIJD het maken van lange query's

U wordt aangeraden uw benadering te evalueren wanneer u een lange query maakt. Hoewel er veel scenario's zijn die een lange query nodig hebben (bijvoorbeeld complexe filters of een lange lijst met eigenschappen), bieden ze meestal een vroege indicator van een suboptimaal ontwerp.

Wanneer uw query veel entiteitssleutels in de query bevat (bijvoorbeeld WorkItemId eq {id 1} or WorkItemId eq {id 2} or ...), kunt u deze waarschijnlijk opnieuw schrijven. In plaats van de id's door te geven, probeert u enkele andere criteria te definiëren die dezelfde set entiteiten selecteren. Soms moet u het proces wijzigen (bijvoorbeeld een nieuw veld of een nieuwe tag toevoegen), maar dit is meestal de moeite waard. Query's die meer abstracte filters gebruiken, zijn gemakkelijker te onderhouden en hebben een groter potentieel om beter te werken.

Een ander scenario dat vaak lange query's genereert, treedt op wanneer u veel afzonderlijke datums opneemt (bijvoorbeeld DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or ...). Zoek naar een ander patroon dat u kunt gebruiken om een abstracter filter te maken. Met de volgende query worden bijvoorbeeld alle werkitems geretourneerd die op maandag zijn gemaakt.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedOn/DayOfWeek eq 2
  &$select=WorkItemId, Title, State

✔️ DO specify time zone when filtering on date columns (TIJDZONE opgeven bij filteren op datumkolommen)

In de tijdzone (Edm.DateTimeOffset) worden alle datum- en tijdgegevens weergegeven met een offset die overeenkomt met de tijdzone-instellingen van de organisatie. Deze gegevens zijn nauwkeurig en eenvoudig om tegelijkertijd te interpreteren. Een ander niet-obvious gevolg is dat alle filters ook de tijdzone-informatie moeten doorgeven. Als u deze overslaat, wordt het volgende foutbericht weergegeven.

De query die is opgegeven in de URI, is ongeldig. Er is geen datum/tijd-offset opgegeven. Gebruik een van deze notaties JJJJ-MM-ddZ om alles op te geven sinds middernacht of jjjj-MM-ddThh:mm-hh:mm (ISO 8601 standaardweergave van datums en tijden) om de offset op te geven.

Voeg de tijdzonegegevens toe om dit probleem op te lossen. Als de organisatie bijvoorbeeld is geconfigureerd om gegevens weer te geven in de tijdzone '(UTC-08:00) Pacific Time (US & Canada)', worden met de volgende query alle werkitems opgehaald die zijn gemaakt sinds begin 2020.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDate ge 2020-01-01T00:00:00-08:00
  &$select=WorkItemId, Title, State

Dezelfde oplossing werkt voor tijdzones met positieve offsets, maar het plusteken (+) heeft een speciale betekenis in de URI en u moet deze correct afhandelen. Als u (met een + teken) opgeeft 2020-01-01T00:00:00+08:00 als uitgangspunt, krijgt u de volgende fout.

De query die is opgegeven in de URI, is ongeldig. Syntaxisfout op positie 31 in 'CreatedDate ge 2020-01-01T0000 08:00'.

U kunt dit oplossen door het teken te vervangen door de + gecodeerde versie. %2B Stel bijvoorbeeld dat de organisatie is geconfigureerd voor het weergeven van gegevens in de tijdzone '(UTC+08:00) Beijing, Resourceing, Hong Kong, Urumqi', retourneert de volgende query alle werkitems die zijn gemaakt sinds begin 2020.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDate ge 2020-01-01T00:00:00%2B08:00
  &$select=WorkItemId, Title, State

Een alternatieve methode is het gebruik van eigenschappen van datum surrogaatsleutels omdat ze de tijdzone-informatie niet behouden. De volgende query retourneert bijvoorbeeld alle werkitems die zijn gemaakt sinds begin 2020, ongeacht de instellingen van de organisatie.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge 20200101
  &$select=WorkItemId, Title, State

Prestatierichtlijnen

Do's

Niet

Overwegen

Vermijden

✔️ DO meet het effect van het implementeren van een prestatierichtlijn

Net als bij eventuele aanbevelingen voor prestaties moet u ze niet blind implementeren. Leg in plaats daarvan altijd de basislijn vast en meet het effect van wijzigingen die u aanbrengt. Alle richtlijnen zijn gemaakt op basis van de interacties met klanten van Analytics die specifieke vereisten en uitdagingen hadden. Deze aanbevelingen werden algemeen en mogelijk nuttig geacht voor iedereen die vergelijkbare query's ontwerpt. In zeldzame gevallen kan het volgen van de richtlijnen echter geen effect hebben of zelfs een negatief effect hebben op de prestaties. U moet het verschil meten om het op te merken. Als dit het geval is, geeft u feedback in de Ontwikkelaarscommunity-portal .

Er zijn veel opties om de prestaties te meten. Het eenvoudigste is om twee versies van dezelfde query rechtstreeks in de browser uit te voeren. Bekijk de tijd die nodig is in de ontwikkelhulpprogramma's. U kunt bijvoorbeeld het deelvenster Netwerk gebruiken in Microsoft Edge F12 Developer Tools). Een andere optie is om deze informatie vast te leggen met fiddler Web Debugger Tool.

Wat uw benadering ook is, voer beide query's meerdere keren uit. Voer bijvoorbeeld de query's 30 keer uit om een voldoende grote steekproefset te hebben. Zoek vervolgens de prestatiekenmerken uit. Analytics volgt een architectuur met meerdere tenants. Andere bewerkingen die tegelijkertijd plaatsvinden, kunnen dus van invloed zijn op de duur van uw query's.

✔️ DO use aggregation extensions

Het beste wat u kunt doen om de prestaties van uw query's te verbeteren, is door de aggregatie-extensie OData-extensie voor gegevensaggregatie te gebruiken. Met de aggregatie-extensie vraagt u de service om de gegevensserver samen te vatten en een kleiner antwoord te retourneren dan wat u kunt ophalen door dezelfde functieclientzijde toe te passen. Ten slotte is Analytics geoptimaliseerd voor dit type query's, dus maak er gebruik van.

Zie Statistische gegevens voor meer informatie.

✔️ DO: kolommen in de $select component opgeven

Geef de kolommen op die u belangrijk vindt in de $select component. Analyse is gebouwd op basis van een Columnstore-indextechnologie . Dat betekent dat gegevens zowel opslag als queryverwerking op basis van kolommen zijn. Door de set eigenschappen te verminderen, kunt u in component verwijzen $select naar het aantal kolommen dat moet worden gescand en de algehele prestaties van de query verbeteren.

Met de volgende query worden bijvoorbeeld de kolommen voor werkitems opgegeven.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $select=WorkItemId, Title, State

Notitie

Azure DevOps ondersteunt procesaanpassing. Sommige beheerders gebruiken deze functie en maken honderden aangepaste velden. Als u de $select component weglaat, retourneert uw query alle velden, inclusief aangepaste velden.

✔️ DO specify columns in the $select expand option inside the $expand component

Geef op dezelfde manier als de $select richtlijnen voor de component de eigenschappen op in de $select optie voor uitvouwen binnen de $expand component. Het is gemakkelijk te vergeten, maar als u het weglaat, bevat uw antwoord alle eigenschappen van het uitgevouwen object.

Met de volgende query worden bijvoorbeeld de kolommen voor zowel het werkitem als het bovenliggende item opgegeven.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $select=WorkItemId, Title, State
  &$expand=Parent($select=WorkItemId, Title, State)

✔️ Definieer een filter wanneer RevisedDateSK u query's uitvoert op historische gegevens van werkitems (WorkItemRevisions of WorkItemSnapshot entiteitssets)

Wanneer u een query uitvoert op historische gegevens, is de kans groot dat u geïnteresseerd bent in de meest recente periode (bijvoorbeeld 30 dagen, 90 dagen). Vanwege hoe werkitemsentiteiten worden geïmplementeerd, is er een handige manier om dergelijke query's te schrijven om geweldige prestaties te krijgen. Telkens wanneer u een werkitem bijwerkt, wordt er een nieuwe revisie gemaakt en wordt deze actie vastgelegd in het System.RevisedDate veld, waardoor deze perfect is voor geschiedenisfilters.

In Analytics wordt de herziene datum weergegeven in de RevisedDate eigenschappen (Edm.DateTimeOffset) en RevisedDateSK (Edm.Int32). Gebruik de laatste voor de beste prestaties. Dit is de datum surrogaatsleutel en geeft de datum aan waarop een revisie is gemaakt of voor null actieve, onvolledige revisies. Als u alle datums wilt sinds de {startDate} inclusief, voegt u het volgende filter toe aan uw query.

RevisedDateSK eq null or RevisedDateSK gt {startDateSK}

De volgende query retourneert bijvoorbeeld het aantal werkitems voor elke dag sinds begin 2020. U ziet dat er, afgezien van het voor de hand liggende filter op DateSK kolom, een tweede filter is ingeschakeld RevisedDateSK. Hoewel het misschien overbodig lijkt, kan de query-engine revisies filteren die niet binnen het bereik vallen en de queryprestaties aanzienlijk verbeteren.

https://analytics.dev.azure.com/{OrganizationName}/_odata/v1.0/WorkItemSnapshot?
  $apply=
    filter(DateSK gt 20200101)/
    filter(RevisedDateSK eq null or RevisedDateSK gt 20200101)/
    groupby(
      (DateValue), 
      aggregate($count as Count)
    )

Notitie

We kwamen met deze aanbeveling toen we aan Burndown-widgets werkten. In eerste instantie hebben we filters alleen gedefinieerd, DateSK maar we konden deze query niet goed schalen voor organisaties met grote gegevenssets. Tijdens het profileren van query's hebben we gemerkt dat DateSK revisies niet goed worden gefilterd. Pas nadat we een filter hebben RevisedDateSK toegevoegd, konden we geweldige prestaties op schaal krijgen.
~ Productteam

✔️ GEBRUIK wekelijkse of maandelijkse momentopnamen voor trendquery's die een lange periode omvatten

Standaard worden alle momentopnametabellen gemodelleerd als feitentabellen voor dagelijkse momentopnamen . Als u een query uitvoert op een tijdsbereik, krijgt deze een waarde voor elke dag. Lange tijdsbereiken resulteren in een groot aantal records. Als u deze hoge precisie niet nodig hebt, kunt u wekelijkse of zelfs maandelijkse momentopnamen gebruiken.

U kunt dit doen met andere filterexpressies om dagen te verwijderen die een bepaalde week of maand niet voltooien. Gebruik de IsLastDayOfPeriod eigenschap, die met dit scenario is toegevoegd aan Analytics. Deze eigenschap is van het type Microsoft.VisualStudio.Services.Analytics.Model.Period en kan bepalen of een dag in verschillende perioden is voltooid (bijvoorbeeld weken, maanden enzovoort).

<EnumType Name="Period" IsFlags="true">
  <Member Name="None" Value="0"/>
  <Member Name="Day" Value="1"/>
  <Member Name="WeekEndingOnSunday" Value="2"/>
  <Member Name="WeekEndingOnMonday" Value="4"/>
  <Member Name="WeekEndingOnTuesday" Value="8"/>
  <Member Name="WeekEndingOnWednesday" Value="16"/>
  <Member Name="WeekEndingOnThursday" Value="32"/>
  <Member Name="WeekEndingOnFriday" Value="64"/>
  <Member Name="WeekEndingOnSaturday" Value="128"/>
  <Member Name="Month" Value="256"/>
  <Member Name="Quarter" Value="512"/>
  <Member Name="Year" Value="1024"/>
  <Member Name="All" Value="2047"/>
</EnumType>

Omdat Microsoft.VisualStudio.Services.Analytics.Model.Period deze is gedefinieerd als een opsomming met vlaggen, gebruikt u de OData-operator has en geeft u het volledige type op voor de letterlijke waarde van de periode.

IsLastDayOfPeriod has Microsoft.VisualStudio.Services.Analytics.Model.Period'Month'

De volgende query retourneert bijvoorbeeld het aantal werkitems dat is gedefinieerd op de laatste dag van elke maand.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItemSnapshot?
  $apply=
    filter(IsLastDayOfPeriod has Microsoft.VisualStudio.Services.Analytics.Model.Period'Month')/
    groupby(
      (DateValue), 
      aggregate($count as Count)
    )

✔️ Gebruik Tags de verzamelingseigenschap voor werkitems bij het filteren op tags

U kunt de TagNames eigenschap met de contains functie gebruiken om te bepalen of een werk is gemarkeerd met een specifieke tag. Deze aanpak kan echter leiden tot trage query's, met name bij het controleren op meerdere tags tegelijk. Voor de beste prestaties en resultaten gebruikt u in plaats daarvan de Tags navigatie-eigenschap.

De volgende query haalt bijvoorbeeld alle werkitems op die zijn getagd met een {tag}.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq '{tag}')
  &$select=WorkItemId, Title, State

Deze aanpak werkt ook uitstekend wanneer u op meerdere tags moet filteren. De volgende query retourneert bijvoorbeeld alle werkitems die zijn gelabeld met {tag1}of{tag2}

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq {tag1} or t/TagName eq {tag2})
  &$select=WorkItemId, Title, State

U kunt deze filters ook combineren met een operator 'en'. De volgende query haalt bijvoorbeeld alle werkitems op die zijn getagd met zowel {tag1}als{tag2}

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq {tag1}) and Tags/any(t:t/TagName eq {tag2})
  &$select=WorkItemId, Title, State

✔️ TagNames Gebruik de eigenschap als u alle tags in een werkitem als tekst wilt weergeven

De navigatie-eigenschap Tags, beschreven in de vorige sectie, is ideaal voor filteren. Het werken met de query biedt echter enkele uitdagingen omdat de query tags in een geneste verzameling retourneert. Het gegevensmodel bevat ook een TagNames primitieve eigenschap (Edm.String), die we hebben toegevoegd om verbruiksscenario's voor tags te vereenvoudigen. Het is één tekstwaarde die een lijst bevat met alle tags in combinatie met een puntkomma "; " scheidingsteken. Gebruik deze eigenschap wanneer u alleen tags samen weergeeft. U kunt deze combineren met de eerder beschreven tagsfilters.

De volgende query haalt bijvoorbeeld alle werkitems op die zijn getagd met een {tag}. Hiermee wordt de werkitem-id, titel, status en een tekstweergave van gecombineerde tags geretourneerd.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq '{tag}')
  &$select=WorkItemId, Title, State, TagNames

Belangrijk

De eigenschap TagNames heeft een lengtelimiet van 1024 tekens. Het bevat een set tags die binnen die limiet passen. Als een werkitem veel tags bevat of als de tags erg lang zijn, TagNames bevat u niet de volledige set en Tag moet de navigatie-eigenschap in plaats daarvan worden gebruikt.

❌NIET GEBRUIKEN en toupper functies gebruiken tolower om hoofdlettergevoelige vergelijkingen uit te voeren

Als u met andere systemen hebt gewerkt, kunt u verwachten dat u de tolower of toupper functies gebruikt voor een niet-hoofdlettergevoelige vergelijking. Met Analytics zijn alle tekenreeksvergelijkingen standaard niet hoofdlettergevoelig, dus u hoeft geen functies toe te passen om deze expliciet te verwerken.

Met de volgende query worden bijvoorbeeld alle werkitems opgehaald die zijn getagd met 'KWALITEIT', 'kwaliteit' of een andere combinatie van dit woord.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=Tags/any(t:t/TagName eq 'quality')
  &$select=WorkItemId, Title, State, TagNames

❌ Gebruik geen niet-afhankelijke uitbreiding met $levels=max

OData biedt de mogelijkheid om alle niveaus van een hiërarchische structuur uit te breiden. Het bijhouden van werkitems bevat bijvoorbeeld een aantal entiteiten waarbij een niet-afhankelijke uitbreiding kan worden toegepast. Deze bewerking werkt alleen voor organisaties met een kleine hoeveelheid gegevens. Het schaalt niet goed voor grotere gegevenssets. Gebruik het helemaal niet als:

  • U werkt met grote gegevenssets.
  • U ontwikkelt een widget en u hebt geen controle over waar de widget wordt geïnstalleerd.

✔️ DO use server-driven paging

Als u vraagt om een set die te groot is om in één antwoord te worden verzonden, past Analytics paging toe. Het antwoord bevat slechts een gedeeltelijke set en een koppeling waarmee de volgende gedeeltelijke set items kan worden opgehaald. Deze strategie wordt beschreven in de OData-specificatie - OData-versie 4.0. Deel 1: Protocol - Servergestuurde paging. Door de service de paging te laten beheren, krijgt u de beste prestaties omdat de skiptoken entiteit zorgvuldig is ontworpen om zo efficiënt mogelijk te zijn.

De koppeling naar de volgende pagina is opgenomen in de @odata.nextLink eigenschap.

{
  "@odata.context": "https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/$metadata#WorkItems(*)",
  "value": [
    ...
  ],
  "@odata.nextLink":"https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?$skiptoken=12345"}

Notitie

De meeste bestaande OData-clients kunnen servergestuurde paging automatisch verwerken. Deze strategie wordt bijvoorbeeld al gebruikt door de volgende hulpprogramma's: Power BI, SQL Server Integration Services en Azure Data Factory.

❌ Geen gebruik $top en $skip queryopties voor het implementeren van clientgestuurde paging

Met andere REST API's hebt u mogelijk clientgestuurde paging met $top en $skip queryopties geïmplementeerd. Gebruik ze niet met Analytics. Er zijn verschillende problemen met deze aanpak en prestaties zijn er een van. Gebruik in plaats daarvan de servergestuurde pagingstrategie die in de vorige sectie wordt beschreven.

✔️ Gebruik $top de queryoptie om het aantal records te beperken

De queryoptie $top wordt alleen afgeraden wanneer deze samen met $skip. Als u in uw rapportagescenario slechts een subset van records nodig hebt (bijvoorbeeld voorbeeld), is het prima om de queryoptie te gebruiken $top . Als u records wilt rangschikken op basis van een aantal criteria, moet u ook altijd $top in combinatie met $orderby een stabiel resultaat krijgen met de hoogste gerangschikte records.

✔️ OVERWEEG een query te schrijven om een klein aantal records te retourneren

Het schrijven van een query om een klein aantal records te retourneren, is de meest intuïtieve richtlijn. Probeer altijd alleen de gegevens op te halen die u echt belangrijk vindt. U kunt dit bereiken door de meeste krachtige filtermogelijkheden beschikbaar te maken in de OData-querytaal.

✔️ OVERWEEG het aantal geselecteerde eigenschappen tot een minimum te beperken

Sommige projectbeheerders passen hun processen sterk aan door aangepaste velden toe te voegen. Zware aanpassing kan leiden tot prestatieproblemen bij het ophalen van alle beschikbare kolommen op brede entiteiten (bijvoorbeeld WorkItems). Analyse is gebouwd op basis van een Columnstore-indextechnologie . Dat betekent dat gegevens zowel opslag als queryverwerking op basis van kolommen zijn. Dus hoe meer eigenschappen een query verwijst, hoe duurder het is om te verwerken. Probeer altijd de set eigenschappen in uw query's te beperken tot wat u echt belangrijk vindt in uw rapportagescenario.

✔️ OVERWEEG filteren op eigenschappen van surrogaatsleutels (DateSK achtervoegsel)

Er zijn veel manieren waarop u een datumfilter kunt definiëren. U kunt filteren op de datumeigenschap rechtstreeks (bijvoorbeeld CreatedDate), de navigatie-tegenhanger (bijvoorbeeld CreatedOnDate), of de surrogaatsleutelweergave (bijvoorbeeld CreatedDate). De laatste optie levert de beste prestaties op en heeft de voorkeur wanneer de rapportagevereisten dit toestaan.

De volgende query haalt bijvoorbeeld alle werkitems op die zijn gemaakt sinds begin 2020.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge 20200101

✔️ OVERWEGEN om te filteren op surrogaatsleutelkolommen

Als u de gegevens wilt filteren op de waarde van een gerelateerd object (bijvoorbeeld het filteren van een werkitem op de projectnaam), hebt u altijd twee opties. U kunt de navigatie-eigenschap (bijvoorbeeld Project/ProjectName) gebruiken of de surrogaatsleutel vooraf vastleggen en rechtstreeks in de query gebruiken (bijvoorbeeld ProjectSK).

Als u een widget bouwt, raden we u aan de laatste optie te gebruiken. Wanneer de sleutel wordt doorgegeven als onderdeel van de query, wordt het aantal entiteitssets dat moet worden aangeraakt verminderd en worden de prestaties verbeterd.

De volgende queryfilters WorkItems bijvoorbeeld met behulp van eigenschap in plaats Project/ProjectName van ProjectSK navigatie-eigenschap.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=ProjectSK eq {projectSK}

❌ VERMIJD het gebruik Parentvan, Childrenof Revisions eigenschappen in de $filter of $expand componenten

Werkitems zijn de duurste entiteiten in het hele gegevensmodel. Ze hebben verschillende navigatie-eigenschappen die u kunt gebruiken voor toegang tot gerelateerde werkitems: Parent, Children, Revisions. Telkens wanneer u deze in een query gebruikt, verwacht u echter een afname van de prestaties. Vraag altijd of u echt een van deze eigenschappen nodig hebt en mogelijk uw ontwerp bijwerkt.

In plaats van uit te breiden Parentkunt u bijvoorbeeld meer werkitems ophalen en de eigenschap gebruiken ParentWorkItemId om de volledige hiërarchie aan de clientzijde te reconstrueren. Voer dergelijke optimalisatie per geval uit.

✔️ OVERWEEG de voorkeur door te geven VSTS.Analytics.MaxSize in de koptekst

Wanneer u een query uitvoert, weet u niet hoeveel records de query retourneert. Verzend een andere query met aggregaties of volg alle volgende koppelingen en haal de volledige gegevensset op. Analyse respecteert VSTS.Analytics.MaxSize de voorkeur, waardoor u snel kunt mislukken in die gevallen dat de gegevensset groter is dan wat uw client kan accepteren.

Deze optie is handig in scenario's voor gegevensexport. Als u deze wilt gebruiken, moet u header toevoegen Prefer aan uw HTTP-aanvraag en instellen VSTS.Analytics.MaxSize op een niet-negatieve waarde. De VSTS.Analytics.MaxSize waarde vertegenwoordigt het maximum aantal records dat u kunt accepteren. Als u deze instelt op nul, wordt een standaardwaarde van 200 K gebruikt.

De volgende query retourneert bijvoorbeeld werkitems als de gegevensset kleiner of gelijk is aan 1000 records.

GET https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems HTTP/1.1
User-Agent: {application}
Prefer: VSTS.Analytics.MaxSize=1000
OData-MaxVersion: 4.0
Accept: application/json;odata.metadata=minimal
Host: analytics.dev.azure.com/{OrganizationName}

Als de gegevensset de limiet van 1000 records overschrijdt, mislukt de query onmiddellijk met de volgende fout.

Het queryresultaat bevat 1296 rijen en overschrijdt de maximaal toegestane grootte van 1000. Verminder het aantal records door extra filters toe te passen

Zie de eigenschap ODataPreferenceHeader.MaxPageSize voor informatie over het instellen van het maximale paginaformaat.

Richtlijnen voor querystijl

✔️ Gebruik $count wel virtuele eigenschap in de aggregatiemethoden

Sommige entiteiten maken eigenschap beschikbaar Count . Ze maken enkele rapportagescenario's eenvoudiger wanneer de gegevens naar een andere opslag worden geëxporteerd. U moet deze kolommen echter niet gebruiken in aggregaties in OData-query's. Gebruik in plaats daarvan de $count virtuele eigenschap.

De volgende query retourneert bijvoorbeeld het totale aantal werkitems.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $apply=aggregate($count as Count)

❌ VERMIJD het gebruik van $count virtuele eigenschap in het URL-segment

Hoewel U met OData Standard virtuele eigenschappen kunt gebruiken $count voor entiteitssets (bijvoorbeeld _odata/v1.0/WorkItems/$count), kunnen niet alle clients het antwoord correct interpreteren. Daarom is het raadzaam om in plaats daarvan aggregaties te gebruiken.

De volgende query retourneert bijvoorbeeld het totale aantal werkitems.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $apply=aggregate($count as Count)

✔️ OVERWEEG om parameteraliassen te gebruiken om vluchtige onderdelen van de query te scheiden

Parameteraliassen bieden een elegante oplossing voor het extraheren van vluchtige onderdelen, zoals parameterwaarden uit de hoofdquerytekst. U kunt deze gebruiken in expressies die het volgende evalueren:

  • Een primitieve waarde
  • Een complexe waarde
  • Een verzameling primitieve of complexe waarden.

Zie OData-versie 4.0 voor meer informatie. Deel 2: URL-conventies - 5.1.1.13 Parameteraliassen. Parameters zijn handig wanneer de querytekst wordt gebruikt als een sjabloon die kan worden geïnstantieerd met door de gebruiker opgegeven waarden.

In de volgende query wordt bijvoorbeeld een parameter gebruikt @createdDateSK om de waarde van de filterexpressie te scheiden.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=CreatedDateSK ge @createdDateSK
  &$select=WorkItemId, Title, State
  &@createdDateSK=20200101

❌ VERMIJD menging $apply en $filter componenten in één query

Als u wilt toevoegen filter aan uw query, hebt u twee opties. U kunt dit doen met de $filter component of de $apply=filter() combinatie. Elk van deze opties werkt zelfstandig, maar het combineren ervan kan leiden tot onverwachte resultaten.

Ondanks de verwachting die men kan hebben, definieert OData duidelijk een volgorde van de evaluatie. Bovendien heeft de $apply component prioriteit boven $filter. Daarom moet u een of meer opties kiezen, maar deze twee filteropties in één query vermijden. Het is belangrijk dat de query's automatisch worden gegenereerd.

De volgende query filtert bijvoorbeeld eerst werkitems op StoryPoint gt 5, voegt resultaten samen op pad en filtert ten slotte het resultaat op StoryPoints gt 2. Met deze evaluatievolgorde retourneert de query altijd een lege set.

https://analytics.dev.azure.com/{OrganizationName}/_odata/{version}/WorkItems?
  $filter=StoryPoints gt 2
  $apply=
    filter(StoryPoints gt 5)/
    groupby(
      (Area/AreaPath),
      aggregate(StoryPoints with sum as StoryPoints)
    )

✔️ OVERWEEG om uw query te structureren zodat deze overeenkomt met de OData-evaluatievolgorde

Omdat menging $apply en filter componenten in één query tot mogelijke verwarring kunnen leiden, raden we u aan om uw queryclausules te structuren zodat deze overeenkomen met de evaluatievolgorde.

  1. $apply
  2. $filter
  3. $orderby
  4. $expand
  5. $select
  6. $skip
  7. $top

✔️ OVERWEEG OData-mogelijkheden te bekijken die worden beschreven in de metagegevensaantekeningen

Wanneer u niet zeker weet welke OData-mogelijkheden Analytics ondersteunt, kunt u aantekeningen opzoeken in de metagegevens. Het technische comité OASIS Open Data Protocol (OData) in een TC GitHub-opslagplaats onderhoudt een lijst met beschikbare aantekeningen.

De lijst met ondersteunde filterfuncties is bijvoorbeeld beschikbaar in aantekeningen op Org.OData.Capabilities.V1.FilterFunctions de entiteitscontainer.

<Annotation Term="Org.OData.Capabilities.V1.FilterFunctions">
  <Collection>
  <String>contains</String>
  <String>endswith</String>
  [...]
  </Collection>
</Annotation>

Een andere handige aantekening is Org.OData.Capabilities.V1.ExpandRestrictions, waarin wordt uitgelegd welke navigatie-eigenschappen u niet kunt gebruiken in de $expand component. In de volgende aantekening wordt bijvoorbeeld uitgelegd dat Revisions in de WorkItems entiteitsset niet kan worden uitgebreid.

<EntitySet Name="WorkItems" EntityType="Microsoft.VisualStudio.Services.Analytics.Model.WorkItem">
  [...]
  <Annotation Term="Org.OData.Capabilities.V1.ExpandRestrictions">
    <Record>
      <PropertyValue Property="Expandable" Bool="true"/>
      <PropertyValue Property="NonExpandableProperties">
        <Collection>
          <NavigationPropertyPath>Revisions</NavigationPropertyPath>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</EntitySet>