OData Analytics-Abfragerichtlinien für Azure DevOps

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Erweiterungsentwickler können profitieren, indem Sie die in diesem Artikel aufgeführten Richtlinien befolgen, um effiziente OData-Abfragen für Analytics für Azure DevOps zu entwerfen. Anhand dieser Richtlinien können Sie sicherstellen, dass die Abfragen eine gute Leistung für die Ausführungszeit und den Ressourcenverbrauch aufweisen. Abfragen, die nicht diesen Richtlinien entsprechen, können zu einer schlechten Leistung führen, mit langen Wartezeiten im Bericht, Abfragen, die den zulässigen Ressourcenverbrauch überschreiten, oder Dienstsperrungen.

Diese Richtlinien sind unsere Empfehlungen, die den Begriffen DO, CONSIDER, AVOID und DON'T vorangestellt sind. Restriktive Regeln, die von Analytics erzwungen werden, enthalten das Präfix [BLOCKED] . Sie sollten die Kompromisse zwischen verschiedenen Lösungen verstehen. Unter bestimmten Umständen verfügen Sie möglicherweise über Datenanforderungen, die sie zwingen, gegen eine oder mehrere Richtlinien zu verstoßen. Solche Fälle sollten selten sein. Es wird empfohlen, dass Sie einen klaren und überzeugenden Grund für solche Entscheidungen haben.

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

Fehler und Warnmeldungen

✔️ ÜBERPRÜFEN Sie OData-Antwortwarnungen

Jede ausgeführte Abfrage wird anhand einer Reihe vordefinierter Regeln überprüft. Verstöße geben die folgende OData-Antwort @vsts.warningszurück. Überprüfen Sie diese Warnungen, da sie aktuelle und kontextbezogene Informationen zur Verbesserung Ihrer Abfrage bereitstellen.

{
  "@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-Fehlermeldungen überprüfen

Abfragen, die gegen eine OData-Fehlerregel verstoßen, führen zu einer fehlgeschlagenen Antwort mit einem Statuscode 400 (Ungültige Anforderung). Zuordnungsmeldungen werden nicht in der @vsts.warnings Eigenschaft angezeigt. Stattdessen erzeugen sie eine Fehlermeldung in der message-Eigenschaft der JSON-Antwort.

{
  "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."
  }
}

Beschränkungen

Empfohlene Vorgehensweisen

• ✔️ Begrenzen Sie die Abfrage auf die Projekte, zu denen Sie Zugang haben
• ✔️ GEBEN Sie den Projektfilter innerhalb der $expand Klausel an, wenn ihre Erweiterung Daten in anderen, potenziell nicht zugänglichen Projekten enthalten kann.
• ✔️ Warten Sie oder stoppen Sie den Vorgang, wenn Ihre Abfrage die Nutzungsbeschränkungen überschreitet
• ✔️ Warten oder stoppen Sie den Vorgang, wenn Ihre Abfrage mit einem Timeout fehlschlägt
• ✔️ Nimm die DateSK oder DateValue Spalte in die groupby-Klausel auf, wenn du über Snapshottabellen aggregierst
• ✔️ Adressieren Sie explizit Entitäten mit Filterklauseln
• ✔️ Verwenden Sie WorkItemRevisions Entity Set, um alle Revisionen für ein bestimmtes Arbeitselement zu laden.
• ✔️ Benutzen Sie den Batch-Endpunkt für lange Abfragen
• ✔️ ANGEBEN der Zeitzone beim Filtern nach Datumsspalten

Betrachten Sie Storm oder Flink

• ✔️ ERWÄGEN SIE, Abfragen mit dem projektbezogenen Endpunkt durchzuführen

Blockiert

• ❌ [BLOCKIERT] VERWENDEN SIE keine Momentaufnahmeentitäten für andere Elemente als Aggregationen.
• ❌ [BLOCKIERT] VERWENDEN SIE keine Entitätsschlüssel in Ressourcenpfaden für die Entitätsadressierung.
• ❌ [BLOCKIERT] NICHT Revisions auf WorkItem-Entität erweitern
• ❌ [BLOCKIERT] NICHT gruppieren in unterschiedlichen Spalten
• ❌[BLOCKIERT] KEINE Aggregation verwenden countdistinct
• ❌ [BLOCKIERT] VERWENDEN Sie keinen Batchendpunkt zum Senden mehrerer Abfragen.
• ❌ [BLOCKIERT] VERWENDEN SIE KEINE Abfragen, die zu mehr als 800 Spalten führen

Vermeiden

• ❌ VERMEIDEN von Aggregationen, die zu arithmetischen Überlauf führen können
• ❌ VERMEIDEN sie das Erstellen langer Abfragen

✔️ Begrenzen Sie die Abfrage auf das Projekt bzw. die Projekte, auf die Sie Zugriff haben

Wenn Ihre Abfrage auf Daten aus einem Projekt abzielt, auf das Sie keinen Zugriff haben, gibt die Abfrage eine Meldung "Projektzugriff verweigert" zurück. Um sicherzustellen, dass Sie Zugriff haben, stellen Sie sicher, dass Die Berechtigung " Analyse anzeigen " auf "Zulassen" für alle Projekte festgelegt ist, die Sie abfragen. Weitere Informationen finden Sie unter Berechtigungen, die für den Zugriff auf Analytics erforderlich sind.

Wenn Sie keinen Zugriff auf ein Projekt haben, wird die folgende Meldung angezeigt:

Die Abfrageergebnisse enthalten Daten in einem oder mehreren Projekten, für die Sie keinen Zugriff haben. Fügen Sie einen oder mehrere Projekte filter hinzu, um die Projekt(en) anzugeben, auf die Sie in der Entität "WorkItems" Zugriff haben. Wenn Sie $expand- oder Navigationseigenschaften verwenden, ist der Projektfilter für diese Entitäten erforderlich.

Um dieses Problem zu umgehen, können Sie entweder explizit einen Projektfilter hinzufügen oder den projektbezogenen Endpunkt verwenden, wie weiter unten in diesem Artikel erläutert.

Die folgende Abfrage ruft beispielsweise Arbeitsaufgaben ab, die zu Projekten mit den Namen {projectSK1} und {projectSK2} gehören.

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

✔️ GEBEN Sie den Projektfilter innerhalb der $expand Klausel an, wenn ihre Erweiterung Daten in anderen, potenziell nicht zugänglichen Projekten enthalten kann.

Wenn Sie Navigationseigenschaften erweitern, besteht die Möglichkeit, dass Sie auf Daten aus anderen, nicht zugänglichen Projekten verweisen. Wenn Sie auf nicht zugängliche Daten verweisen, erhalten Sie die gleiche Fehlermeldung, die zuvor aufgeführt ist: "Die Abfrageergebnisse enthalten Daten in einem oder mehreren Projekten...". Ebenso können Sie dieses Problem beheben, indem Sie explizite Projektfilter hinzufügen, um die erweiterten Daten zu steuern.

