Megosztás a következőn keresztül:

OData Analytics-lekérdezési irányelvek az Azure DevOpshoz

  • Cikk

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

A bővítményfejlesztők az ebben a cikkben ismertetett irányelveket követve hatékony OData-lekérdezéseket tervezhetnek az Azure DevOps-hoz készült Analytics használatával. Az irányelvek követésével biztosítható, hogy a lekérdezések megfelelő teljesítménnyel rendelkezzenek a végrehajtási idő és az erőforrás-felhasználás szempontjából. Az irányelveknek nem megfelelő lekérdezések gyenge teljesítményt eredményezhetnek, hosszú jelentésmegadási idő, engedélyezett erőforrás-felhasználást meghaladó lekérdezések vagy szolgáltatásblokkolások esetén.

Feljegyzés

Az Elemzési szolgáltatás automatikusan engedélyezve és támogatva van az összes Azure DevOps Services esetében az éles környezetben. Az Elemzési szolgáltatás OData-hírcsatornájának Power BI-integrációja és hozzáférése általánosan elérhető. Javasoljuk, hogy használja és küldjön nekünk visszajelzést. A rendelkezésre álló adatok verziófüggők. A legújabb támogatott verzióv2.0, és a legújabb előzetes verzió.v4.0-preview További információ: OData API-verziószámozás.

Feljegyzés

Az Analytics szolgáltatás automatikusan települ és támogatott éles környezetben az Azure DevOps Server 2020 és újabb verziók összes új projektgyűjteményéhez. Az Elemzési szolgáltatás OData-hírcsatornájának Power BI-integrációja és hozzáférése általánosan elérhető. Javasoljuk, hogy használja és küldjön nekünk visszajelzést. Ha az Azure DevOps Server 2019-ről frissített, a frissítés során telepítheti az Analytics szolgáltatást.

A rendelkezésre álló adatok verziófüggők. A legújabb támogatott verzióv2.0, és a legújabb előzetes verzió.v4.0-preview További információ: OData API-verziószámozás.

Feljegyzés

Az Analytics szolgáltatás előzetes verzióban érhető el az Azure DevOps Server 2019-hez. Engedélyezheti vagy telepítheti egy projektgyűjteményhez. Az Elemzési szolgáltatás OData-hírcsatornájának Power BI-integrációja és elérése előzetes verzióban érhető el. Javasoljuk, hogy használja és küldjön nekünk visszajelzést.

A rendelkezésre álló adatok verziófüggők. A legújabb támogatott verzióv2.0, és a legújabb előzetes verzió.v4.0-preview További információ: OData API-verziószámozás.

Ezek az irányelvek a DO, a CONSIDER, a AVOID és a DON't kifejezéssel előtaggal ellátott javaslatok. Az Analytics által kikényszerített korlátozó szabályok tartalmazzák a [BLOCKED] előtagot. Tisztában kell lennie a különböző megoldások közötti kompromisszumokkal. Bizonyos körülmények között előfordulhat, hogy olyan adatkövetelményekkel rendelkezik, amelyek egy vagy több irányelv megsértésére kényszerítik. Az ilyen eseteknek ritkanak kell lenniük. Javasoljuk, hogy egyértelmű és meggyőző indoka legyen az ilyen döntésekre.

Tipp.

A dokumentumban látható példák az Azure DevOps Services URL-címén alapulnak. Helyettesítések használata a helyszíni verziókhoz.

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

Hibaüzenetek és figyelmeztető üzenetek

✔️ Do review OData response warnings

A rendszer minden végrehajtott lekérdezést előre meghatározott szabályok alapján ellenőriz. A szabálysértések a következő @vsts.warningsOData-választ adják vissza. Tekintse át ezeket a figyelmeztetéseket, mivel aktuális és környezetfüggő információkat nyújtanak a lekérdezés javításáról.

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

✔️ Do review OData hibaüzenetek

Az OData-hibaszabályt sértő lekérdezések 400 -os (hibás kérelem) állapotkóddal rendelkező sikertelen választ eredményeznek. A társított üzenetek nem jelennek meg a tulajdonságban @vsts.warnings . Ehelyett hibaüzenetet hoznak létre a message tulajdonságban a JSON-válaszban.

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

Korlátozások

Do's

Tekint

Blokkolva

Elkerülés

✔️ A DO a lekérdezést arra a projektre korlátozza, amelyhez hozzáféréssel rendelkezik

Ha a lekérdezés olyan projekt adatait célozza meg, amelyhez nincs hozzáférése, a lekérdezés egy "Project access denied" üzenetet ad vissza. A hozzáférés biztosításához győződjön meg arról, hogy a Nézetelemzési engedély engedélyezve van az összes lekérdezett projekt esetében. További információ: Az Elemzés eléréséhez szükséges engedélyek.

Ha nincs hozzáférése egy projekthez, a következő üzenet jelenik meg:

A lekérdezés eredményei egy vagy több olyan projekt adatait tartalmazzák, amelyekhez nincs hozzáférése. Adjon hozzá egy vagy több projektszűrőt a "WorkItems" entitásban elérhető projekt(ek) megadásához. Ha $expand vagy navigációs tulajdonságokat használ, ezekhez az entitásokhoz projektszűrő szükséges.

A probléma megoldásához explicit módon hozzáadhat egy projektszűrőt, vagy használhatja a projekt hatókörű végpontot a cikk későbbi részében ismertetett módon.

Az alábbi lekérdezés például lekéri a nevesített és {projectSK2}a nevesített {projectSK1} projektekhez tartozó munkaelemeket.

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

✔️ DO adja meg a projektszűrőt a $expand záradékon belül, ha a bővítés más, potenciálisan elérhetetlen projektekben is tartalmazhat adatokat

