Freigeben über

OData Analytics-Abfragerichtlinien für Azure DevOps

  • Artikel

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

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.

Hinweis

Der Analysedienst wird automatisch aktiviert und in der Produktion für alle Azure DevOps-Dienste unterstützt. Power BI-Integration und Zugriff auf den OData-Feed des Analytics-Diensts sind allgemein verfügbar. Wir empfehlen Ihnen, sie zu verwenden und uns Feedback zu geben. Verfügbare Daten sind versionsabhängig. Die neueste unterstützte Version ist v2.0, und die neueste Vorschauversion ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Hinweis

Der Analysedienst wird automatisch installiert und in der Produktion für alle neuen Projektsammlungen für Azure DevOps Server 2020 und höhere Versionen unterstützt. Power BI-Integration und Zugriff auf den OData-Feed des Analytics-Diensts sind allgemein verfügbar. Wir empfehlen Ihnen, sie zu verwenden und uns Feedback zu geben. Wenn Sie ein Upgrade von Azure DevOps Server 2019 durchgeführt haben, können Sie den Analysedienst während des Upgrades installieren.

Verfügbare Daten sind versionsabhängig. Die neueste unterstützte Version ist v2.0, und die neueste Vorschauversion ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

Hinweis

Der Analysedienst befindet sich in der Vorschau für Azure DevOps Server 2019. Sie können es für eine Projektsammlung aktivieren oder installieren. Die Power BI-Integration und der Zugriff auf den OData-Feed des Analytics-Diensts befinden sich in der Vorschau. Wir empfehlen Ihnen, sie zu verwenden und uns Feedback zu geben.

Verfügbare Daten sind versionsabhängig. Die neueste unterstützte Version ist v2.0, und die neueste Vorschauversion ist v4.0-preview. Weitere Informationen finden Sie unter OData-API-Versionsverwaltung.

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.

Tipp

Die in diesem Dokument gezeigten Beispiele basieren auf einer Azure DevOps Services-URL. Verwenden Sie Ersetzungen für lokale Versionen.

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

Fehler und Warnmeldungen

✔️ OData-Antwortwarnungen überprüfen

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). Zuordnen von Nachrichten werden nicht innerhalb der @vsts.warnings Eigenschaft angezeigt. Stattdessen generieren sie eine Fehlermeldung in der Eigenschaft in der message 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

Storm oder Flink

Blockiert

Vermeiden

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

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 Ihre Ansichtsanalyseberechtigung 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 dem Namen und {projectSK2}dem Namen {projectSK1} 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 verschieben, um die Option zum Erweitern in der $expand Klausel zu $filter erweitern. 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 Erweiterungssammlungseigenschaft verwenden, z Children . B. im WorkItems Entitätssatz. Die folgende Abfrage gibt beispielsweise alle Arbeitsaufgaben aus einem bestimmten Projekt zusammen mit allen untergeordneten Elementen 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 die Abfrage mithilfe des endpunktbereichsbezogenen Projekts

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.

✔️ DO-Warten oder Beenden des Vorgangs, wenn Ihre Abfrage die Nutzungsgrenzwerte überschreitet

Wenn Sie viele Abfragen ausführen oder für die Abfragen viele Ressourcen ausgeführt werden müssen, überschreiten Sie möglicherweise Dienstgrenzwerte und werden vorübergehend blockiert. 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.

✔️ Do wait or stop the operation if your query fails with a timeout

Ä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 bitte 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. einen einzelnen WorkItemIdabfragen WorkItemSnapshot und filtern, erhalten Sie einen Datensatz für jeden Tag, da 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.

Die folgende Abfrage ruft beispielsweise die Anzahl der Arbeitsaufgaben ab, um zu beobachten, wie sie im Januar 2020 zunahm.

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

✔️ Do include DateSK or DateValue column in groupby clause when you aggregate over snapshot tables

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 AssignedTo Eigenschaft gruppiert WorkItemSnapshot und mit der Anzahl aggregiert haben, werden alle Arbeitsaufgaben, die Personen zugewiesen sind, mit der Anzahl der Tage multipliziert, in 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.

✔️ Do explizit adressiert 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 eine einzelne Arbeitsaufgabe anhand des Bezeichners 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 WorkItemId sind sie Revision Schlüsselspalten für die WorkItemRevision Entität.

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

❌ [BLOCKIERT] KEINE Erweiterung Revisions der WorkItem Entität

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 eingerichtet, um jeden zu ermutigen, die empfohlene Lösung zu verwenden, die Überarbeitungen abruft, WorkItemRevisions wie im folgenden Abschnitt erläutert.

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

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 gruppieren in unterschiedlichen Spalten

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 unterschiedliche 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 eine Aggregationsabfrage probleme mit arithmetischem Überlauf auftreten. Beispielsweise kann es passieren, wenn Sie einige numerische Eigenschaften addieren, die nicht für die Summe vorgesehen sind, z StackRank . B. in den Arbeitsaufgabenentitä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 des Batchendpunkts 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 Batchendpunkt zum Senden mehrerer Abfragen.