Dies ist in der regulären $filter Klausel für einfache Navigationseigenschaften möglich. Die folgende Abfrage fordert beispielsweise explizit an WorkItemLinks , wo sowohl der Link als auch das Ziel im selben Projekt vorhanden sind.

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)

Stattdessen können Sie den Filter zur Option $filter Erweitern in der Klausel $expand verschieben. Sie ändert jedoch die Semantik der Abfrage. Die folgende Abfrage ruft beispielsweise alle Verknüpfungen aus einem bestimmten Projekt ab und erweitert das Ziel nur, wenn es im selben Projekt vorhanden ist. Obwohl gültig, kann dieser Ansatz Verwirrung verursachen, da es schwierig sein kann zu bestimmen, ob eine Eigenschaft nicht erweitert wird, weil sie null ist oder weil sie herausgefiltert wurde. Verwenden Sie diese Lösung nur, wenn Sie dieses bestimmte Verhalten wirklich benötigen.

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)

Die $filter Erweiterungsoption ist nützlich, wenn Sie die Eigenschaft zur Erweiterung von Sammlungen verwenden, z. B. im WorkItems Entitätssatz. Die folgende Abfrage gibt beispielsweise alle Arbeitselemente aus einem bestimmten Projekt sowie alle untergeordneten Elemente zurück, die zum gleichen Projekt gehören.

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)

Geben Sie den Filter an, wenn Sie eine der folgenden Eigenschaften erweitern:

• WorkItems Entitätssatz: Parent, Children
• WorkItemLinks Entitätssatz: TargetWorkItem.

✔️ Erwägen Sie, Abfragen über den projektbezogenen Endpunkt auszuführen.

Wenn Sie an Daten aus einem einzelnen Projekt interessiert sind, empfehlen wir die Verwendung des projektbezogenen OData-Endpunkts (/{ProjectName}/_odata/v1.0). Es werden die in den vorherigen beiden Abschnitten beschriebenen Probleme vermieden, und Daten werden implizit auf das ein Projekt, den Referenzentitätssatz und alle erweiterten Navigationseigenschaften gefiltert.

Mit dieser Vereinfachung können die Abfragen aus dem vorherigen Abschnitt in das folgende Formular umgeschrieben werden. Der Filter in der Erweiterungsklausel wurde nicht nur ausgeblendet, sondern auch der Filter für den Hauptentitätssatz ist nicht mehr erforderlich.

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

Die Abfrage für untergeordnete Arbeitsaufgaben ist auch viel kürzer und einfacher.

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

Sie können diese Lösung nur anwenden, wenn der Fokus Daten aus einem einzelnen Projekt ist. Für projektübergreifende Berichterstellung müssen Sie Filterstrategien verwenden, die in den vorherigen Abschnitten beschrieben sind.

✔️ Warten oder beenden Sie den Vorgang, wenn Ihre Abfrage die Nutzungsgrenzen überschreitet.

Wenn Sie viele Abfragen ausführen oder die Abfragen viele Ressourcen erfordern, könnten Sie die Servicegrenzen überschreiten und vorübergehend blockiert werden. Wenn Sie die Dienstgrenzwerte überschreiten, beenden Sie den Vorgang, da die wahrscheinliche nächste von Ihnen gesendete Abfrage mit derselben Fehlermeldung fehlschlägt.

Die Anforderung wurde aufgrund einer Überschreitung der Verwendung der Ressource "{resource}" im Namespace "{namespace}" blockiert.

Weitere Informationen zur Zinsbegrenzung finden Sie unter "Zinslimits". Informationen zum Entwerfen effizienter OData-Abfragen finden Sie in den Leistungsrichtlinien weiter unten in diesem Artikel.

✔️ Warten oder stoppen Sie den Vorgang, wenn Ihre Abfrage mit einem Zeitüberschreitung fehlschlägt.

Ähnlich wie beim Überschreiten der Nutzungsgrenzwerte sollten Sie den Vorgang warten oder beenden, wenn ihre Abfrage über ein Timeout verfügt. Es könnte ein vorübergehendes Problem signalisieren, sodass Sie einmal versuchen, zu sehen, ob das Problem behoben wird. Persistente Timeouts deuten jedoch darauf hin, dass die Abfrage wahrscheinlich zu teuer ist, um ausgeführt zu werden. Weitere Wiederholungen führen nur zu einer Überschreitung der Nutzungsgrenzwerte, und Sie werden blockiert.

TF400733: Die Anforderung wurde abgebrochen: Die Anforderung hat das Timeout der Anforderung überschritten, versuchen Sie es erneut.

Timeouts deuten darauf hin, dass eine Abfrage eine Optimierung erfordert. Informationen zum Entwerfen effizienter OData-Abfragen finden Sie in den Leistungsrichtlinien weiter unten in diesem Artikel.

❌ [BLOCKIERT] VERWENDEN SIE keine Momentaufnahmeentitäten für andere Elemente als Aggregationen.

Snapshot-Entitätssätze mit dem Snapshot Suffix sind besonders, da sie als tägliche Momentaufnahmen modelliert werden. Sie können sie verwenden, um einen Status von Entitäten zu erhalten, wie sie am Ende jedes Tages in der Vergangenheit waren. Wenn Sie z. B. WorkItemSnapshot abfragen und auf einen einzelnen WorkItemId filtern, erhalten Sie einen Datensatz für jeden Tag, seit die Arbeitsaufgabe erstellt wurde. Das direkte Laden aller daten wäre teuer und würde höchstwahrscheinlich die Nutzungsgrenzwerte überschreiten und blockiert werden. Aggregationen für diese Entitäten sind jedoch sowohl zulässig als auch empfohlen. Tatsächlich wurden die Snapshot-Entitätssätze unter Berücksichtigung von Aggregationsszenarien entwickelt.

Zum Beispiel gibt die folgende Abfrage die Anzahl der Arbeitsaufgaben nach Datum an, um zu beobachten, wie sie sich im Januar 2020 entwickelt haben.

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

Weitere Informationen zu Aggregationen finden Sie unter "Aggregierte Daten".

✔️ Fügen Sie die DateSK- oder DateValue-Spalte in die groupby-Klausel ein, wenn Sie über Snapshot-Tabellen aggregieren.

Da alle Momentaufnahmeentitäten als tägliche Momentaufnahmetabellen modelliert werden, sollten Sie immer eine der Tageseigenschaften (DateSK oder DateValue) in die Gruppierungsklausel aufnehmen. Andernfalls kann das Ergebnis fälschlicherweise aufgeblasen angezeigt werden.