A navigációs tulajdonságok kibontásakor előfordulhat, hogy más, elérhetetlen projektek adataira hivatkozik. Ha elérhetetlen adatokra hivatkozik, ugyanazt a korábban felsorolt hibaüzenetet kapja: "A lekérdezés eredményei egy vagy több projekt adatait tartalmazzák...". Hasonlóképpen megoldhatja ezt a problémát úgy is, hogy explicit projektszűrőket ad hozzá a kibontott adatok szabályozásához.

Ezt az egyszerű navigációs tulajdonságok normál $filter záradékában teheti meg. Az alábbi lekérdezés például kifejezetten azt kéri WorkItemLinks , hogy a hivatkozás és a cél is hol található ugyanabban a projektben.

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)

Ehelyett áthelyezheti a szűrőt a záradék kibontásához $filter $expand . Ez azonban megváltoztatja a lekérdezés szemantikai változását. Az alábbi lekérdezés például lekéri az összes hivatkozást egy adott projektből, és csak akkor bontja ki feltételesen a célt, ha ugyanabban a projektben található. Bár érvényes, ez a megközelítés zavart okozhat, mivel nehéz lehet megállapítani, hogy egy tulajdonság nem bontható-e ki, null mert az vagy azért van, mert szűrték. Ezt a megoldást csak akkor használja, ha valóban szüksége van erre a viselkedésre.

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)

A $filter kibontás lehetőség akkor hasznos, ha a kibontott gyűjtemény tulajdonságot használja, például Children az entitáskészletben WorkItems . Az alábbi lekérdezés például egy adott projekt összes munkaelemét visszaadja az összes gyermekével együtt, akik ugyanabba a projektbe tartoznak.

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)

Adja meg a szűrőt, ha az alábbi tulajdonságok egyikét bontja ki:

  • WorkItems entitáskészlet: Parent, Children
  • WorkItemLinks entitáskészlet: TargetWorkItem.

✔️ FONTOLJA meg a lekérdezést a projekt hatókörű végpont használatával

Ha egyetlen projekt adatai érdeklik, javasoljuk, hogy használja a projekt hatókörű OData-végpontját (/{ProjectName}/_odata/v1.0). Elkerüli az előző két szakaszban ismertetett problémákat, és implicit módon szűri az adatokat egy projektre, a hivatkozott entitáskészletre és az összes kibontott navigációs tulajdonságra.

Ezzel az egyszerűsítéssel az előző szakasz lekérdezései átírhatók az alábbi űrlapra. A kibontási záradékban lévő szűrő nemcsak eltűnt, de a fő entitáskészleten sincs szükség a szűrőre.

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

A gyermek munkaelem lekérdezése is sokkal rövidebb és egyszerűbb.

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

Ezt a megoldást csak akkor alkalmazhatja, ha a fókusz egyetlen projekt adataira összpontosít. Projektközi jelentéskészítéshez az előző szakaszokban ismertetett szűrési stratégiákat kell használnia.

✔️ DO várjon vagy állítsa le a műveletet, ha a lekérdezés túllépi a használati korlátokat

Ha sok lekérdezést hajt végre, vagy a lekérdezések futtatásához sok erőforrásra van szükség, előfordulhat, hogy túllépi a szolgáltatási korlátokat, és ideiglenesen le lesz tiltva. Ha túllépi a szolgáltatási korlátokat, állítsa le a műveletet, mert valószínű, hogy a következő elküldött lekérdezés ugyanazzal a hibaüzenettel meghiúsul.

A kérés a(z) "{resource}" erőforrás {namespace} névtérben való használatának túllépése miatt lett letiltva.

A sebességkorlátozásról további információt a Sebességkorlátok című témakörben talál. Ha szeretné megtudni, hogyan tervezhet hatékony OData-lekérdezéseket, tekintse meg a cikk későbbi, teljesítményre vonatkozó irányelveit .

✔️ DO várakozás vagy a művelet leállítása, ha a lekérdezés időtúllépéssel meghiúsul

A használati korlátok túllépéséhez hasonlóan várnia kell vagy le kell állítania a műveletet, ha a lekérdezés időtúllépésen megy keresztül. Átmeneti problémát jelezhet, ezért újrapróbálkozhat egyszer, hogy kiderüljön, megoldódott-e a probléma. Az állandó időtúllépések azonban azt jelzik, hogy a lekérdezés futtatása valószínűleg túl költséges. A további újrapróbálkozások csak a használati korlátok túllépése miatt lesznek letiltva.

TF400733: A kérés megszakadt: A kérés túllépte a kérelem időtúllépését, próbálkozzon újra.

Az időtúllépések azt jelzik, hogy a lekérdezések optimalizálást igényelnek. A hatékony OData-lekérdezések tervezéséről a cikk későbbi, teljesítményre vonatkozó irányelveiből tájékozódhat.

❌ [LETILTVA] NE használjon pillanatkép-entitásokat más összesítésekhez

Az utótaggal rendelkező Snapshot pillanatkép-entitáskészletek azért különlegesek, mert napi pillanatképekként vannak modellelve. Az entitások állapotának lekéréséhez használhatja őket, ahogy azok a múltban minden nap végén voltak. Ha például egyetlenre WorkItemIdkérdez le WorkItemSnapshot és szűr, akkor a munkaelem létrehozása óta minden nap egy rekordot kap. Az adatok közvetlen betöltése költséges lenne, és valószínűleg túllépné a használati korlátokat, és blokkolva lenne. Az ezen entitásokon lévő összesítések azonban engedélyezettek és ajánlottak is. Valójában a pillanatkép-entitáskészleteket az összesítési forgatókönyvek szem előtt tartásával tervezték.

Az alábbi lekérdezés például dátum szerint lekéri a munkaelemek számát, hogy megfigyelje, hogyan nőtt 2020 januárjában.

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

Az aggregációkról további információt az Adatok összesítése című témakörben talál.

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

