Munkaelem lekérdezési nyelvének szintaxisreferenciája

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

A WIQL szintaxissal hiperhivatkozásként vagy a munkaelem-lekérdezési nyelv (REST API) használatakor definiálhat lekérdezést.

A WIQL támogatja a webes portál Lekérdezésszerkesztőjében elérhető összes függvényt, valamint még néhányat. Megadhatja a visszaadandó mezőket és a lekérdezési záradékok logikai csoportosítását. Egy záradék használatával ASOF a hozzárendelések alapján is szűrhet az előző dátum alapján.

Important

A WIQL szintaxis a Lekérdezés wiql REST API általi végrehajtására szolgál. Az API csak munkaelem-azonosítókat ad vissza, függetlenül attól, hogy az utasítás mely mezőket SELECT tartalmazza. A teljes információ lekéréséhez (1) kérje le az azonosítókat a WIQL-ből, majd (2) szerezze be a munkaelemeket a munkaelemek listájának beolvasása azonosító és adott mezők alapján.

Prerequisites

Category	Requirements
Permissions	Munkaelemek megtekintése vagy Munkaelemek megtekintése ezen a csomóponton engedélykészlet engedélyezése. Ezeket az engedélyeket általában az Olvasók és közreműködők csoportok tagjai kapják meg minden egyes csapatprojekthez. További információ: Engedélyek és csoportok.

A lekérdezés nyelvének áttekintése

A WIQL öt részből áll, amint az a következő szintaxisrészletben látható és a táblázatban leírt. A WIQL szintaxisa nem érzékeny a kis- és nagybetűkre.

SELECT
    [System.Id],
    [System.AssignedTo],
    [System.State],
    [System.Title],
    [System.Tags]
FROM workitems
WHERE
    [System.TeamProject] = 'Design Agile'
    AND [System.WorkItemType] = 'User Story'
    AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2025'

Tip

A Wiql Editor Marketplace-bővítmény telepítésével lekérdezéseket hozhat létre a Lekérdezésszerkesztővel, és megtekintheti a WIQL szintaxist. Ezután másolhatja és módosíthatja a WIQL szintaxist, és futtathatja a lekérdezést a Táblákhoz hozzáadott Wiql Playground hub használatával.

Záradék	Példa/leírás
`SELECT`	Az egyes munkaelemekhez visszaadandó mezőket azonosítja. Megadhatja a rövid nevet vagy a hivatkozás nevét. Használjon szögletes zárójeleket (`[]`), ha a név üres vagy pontokat tartalmaz.
`FROM`	Azt jelzi, hogy a lekérdezés munkaelemeket vagy munkaelemek közötti hivatkozásokat keres-e. – Munkaelemek visszaadására használható `FROM WorkItems` . – A munkaelemek közötti kapcsolatok visszaadására használható `FROM workItemLinks` . További információ: A munkaelemek közötti hivatkozások lekérdezései.
`WHERE`	Megadja a lekérdezés szűrőfeltételeit. További információ: Szűrési feltételek (`WHERE`).
`ORDER BY`	A visszaadott munkaelemek rendezési sorrendjét adja meg. Egy vagy több mezőhöz megadhat növekvő (`Asc`) vagy csökkenő (`Desc`) értéket. Például: `ORDER BY [State] Asc, [Changed Date] Desc`
`ASOF`	Előzmény lekérdezést ad meg a szűrő alkalmazásának dátumával. Ez a lekérdezés például az összes olyan felhasználói történetet visszaadja, amelyek 2025. február 11-én aktívként lettek definiálva. Adja meg a dátumot a Dátum és idő minta útmutatójának megfelelően. `ASOF '02-11-2025'`

Note

Az Azure Boardson végzett WIQL-lekérdezések nem haladhatják meg a 32 K karaktert. A rendszer nem teszi lehetővé az ilyen hosszúságú lekérdezések létrehozását vagy futtatását.

Dátum- és időminta

A DateTime mezőkhöz megadott dátum- és időmintának meg kell egyeznie azzal, amelyet a profilon keresztül választ ki. A kijelölés megtekintéséhez vagy módosításához olvassa el a Felhasználói beállítások megadása című témakört.