Wenn Sie beispielsweise nur nach der AssignedTo Eigenschaft gruppiert und mit der Anzahl zusammenfassen, werden alle Arbeitsaufgaben, die Personen zugeordnet sind, mit der Anzahl der Tage multipliziert, an denen jede Zuordnung aktiv war. Während Sie vielleicht eine Situation haben, in der es das gewünschte Ergebnis ist, sind solche Fälle selten.

❌ [BLOCKIERT] VERWENDEN SIE keine Entitätsschlüssel in Ressourcenpfaden für die Entitätsadressierung.

OData-Syntax bietet eine Möglichkeit, auf eine bestimmte Entität zuzugreifen, indem sie ihre Schlüssel direkt in die URL-Segmente einbezieht. Weitere Informationen finden Sie unter OData Version 4.0. Teil 2: URL-Konventionen - 4.3 Adressierung von Entitäten. Obwohl OData eine solche Adressierung zulässt, blockiert Analytics sie. Die Einbindung in eine Abfrage führt zu folgendem Fehler.

Die im URI angegebene Abfrage ist ungültig. Analytics unterstützt keine Schlüssel- oder Eigenschaftennavigation wie WorkItems(Id) oder WorkItem(Id)/AssignedTo. Wenn Sie diesen Fehler in PowerBI erhalten, schreiben Sie Ihre Abfrage erneut, um eine falsche Faltung zu vermeiden, die ein Problem mit N+1 verursacht.

Da die Fehlermeldungen darauf hinweisen, können bestimmte Clienttools direkte Entitätsadressierung missbrauchen. Anstatt alle Daten in einer einzigen Anforderung zu laden, können solche Clients auswählen, dass jede Entität unabhängig voneinander angefordert werden soll. Diese Vorgehensweise wird abgeraten, da sie zu einer hohen Anzahl von Anforderungen führen kann. Stattdessen wird empfohlen, explizite Entitätsadressierung zu verwenden, wie im folgenden Abschnitt erläutert.

Adressiere explizit Entitäten mit Filterklauseln

Wenn Sie Daten für eine einzelne Entität abrufen möchten, sollten Sie denselben Ansatz wie für eine Sammlung von Entitäten verwenden und filter in der $filter Klausel explizit definieren.

Die folgende Abfrage ruft beispielsweise ein einzelnes Arbeitselement anhand seiner Kennung ab.

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

Wenn Sie nicht sicher sind, welche Eigenschaften Sie in einen solchen Filter aufnehmen sollten, können Sie sie in den Metadaten nachschlagen. Siehe Erstellen von OData-Abfragen für Analytics, URL-Komponenten zum Abfragen der Metadaten. Eigenschaften befinden sich im Key Element der EntityType. Beispielsweise sind WorkItemId und Revision Schlüsselspalten für die WorkItemRevision Entität.

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

❌ [BLOCKIERT] nicht Revisions auf WorkItem Entität erweitern

Das Analysedatenmodell verbietet bestimmte Arten von Erweiterungen. Eine davon, die für einige überraschend sein könnte, ist die Revisions Sammlungseigenschaft für die WorkItem Entität. Wenn Sie versuchen, diese Eigenschaft zu erweitern, wird die folgende Fehlermeldung angezeigt.

Die im URI angegebene Abfrage ist ungültig. Die Eigenschaft 'Revisions' kann nicht in der abfrageoption $expand verwendet werden.

Diese Einschränkung wurde eingeführt, um alle dazu zu ermutigen, die empfohlene Lösung zu nutzen, nämlich Überarbeitungen von WorkItemRevisions abzurufen, wie im folgenden Abschnitt erläutert.

✔️ Verwenden Sie das WorkItemRevisions-Entity-Set, um alle Revisionen für ein gegebenes Arbeitselement zu laden.

Verwenden Sie WorkItemRevisions jedes Mal, wenn Sie den vollständigen Verlauf für eine Arbeitsaufgabe oder eine Sammlung von Arbeitsaufgaben abrufen möchten.

Die folgende Abfrage gibt beispielsweise alle Überarbeitungen einer Arbeitsaufgabe mit dem {id} Bezeichner zurück.

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

Wenn Sie sich um den vollständigen Verlauf aller Arbeitsaufgaben kümmern, die bestimmten Kriterien entsprechen, drücken Sie ihn mithilfe eines Filters für die WorkItem Navigationseigenschaft aus. Die folgende Abfrage ruft beispielsweise alle Überarbeitungen aller aktuell aktiven Arbeitsaufgaben ab.

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

❌ [BLOCKIERT] NICHT auf einzelne Spalten gruppieren

Sie verwenden einen Gruppierungsvorgang, um die Anzahl der Datensätze zu verringern. Die Verwendung unterschiedlicher Spalten in der groupby Klausel weist auf ein Problem hin, und die Abfrage schlägt sofort fehl. Sollte diese Situation versehentlich auftreten, erhalten Sie die folgende Fehlermeldung.

Mindestens eine der Spalten, die in der Groupby-Klausel dieser Abfrage angegeben sind, wird nicht empfohlen.

Um dieses Problem zu beheben, entfernen Sie die eindeutige Spalte aus der groupby Klausel.

❌[BLOCKIERT] KEINE Aggregation verwenden countdistinct

Analytics unterstützt die countdistinct Funktion nicht, obwohl OData dies tut. Obwohl wir beabsichtigen, in Zukunft Support hinzuzufügen, ist es derzeit nicht verfügbar. Eine Abfrage, die diese Funktion enthält, gibt die folgende Fehlermeldung zurück.

Abfragen, die eine mit einer Aggregation getrennte Anzahl anwenden, werden nicht unterstützt.

❌ VERMEIDEN von Aggregationen, die zu arithmetischen Überlauf führen können

In seltenen Fällen kann es bei einer Aggregationsabfrage zu Problemen mit arithmetischem Überlauf kommen. Beispielsweise kann es vorkommen, dass Sie einige numerische Eigenschaften addieren, die nicht für die Addition vorgesehen sind, wie etwa StackRank in den Arbeitselement-Entitäten. Da die OData-Erweiterung für den Datenaggregationsstandard keine Möglichkeit zum Umwandeln einer Eigenschaft in einen anderen Typ bietet, besteht die einzige Möglichkeit zum Beheben dieses Problems darin, die problematische Eigenschaft aus der Aggregation zu entfernen.

✔️ Verwenden Sie den Batchendpunkt für lange Abfragen

Es können Probleme mit langen Abfragen auftreten. Insbesondere können Probleme auftreten, wenn:

• Sie fragen ein Projekt mit vielen benutzerdefinierten Feldern ab.
• Ihre Abfrage wird programmgesteuert erstellt.

Der aktuelle Grenzwert für gesendete HTTP GET OData-Abfragen beträgt 3.000 Zeichen. Wenn Sie dies überschreiten, erhalten Sie eine Antwort "404 Nicht gefunden".