Mivel az összes pillanatkép-entitás napi pillanatképtáblákként van modellezve, a csoportosítási záradékban mindig szerepelnie kell a napi tulajdonságok egyikének (DateSK vagy DateValue) a csoportosítási záradékban. Ellenkező esetben előfordulhat, hogy az eredmény helytelenül felfújva jelenik meg.

Ha például csak tulajdonság szerint AssignedTo csoportosítja WorkItemSnapshot és összesíti a számmal, a személyekhez rendelt munkaelemek száma megszorozódik az egyes hozzárendelések aktív napjainak számával. Bár előfordulhat, hogy ez a kívánt eredmény, az ilyen esetek ritkán fordulnak elő.

❌ [LETILTVA] NE használjon entitáskulcsokat az erőforrás-útvonalakban az entitáscímzéshez

Az OData szintaxis lehetővé teszi egy adott entitás elérését úgy, hogy a kulcsait közvetlenül az URL-szegmensekbe foglalja. További információ: OData 4.0-s verzió. 2. rész: URL-konvenciók – 4.3 Entitások kezelése. Bár az OData lehetővé teszi az ilyen címzést, az Analytics letiltja azt. A lekérdezésbe való belefoglalás a következő hibát eredményezi.

Az URI-ban megadott lekérdezés érvénytelen. Az Elemzés nem támogatja a kulcs- vagy tulajdonságnavigációt, például a WorkItems(Id) vagy a WorkItem(Id)/AssignedTo. Ha ezt a hibát a PowerBI-ban kapja, írja át a lekérdezést, hogy elkerülje az N+1 problémát okozó helytelen összecsukást.

Ahogy a hibaüzenetek jelzik, bizonyos ügyféleszközök visszaélhetnek a közvetlen entitások címzésével. Ahelyett, hogy az összes adatot egyetlen kérelembe töltené be, az ilyen ügyfelek dönthetnek úgy, hogy egymástól függetlenül kérdezik le az egyes entitásokat. Ez a gyakorlat nem ajánlott, mivel sok kérést eredményezhet. Ehelyett azt javasoljuk, hogy az alábbi szakaszban ismertetett módon használjon explicit entitáscímzést.

✔️ DO explicit módon kezeli az entitásokat szűrési záradékokkal

Ha egyetlen entitás adatait szeretné lekérni, ugyanazt a megközelítést kell használnia, mint az entitások gyűjteményéhez, és explicit módon definiálnia kell a szűrőket a $filter záradékban.

Az alábbi lekérdezés például egyetlen munkaelemet kér le az azonosítója alapján.

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

Ha nem biztos abban, hogy milyen tulajdonságokat kell tartalmaznia egy ilyen szűrőnek, megkeresheti azt a metaadatokban. Lásd: OData-lekérdezések összeállítása az Analyticshez, URL-összetevők a metaadatok lekérdezéséhez. A tulajdonságok a Key EntityType. Például az WorkItemId Revision entitás kulcsoszlopai WorkItemRevision .

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

❌[LETILTVA] NE bontsa ki Revisions az entitást WorkItem

Az Analytics-adatmodell nem engedélyezi bizonyos típusú bővítéseket. Az egyik, ami néhány számára meglepő lehet, az Revisions entitás gyűjteménytulajdonsága WorkItem . Ha megpróbálja kibontani ezt a tulajdonságot, a következő hibaüzenet jelenik meg.

Az URI-ban megadott lekérdezés érvénytelen. A "Változatok" tulajdonság nem használható a $expand lekérdezési beállításban.

Ez a korlátozás azért lett érvényben, hogy mindenkit arra ösztönözzön, hogy használja az ajánlott megoldást, amely lekéri a változatokat WorkItemRevisions a következő szakaszban ismertetett módon.

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

Minden alkalommal használja WorkItemRevisions , amikor le szeretné kérni egy munkaelem vagy munkaelemgyűjtemény teljes előzményeit.

Az alábbi lekérdezés például egy munkaelem összes változatát visszaadja az {id} azonosítóval.

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

Ha érdekli az összes olyan munkaelem teljes előzménye, amely megfelel bizonyos feltételeknek, fejezze ki a WorkItem navigációs tulajdonság szűrőjének használatával. Az alábbi lekérdezés például lekéri az összes jelenleg aktív munkaelem korrektúráit.

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

❌ [LETILTVA] DON't group on distinct columns

Csoportosítási művelettel csökkentheti a rekordok számát. A záradék eltérő groupby oszlopainak használata problémát jelez, és a lekérdezés azonnal meghiúsul. Ha véletlenül belefut ebbe a helyzetbe, a következő hibaüzenet jelenik meg.

A lekérdezés groupby záradékában megadott egy vagy több oszlop nem ajánlott.

A probléma megoldásához távolítsa el az eltérő oszlopot a groupby záradékból.

❌ [LETILTVA] NE használjon countdistinct összesítést

Az Elemzés nem támogatja a függvényt, annak ellenére, hogy az countdistinct OData igen. Bár azt tervezzük, hogy a jövőben támogatást adunk hozzá, ez jelenleg nem érhető el. A függvényt tartalmazó lekérdezés a következő hibaüzenetet adja vissza.

Az összesítéssel eltérő darabszámot alkalmazó lekérdezések nem támogatottak.

❌ KERÜLJE az aggregációkat, amelyek aritmetikai túlcsordulást eredményezhetnek

Ritkán az aggregációs lekérdezések aritmetikai túlcsordulással kapcsolatos problémákba ütközhetnek. Ez például akkor fordulhat elő, ha olyan numerikus tulajdonságokat ad össze, amelyek nem összegzésre szolgálnak, például StackRank a munkaelem-entitásokban. Mivel az adatösszesítési szabvány OData-bővítménye nem biztosít módot arra, hogy egy tulajdonságot más típusúra alakítson, a probléma megoldásának egyetlen módja az, ha eltávolítja a problémás tulajdonságot az összesítésből.