Képernyőkép a Dátumminta legördülő listáról az Idő és a Területi beállítás panelen. Képernyőkép az Időminta legördülő listáról az Idő és a Területi beállítás panelen.

Képernyőkép az Idő és a Területi beállítás panelről Dátumminta és Időminta mezőkkel.

Az összehasonlításokban használt idézőjelek (az egy- vagy kettős idézőjelek támogatottak). DateTime A lekérdezést futtató helyi ügyfélszámítógép .NET DateTime formátumúnak kell lennie. Ha nincs megadva időzóna, DateTime a literálok a helyi számítógép időzónájában vannak.

WHERE 
   AND [System.ChangedDate] >= '01-18-2025 GMT'
   AND ([Closed Date] < '01-09-2025 GMT'
   OR [Resolved Date] >= '01-18-2025 14:30:01')

Ha az idő ki van hagyva egy DateTime literálban, és a dayPrecision paraméter értéke hamis, akkor az idő nullának (éjfélnek) számít. A paraméter alapértelmezett beállítása dayPrecision hamis.

Megadhatja az ISO 8601 formátumot is, amely a területi beállítástól függetlenül érvényes. Az ISO 8601 a dátumot és az időt jelöli az évtől kezdve, majd a hónapot, a napot, az órát, a perceket, a másodperceket és az ezredmásodperceket. Például 2025-12-10 15:00:00.000 helyi idő szerint 2025. december 10-én 15 órakor. Példa az ISO 8601 formátum használatára:

WHERE 
   AND [System.ChangedDate] >= '2025-01-18T00:00:00.0000000'
   AND ([Closed Date] < '2025-01-09T00:00:00.0000000'
   OR [Resolved Date] >= '2025-01-18T00:00:00.0000000')

Egyéni mezők

Egyéni mezőt is hozzáadhat egy lekérdezési záradékhoz. A WIQL használatával meg kell adnia az egyéni mező referencianevét. Öröklődő folyamatmodellt használó projektek esetében az egyéni mezőket általában a nevükre előre felerősített címkével Custom. jelölik meg, a szóközök pedig el lettek távolítva. Például:

Barátságos név	Hivatkozási név
`Approver`	`Custom.Approver`
`Request Type`	`Custom.RequestType`
`Scope Estimate`	`Custom.CustomEstimate`

A helyszíni XML-folyamatmodellt használó projektek esetében a referencianevet az XML-munkaelem-típusdefiníciók határozzák meg.

További információ: Munkaelem mezői és attribútumai.

Szűrőzáradékok megadása (`WHERE`)

A WHERE záradék megadja a szűrési feltételeket. A lekérdezés csak a megadott feltételeknek megfelelő munkaelemeket adja vissza. Az alábbi példamondat WHERE például olyan felhasználói történeteket ad vissza, amelyek aktívak és önhöz vannak rendelve.

WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me

A logikai operátorok kiértékelésének sorrendjét úgy szabályozhatja, hogy zárójelek közé rendezi őket a szűrőfeltételek csoportosításához. Ha például az Önhöz rendelt vagy bezárt munkaelemeket szeretné visszaadni, használja az alábbi példát.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
        )
    )

Szűrési feltételek

Minden szűrőfeltétel három részből áll, amelyek mindegyikének meg kell felelnie a következő szabályoknak:

Mező: Megadhatja a hivatkozás nevét vagy a rövid nevet. Az alábbi példák érvényes WIQL-szintaxist jelentenek:
- Hivatkozás neve: SELECT [System.AssignedTo] ...
- Rövid név szóközökkel: SELECT [Assigned To] ...
- A szóköz nélküli nevekhez nincs szükség szögletes zárójelekre: SELECT ID, Title ...
Operátor: Az érvényes értékek a cikk későbbi , Operátorok szakaszában vannak megadva.
Mezőérték: A megadott mezőtől függően a következő három érték egyikét adhatja meg.
- A literális értéknek meg kell egyeznie a mezőérték adattípusával.
- Egy adott értéket jelző változó vagy makró. Például azt a személyt jelzi, @Me aki a lekérdezést futtatja. További információ: Makrók és változók.
- Egy másik mező neve. Használhatja például a [Assigned to] = [Changed by] munkaelemet legutóbb módosító személyhez rendelt munkaelemeket.