HTTP/1.1 404 Not Found
Content-Length: 0

Um dieses Problem zu beheben, verwenden Sie den OData-Batchendpunkt, wie in der Spezifikation , OData Version 4.0 erläutert. Teil 1: Protokoll - 11.7 Batchanforderungen. Batchfunktion wurde in erster Linie entwickelt, um mehrere Vorgänge in eine einzelne HTTP Anforderungsnutzlast zu gruppieren. Sie können sie aber auch als Problemumgehung für die Einschränkung der Abfragelänge verwenden. Durch das Senden einer HTTP POST Anforderung können Sie eine Abfrage einer beliebigen Länge übergeben und der Dienst diese ordnungsgemäß interpretiert.

❌ [BLOCKIERT] Verwenden Sie keinen Batch-Endpoint zum Senden mehrerer Abfragen.

Wir beschränken die Verwendung des Batchendpunkts, sodass er keinen Batch mehrerer Anfragen bearbeiten kann. Eine einzelne Anforderung kann immer noch nur eine Abfrage haben. Wenn Sie versuchen, einen Batch mehrerer Abfragen zu senden, schlägt der Vorgang mit der folgenden Fehlermeldung fehl. Die einzige Lösung besteht darin, Abfragen in mehrere Anforderungen aufzuteilen.

Analytics unterstützt keine Verarbeitung mehrerer Vorgänge, die die aktuelle Batchnachricht enthält. Analytics verwendet OData-Batch zur Unterstützung von POST-Anforderungen, erfordert jedoch, dass Sie den Vorgang auf eine einzelne Anforderung beschränken.

❌ [BLOCKIERT] VERWENDEN SIE KEINE Abfragen, die zu mehr als 800 Spalten führen

Wir beschränken Abfragen, die zu mehr als 800 Spalten führen. Wenn Sie nicht wählerisch genug sind bei der Auswahl der Spalten, die Ihre Abfrage zurückgibt, erhalten Sie möglicherweise die folgende Fehlermeldung.

VS403670: Die angegebene Abfrage gibt "N"-Spalten zurück, die höher als der zulässige Grenzwert von 800 Spalten sind. Verwenden Sie explizite $select (einschließlich der $expand)-Optionen, um die Anzahl der Spalten einzuschränken.

Fügen Sie Ihrer Abfrage eine $select-Klausel sowie $expand-Vorgänge hinzu, um eine Überschreitung dieses Grenzwerts zu vermeiden.

❌ VERMEIDEN sie das Erstellen langer Abfragen

Wir empfehlen, Ihren Ansatz auszuwerten, wann immer Sie eine lange Abfrage erstellen. Obwohl es viele Szenarien gibt, die eine lange Abfrage benötigen (z. B. komplexe Filter oder eine lange Liste von Eigenschaften), bieten sie in der Regel einen frühen Indikator für einen suboptimalen Entwurf.

Wenn Ihre Abfrage viele Entitätsschlüssel in der Abfrage enthält (z. B WorkItemId eq {id 1} or WorkItemId eq {id 2} or .... ), können Sie sie wahrscheinlich neu schreiben. Anstatt die Bezeichner zu übergeben, versuchen Sie, andere Kriterien zu definieren, die denselben Satz von Entitäten auswählen. Manchmal müssen Sie Ihren Prozess ändern (z. B. ein neues Feld oder tag hinzufügen), aber es lohnt sich in der Regel. Abfragen, die abstraktere Filter verwenden, sind einfacher zu verwalten und haben ein größeres Potenzial, besser zu arbeiten.

Ein weiteres Szenario, das dazu neigt, lange Abfragen zu generieren, tritt auf, wenn Sie viele einzelne Datumsangaben (z. B DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or .... ) einschließen. Suchen Sie nach einem anderen Muster, mit dem Sie einen abstrakteren Filter erstellen können. Die folgende Abfrage gibt beispielsweise alle Arbeitsaufgaben zurück, die am Montag erstellt wurden.

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

✔️ ANGEBEN der Zeitzone beim Filtern nach Datumsspalten

Die Zeitzone (Edm.DateTimeOffset) macht alle Datums- und Uhrzeitinformationen mit einem Offset verfügbar, der den Zeitzoneneinstellungen der Organisation entspricht. Diese Daten sind präzise und einfach gleichzeitig zu interpretieren. Eine weitere nicht beobachtende Folge ist, dass alle Filter auch die Zeitzoneninformationen übergeben müssen. Wenn Sie es überspringen, erhalten Sie die folgende Fehlermeldung.

Die im URI angegebene Abfrage ist ungültig. Es wurde kein Datetime-Offset angegeben. Verwenden Sie eines dieser Formate JJJJ-MM-ddZ, um alles seit Mitternacht oder yyyy-MM-ddThh anzugeben:mm-hh:mm (ISO 8601-Standarddarstellung von Datums- und Uhrzeitangaben), um den Offset anzugeben.

Um dieses Problem zu lösen, fügen Sie die Zeitzoneninformationen hinzu. Angenommen, die Organisation ist so konfiguriert, dass Daten in der Zeitzone "(UTC-08:00) Pacific Time (USA & Kanada)" angezeigt werden, ruft die folgende Abfrage alle Seit Anfang 2020 erstellten Arbeitsaufgaben ab.

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

Dieselbe Lösung funktioniert für Zeitzonen mit positiven Offsets, das Pluszeichen (+) hat jedoch eine besondere Bedeutung im URI, und Sie müssen sie richtig behandeln. Wenn Sie 2020-01-01T00:00:00+08:00 (mit einem + Zeichen) als Ausgangspunkt angeben, erhalten Sie den folgenden Fehler.

Die im URI angegebene Abfrage ist ungültig. Syntaxfehler bei Position 31 in "CreatedDate ge 2020-01-01T000 08:00".

Um es zu lösen, ersetzen Sie das + Zeichen durch seine codierte Version, %2B. Angenommen, die Organisation ist so konfiguriert, dass Daten in "(UTC+08:00) Beijing, Chongqing, Hong Kong, Urumqi" Zeitzone angezeigt werden, gibt die folgende Abfrage alle Seit Anfang 2020 erstellten Arbeitsaufgaben zurück.

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

Ein alternativer Ansatz besteht darin, Datums-Ersatzschlüsseleigenschaften zu verwenden, da sie die Zeitzoneninformationen nicht beibehalten. Die folgende Abfrage gibt beispielsweise alle Arbeitsaufgaben zurück, die seit Anfang 2020 erstellt wurden, unabhängig von den Einstellungen der Organisation.

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

Leistungsrichtlinien

Empfohlene Vorgehensweisen