✔️ DO használjon kötegelt végpontot hosszú lekérdezésekhez

A hosszú lekérdezésekkel kapcsolatban problémák merülhetnek fel. Különösen a következő esetekben fordulhatnak elő problémák:

  • Több egyéni mezővel rendelkező projektet kérdez le.
  • A lekérdezés programozott módon van létrehozva.

Az OData-lekérdezések HTTP GET jelenlegi korlátja 3000 karakter. Ha túllépi, a "404 Nem található" választ kapja vissza.

HTTP/1.1 404 Not Found
Content-Length: 0

A probléma megoldásához használja az OData kötegvégpontot az OData 4.0-s verziójának specifikációjában leírtak szerint. 1. rész: Protokoll – 11.7 Batch-kérelmek. A Batch képességet elsősorban arra tervezték, hogy több műveletet csoportosítson egyetlen HTTP kérelem hasznos adatába, de áthidaló megoldásként is használható a lekérdezés hosszának korlátozásához. A HTTP POST kérés elküldésével tetszőleges hosszúságú lekérdezést adhat át, és a szolgáltatás helyesen értelmezi azt.

❌ [LETILTVA] NE használjon kötegelt végpontot több lekérdezés küldéséhez

Korlátozzuk, hogy a kötegvégpont több kérelemből álló köteget kezeljen. Egyetlen kérelemnek továbbra is csak egy lekérdezése lehet. Ha több lekérdezésből álló köteget próbál elküldeni, a művelet az alábbi hibaüzenettel meghiúsul. Az egyetlen megoldás a lekérdezések több kérelemre való felosztása.

Az Elemzés nem támogatja az aktuális kötegüzenet által tartalmazott műveletek feldolgozását. Az Analytics OData-köteget használ a POST-kérések támogatásához, de a műveletet egyetlen kérelemre kell korlátoznia.

❌ [LETILTVA] NE használjon 800-nál több oszlopot eredményező lekérdezéseket

Korlátozzuk azokat a lekérdezéseket, amelyek több mint 800 oszlopot eredményeznek. Ha nem elég szelektív a lekérdezés által visszaadott oszlopokban, a következő hibaüzenet jelenhet meg.

VS403670: A megadott lekérdezés "N" oszlopokat ad vissza, amely meghaladja a megengedett 800 oszlopos korlátot. Az oszlopok számának korlátozásához használjon explicit $select (beleértve a $expand)-beállításokat is.

Adjon hozzá egy $select záradékot a lekérdezéshez, és $expand műveleteket a lekérdezésben, hogy elkerülje a korlát túllépését.

❌ NE hozzon létre hosszú lekérdezéseket

Javasoljuk, hogy hosszú lekérdezések létrehozásakor értékelje ki a megközelítést. Bár sok olyan forgatókönyv van, amely hosszú lekérdezést igényel (például összetett szűrőket vagy tulajdonságok hosszú listáját), általában korai jelzést adnak a nem optimális kialakításról.

Ha a lekérdezés számos entitáskulcsot tartalmaz a lekérdezésben (például WorkItemId eq {id 1} or WorkItemId eq {id 2} or ...), valószínűleg újraírhatja. Az azonosítók átadása helyett próbáljon meg definiálni néhány olyan feltételt, amely ugyanazt az entitáskészletet választja ki. Előfordulhat, hogy módosítania kell a folyamatot (például új mezőt vagy címkét kell hozzáadnia), de általában megéri. Az absztraktabb szűrőket használó lekérdezések könnyebben karbantarthatóak, és nagyobb potenciállal rendelkeznek a jobb működésre.

Egy másik, hosszú lekérdezéseket generáló forgatókönyv akkor fordul elő, ha több dátumot is tartalmaz (például DateSK eq {dateSK 1} or DateSK eq {dateSK 2} or ...). Keressen egy másik mintát, amellyel absztraktabb szűrőt hozhat létre. Az alábbi lekérdezés például a hétfőn létrehozott összes munkaelemet adja vissza.

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

✔️ Do adja meg az időzónát a dátumoszlopok szűrésekor

Az időzóna (Edm.DateTimeOffset) a szervezet időzóna-beállításainak megfelelő eltolással teszi elérhetővé az összes dátum- és időinformációt. Ezek az adatok pontosak és egyszerűen értelmezhetők egyszerre. Egy másik nem feltűnő következmény az, hogy az összes szűrőnek át kell adnia az időzóna adatait is. Ha kihagyja, a következő hibaüzenet jelenik meg.

Az URI-ban megadott lekérdezés érvénytelen. Nincs megadva dátum/idő eltolás. Az eltolás megadásához használja az YYYYY-MM-ddZ formátumok egyikét, vagy az yyyy-MM-ddThh:mm-hh:mm (ISO 8601 szabvány a dátumok és időpontok megjelenítését) óta.

A probléma megoldásához adja hozzá az időzóna adatait. Tegyük fel például, hogy a szervezet úgy van konfigurálva, hogy adatokat jelenítsen meg az "(UTC-08:00) Csendes-óceáni idő (USA és Kanada)" időzónában, az alábbi lekérdezés lekéri a 2020 eleje óta létrehozott összes munkaelemet.

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

Ugyanez a megoldás pozitív eltolásokkal rendelkező időzónák esetében is működik, a plusz karakter (+) azonban különleges jelentéssel rendelkezik az URI-ban, és helyesen kell kezelnie. Ha kezdőpontként egy karaktert + ad meg 2020-01-01T00:00:00+08:00 , a következő hibaüzenet jelenik meg.

Az URI-ban megadott lekérdezés érvénytelen. Szintaxishiba a 31. pozícióban a "CreatedDate ge 2020-01-01T0000 08:00" helyen.