A rendszer által definiált mezők leírását és hivatkozásnevét lásd: Munkaelem mezőindexe.

Operators

A lekérdezések logikai kifejezésekkel minősítik az eredményhalmazokat. Ezeket a logikai kifejezéseket egy vagy több összekapcsolt művelet alkotja.

Néhány egyszerű lekérdezési művelet a következő:

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'

Az alábbi táblázat összefoglalja a különböző mezőtípusok összes támogatott operátorát. Az egyes mezőtípusokról további információt a Munkaelem mezők és attribútumok című témakörben talál.

A =, <>, >, <, >=és <= operátorok a várt módon működnek. Például az System.ID > 100 összes 100-nál nagyobb munkaelem lekérdezése ID . System.ChangedDate > '01-01-25 12:00:00' 2025. január 1., dél után módosult összes munkaelem lekérdezései.

Ezen alapműveletek mellett bizonyos mezőtípusokra jellemző viselkedések és operátorok is léteznek.

Note

Az Ön számára elérhető operátorok a platformtól és a verziótól függenek. További információ: Lekérdezés – gyorshivatkozás.

Mezőtípus	Támogatott operátorok
`Boolean`	`= , <> , =[Field] , <>[Field]`
`DateTime`	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever`
\, \, \	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever`
`Identity`	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever`
`PlainText`	`Contains Words, Not Contains Words, Is Empty, Is Not Empty`
`String`	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever`
`TreePath`	`=, <>, In, Not In, Under, Not Under`

Logikai csoportosítások

A kifejezések AND és OR a tipikus logikai értelemben két záradék kiértékelésére használhatók. Használhatja a feltételeket AND EVER , és OR EVER ha operátort WAS EVER ad meg. Szükség szerint csoportosíthatja a logikai kifejezéseket, és további összekapcsolhatja őket. Az alábbi példák bemutatják.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        )
    )

A , containsés under operátorokat a inkövetkezővel nottagadhatja meg: . Nem tagadhatja meg az operátort ever . Az alábbi példa lekérdezi az összes olyan munkaelemet, amely nincs hozzárendelve a részhalmazhoz Fabrikam Fiber\Account Management.

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'

Példa lekérdezésre, amelyhez valaha hozzá lett rendelve

Az alábbi Lekérdezésszerkesztő-példa megkeresi a Jamal Hartnetthez valaha hozzárendelt összes munkaelemet.

Képernyőkép a Lekérdezésszerkesztő, egybesimított lista lekérdezéséről.

A megfelelő WIQL-szintaxis a következő:

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

Makrók vagy változók

Az alábbi táblázat a WIQL-lekérdezésekben használható makrókat és változókat sorolja fel.

Macro	Usage
`@Me`	Ezzel a változóval automatikusan megkeresheti az aktuális felhasználó aliasát egy felhasználói aliasokat tartalmazó mezőben. Megtalálhatja például a megnyitott munkaelemeket, ha az `Field` oszlopot a következőre `Activated By`állítja, az `Operator` oszlopot pedig a következőre `=Value@Me`.
`@CurrentIteration`	Ezzel a változóval automatikusan szűrheti a kijelölt csapat aktuális futamához rendelt munkaelemeket a kijelölt csapat környezete alapján.
`@Project`	Ezzel a változóval kereshet munkaelemeket az aktuális projektben. Az aktuális projektben például az összes munkaelemet megtalálhatja, ha az `Field` oszlopot a következőre `Team Project`állítja, az `Operator` oszlopot pedig a következőre`=Value@Project`.
`@StartOfDay` `@StartOfWeek` `@StartOfMonth` `@StartOfYear`	Ezekkel a makrókkal szűrheti `DateTime` a mezőket az aktuális nap, hét, hónap, év kezdete vagy az értékek egyikének eltolása alapján. Az elmúlt három hónapban létrehozott összes elemet megtalálhatja például, ha az `Field` oszlopot a következőre `Created Date`állítja, az `Operator` oszlopot pedig a következőre `>=Value@StartOfMonth - 3`.
`@Today`	Ezzel a változóval megkeresheti az aktuális dátumhoz vagy egy korábbi dátumhoz kapcsolódó munkaelemeket. A változót napok `@Today` kivonásával is módosíthatja. Például az elmúlt héten aktivált összes elemet megtalálhatja, ha az `Field` oszlopot a következőre `Activated Date`állítja, az `Operator` oszlopot pedig a következőre `>=Value@Today - 7`.
`[Any]`	Ezzel a változóval olyan munkaelemeket kereshet, amelyek egy adott mezőhöz definiált bármely értékhez kapcsolódnak.