• ✔️ DO messen die Auswirkungen der Implementierung einer Leistungsrichtlinie
• ✔️ Verwenden Sie Aggregationserweiterungen
• ✔️ Geben Sie Spalten in der $select Klausel an
• ✔️ GEBEN Sie Spalten in der Option zum Erweitern $select innerhalb der $expand Klausel an
• ✔️ DEFINIEREN SIE einen Filter auf RevisedDateSK , wenn Sie historische Arbeitsaufgabendaten (WorkItemRevisions- oder WorkItemSnapshot-Entitätssätze) abfragen
• ✔️ Verwenden Sie wöchentliche oder monatliche Momentaufnahmen für Trendabfragen, die einen langen Zeitraum umfassen.
• ✔️ Verwenden Sie die Sammlungseigenschaft für Arbeitselemente, wenn Sie nach Tags filtern.
• ✔️ Verwenden Sie die TagNames-Eigenschaft, wenn Sie alle Tags eines Arbeitselements als Text anzeigen möchten
• ✔️ DO Verwenden Sie servergesteuertes Paging
• ✔️ Verwenden Sie die $top Abfrageoption, um die Anzahl der Datensätze zu begrenzen

Nicht

• ❌ Verwenden Sie nicht die tolower- und toupper-Funktionen für einen groß-/kleinschreibungsunabhängigen Vergleich
• ❌ VERWENDEN SIE keine grenzenlose Expansion mit $levels=max
• ❌ VERWENDEN SIE NICHT $top und $skip Abfrageoptionen zur Implementierung von clientgesteuertem Paging

Betrachten Sie Storm oder Flink

• ✔️ ERWÄGEN SIE das Schreiben von Abfragen, um kleine Datensätze zurückzugeben.
• ✔️ ERWÄGEN SIE, die Anzahl der ausgewählten Eigenschaften auf ein Minimum zu beschränken.
• ✔️ ZIEHEN SIE IN BETRACHT, nach Datumszusatzschlüsseleigenschaften zu filtern (DateSK Suffix)
• ✔️ Erwägen Sie das Filtern über Ersatzschlüsselspalten
• ✔️ Ziehen Sie in Betracht, die Präferenz im Header zu übergeben vsts.analytics.maxsize.

Vermeiden

• Vermeiden Sie die Verwendung von Parent, Children oder Revisions Eigenschaften in den $filter oder $expand Klauseln

✔️ DO messen die Auswirkungen der Implementierung einer Leistungsrichtlinie

Wie bei allen Leistungsempfehlungen sollten Sie sie nicht blind implementieren. Erfassen Sie stattdessen immer den Basisplan, und messen Sie die Auswirkungen von Änderungen, die Sie vornehmen. Alle Richtlinien wurden basierend auf den Interaktionen mit Kunden von Analytics erstellt, die bestimmte Anforderungen und Herausforderungen hatten. Diese Empfehlungen wurden als allgemein und potenziell nützlich für alle Personen angesehen, die ähnliche Abfragen entwirft. In seltenen Fällen kann die Einhaltung der Richtlinien jedoch keine Auswirkungen oder sogar negative Auswirkungen auf die Leistung haben. Sie müssen den Unterschied messen, um ihn zu bemerken. Sollte dies geschehen, geben Sie Feedback im Entwicklercommunity Portal.

Es gibt viele Optionen zum Messen der Leistung. Am einfachsten ist es, zwei Versionen derselben Abfrage direkt im Browser auszuführen. Beobachten Sie die Zeit, die es in den Entwicklertools benötigt. Sie können beispielsweise den Netzwerkbereich in den Microsoft Edge F12-Entwicklertools verwenden. Eine weitere Möglichkeit besteht darin, diese Informationen mithilfe des Fiddler-Webdebuggertools zu erfassen.

Unabhängig davon, was Ihr Ansatz ist, führen Sie beide Abfragen mehrmals aus. Führen Sie beispielsweise die Abfragen 30 Mal aus, um einen ausreichend großen Beispielsatz zu haben. Ermitteln Sie dann die Leistungsmerkmale. Analytics folgt einer mehrinstanzenfähigen Architektur. Andere Vorgänge, die gleichzeitig auftreten, können sich also auf die Dauer Ihrer Abfragen auswirken.

✔️ Verwenden Sie Aggregationserweiterungen

Das Beste, was Sie tun können, um die Leistung Ihrer Abfragen zu verbessern, ist die Verwendung der Aggregationserweiterung - OData-Erweiterung für Die Datenaggregation. Bitten Sie den Dienst bei der Aggregationserweiterung, datenserverseitig zusammenzufassen und eine kleinere Antwort zurückzugeben, als das, was Sie abrufen können, indem Sie dieselbe clientseitige Funktion anwenden. Schließlich ist Analytics für diese Art von Abfragen optimiert, verwenden Sie sie also.

Weitere Informationen finden Sie unter "Aggregierte Daten".

✔️ Geben Sie Spalten in der $select-Klausel an.

Geben Sie die Spalten an, die Sie in der $select Klausel interessieren. Analytics basiert auf einer Columnstore-Indextechnologie . Das bedeutet, dass sowohl die Datenspeicherung als auch die Abfrageverarbeitung spaltenbasiert erfolgt. Indem Sie die Menge der Eigenschaften im $select-Klausel reduzieren, können Sie die Anzahl der zu scannenden Spalten verringern und die Gesamtleistung der Abfrage verbessern.

Die folgende Abfrage gibt beispielsweise die Spalten für Arbeitsaufgaben an.

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

✔️ Geben Sie Spalten in der $select Erweiterungsoption innerhalb der $expand Klausel an

Ähnlich wie bei den $select Richtlinien für Klauseln geben Sie die Eigenschaften in der $select Erweiterungsoption innerhalb der $expand Klausel an. Es ist einfach zu vergessen, aber wenn Sie es weglassen, enthält Ihre Antwort alle Eigenschaften des erweiterten Objekts.

Die folgende Abfrage spezifiziert beispielsweise die Spalten sowohl für das Arbeitselement als auch für dessen übergeordnetes Element.

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

✔️ DEFINIEREN SIE EINEN FILTER auf RevisedDateSK, wenn Sie historische Arbeitsaufgabendaten abfragen (WorkItemRevisions- oder WorkItemSnapshot-Entitätssätze)

Wenn Sie nach historischen Daten abfragen, besteht die Wahrscheinlichkeit, dass Sie sich für den letzten Zeitraum interessieren (z. B. 30 Tage, 90 Tage). Aufgrund der Implementierung von Arbeitsaufgaben-Objekten gibt es eine effiziente Möglichkeit, solche Abfragen zu formulieren, um eine hohe Effizienz zu erzielen. Jedes Mal, wenn Sie ein Arbeitselement aktualisieren, wird eine neue Überarbeitung erstellt und diese Aktion im System.RevisedDate-Feld aufgezeichnet, wodurch es sich ideal für Historienfilter eignet.