A megoldáshoz cserélje le a karaktert a + kódolt verzióra. %2B Tegyük fel például, hogy a szervezet úgy van konfigurálva, hogy adatokat jelenítsen meg "(UTC+08:00) Peking, Chongqing, Hong Kong, Urumqi" időzónában, az alábbi lekérdezés a 2020 eleje óta létrehozott összes munkaelemet visszaadja.

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

Egy másik módszer a dátum helyettesítő kulcstulajdonságok használata, mivel nem őrzik meg az időzóna adatait. Az alábbi lekérdezés például a 2020 eleje óta létrehozott összes munkaelemet adja vissza a szervezet beállításaitól függetlenül.

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

Teljesítményre vonatkozó irányelvek

Do's

Nem

Tekint

Elkerülés

✔️ A DO méri a teljesítményre vonatkozó útmutató implementálásának hatását

A teljesítményre vonatkozó javaslatokhoz hasonlóan nem szabad vakon implementálni őket. Ehelyett mindig rögzítse az alaptervet, és mérje meg a módosítások hatását. Az összes irányelv az Analytics olyan ügyfeleivel folytatott interakciók alapján jött létre, akik speciális követelményekkel és kihívásokkal szembesültek. Ezeket a javaslatokat általánosnak tekintették, és potenciálisan hasznosak voltak azok számára, akik hasonló lekérdezéseket terveznek. Ritkán azonban az iránymutatások követése nem, vagy akár negatív hatással sem lehet a teljesítményre. Ahhoz, hogy észrevehesse, meg kell mérnie a különbséget. Ha ez történik, küldjön visszajelzést a fejlesztői közösségi portálon.

A teljesítmény mérésére számos lehetőség áll rendelkezésre. A legegyszerűbb, ha ugyanazon lekérdezés két verzióját futtatja közvetlenül a böngészőben. Figyelje meg, hogy mennyi időbe telik a fejlesztői eszközök használata. Használhatja például a Hálózati panelt a Microsoft Edge F12 Fejlesztői eszközökben. Egy másik lehetőség az információk rögzítése a Fiddler Web Debugger Tool használatával.

Bármi legyen is a megközelítése, futtassa mindkét lekérdezést többször. Futtassa például a lekérdezéseket 30-szor, hogy kellően nagy mintakészlettel rendelkezzen. Ezután állapítsa meg a teljesítmény jellemzőit. Az Elemzés a több-bérlős architektúrát követi. Így az egyidejűleg végrehajtott egyéb műveletek hatással lehetnek a lekérdezések időtartamára.

✔️ DO aggregációs bővítmények használata

A lekérdezések teljesítményének javítása érdekében messze a legjobb megoldás az aggregációs bővítmény használata – OData-bővítmény adatösszesítéshez. Az aggregációs bővítmény használatával kérje meg a szolgáltatást, hogy összegezze az adatkiszolgálói oldalt, és adjon vissza egy kisebb választ, mint amit ugyanazzal a függvény ügyféloldali alkalmazásával lekérhet. Végül az Analytics az ilyen típusú lekérdezésekhez van optimalizálva, ezért használja ki.

További információ: Adatok összesítése.

✔️ DO– oszlopok megadása a $select záradékban

Adja meg a záradékban $select a fontos oszlopokat. Az elemzés a Columnstore Index technológiára épül. Ez azt jelenti, hogy az adatok tárolása és a lekérdezésfeldolgozás is oszlopalapú. A tulajdonságok halmazának csökkentésével a záradékban $select hivatkozhat a vizsgálandó oszlopok számának csökkentésére, és javíthatja a lekérdezés általános teljesítményét.

Az alábbi lekérdezés például a munkaelemek oszlopait adja meg.

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

Feljegyzés

Az Azure DevOps támogatja a folyamatok testreszabását. Egyes rendszergazdák ezt a funkciót használják, és több száz egyéni mezőt hoznak létre. Ha kihagyja a $select záradékot, a lekérdezés az összes mezőt visszaadja, beleértve az egyéni mezőket is.

✔️ Do adja meg az oszlopokat a $select záradékon belüli $expand kibontási beállításban

A záradék irányelveihez $select hasonlóan adja meg a tulajdonságokat a $select záradék kibontási lehetőségében $expand . Könnyű elfelejteni, de ha kihagyja, a válasz tartalmazza a kibontott objektum összes tulajdonságát.

Az alábbi lekérdezés például a munkaelem és a szülő oszlopait határozza meg.

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

✔️ DO– szűrő RevisedDateSK definiálása az előzmény munkaelemek adatainak (WorkItemRevisions vagy WorkItemSnapshot entitáskészleteinek) lekérdezésekor

Az előzményadatok lekérdezésekor valószínű, hogy a legutóbbi időszak érdekli (például 30 nap, 90 nap). A munkaelem-entitások implementálásának köszönhetően kényelmesen írhat ilyen lekérdezéseket, így nagyszerű teljesítményt érhet el. Minden alkalommal, amikor frissít egy munkaelemet, létrehoz egy új változatot, és rögzíti ezt a műveletet a System.RevisedDate mezőben, ami tökéletessé teszi az előzményszűrőkhöz.

Az Analyticsben a módosított dátum a RevisedDate (Edm.DateTimeOffset) és RevisedDateSK (Edm.Int32) tulajdonságokban jelenik meg. A legjobb teljesítmény érdekében használja az utóbbit. Ez a dátum helyettesítő kulcs , és azt a dátumot jelöli, amikor egy változat létrejött, vagy aktív null , hiányos változatok esetén. Ha az összes dátumot a befogadó óta {startDate} szeretné megadni, adja hozzá a következő szűrőt a lekérdezéshez.

RevisedDateSK eq null or RevisedDateSK gt {startDateSK}