`@me` makró

A @me makró lecseréli a lekérdezést futtató felhasználó Integrált Windows-fióknevét. Az alábbi példa bemutatja, hogyan használhatja a makrót és az azzal egyenértékű statikus utasítást. A makró olyan identitásmezőkhöz használható, mint a Assigned To.

WHERE  
   [System.AssignedTo] = @Me

`@today` makró

A makró bármilyen @todayDateTime mezővel használható. Ez a makró az aktuális dátum éjfélét váltja fel a lekérdezést futtató helyi számítógépen. Megadhatja @today+x vagy @today-y használhatja az egész szám eltolását az x nap után @today , illetve az azt megelőző @todayy napon belül. A makrót használó lekérdezések @today a futtatás időzónájától függően különböző eredményhalmazokat adhatnak vissza.

Az alábbi példák feltételezik, hogy ma 2025.01.03.

WHERE  
   [System.CreatedDate] = @today

Egyenértékű a következő értékével:

WHERE  
   [System.CreatedDate] = '01-03-2025'

And

WHERE  
   [System.CreatedDate] > @today-2

Egyenértékű a következő értékével:

WHERE  
   [System.CreatedDate] > '01-01-2025'

`@StartOfDay`, `@StartOfWeek`, `@StartOfMonth`makrók `@StartOfYear`

A @StartOf... makrókat bármilyen DateTime mezővel használhatja. Ez a makró az aktuális nap éjfélét, a hét kezdetét, a hónap kezdetét vagy az évkezdetet váltja fel a lekérdezést futtató helyi számítógépen.

Ezek a makrók elfogadnak egy módosító sztringet, amelynek formátuma (+/-)nn(y|M|w|d|h|m): . A makróhoz @Today hasonlóan megadhat plusz vagy mínusz egész szám eltolásokat. Ha az időegység-minősítő nincs megadva, alapértelmezés szerint a függvény természetes időszaka lesz. Például ugyanaz, @StartOfWeek("+1") mint @StartOfWeek("+1w")a . Ha a plusz/mínusz (+/-) jel nincs megadva, a pluszjelet feltételezzük.

Ez a szintaxis lehetővé teszi a módosítók beágyazását és a lekérdezés kétszeri eltolását. A záradék Closed Date >= @StartOfYear - 1 például szűri a tavaly óta bezárt munkaelemeket. Ha módosítja, Closed Date >= @StartOfYear('+3M') - 1az kizárja az előző év első három hónapjában bezárt munkaelemeket. Az alábbi WIQL-szintaxis a következőket mutatja be:

WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1

Az alábbi példák feltételezik, hogy 2025. 04. 05.

WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3

Egyenértékű a következő értékével:

WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2025'

And

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear

Egyenértékű a következő értékével:

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2025'

Egyéni makrók

A WIQL tetszőleges egyéni makrókat is támogat. A rendszer minden sztringelőtagot @ egyéni makróként kezel, és lecseréli őket. Az egyéni makró csereértéke az objektummodell lekérdezési metódusának környezeti paraméteréből lesz lekérve. A makrókhoz használt API a következő módszer:

public WorkItemCollection Query(string wiql, IDictionary context)

A környezeti paraméter kulcs-érték párokat tartalmaz a makrókhoz. Ha például a környezet tartalmaz egy kulcs-érték párot (project, ), akkor MyProject a rendszer lecseréli @project a WIQL-benMyProject. Ez a csere az, ahogyan a munkaelem-lekérdezésszerkesztő kezeli a makrót a @project Visual Studióban.