In Analytics wird das überarbeitete Datum in den RevisedDate Eigenschaften (Edm.DateTimeOffset) und RevisedDateSK (Edm.Int32) angezeigt. Verwenden Sie letzteres, um optimale Leistung zu erzielen. Der Datums-Ersatzschlüssel stellt das Datum dar, an dem eine Überarbeitung erstellt wurde, oder es gilt für null aktive, unvollständige Überarbeitungen. Wenn Sie alle Datumsangaben seit einschließlich {startDate} wünschen, fügen Sie der Abfrage den folgenden Filter hinzu.

RevisedDateSK eq null or RevisedDateSK gt {startDateSK}

Die folgende Abfrage gibt beispielsweise die Anzahl der Arbeitsaufgaben für jeden Tag seit Anfang 2020 zurück. Beachten Sie, dass neben dem offensichtlichen Filter auf der DateSK-Spalte ein zweiter Filter auf RevisedDateSK aktiviert ist. Obwohl es redundant erscheinen mag, hilft es dem Abfragemodul, Überarbeitungen herauszufiltern, die nicht im Geltungsbereich liegen, und verbessert die Abfrageleistung erheblich.

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)
    )

✔️ Verwenden Sie wöchentliche oder monatliche Momentaufnahmen für Trendabfragen, die einen langen Zeitraum umfassen.

Standardmäßig werden alle Snapshot-Tabellen als tägliche Snapshot-Faktentabellen modelliert. Wenn Sie einen Zeitraum abfragen, wird für jeden Tag ein Wert abgerufen. Lange Zeitbereiche führen zu einer großen Anzahl von Datensätzen. Wenn Sie diese hohe Genauigkeit nicht benötigen, können Sie wöchentliche oder sogar monatliche Momentaufnahmen verwenden.

Sie können dies mit anderen Filterausdrücken tun, um Tage zu entfernen, die eine vorgegebene Woche oder einen Monat nicht abschließen. Verwenden Sie die IsLastDayOfPeriod Eigenschaft, die in Analytics für dieses Szenario hinzugefügt wurde. Diese Eigenschaft ist vom Typ Microsoft.VisualStudio.Services.Analytics.Model.Period und kann feststellen, ob ein Tag in unterschiedlichen Zeiträumen endet, zum Beispiel in Wochen oder Monaten.

<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>

Da Microsoft.VisualStudio.Services.Analytics.Model.Period als enum mit Flags definiert ist, sollten Sie den OData-Operator has verwenden und den vollständigen Typ für die Literale im angegebenen Zeitraum angeben.

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

Die folgende Abfrage gibt beispielsweise eine Anzahl von Arbeitsaufgaben zurück, die am letzten Tag jedes Monats definiert wurden.

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)
    )

✔️ DO Verwenden Tags collection property für Arbeitselemente beim Filtern nach Tags

Sie können die Eigenschaft TagNames mit der Funktion contains verwenden, um zu ermitteln, ob ein Projekt mit einem bestimmten Tag markiert wurde. Dieser Ansatz kann jedoch zu langsamen Abfragen führen, insbesondere bei der gleichzeitigen Suche nach mehreren Tags. Verwenden Sie stattdessen die Tags Navigationseigenschaft, um optimale Leistung und Ergebnisse zu erzielen.

Die folgende Abfrage ruft beispielsweise alle Arbeitsaufgaben ab, die mit einem {tag}Markiert wurden.

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

Dieser Ansatz funktioniert auch hervorragend, wenn Sie nach mehreren Tags filtern müssen. Die folgende Abfrage gibt beispielsweise alle Arbeitsaufgaben zurück, die mit einem bestimmten Tag versehen wurden, der {tag1}oder{tag2} enthält.

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

Sie können diese Filter auch mit einem Operator "und" kombinieren. Die folgende Abfrage ruft beispielsweise alle Arbeitselemente ab, die mit sowohl {tag1} als auch {tag2} markiert wurden.

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

Verwenden Sie die TagNames-Eigenschaft, wenn Sie alle Tags eines Arbeitselements als Text anzeigen möchten.

Navigationseigenschaft Tags, die im vorherigen Abschnitt beschrieben wird, eignet sich hervorragend zum Filtern. Die Arbeit mit ihnen stellt jedoch einige Herausforderungen dar, da die Abfrage Tags in einer geschachtelten Auflistung zurückgibt. Das Datenmodell enthält auch eine TagNames primitive Eigenschaft (Edm.String), die wir hinzugefügt haben, um Die Verwendungsszenarien für Tags zu vereinfachen. Es ist ein einzelner Textwert, der eine Liste aller Tags enthält, die mit einem Semikolon "; " Trennzeichen kombiniert werden. Verwenden Sie diese Eigenschaft, wenn es Ihnen nur darum geht, Tags gemeinsam anzuzeigen. Sie können sie mit den zuvor beschriebenen Tag-Filtern kombinieren.

Die folgende Abfrage ruft beispielsweise alle Arbeitsaufgaben ab, die mit einem {tag}Markiert wurden. Sie gibt die Arbeitsaufgaben-ID, den Titel, den Status und eine Textdarstellung kombinierter Tags zurück.

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

❌ Verwenden Sie tolower und toupper Funktionen nicht, um vergleichsunempfindlich für Groß-/Kleinschreibung zu sein.

Wenn Sie mit anderen Systemen gearbeitet haben, können Sie erwarten, dass Sie die Funktionen tolower oder toupper für einen vergleich ohne Berücksichtigung der Groß-/Kleinschreibung verwenden. Bei Analytics sind Vergleiche von Zeichenfolgen standardmäßig ohne Berücksichtigung der Groß- und Kleinschreibung, sodass Sie keine Funktionen anwenden müssen, um dies explizit zu behandeln.

Die folgende Abfrage ruft beispielsweise alle Arbeitsaufgaben ab, die mit "QUALITÄT", "Qualität" oder einer anderen Kombination aus diesem Wort markiert sind.

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

❌ VERWENDEN SIE keine ungebundene Erweiterung mit $levels=max

OData verfügt über die Möglichkeit, alle Ebenen einer hierarchischen Struktur zu erweitern. Beispielsweise enthält die Nachverfolgung von Arbeitsaufgaben einige Entitäten, bei denen eine ungebundene Erweiterung angewendet werden kann. Dieser Vorgang funktioniert nur für Organisationen mit einer kleinen Datenmenge. Es skaliert nicht gut für größere Datasets. Verwenden Sie sie überhaupt nicht, wenn:

• Sie arbeiten mit großen Datasets.
• Sie entwickeln ein Widget, und Sie haben keine Kontrolle darüber, wo das Widget installiert wird.

✔️ Verwenden Sie servergesteuertes Paging