Az alábbi lekérdezés például a 2020 eleje óta minden naphoz tartozó munkaelemek számát adja vissza. Figyelje meg, hogy az oszlop nyilvánvaló szűrőjén DateSK kívül van egy második szűrő is.RevisedDateSK Bár redundánsnak tűnhet, segít a lekérdezési motornak kiszűrni a hatókörön kívüli változatokat, és jelentősen javítja a lekérdezési teljesítményt.

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

Feljegyzés

Ezt a javaslatot a Burndown-vezérlők használata során fogalmaztuk meg. Kezdetben csak a DateSK szűrőket határoztuk meg, de nem sikerült elérni, hogy ez a lekérdezés megfelelően méretezhető legyen a nagy adathalmazokkal rendelkező szervezetek számára. A lekérdezésprofilozás során észrevettük, hogy DateSK nem szűri jól a korrektúrákat. Csak azután, hogy hozzáadtunk egy szűrőt, RevisedDateSK nagy léptékű teljesítmény érhető el.
~ Termékcsapat

✔️ DO használjon heti vagy havi pillanatképeket a hosszú ideig tartó trend lekérdezésekhez

Alapértelmezés szerint az összes pillanatképtáblát napi pillanatkép-ténytáblákként modellezi a rendszer. Ha egy időtartományt kérdez le, az minden naphoz kap egy értéket. A hosszú időtartományok sok rekordot eredményeznek. Ha nincs szüksége ilyen nagy pontosságra, heti vagy akár havi pillanatképeket is használhat.

Ezt más szűrőkifejezésekkel is megteheti, hogy eltávolítja azokat a napokat, amelyek nem fejeződnek be egy adott héten vagy hónapban. Használja a tulajdonságot, amelyet ezzel a IsLastDayOfPeriod forgatókönyvvel adtunk hozzá az Analyticshez. Ez a tulajdonság típus Microsoft.VisualStudio.Services.Analytics.Model.Period , és meghatározhatja, hogy egy nap különböző időszakokban fejeződik-e be (például hetekben, hónapokban stb.).

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

Mivel Microsoft.VisualStudio.Services.Analytics.Model.Period jelzőkkel rendelkező számként van definiálva, használja az OData has operátort, és adja meg a pontkonstansok teljes típusát.

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

Az alábbi lekérdezés például az egyes hónapok utolsó napján definiált munkaelemek számát adja vissza.

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

A tulajdonság és a contains függvény segítségével TagNames megállapíthatja, hogy egy munka egy adott címkével van-e megjelölve. Ez a megközelítés azonban lassú lekérdezéseket eredményezhet, különösen akkor, ha egyszerre több címkét keres. A legjobb teljesítmény és eredmény érdekében használja inkább a Tags navigációs tulajdonságot.

Az alábbi lekérdezés például lekéri az összes olyan munkaelemet, amely egy {tag}címkével van megjelölve.

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