Előzmény típusú lekérdezések megadása (`ASOF`)

A lekérdezések záradékával ASOF szűrheti azokat a munkaelemeket, amelyek megfelelnek a megadott szűrési feltételeknek egy adott dátumon és időpontban meghatározottak szerint.

Note

A Visual Studióban nem hozhat létre ASOF lekérdezéseket a lekérdezésszerkesztőben. Ha létrehoz egy záradékot tartalmazó .wiq lekérdezésfájlt (ASOF), majd betölti azt a Visual Studióban, a ASOF záradék figyelmen kívül lesz hagyva.

Tegyük fel, hogy egy munkaelemet 2025. 05. 05. előtt a "Jamal Hartnett" osztályba Iteration PathFabrikam Fiber\Release 1 soroltak és hozzárendeltek. A munkaelemet azonban nemrég hozzárendelték a "Raisa Pokrovskaya"-hoz, és a 2. kiadás új iterációs útvonalára került. Az alábbi példa lekérdezés a Jamal Hartnetthez rendelt munkaelemeket adja vissza, mivel a lekérdezés a munkaelemek múltbeli dátum és idő szerinti állapotán alapul.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>') 
    ASOF  '01-05-2025 00:00:00.0000000'

Note

Ha nincs megadva idő, a WIQL éjfélt használ. Ha nincs megadva időzóna, a WIQL a helyi ügyfélszámítógép időzónáját használja.

Rendezési sorrend beállítása (`ORDER BY`)

A ORDER BY záradék használatával egy lekérdezés eredményeit egy vagy több mező alapján rendezheti növekvő vagy csökkenő sorrendben.

Note

Az adatszinten lévő SQL Server rendezési beállításai határozzák meg az alapértelmezett rendezési sorrendet. Az explicit rendezési sorrend kiválasztásához azonban használhatja a paramétereket vagy asc a desc paramétereket.

Az alábbi példa a munkaelemeket először Priority növekvő sorrendben (alapértelmezett), majd Created Date csökkenő sorrendben (DESC) rendezi.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.State] =  'Active'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC

Munkaelemek közötti hivatkozások lekérdezése

A munkaelemek közötti hivatkozások visszaadásához adja meg a kívánt FROM WorkItemLinksértéket. A záradékban szereplő szűrési WHERE feltételek vonatkozhatnak a hivatkozásokra vagy bármely olyan munkaelemre, amely a hivatkozás forrása vagy célja. Az alábbi példa az aktív gyermekelemek közötti Product Backlog Items kapcsolatokat adja vissza.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] = 'Product Backlog Item'
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.State] <> 'Closed'
    )
MODE (Recursive)

Az alábbi táblázat összefoglalja a munkaelem-lekérdezések és a munkaelemek közötti kapcsolatok lekérdezései közötti különbségeket.

Záradék	Munkaelemek	Munkaelemek közötti hivatkozások
`FROM`	`FROM WorkItems`	`FROM WorkItemLinks`
`WHERE`	`[FieldName] = Value`	Adjon meg egy vagy többet a következők közül: `[Source].[FieldName] = Value` `[Target].[FieldName] = Value` `[System.Links.LinkType] = 'LinkName'`
`MODE`	nem alkalmazható	Adja meg az alábbiak egyikét: - `MODE (MustContain)`: (Alapértelmezett) Csak `WorkItemLinkInfo` olyan rekordokat ad vissza, amelyeknél a forrás, a cél és a hivatkozás feltételei teljesülnek. - `MODE (MayContain)`: Az összes olyan munkaelem rekordjait `WorkItemLinkInfo` adja vissza, amelyek megfelelnek a forrás- és csatolási feltételeknek, még akkor is, ha egyetlen csatolt munkaelem sem felel meg a célfeltételnek. - `MODE (DoesNotContain)`: A forrásnak megfelelő összes munkaelem rekordjait `WorkItemLinkInfo` adja vissza, csak akkor, ha egyetlen csatolt munkaelem sem felel meg a hivatkozásnak és a célfeltételnek. - `MODE (Recursive)`: Fa lekérdezésekhez használható (`[System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'`). A hivatkozástípusnak fa topológiának és előrefelé irányulónak kell lennie. Az összes olyan munkaelem rekordjait `WorkItemLinkInfo` adja vissza, amelyek megfelelnek a forrásnak, rekurzívan a célhoz. `ORDER BY` és `ASOF` nem kompatibilisek a fa lekérdezésekkel.
`RETURNS`	`WorkItemQueryResult`	`WorkItemLink`