Wenn Sie nach einem Satz fragen, der zu groß ist, um in einer einzigen Antwort gesendet zu werden, wendet Analytics Paging an. Die Antwort enthält nur einen Teilsatz und einen Link, der das Abrufen des nächsten Teilsatzes von Elementen ermöglicht. Diese Strategie wird in der OData-Spezifikation – OData Version 4.0 beschrieben. Teil 1: Protokoll - Servergesteuertes Paging. Indem Sie die Steuerung des Pagings von dem Dienst übernehmen lassen, erhalten Sie die beste Leistung, da die skiptoken für jede Entität so effizient wie möglich gestaltet ist.

Der Link zur nächsten Seite ist in der @odata.nextLink Eigenschaft enthalten.

{
  "@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"}

❌ Verwenden Sie $top und $skip Abfrageoptionen nicht zur Implementierung von client-gesteuertem Paging.

Bei anderen REST-APIs haben Sie möglicherweise clientgesteuerte Paging mit $top und $skip Abfrageoptionen implementiert. Verwenden Sie sie nicht mit Analytics. Es gibt mehrere Probleme mit diesem Ansatz, und die Leistung ist eine davon. Übernehmen Sie stattdessen die servergesteuerte Pagingstrategie, die im vorherigen Abschnitt beschrieben wird.

✔️ Verwenden Sie die $top -Abfrageoption, um die Anzahl der Datensätze zu begrenzen.

Von der Verwendung der Abfrageoption $top wird nur abgeraten, wenn sie zusammen mit $skip verwendet wird. Wenn Sie in Ihrem Berichterstellungsszenario nur eine Teilmenge von Datensätzen (z. B. Beispiel) benötigen, ist es in Ordnung, die Abfrageoption zu verwenden $top . Zusätzlich sollten Sie, wenn Sie Datensätze nach bestimmten Kriterien rangieren müssen, immer $top in Kombination mit $orderby verwenden, um ein stabiles Ergebnis mit höchstbewerteten Datensätzen zu erzielen.

✔️ ERWÄGEN SIE, eine Abfrage zu schreiben, um eine kleine Anzahl von Datensätzen zurückzugeben.

Das Schreiben einer Abfrage zur Rückgabe kleiner Datensätze ist die intuitivste Richtlinie. Ziel ist es immer, nur die Daten abzurufen, die Sie wirklich interessieren. Sie können dies erreichen, indem Sie die leistungsstarken Filterfunktionen in der OData-Abfragesprache zur Verfügung stellen.

✔️ ERWÄGEN, die Anzahl der ausgewählten Eigenschaften auf ein Minimum zu beschränken

Einige Projektadministratoren passen ihre Prozesse stark an, indem benutzerdefinierte Felder hinzugefügt werden. Schwere Anpassungen können zu Leistungsproblemen führen, wenn alle verfügbaren Spalten in breiten Entitäten abgerufen werden (z. B WorkItems. ). Analytics basiert auf einer Columnstore-Indextechnologie . Das bedeutet, dass sowohl die Datenspeicherung als auch die Abfrageverarbeitung spaltenbasiert sind. Je mehr Eigenschaften eine Abfrage referenziert, desto teurer ist die Verarbeitung. Zielen Sie immer darauf ab, den Satz von Eigenschaften in Ihren Abfragen auf das zu beschränken, was Sie in Ihrem Berichterstellungsszenario wirklich interessieren.

✔️ Ziehen Sie in Betracht, nach Eigenschaften des Datumsersatzschlüssels (DateSK Suffix) zu filtern

Es gibt viele Möglichkeiten, einen Datumsfilter zu definieren. Sie können direkt nach der Datumseigenschaft (z CreatedDate. B. ), dessen Navigationsentsprechung (z. B CreatedOnDate. ) oder dessen Ersatzschlüsseldarstellung (z CreatedDate. B. ) filtern. Die letzte Option liefert die beste Leistung und wird bevorzugt, wenn die Berichtsanforderungen dies zulassen.

Die folgende Abfrage ruft beispielsweise alle Seit Anfang 2020 erstellten Arbeitsaufgaben ab.

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

✔️ ERWÄGEN SIE das Filtern nach Ersatzschlüsselspalten

Wenn Sie die Daten nach dem Wert eines verknüpften Objekts filtern möchten (z. B. Filtern einer Arbeitsaufgabe für den Projektnamen), stehen Ihnen immer zwei Optionen zur Verfügung. Sie können entweder die Navigationseigenschaft (z. B. Project/ProjectName) verwenden oder den Ersatzschlüssel vorab erfassen und ihn direkt in der Abfrage verwenden (z. B. ProjectSK).

Wenn Sie ein Widget erstellen, empfiehlt es sich, die letztere Option zu verwenden. Wenn der Schlüssel als Teil der Abfrage übergeben wird, wird die Anzahl der Entitätssätze, die berührt werden müssen, reduziert und die Leistung verbessert.

Die folgende Abfrage filtert WorkItems unter Verwendung der ProjectSK-Eigenschaft anstelle der Project/ProjectName-Navigationseigenschaft.

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

❌Vermeiden Sie die Verwendung von Parent, Children oder Revisions Eigenschaften in den $filter oder $expand Klauseln

Arbeitsaufgaben sind die teuersten Entitäten im gesamten Datenmodell. Sie verfügen über mehrere Navigationseigenschaften, mit denen Sie auf verwandte Arbeitsaufgaben zugreifen können: Parent, , Children. Revisions Jedes Mal, wenn Sie sie in einer Abfrage verwenden, erwarten Sie jedoch einen Leistungsrückgang. Stellen Sie sich immer die Frage, ob Sie eine dieser Funktionen wirklich benötigen und Ihr Design eventuell überarbeiten.

Anstatt Parent zu erweitern, können Sie zum Beispiel mehr Arbeitsaufträge abrufen und die ParentWorkItemId-Eigenschaft verwenden, um die vollständige Hierarchie clientseitig zu rekonstruieren. Führen Sie eine solche Optimierung fallweise aus.

✔️ ERWÄGEN SIE, die Präferenz im Header zu übermitteln VSTS.Analytics.MaxSize.

Wenn Sie eine Abfrage ausführen, wissen Sie nicht, wie viele Datensätze die Abfrage zurückgibt. Senden Sie entweder eine andere Abfrage mit Aggregationen, oder folgen Sie allen nächsten Links, und rufen Sie das gesamte Dataset ab. Analytics berücksichtigt VSTS.Analytics.MaxSize Präferenzen, die es Ihnen ermöglichen, in solchen Fällen schnell zu reagieren, in denen das Dataset größer ist, als Ihr Client akzeptieren kann.