Ez a módszer akkor is jól működik, ha több címkére kell szűrnie. Az alábbi lekérdezés például az összes olyan munkaelemet visszaadja, amely címkézett {tag1} vagy {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

Ezeket a szűrőket "és" operátorral is kombinálhatja. Az alábbi lekérdezés például lekéri az összes olyan munkaelemet, amely mindkettővel {tag1} és {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 tulajdonság használata TagNames , ha a munkaelem összes címkéjét szövegként szeretné megjeleníteni

Az előző szakaszban ismertetett navigációs tulajdonság Tagskiválóan alkalmas szűrésre. A velük való munka azonban kihívást jelent, mivel a lekérdezés címkéket ad vissza egy beágyazott gyűjteményben. Az adatmodell tartalmaz egy TagNames primitív tulajdonságot is (Edm.String), amelyet a címkék felhasználási forgatókönyveinek egyszerűsítése érdekében adtunk hozzá. Ez egyetlen szöveges érték, amely tartalmazza az összes címke listáját egy pontosvesszővel (; " elválasztó) kombinálva. Ezt a tulajdonságot akkor használja, ha csak a címkék együttes megjelenítése érdekli. Kombinálhatja a korábban ismertetett címkék szűrőivel.

Az alábbi lekérdezés például lekéri az összes olyan munkaelemet, amely egy {tag}címkével van megjelölve. Visszaadja a munkaelem azonosítóját, címét, állapotát és a kombinált címkék szöveges ábrázolását.

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

Fontos

A tulajdonság TagNames hossza 1024 karakter. A korláton belülre illeszkedő címkéket tartalmaz. Ha egy munkaelem sok címkével rendelkezik, vagy a címkék nagyon hosszúak, akkor TagNames ne tartalmazza a teljes készletet, és Tag inkább a navigációs tulajdonságot használja.

❌ NE használjon és ne használjon tolower függvényeket a kis- és toupper nagybetűk érzéketlen összehasonlításához

Ha más rendszerekkel is dolgozott, akkor a kis- és toupper nagybetűk tolower érzéketlen összehasonlítására is számíthat. Az Analytics esetében az összes sztring-összehasonlítás alapértelmezés szerint érzéketlen a kis- és nagybetűk között, így nem kell függvényeket alkalmaznia a műveletek explicit kezeléséhez.

Az alábbi lekérdezés például lekéri a "QUALITY", "quality" (Minőség) címkével ellátott összes munkaelemet, vagy a szó bármely más esetkombinációját.

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

❌ NE használjon kötetlen bővítést a következővel: $levels=max

Az OData képes kibontani a hierarchikus struktúra összes szintjét. A munkaelemek nyomon követése például olyan entitásokkal rendelkezik, amelyekben kötetlen bővítés alkalmazható. Ez a művelet csak kis mennyiségű adattal rendelkező szervezetek esetében működik. Nagyobb adathalmazok esetében nem skálázható megfelelően. Ne használja egyáltalán, ha:

  • Nagy adathalmazokkal dolgozik.
  • Egy widgetet fejleszt, és nincs szabályozva, hogy a widget hol legyen telepítve.

✔️ DO kiszolgálóalapú lapozás használata

Ha olyan készletet kér, amely túl nagy ahhoz, hogy egyetlen válaszban lehessen elküldeni, az Analytics a lapozást alkalmazza. A válasz csak egy részleges készletet és egy hivatkozást tartalmaz, amely lehetővé teszi a következő részleges elemkészlet lekérését. Ezt a stratégiát az OData specifikációja ismerteti – OData 4.0-s verzió. 1. rész: Protokoll – Kiszolgálóalapú lapozás. Ha lehetővé teszi, hogy a szolgáltatás vezérelje a lapozást, a lehető legjobb teljesítményt érheti el, mivel az skiptoken egyes entitások tervezése során a lehető leghatékonyabban lett kialakítva.

A tulajdonság tartalmazza @odata.nextLink a következő lapra mutató hivatkozást.

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

Feljegyzés

A legtöbb meglévő OData-ügyfél képes automatikusan kezelni a kiszolgálóalapú lapozást. Ezt a stratégiát például már használják a következő eszközök: Power BI, SQL Server Integration Services és Azure Data Factory.

❌ NE használjon $top és $skip lekérdezési beállításokat az ügyfélalapú lapozás implementálásához

Más REST API-knál előfordulhat, hogy ügyfélvezérelt lapozást $top és $skip lekérdezési beállításokat is implementált. Ne használja őket az Analytics szolgáltatással. Ezzel a megközelítéssel több probléma is van, és a teljesítmény az egyik. Ehelyett fogadja el az előző szakaszban ismertetett kiszolgálóalapú lapozási stratégiát.

✔️ DO a lekérdezési beállítással $top korlátozza a rekordok számát

A lekérdezési beállítás $top csak akkor nem használható, ha együtt használják.$skip Ha a jelentéskészítési forgatókönyvben csak a rekordok egy részhalmazára (például mintára) van szüksége, akkor érdemes a lekérdezési lehetőséget használni $top . Emellett, ha bizonyos feltételeknek megfelelően kell rangsorolnia a rekordokat, akkor a stabil eredmény és a legmagasabb rangsorolású rekordok együttes $orderby használata $top ajánlott.

✔️ FONTOLJA meg, hogy lekérdezést írjon kis számú rekord visszaadásához

A lekérdezés írása kis számú rekord visszaadásához a leg intuitívabb útmutató. Mindig csak azokat az adatokat szeretné beolvasni, ami igazán fontos Önnek. Ezt úgy érheti el, hogy a nagy teljesítményű szűrési képességek nagy részét elérhetővé teszi az OData lekérdezési nyelven.

✔️ FONTOLJA meg a kijelölt tulajdonságok számának minimálisra való korlátozását

Egyes projektgazdák egyéni mezők hozzáadásával nagymértékben testre szabják a folyamataikat. A nagy testreszabás teljesítményproblémákat okozhat a széles entitások összes elérhető oszlopának beolvasásakor (például WorkItems). Az elemzés a Columnstore Index technológiára épül. Ez azt jelenti, hogy az adatok tárolása és a lekérdezésfeldolgozás is oszlopalapú. Minél több tulajdonságra hivatkozik egy lekérdezés, annál drágább a feldolgozás. Mindig arra törekedjen, hogy a lekérdezések tulajdonságainak halmazát arra korlátozza, ami igazán fontos a jelentéskészítési forgatókönyvben.

✔️ FONTOLJA meg a dátum szerinti helyettesítő kulcstulajdonságok (DateSK utótag) szűrését

A dátumszűrők számos módon definiálhatók. A dátumtulajdonságra közvetlenül (például CreatedDate), navigációs megfelelőjére (például CreatedOnDate) vagy helyettesítő kulcsábrázolására (például CreatedDate) szűrhet. Az utolsó lehetőség a legjobb teljesítményt nyújtja, és előnyben részesíti, ha a jelentéskészítési követelmények lehetővé teszik.

Az alábbi lekérdezés például lekéri a 2020 eleje óta létrehozott összes munkaelemet.

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

✔️ FONTOLJA meg a helyettesítő kulcsoszlopok szűrését

Ha egy kapcsolódó objektum értékére szeretné szűrni az adatokat (például egy munkaelem szűrése a projekt nevére), mindig két lehetőség közül választhat. Használhatja a navigációs tulajdonságot (például ), vagy előre rögzítheti a helyettesítő kulcsot, Project/ProjectNameés közvetlenül a lekérdezésben használhatja (példáulProjectSK).

Ha widgetet készít, azt javasoljuk, hogy az utóbbi lehetőséget használja. Amikor a kulcs átadása a lekérdezés részeként történik, csökken az érintendő entitáskészletek száma, és javul a teljesítmény.

A következő lekérdezés WorkItems például tulajdonságot használ ProjectSK a navigációs tulajdonság helyett Project/ProjectName .

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

❌ NE használjon Parent, Childrenvagy Revisions tulajdonságokat a $filter vagy $expand záradékokban

A munkaelemek a teljes adatmodell legdrágább entitásai. Számos navigációs tulajdonsággal rendelkeznek, amelyekkel elérheti a kapcsolódó munkaelemeket: Parent, Children, Revisions. Minden alkalommal, amikor egy lekérdezésben használja őket, a teljesítmény csökkenése várható. Mindig kérdés, hogy valóban szüksége van-e ezekre a tulajdonságokra, és esetleg frissíti a tervet.

Kibontás Parenthelyett például több munkaelemet is lekérhet, és a tulajdonság használatával ParentWorkItemId rekonstruálhatja a teljes hierarchia ügyféloldalát. Végezze el az ilyen optimalizálást eseti alapon.

✔️ FONTOLJA meg a fejléc beállításának VSTS.Analytics.MaxSize átadását

Lekérdezés végrehajtásakor nem tudja, hogy hány rekordot ad vissza a lekérdezés. Küldjön egy másik lekérdezést aggregációkkal, vagy kövesse az összes következő hivatkozást, és kérje le a teljes adatkészletet. Az Elemzés tiszteletben tartja VSTS.Analytics.MaxSize a beállításokat, így azokban a példányokban, amelyekben az adathalmaz nagyobb, mint amit az ügyfél elfogadhat, gyorsan meghiúsulhat.

Ez a lehetőség hasznos adatexportálási forgatókönyvekben. A használatához fejlécet kell hozzáadnia Prefer a HTTP-kérelemhez, és nem negatív értékre kell állítania VSTS.Analytics.MaxSize . Az VSTS.Analytics.MaxSize érték az elfogadható rekordok maximális számát jelöli. Ha nullára állítja, akkor a rendszer egy alapértelmezett 200 K értéket használ.

Az alábbi lekérdezés például munkaelemeket ad vissza, ha az adathalmaz kisebb vagy egyenlő 1000 rekordkal.

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}

Ha az adathalmaz túllépi az 1000 rekordot, a lekérdezés az alábbi hibával azonnal meghiúsul.

A lekérdezés eredménye 1296 sort tartalmaz, és meghaladja az 1000-es maximális megengedett méretet. Csökkentse a rekordok számát további szűrők alkalmazásával

A maximális oldalméret beállításáról további információt az ODataPreferenceHeader.MaxPageSize tulajdonságban talál.

Lekérdezésstílusra vonatkozó irányelvek

✔️ DO virtuális tulajdonság használata $count az összesítési metódusokban

Egyes entitások tulajdonságot fednek fel Count . Megkönnyítik a jelentéskészítési forgatókönyveket, ha az adatokat egy másik tárolóba exportálják. Ezeket az oszlopokat azonban nem szabad az OData-lekérdezésekben lévő összesítésekben használni. Használja inkább a $count virtuális tulajdonságot.

Az alábbi lekérdezés például a munkaelemek teljes számát adja vissza.

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

❌ NE használjon $count virtuális tulajdonságot az URL-szegmensben

Bár az OData standard lehetővé teszi, hogy virtuális tulajdonságot használjon $count entitáskészletekhez (például _odata/v1.0/WorkItems/$count), nem minden ügyfél tudja megfelelően értelmezni a választ. Ezért javasoljuk, hogy inkább aggregációkat használjon.

Az alábbi lekérdezés például a munkaelemek teljes számát adja vissza.

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

✔️ FONTOLJA meg a paraméter-aliasok használatát a lekérdezés változó részeinek elkülönítéséhez

A paraméter-aliasok elegáns megoldást nyújtanak az illékony részek, például a paraméterértékek kinyerésére a fő lekérdezési szövegből. Ezeket a következő kiértékelő kifejezésekben használhatja:

  • Primitív érték
  • Összetett érték
  • Primitív vagy összetett értékek gyűjteménye.

További információ: OData 4.0-s verzió. 2. rész: URL-konvenciók – 5.1.1.13 Paraméter aliasok. A paraméterek akkor hasznosak, ha a lekérdezés szövegét sablonként használják, amely a felhasználó által megadott értékekkel hozható létre.

Az alábbi lekérdezés például paraméterrel választja @createdDateSK el az értéket a szűrőkifejezéstől.

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

❌ KERÜLJE a keverést $apply és $filter a záradékokat egyetlen lekérdezésben

Ha hozzá szeretne adni filter a lekérdezéshez, két lehetősége van. Ezt a záradékkal vagy a $filter $apply=filter() kombinációval is megteheti. Ezek a lehetőségek önmagukban is nagyszerűen működnek, de az egyesítések váratlan eredményekhez vezethetnek.

Az elvárás ellenére az OData egyértelműen meghatározza a kiértékelés sorrendjét. Emellett a $apply záradék elsőbbséget élvez a $filter. Ezért érdemes választania egyet vagy másikat, de egyetlen lekérdezésben kerülje el ezt a két szűrőbeállítást. Fontos, hogy a lekérdezések automatikusan létre legyenek hozva.

Az alábbi lekérdezés például először a munkaelemeket StoryPoint gt 5szűri, az eredményeket elérési út alapján összesíti, végül pedig az eredményt szűri.StoryPoints gt 2 Ezzel a kiértékelési sorrenddel a lekérdezés mindig egy üres készletet ad vissza.

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

✔️ FONTOLJA meg a lekérdezés strukturálását az OData-kiértékelési sorrendnek megfelelően

Mivel az egyetlen lekérdezés keverése $apply és filter záradékai potenciális zavart okozhatnak, javasoljuk, hogy a lekérdezési záradékokat a kiértékelési sorrendnek megfelelően strukturálja.

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

✔️ FONTOLJA meg a metaadat-megjegyzésekben leírt OData-képességek áttekintését

Ha nem biztos abban, hogy melyik OData-képességeket támogatja az Analytics, megkeresheti a metaadatokban lévő széljegyzeteket. A TC GitHub-adattárban található OASIS Open Data Protocol (OData) műszaki bizottság fenntartja a rendelkezésre álló széljegyzetek listáját.

A támogatott szűrőfüggvények listája például széljegyzetben Org.OData.Capabilities.V1.FilterFunctions érhető el az entitástárolón.

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

Egy másik hasznos megjegyzés, Org.OData.Capabilities.V1.ExpandRestrictionsamely elmagyarázza, hogy mely navigációs tulajdonságokat nem használhatja a $expand záradékban. Az alábbi széljegyzet például azt ismerteti, hogy Revisions az WorkItems entitáskészlet nem bontható ki.

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