Wir beschränken die Verwendung des Batchendpunkts auf die Behandlung eines Batches mehrerer Anforderungen. 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, um POST-Anforderungen zu unterstützen, 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 selektiv genug sind, in denen 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 hinzu, und $expand Vorgängen in Ihrer Abfrage, um eine Überschreitung dieses Grenzwerts zu vermeiden.

❌ VERMEIDEN sie das Erstellen langer Abfragen

Es wird empfohlen, ihren Ansatz immer dann auszuwerten, wenn 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:mm-hh:mm (ISO 8601-Standarddarstellung von Datums- und Uhrzeitangaben) anzugeben, 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 (mit einem + Zeichen) als Ausgangspunkt angeben 2020-01-01T00:00:00+08:00 , wird der folgende Fehler angezeigt.

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

Nicht

Storm oder Flink

Vermeiden

✔️ 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 von 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".

✔️ DO-Angabe von Spalten in der $select Klausel

Geben Sie die Spalten an, die Sie in der $select Klausel interessieren. Analytics basiert auf einer Columnstore-Indextechnologie . Das bedeutet, dass Daten sowohl Speicher als auch Abfrageverarbeitung spaltenbasiert sind. Indem Sie den Satz von Eigenschaften reduzieren, verweisen Sie in $select Klauseln darauf, um die Anzahl der Spalten zu reduzieren, die gescannt werden müssen, und die Gesamtleistung der Abfrage zu 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

Hinweis

Azure DevOps unterstützt Prozessanpassungen. Einige Administratoren verwenden dieses Feature und erstellen Hunderte von benutzerdefinierten Feldern. Wenn Sie die $select Klausel weglassen, gibt Ihre Abfrage alle Felder einschließlich benutzerdefinierter Felder zurück.

✔️ DO-Angabe von Spalten in der Erweiterungsoption $select innerhalb der $expand Klausel

Ä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 gibt beispielsweise die Spalten für die Arbeitsaufgabe und das übergeordnete Element an.

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

✔️ DEFINIEREN SIE einen Filter 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 Arbeitsaufgabenentitäten gibt es eine bequeme Möglichkeit, um solche Abfragen zu schreiben, um eine hervorragende Leistung zu erzielen. Jedes Mal, wenn Sie eine Arbeitsaufgabe aktualisieren, wird eine neue Überarbeitung erstellt und diese Aktion im System.RevisedDate Feld aufgezeichnet, wodurch sie perfekt für Verlaufsfilter geeignet ist.

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. Es ist der Datums-Ersatzschlüssel und stellt das Datum dar, an dem eine Überarbeitung erstellt wurde oder für null aktive, unvollständige Überarbeitungen verfügt. Wenn Sie alle Datumsangaben seit dem Inklusiven {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 für DateSK Die Spalte ein zweiter Filter aktiviert RevisedDateSKist. Obwohl es redundant erscheinen mag, hilft es dem Abfragemodul, Überarbeitungen herauszufiltern, die sich nicht im Bereich befinden, 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)
    )

Hinweis

Wir haben diese Empfehlung erhalten, als wir an Burndown-Widgets gearbeitet haben. Zunächst haben wir Filter nur für DateSK diese Abfrage definiert, aber wir konnten diese Abfrage nicht abrufen, um für Organisationen mit großen Datasets gut zu skalieren. Während der Abfrageprofilerstellung haben wir festgestellt, dass DateSK Überarbeitungen nicht gut gefiltert werden. Erst nachdem wir einen Filter RevisedDateSK hinzugefügt haben, konnten wir große Leistung im großen Maßstab erzielen.
~ Produktteam

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

Standardmäßig werden alle Momentaufnahmetabellen als tägliche 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 keine bestimmte Woche oder einen bestimmten Monat beenden. Verwenden Sie die IsLastDayOfPeriod Eigenschaft, die analytics mit diesem Szenario hinzugefügt wurde. Diese Eigenschaft ist vom Typ und Microsoft.VisualStudio.Services.Analytics.Model.Period kann bestimmen, ob ein Tag in verschiedenen Zeiträumen endet (z. B. Wochen, Monate usw.).

<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 Enumeration mit Flags definiert ist, verwenden Sie den OData-Operator has , und geben Sie den vollständigen Typ für die Periodenliterale an.

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 use Tags collection property on work items when filtering by tags