Diese Option ist in Datenexportszenarien hilfreich. Um es zu verwenden, müssen Sie Prefer als Kopfzeile zu Ihrer HTTP-Anforderung hinzufügen und VSTS.Analytics.MaxSize auf einen nicht-negativen Wert setzen. Der VSTS.Analytics.MaxSize Wert stellt die maximale Anzahl von Datensätzen dar, die Sie akzeptieren können. Wenn Sie ihn auf Null festlegen, wird ein Standardwert von 200 K verwendet.

Die folgende Abfrage gibt beispielsweise Arbeitsaufgaben zurück, wenn das Dataset kleiner oder gleich 1000 Datensätze ist.

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}

Wenn das Dataset den Grenzwert von 1000 Datensätzen überschreitet, schlägt die Abfrage sofort mit dem folgenden Fehler fehl.

Das Abfrageergebnis enthält 1.296 Zeilen und überschreitet die maximal zulässige Größe von 1000. Verringern der Anzahl von Datensätzen durch Anwenden zusätzlicher Filter

Informationen zum Festlegen der maximalen Seitengröße finden Sie unter ODataPreferenceHeader.MaxPageSize-Eigenschaft.

Richtlinien für Abfragestil

• ✔️ DO verwenden $count virtuelle Eigenschaft in den Aggregationsmethoden
• ❌ VERMEIDEN der Verwendung $count virtueller Eigenschaften im URL-Segment
• ❌ VERMEIDEN von Misch- $apply und $filter Klauseln in einer einzelnen Abfrage
• ✔️ ERWÄGEN SIE die Verwendung von Parameteraliasen, um veränderliche Teile der Abfrage zu trennen
• ✔️ ERWÄGEN SIE, Ihre Abfrage so zu strukturieren, dass sie der OData-Auswertungsreihenfolge entspricht.
• ✔️ ERWÄGEN SIE, OData-Funktionen zu überprüfen, die in den Metadatenanmerkungen beschrieben sind.

✔️ DO verwenden $count virtuelle Eigenschaft in den Aggregationsmethoden

Einige Entitäten machen die Count Eigenschaft verfügbar. Sie vereinfachen einige Berichterstellungsszenarien, wenn die Daten in einen anderen Speicher exportiert werden. Sie sollten diese Spalten jedoch nicht in Aggregationen in OData-Abfragen verwenden. Verwenden Sie stattdessen die $count virtuelle Eigenschaft.

Die folgende Abfrage gibt beispielsweise die Gesamtanzahl der Arbeitsaufgaben zurück.

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

❌ VERMEIDEN der Verwendung $count virtueller Eigenschaften im URL-Segment

Obwohl der OData-Standard die Verwendung der $count-virtuellen Eigenschaft für Entitätssätze (z. B. _odata/v1.0/WorkItems/$count) ermöglicht, können nicht alle Clients die Antwort richtig interpretieren. Daher empfiehlt es sich, stattdessen Aggregationen zu verwenden.

Die folgende Abfrage gibt beispielsweise die Gesamtanzahl der Arbeitsaufgaben zurück.

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

✔️ ERWÄGEN SIE die Verwendung von Parameteraliasen, um veränderliche Teile der Abfrage zu trennen

Parameteraliasen bieten eine elegante Lösung, um veränderliche Teile wie Parameterwerte aus dem Hauptabfragetext zu extrahieren. Sie können sie in Ausdrücken verwenden, die folgendes auswerten:

• Primitiver Wert
• Ein komplexer Wert
• Eine Auflistung von primitiven oder komplexen Werten.

Weitere Informationen finden Sie unter OData Version 4.0. Teil 2: URL-Konventionen - 5.1.1.13 Parameteraliasen. Parameter sind nützlich, wenn der Abfragetext als Vorlage verwendet wird, die mit vom Benutzer angegebenen Werten instanziiert werden kann.

Die folgende Abfrage verwendet beispielsweise den @createdDateSK Parameter, um den Wert vom Filterausdruck zu trennen.

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

❌ Vermeiden Sie die Mischung von $apply- und $filter-Klauseln in einer einzelnen Abfrage

Wenn Sie Ihrer Abfrage hinzufügen filter möchten, haben Sie zwei Optionen. Sie können dies entweder mit der $filter Klausel oder der $apply=filter() Kombination tun. Jede dieser Optionen eignet sich hervorragend, aber die Kombination dieser Optionen kann zu unerwarteten Ergebnissen führen.

Trotz der Erwartung, die man haben könnte, definiert OData eindeutig eine Reihenfolge der Auswertung. Außerdem hat die $apply Klausel Vorrang vor $filter. Aus diesem Grund sollten Sie eine oder eine andere auswählen, aber vermeiden Sie diese beiden Filteroptionen in einer einzelnen Abfrage. Es ist wichtig, wenn die Abfragen automatisch generiert werden.

Die folgende Abfrage filtert z. B. zuerst Arbeitsaufgaben nach StoryPoint gt 5, aggregiert Ergebnisse nach Pfad und filtert schließlich das Ergebnis nach StoryPoints gt 2. Mit dieser Auswertungsreihenfolge gibt die Abfrage immer einen leeren Satz zurück.

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)
    )

✔️ ERWÄGEN SIE, Ihre Abfrage so zu strukturieren, dass sie der OData-Auswertungsreihenfolge entspricht.

Da das Mischen $apply und filter Klauseln in einer einzelnen Abfrage zu potenziellen Verwirrungen führen kann, empfehlen wir Ihnen, Die Abfrageklauseln so zu strukturieren, dass sie der Auswertungsreihenfolge entsprechen.

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

✔️ ERWÄGEN SIE, OData-Funktionen zu überprüfen, die in den Metadatenanmerkungen beschrieben sind.

Wenn Sie nicht sicher sind, welche OData-Funktionen Analytics unterstützt, können Sie Anmerkungen in den Metadaten nachschlagen. Der Technische Ausschuss OASIS Open Data Protocol (OData) führt in einem TC GitHub Repository eine Liste der verfügbaren Anmerkungen.

Beispielsweise ist die Liste der unterstützten Filterfunktionen in Org.OData.Capabilities.V1.FilterFunctions Anmerkung für den Entitätscontainer verfügbar.

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

Eine weitere nützliche Anmerkung ist Org.OData.Capabilities.V1.ExpandRestrictions, in der erläutert wird, welche Navigationseigenschaften in der $expand Klausel nicht verwendet werden können. In der folgenden Anmerkung wird beispielsweise erläutert, dass der WorkItems Entitätssatz Revisions nicht erweitert werden kann.

<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>

Verwandte Inhalte

• Erstellen von OData-Abfragen für Analytics
• Abfragen von Nachverfolgungsdaten für Arbeitsaufgaben
• Aggregatdaten
• Abfragetrenddaten
• Abfrage von Arbeitselementverknüpfungen
• Unterstützte Funktionen und Klauseln
• Einschränkungen für Arbeitsnachverfolgung, Prozesse und Projekte