Az alábbi rendszerhivatkozás-típusnevek egyikét adhatja meg.

A következő rendszerhivatkozás-típusnevek egyikét vagy a helyszíni XML-folyamattal definiált egyéni hivatkozástípust adhatja meg.

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Related
System.LinkTypes.Dependency-Predecessor
System.LinkTypes.Dependency-Successor
Microsoft.VSTS.Common.Affects-Forward (CMMI-folyamat)

További információ: Hivatkozástípus-hivatkozás.

Példa fatípusú lekérdezésre

Note

ORDER BY és ASOF nem kompatibilisek a fa lekérdezésekkel. Ezeket a záradékokat ne vegye fel fa lekérdezésekbe.

Az alábbi lekérdezés az aktuális projektben definiált munkaelem-típusokat adja vissza. A Lekérdezésszerkesztő az alábbi képen látható módon jeleníti meg a lekérdezést.

Képernyőkép a Lekérdezésszerkesztő, a fa lekérdezésről, az összes munkaelemről és állapotról.

Az egyenértékű WIQL szintaxis a következő:

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
    )
MODE (Recursive)

Példa közvetlen csatolású lekérdezésre

Az alábbi példa az aktuális projektben definiált összes munkaelem-típust adja vissza. A Lekérdezésszerkesztő az alábbi képen látható módon jeleníti meg a lekérdezést.

Képernyőkép Lekérdezésszerkesztő, közvetlen csatolású lekérdezésről, az összes munkaelemről és állapotról.

Az egyenértékű WIQL szintaxis a következő:

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
    )
ORDER BY [System.Id]
MODE (MustContain)

További lekérdezési példák

Az alábbi tipikus WIQL-lekérdezési példa hivatkozásneveket használ a mezőkhöz. A lekérdezés kijelöli a munkaelemeket (nincs megadva munkaelem-típus) egy Priority=1. A lekérdezés oszlopként adja vissza a IDTitle visszatérési halmazt. Az eredmények növekvő sorrendbe vannak rendezve ID .

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]

Dátum-idő minta

A dátum-idő mintát két minta egyikének megfelelően adhatja meg:

A Dátumminta és az Időminta formátum a felhasználói beállításokból, időpontból és területi beállításokból származik
Az UTC által megadott minta, amely ezt a mintát követi (Z hozzáfűzve a dátum-időhöz).

AND [System.ChangedDate] >= '1/1/2025 00:00:00Z'

Példa záradékok

Az alábbi példautasítások konkrét minősítő záradékokat mutatnak be.