Sie können die Eigenschaft mit der TagNames contains Funktion verwenden, um zu ermitteln, ob eine Arbeit 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 {tag1} oder {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

Sie können diese Filter auch mit einem Operator "und" kombinieren. Die folgende Abfrage ruft beispielsweise alle Arbeitsaufgaben ab, die mit beiden {tag1} und {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

✔️ Do use TagNames property if you want to display all the tags on a work item as text

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 Tags zusammen angezeigt werden. Sie können sie mit den zuvor beschriebenen Kategorienfiltern 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

Wichtig

Eigenschaft TagNames hat eine Längenbeschränkung von 1024 Zeichen. Sie enthält eine Reihe von Tags, die in diesen Grenzwert passen. Wenn eine Arbeitsaufgabe viele Tags enthält oder die Tags sehr lang sind, sollten Sie stattdessen TagNames nicht den vollständigen Satz Tag und die Navigationseigenschaft verwenden.

❌ Verwenden tolower Und Funktionen nicht verwenden und toupper verwenden, um den Vergleich zwischen Groß-/Kleinschreibung zu vermeiden

Wenn Sie mit anderen Systemen gearbeitet haben, können Sie davon ausgehen tolower toupper , dass die Groß-/Kleinschreibung nicht beachtet wird. Bei Analytics werden alle Zeichenfolgenvergleiche standardmäßig ohne Groß-/Kleinschreibung unterschieden, sodass Sie keine Funktionen anwenden müssen, um sie 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. Die Skalierung eignet sich 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.

✔️ Do use server-driven 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. Durch die Steuerung des Pagings durch den Dienst erhalten Sie die beste Leistung, da die skiptoken einzelnen Entitäten so effizient wie möglich gestaltet wurden.

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

Hinweis

Die meisten vorhandenen OData-Clients können die servergesteuerte Paging automatisch verarbeiten. Diese Strategie wird beispielsweise bereits von den folgenden Tools verwendet: Power BI, SQL Server Integration Services und Azure Data Factory.

❌ VERWENDEN $top und $skip Abfrageoptionen nicht zum Implementieren von clientgesteuerten 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.

✔️ Do use $top query option to limit the number of records

Die Abfrageoption $top wird nur abgeraten, wenn sie zusammen mit $skip. 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 . Wenn Sie Datensätze nach einigen Kriterien rangieren müssen, sollten Sie immer in Kombination mit $orderby dem stabilen Ergebnis mit top bewerteten Datensätzen verwenden$top.

✔️ 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 Daten sowohl Speicher als auch 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 Datumszusatzschlüsseleigenschaften zu filtern (DateSK Suffix)

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 Project/ProjectName. B. ) verwenden oder den Ersatzschlüssel im Vorfeld erfassen und 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 folgenden Abfragefilter verwenden WorkItems ProjectSK z. B. die Eigenschaft anstelle Project/ProjectName der Navigationseigenschaft.

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

❌VERMEIDEN der Verwendung von ParentEigenschaften Childrenoder Revisions Eigenschaften in den $filter Oder-Klauseln $expand

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 immer frage, ob Sie eine dieser Eigenschaften wirklich benötigen und ihr Design möglicherweise aktualisieren.

Statt beispielsweise zu erweitern Parent, können Sie mehr Arbeitsaufgaben abrufen und die Eigenschaft verwenden ParentWorkItemId , um die clientseitige vollständige Hierarchie zu rekonstruieren. Führen Sie eine solche Optimierung fallweise aus.

✔️ ERWÄGEN SIE, die Einstellung in der Kopfzeile zu übergeben 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. Die Analyse berücksichtigt VSTS.Analytics.MaxSize einstellungen, sodass Sie in diesen Instanzen, die das Dataset akzeptieren können, schnell fehlschlagen können.

Diese Option ist in Datenexportszenarien hilfreich. Um sie zu verwenden, müssen Sie ihrer HTTP-Anforderung Kopfzeile hinzufügen Prefer und auf einen nicht negativen Wert festlegen VSTS.Analytics.MaxSize . 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 Sie die Anzahl der Datensätze, indem Sie zusätzliche Filter anwenden.

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

Richtlinien für Die Abfrageformatvorlage

✔️ DO verwenden $count virtuelle Eigenschaft in den Aggregationsmethoden

Einige Entitäten machen die Eigenschaft verfügbar Count . 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 $count der virtuellen Eigenschaft für Entitätssätze (z _odata/v1.0/WorkItems/$count. B. ) 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:

  • Grundtypwert
  • 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 @createdDateSK beispielsweise 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 von Misch- $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) in einem TC GitHub Repository unterhält 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 Revisions der WorkItems Entitätssatz 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>