Záradék	Example
`AND`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'`
`OR`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND ([System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>OR [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>')`
`NOT`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'`
`EVER`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'`
`UNDER`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AreaPath] UNDER 'Agile1\Area 0'`
`ORDER BY`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ORDER BY [System.Id] [asc \| desc]`
`ASOF` (Időszűrő)	`SELECT [System.Title]<br>FROM workitems<br>WHERE [System.IterationPath] = 'MyProject\Beta'<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ASOF '3/16/25 12:30'`

Sztring és egyszerű szöveg

Idézőjelek sztringkonstansai (az egy- vagy kettős idézőjelek támogatottak) egy String vagy PlainText több mező összehasonlításában. A sztringkonstansok támogatják az összes Unicode-karaktert.

WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'

Az contains operátorral a mező értékének bármely pontján kereshet részszűrést.

WHERE [System.Description] contains 'WIQL'

Terület és iteráció (`TreePath`)

Az operátort használhatja UNDER a mezőkhöz és Area Path a Iteration Path mezőkhöz. Az UNDER operátor kiértékeli, hogy egy érték egy adott besorolási csomópont altartományán belül van-e. Az alábbi kifejezés például igaz értéket ad vissza, ha az altartományban található Area PathMyProject\Server\Administration, MyProject\Server\Administration\Feature 1MyProject\Server\Administration\Feature 2\SubFeature 5vagy bármely más csomópont.

WHERE [System.AreaPath] UNDER `MyProject\Server\Administration`

Módosítók és speciális operátorok

A lekérdezési kifejezésekben használhat néhány módosítót és speciális operátort.

IN Az operátorral kiértékelhető, hogy egy mező értéke egyenlő-e bármely értékkészlettel. Ez az operátor a , String, Integerés Double mezőtípusok esetében DateTimetámogatott. Ezt az alábbi példa és szemantikai megfelelője szemlélteti.

WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>', 'Christie Church <fabrikamfiber1@hotmail.com>')

or

WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR [System.CreatedBy] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

Az EVER operátor annak kiértékelésére szolgál, hogy egy mező értéke egyenlő vagy valaha is egyenlő-e egy adott értékkel a munkaelemek összes korábbi változatában. A String, Integer, Doubleés DateTime mezőtípusok támogatják ezt az operátort. Az operátornak vannak alternatív szintaxisai EVER . Az alábbi kódrészletek például azt kérdezik le, hogy az összes munkaelem hozzá lett-e rendelve a Jamalhoz, a Raisához vagy a Christie-hez.

WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

WiQL írása, javítása és optimalizálása a Copilot használatával

A WIQL-lekérdezések létrehozásához, javításához vagy optimalizálásához használhat AI-asszisztenst (például GitHub Copilotot vagy más copilots). Kezelje a Copilotot hatékonyságnövelő támogatásként – nem mérvadó forrásként –, és mindig tekintse át és tesztelje a létrehozott lekérdezéseket, mielőtt éles adatokon futtatja.

Útmutatás és ajánlott eljárások:

Képességek: A Copilot lefordíthatja az egyszerű nyelvi követelményeket WIQL-re, kijavíthatja a szintaxishibákat (nem egyező zárójelek, hiányzó vesszők, helytelen kulcsszavak), átalakíthatja a SELECT listákat a felhasználóbarát és a hivatkozásnevek között, záradékokat vagy dátumkonstansokat hozhat létre ASOF , és javaslatot tehet a záradék újraírására az eredményhalmazok szűkítéséhez vagy szélesítéséhez.
Ellenőrzés: Mindig ellenőrizze a létrehozott WIQL-t a Lekérdezésszerkesztőben vagy egy biztonságos tesztprojektben. Használat előtt ellenőrizze a makrókat (például @Me: @Today) és a területi beállításoktól függő dátumformátumokat.
Biztonság: Soha ne illessze be a titkos kulcsokat, a hozzáférési jogkivonatokat vagy a privát kapcsolati sztringeket a parancssorokba. Távolítsa el vagy módosítsa a Copilotnak betáplálandó példákban szereplő bizalmas értékeket.
Teljesítmény: Kérje meg a Copilot, hogy minimalizálja az eredmény hasznos adatait (csak a szükséges mezőket adja vissza), adjon hozzá megfelelő WHERE szűrőket, és kerülje a túl széles körű vagy a kötetlen IN keresések használatátLIKE. Jegyezze meg a WIQL-lekérdezések 32 K karakterkorlátját.
Éles esetek áttekintése: A korábbi (ASOF) lekérdezések, fa-/csatolású lekérdezések (FROM workItemLinks) és WAS EVER/EVER a korrektúrákat beolvasó operátorok viselkedésének megerősítése – ezek összetettebbek lehetnek, és manuális finomhangolásra lehet szükség.

Példa – WIQL létrehozása egyszerű angol nyelvből:

Kérdés: "A Fabrikam projektben hozzárendelt @Me és az elmúlt 30 napban módosított aktív hibák visszaküldési azonosítója és címe. Rendezés a ChangedDate desc szerint."

A Copilot a következőt állítja elő:

SELECT [System.Id], [System.Title]
FROM workitems
WHERE
  [System.TeamProject] = 'Fabrikam'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [System.ChangedDate] >= @Today - 30
ORDER BY [System.ChangedDate] DESC

WIQL-lekérdezések automatizálása REST API-val és AI-vel

A kétlépéses WIQL REST API-folyamat automatizálásához használhat AI-asszisztenseket, például a Copilotot:

A Query By Wiql REST API használatával lekérheti a WIQL-nek megfelelő munkaelem-azonosítókat.
A Munkaelemek lekérése API-val lekérheti az adott azonosítók teljes adatait.

Az AI a következő segítségére lehet:

Hozzon létre WIQL-t egyszerű nyelvről, majd láncolja a két API-hívást kódban (például Python, PowerShell vagy JavaScript).
Irányítópultok vagy jelentések eredményeinek formázása és összegzése.

Tip

A REST API részleteiért lásd: Query By Wiql (REST API).

Példa: WIQL automatizálása Pythonnal és AI-vel

Tegyük fel, hogy egy projekt összes aktív hibájának címét és állapotát listázni szeretné.

A Copilot kérése:
"Olyan Python-kód írása, amely az Azure DevOps REST API-val listázja a projekt összes aktív hibájának címét és állapotát. A WIQL használatával szerezze be az azonosítókat, majd kérje le az azonosítók részleteit."

A Copilot segítségével az alábbihoz hasonló kódot hozhat létre:

import requests

# Azure DevOps organization and project info
org = "your-org"
project = "your-project"
pat = "your-personal-access-token"
headers = {"Authorization": f"Basic {pat}"}

# Step 1: Run WIQL query to get work item IDs
wiql = {
    "query": """
        SELECT [System.Id]
        FROM workitems
        WHERE [System.TeamProject] = '{project}'
          AND [System.WorkItemType] = 'Bug'
          AND [System.State] = 'Active'
    """.format(project=project)
}
wiql_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/wiql?api-version=6.1-preview.2"
resp = requests.post(wiql_url, json=wiql, headers=headers)
ids = [item["id"] for item in resp.json()["workItems"]]

# Step 2: Get work item details
if ids:
    ids_str = ",".join(map(str, ids))
    details_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/workitemsbatch?api-version=6.1-preview.1"
    body = {"ids": ids, "fields": ["System.Title", "System.State"]}
    details_resp = requests.post(details_url, json=body, headers=headers)
    for item in details_resp.json()["value"]:
        print(f"{item['fields']['System.Title']} - {item['fields']['System.State']}")
else:
    print("No active bugs found.")

Visszacsatolás

Hasznos volt ez az oldal?

Last updated on 2025-12-17

Megosztás:

Munkaelem lekérdezési nyelvének szintaxisreferenciája

Prerequisites

A lekérdezés nyelvének áttekintése

Dátum- és időminta

Egyéni mezők

Szűrőzáradékok megadása (WHERE)

Szűrési feltételek

Operators

Logikai csoportosítások

Példa lekérdezésre, amelyhez valaha hozzá lett rendelve

Makrók vagy változók

@me makró

@today makró

@StartOfDay, @StartOfWeek, @StartOfMonthmakrók @StartOfYear

Egyéni makrók

Előzmény típusú lekérdezések megadása (ASOF)

Rendezési sorrend beállítása (ORDER BY)

Munkaelemek közötti hivatkozások lekérdezése

Példa fatípusú lekérdezésre

Példa közvetlen csatolású lekérdezésre

További lekérdezési példák

Dátum-idő minta

Példa záradékok

Sztring és egyszerű szöveg

Terület és iteráció (TreePath)

Módosítók és speciális operátorok

WiQL írása, javítása és optimalizálása a Copilot használatával

WIQL-lekérdezések automatizálása REST API-val és AI-vel

Kapcsolódó tartalom

Visszacsatolás

További források

Szűrőzáradékok megadása (`WHERE`)

`@me` makró

`@today` makró

`@StartOfDay`, `@StartOfWeek`, `@StartOfMonth`makrók `@StartOfYear`

Előzmény típusú lekérdezések megadása (`ASOF`)

Rendezési sorrend beállítása (`ORDER BY`)

Terület és iteráció (`TreePath`)