Udostępnij za pośrednictwem

Dokumentacja składni języka zapytań dla elementów roboczych (WIQL)

  • Artykuł

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

Składnia WIQL umożliwia zdefiniowanie zapytania jako hiperlinku lub użycie języka zapytań elementów roboczych (interfejs API REST).

Składnia WIQL obsługuje wszystkie funkcje dostępne za pośrednictwem portalu internetowego Edytor Power Query oraz kilka innych. Można określić pola, które mają być zwracane, i określać logiczne grupowanie klauzul zapytania. Ponadto można użyć klauzuli ASOF do filtrowania na podstawie przypisań na podstawie poprzedniej daty.

Ważne

Składnia WIQL służy do wykonywania interfejsu API REST Query By Wiql. Obecnie nie ma możliwości wywołania interfejsu API w celu zwrócenia szczegółowych informacji o elemencie roboczym bezpośrednio z zapytania WIQL. Niezależnie od pól uwzględnionych w instrukcji SELECT interfejs API zwraca tylko identyfikatory elementów roboczych. Aby uzyskać pełne informacje, należy wykonać dwa kroki: (1) uzyskać identyfikator elementów roboczych z WIQL, a (2) pobrać elementy robocze za pośrednictwem pozycji Pobierz listę elementów roboczych według identyfikatora i dla określonych pól.

Wymagania wstępne

Zapytanie zwraca tylko te elementy robocze, dla których masz uprawnienie Wyświetl elementy robocze lub Wyświetl elementy robocze w tym węźle. Zazwyczaj te uprawnienia są przyznawane członkom grup Czytelników i Współautorów dla każdego projektu zespołowego. Aby uzyskać więcej informacji, zobacz Uprawnienia i grupy.

Omówienie języka zapytań

Język zapytań elementów roboczych zawiera pięć części pokazanych w poniższym fragmencie składni i opisano je w poniższej tabeli. Składnia WIQL nie uwzględnia wielkości liter.

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

Napiwek

Po zainstalowaniu rozszerzenia Witryny Marketplace edytora Wiql można tworzyć zapytania przy użyciu Edytor Power Query, a następnie wyświetlić składnię WIQL. Następnie możesz skopiować i zmodyfikować składnię WIQL i uruchomić zapytanie przy użyciu centrum Wiql Playground dodanego do tablic.

Klauzula

Przykład

SELECT

Identyfikuje pola, które mają być zwracane dla każdego elementu roboczego zwróconego przez zapytanie. Możesz określić przyjazną nazwę lub nazwę odwołania. Użyj nawiasów kwadratowych ([]), jeśli nazwa zawiera wartości puste lub kropki.

FROM

Wskazuje, czy zapytanie ma znajdować elementy robocze, czy łącza między elementami roboczymi.

  • Użyj polecenia FROM WorkItems , aby zwrócić elementy robocze.
  • Służy FROM workItemLinks do zwracania łączy między elementami roboczymi. Aby uzyskać więcej informacji, zobacz Zapytania dotyczące linków między elementami roboczymi w dalszej części tego artykułu.

WHERE

Określa kryteria filtrowania zapytania. Aby uzyskać więcej informacji, zobacz Warunki filtrowania (WHERE) w dalszej części tego artykułu.

ORDER BY

Określa kolejność sortowania zwracanych elementów roboczych. Można określić rosnąco (Asc) lub Malejąco (Desc) dla co najmniej jednego pola. Na przykład:
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

Określa zapytanie historyczne, wskazując datę zastosowania filtru. Na przykład to zapytanie zwraca wszystkie scenariusze użytkownika, które zostały zdefiniowane jako Aktywne 11 lutego 2020 r. Określ datę zgodnie ze wskazówkami podanymi we wzorcu daty i godziny. ASOF '02-11-2020'

Uwaga

Długość zapytań WIQL wykonanych w usłudze Azure Boards nie może przekraczać 32K znaków. System nie umożliwia tworzenia ani uruchamiania zapytań przekraczających ten czas.

Wzorzec daty i godziny

Wzorzec daty i godziny wprowadzony dla pól DateTime powinien być zgodny z wzorcem wybranym przez profil. Aby wyświetlić lub zmienić wybór, zobacz Ustawianie preferencji użytkownika.

Zrzut ekranu przedstawiający opcje listy rozwijanej Wzorzec daty w okienku Czas i ustawienia regionalne.Zrzut ekranu przedstawiający opcje listy rozwijanej Wzorzec czasu w okienku Czas i ustawienia regionalne.

Zrzut ekranu przedstawiający okienko Czas i ustawienia regionalne z polami Wzorzec daty i Wzorzec godziny.

Cudzysłowy (cudzysłowy pojedyncze lub podwójne są obsługiwane) Literały daty/godziny używane w porównaniach. Muszą być w formacie .NET DateTime komputera klienckiego z uruchomionym zapytaniem. Jeśli nie określono strefy czasowej, literały DateTime znajdują się w strefie czasowej komputera lokalnego.

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

Gdy godzina zostanie pominięta w literału DateTime, a parametr dayPrecision jest równy false, przyjmuje się, że czas ma wartość zero (północ). Ustawieniem domyślnym parametru dayPrecision jest false.

Możesz też określić format ISO 8601, który jest prawidłowy niezależnie od ustawień regionalnych. Iso 8601 reprezentuje datę i godzinę, zaczynając od roku, a następnie miesiąc, dzień, godzinę, minuty, sekundy i milisekundy. Na przykład 2021-12-10 15:00:00.000 reprezentuje 10 grudnia 2021 r. o godzinie 15:00 w czasie lokalnym. Przykład użycia formatu ISO 8601 jest następujący.

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

Pola niestandardowe

Pole niestandardowe można dodać do klauzuli zapytania. W języku WIQL należy określić nazwę odwołania dla pola niestandardowego. W przypadku projektów korzystających z modelu procesów dziedziczonych pola niestandardowe są zwykle oznaczone etykietą Niestandardowy. Są one poprzedzane ich nazwą i usunięte spacje. Na przykład:

Przyjazna nazwa Nazwa odwołania
Osoba zatwierdzająca Custom.Approver
Typ żądania Custom.RequestType
Szacowanie zakresu Custom.CustomEstimate

W przypadku projektów korzystających z lokalnego modelu przetwarzania XML nazwa odwołania jest zdefiniowana przez definicje typu elementu roboczego XML.

Aby uzyskać więcej informacji, zobacz Pola i atrybuty elementu roboczego.

Określanie klauzul filtru (WHERE)

Klauzula WHERE określa kryteria filtrowania. Zapytanie zwraca tylko elementy robocze spełniające określone kryteria. Na przykład poniższa przykładowa WHERE klauzula zwraca aktywne scenariusze użytkownika i przypisane do Ciebie.

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

Możesz kontrolować kolejność oceniania operatorów logicznych, ujęcie ich w nawiasy w celu pogrupowania kryteriów filtrowania. Aby na przykład zwrócić elementy robocze przypisane do Ciebie lub zamknięte, zmień filtr zapytania, aby był zgodny z poniższym przykładem.

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

Warunki filtru

Każdy warunek filtru składa się z trzech części, z których każdy musi być zgodny z następującymi regułami:

  • Pole: możesz określić nazwę odwołania lub przyjazną nazwę. Następujące przykłady są prawidłową składnią WIQL:
    • Nazwa odwołania: SELECT [System.AssignedTo] ...
    • Przyjazna nazwa ze spacjami: SELECT [Assigned To] ...
    • Nazwy bez spacji nie wymagają nawiasów kwadratowych: SELECT ID, Title ...
  • Operator: Prawidłowe wartości są określone w sekcji Operatory w dalszej części tego artykułu.
  • Wartość pola: możesz określić jedną z następujących trzech wartości w zależności od określonego pola.
    • Wartość literału musi być zgodna z typem danych wartości pola.
    • *zmienna lub makro wskazujące określoną wartość. Na przykład @Me wskazuje osobę, która uruchamia zapytanie. Aby uzyskać więcej informacji, zobacz Makra i zmienne w dalszej części tego artykułu.
    • Nazwa innego pola. Możesz na przykład użyć [Assigned to] = [Changed by] polecenia , aby znaleźć elementy robocze przypisane do osoby, która ostatnio zmieniła element roboczy.

Aby uzyskać opis i nazwy odwołań dla wszystkich pól zdefiniowanych przez system, zobacz Indeks pola elementu roboczego.

Operatory

Zapytania używają wyrażeń logicznych do kwalifikowania zestawów wyników. Te wyrażenia logiczne są tworzone przez co najmniej jedną operację łączącą.

Poniżej wymieniono niektóre proste operacje zapytań.

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

Poniższa tabela zawiera podsumowanie wszystkich obsługiwanych operatorów dla różnych typów pól. Aby uzyskać więcej informacji na temat każdego typu pola, zobacz Pola i atrybuty elementu roboczego.

=, <>, >, <, >=, and <= Operatory działają zgodnie z oczekiwaniami. Na przykład System.ID > 100 zapytania dotyczące wszystkich elementów roboczych o identyfikatorze większym niż 100. System.ChangedDate > '01-01-19 12:00:00' zapytania dotyczące wszystkich elementów roboczych zostały zmienione po południu 1 stycznia 2019 r.

Poza tymi podstawowymi operatorami istnieją pewne zachowania i operatory specyficzne dla niektórych typów pól.

Uwaga

Dostępne operatory zależą od platformy i wersji. Aby uzyskać więcej informacji, zobacz Szybki dostęp do zapytań.

Typ pola

Obsługiwane operatory

Wartość logiczna

= , <> , =[Field] , <>[Field]

DateTime

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

Double, GUID, Integer

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

Tożsamość

= , <> , > , < , >= , <= , =[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

Grupowania logiczne

Możesz użyć terminów AND i OR w typowym sensie logicznym, aby ocenić dwie klauzule. Możesz użyć terminów AND EVER i OR EVER podczas określania WAS EVER operatora. Możesz grupować wyrażenia logiczne i dalej połączyć je zgodnie z potrzebami. Poniżej przedstawiono przykłady.

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

Operatory i można negować contains, under, przy użyciu polecenia not.in Nie można negować ever operatora. Poniższy przykład wykonuje zapytania dotyczące wszystkich elementów roboczych, które nie są przypisane w poddrzewie .Fabrikam Fiber\Account Management

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

Przykładowe zapytanie zostało kiedykolwiek przypisane do

Poniższy przykład Edytor Power Query znajduje wszystkie elementy robocze, które kiedykolwiek zostały przypisane do narzędzia Jamal Hartnett.

Zrzut ekranu przedstawiający Edytor Power Query, zapytanie listy płaskiej, które kiedykolwiek zostało przypisane.

A oto odpowiadająca składnia WIQL.

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

Makra lub zmienne

W poniższej tabeli wymieniono makra lub zmienne, których można użyć w zapytaniu WIQL.

Makro Użycie
@Me Ta zmienna służy do automatycznego wyszukiwania aliasu bieżącego użytkownika w polu zawierającym aliasy użytkownika. Możesz na przykład znaleźć elementy robocze, które zostały otwarte, jeśli ustawisz kolumnę Pole na Aktywowano według, kolumnę Operator na =, a kolumnę Value na @Me.
@CurrentIteration Ta zmienna umożliwia automatyczne filtrowanie elementów roboczych przypisanych do bieżącego przebiegu wybranego zespołu na podstawie wybranego kontekstu zespołu.
@Project Ta zmienna służy do wyszukiwania elementów roboczych w bieżącym projekcie. Na przykład możesz znaleźć wszystkie elementy robocze w bieżącym projekcie, jeśli ustawisz kolumnę Field na Team Project, kolumnę Operator na =, i kolumnę Value na @Project.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Użyj tych makr, aby filtrować pola DateTime na podstawie początku bieżącego dnia, tygodnia, miesiąca, roku lub przesunięcia na jedną z tych wartości. Możesz na przykład znaleźć wszystkie elementy utworzone w ciągu ostatnich 3 miesięcy, jeśli ustawisz kolumnę Pole na Wartość utworzona, kolumnę Operator na> =, a kolumnę Value na @StartOfMonth — 3.
@Today Ta zmienna służy do wyszukiwania elementów roboczych powiązanych z bieżącą datą lub datą wcześniejszą. Można również zmodyfikować zmienną @Today , odejmując dni. Możesz na przykład znaleźć wszystkie elementy aktywowane w ostatnim tygodniu, jeśli ustawisz kolumnę Pole na Aktywowana data, kolumnę Operator na >=, a kolumnę Value na @Today — 7.
[Dowolny] Użyj tej zmiennej, aby wyszukać elementy robocze powiązane z dowolną wartością zdefiniowaną dla określonego pola.

@me Makro

Makro @me zastępuje nazwę zintegrowanego konta systemu Windows użytkownika, który uruchamia zapytanie. W poniższym przykładzie pokazano, jak używać makra i równoważnej instrukcji statycznej. Makro jest przeznaczone do użycia z polami tożsamości, takimi jak Assigned To.

WHERE  
   [System.AssignedTo] = @Me

@today Makro

Możesz użyć makra @today z dowolnym polem DateTime . To makro zastępuje północ bieżącej daty na komputerze lokalnym, na który jest uruchamiane zapytanie. Można również określić @today+x lub @today-y użyć przesunięć liczb całkowitych dla x dni po @today i y dni przed @today, odpowiednio. Zapytanie korzystające z @today makra może zwracać różne zestawy wyników w zależności od strefy czasowej, w której jest uruchamiana.

W poniższych przykładach przyjęto założenie, że dzisiaj jest to 1/3/19.

WHERE  
   [System.CreatedDate] = @today

Jest odpowiednikiem:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Jest odpowiednikiem:

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

@StartOfDay, , @StartOfWeek, @StartOfYear @StartOfMonth, makra

Makra można używać @StartOf... z dowolnym polem DateTime . To makro zastępuje północ bieżącego dnia, początek tygodnia, początek miesiąca lub początek roku na komputerze lokalnym, na który jest uruchamiane zapytanie.

Uwaga

Wymaga usługi Azure DevOps Server 2019 Update 1 lub nowszej wersji.

Te makra akceptują ciąg modyfikatora, który ma format (+/-)nn(y|M|w|d|h|m). Podobnie jak w makrze @Today , można określić przesunięcia plusa lub minus liczby całkowitej. Jeśli kwalifikator jednostki czasowej zostanie pominięty, domyślnie jest to naturalny okres funkcji. Na przykład kod @StartOfWeek("+1") jest taki sam jak kod @StartOfWeek("+1w"). Jeśli znak plus/minus (+/-) zostanie pominięty, przyjmuje się plus.

Ta składnia umożliwia zagnieżdżanie modyfikatorów i przesunięcie zapytania dwa razy. Na przykład klauzula Closed Date >= @StartOfYear - 1, filtruje elementy robocze, które zostały zamknięte od ubiegłego roku. Modyfikując go na Closed Date >= @StartOfYear('+3M') - 1, wyklucza elementy robocze zamknięte w ciągu pierwszych trzech miesięcy ostatniego roku. Składnia WIQL jest pokazana w poniższym przykładzie.

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

W poniższych przykładach przyjęto założenie, że dzisiaj jest to 4/5/19.

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

Jest odpowiednikiem:


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

And

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

Jest odpowiednikiem:

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

Makra niestandardowe

WIQL obsługuje również dowolne makra niestandardowe. Każdy ciąg poprzedzony prefiksem @ elementu jest traktowany jako makro niestandardowe i zostaje zastąpiony. Wartość zastępcza makra niestandardowego jest pobierana z parametru kontekstu metody zapytania w modelu obiektów. Następująca metoda to interfejs API używany w makrach:

public WorkItemCollection Query(string wiql, IDictionary context)

Parametr kontekstu zawiera pary klucz-wartość dla makr. Jeśli na przykład kontekst zawiera parę klucz-wartość (projekt, MyProject), @project zostanie zamienieni na MyProject WIQL. To zastąpienie polega na tym, jak konstruktor zapytań elementu roboczego obsługuje makro @project w programie Visual Studio.

Określanie zapytań historycznych (ASOF)

Klauzulę ASOF w zapytaniu można użyć do filtrowania elementów roboczych spełniających określone warunki filtrowania zgodnie z określonymi datami i godzinami.

Uwaga

Nie można tworzyć ASOF zapytań w konstruktorze zapytań w programie Visual Studio. Jeśli tworzysz plik zapytania (.wiq), który zawiera klauzulę ASOF , a następnie załadujesz go w programie Visual Studio, klauzula ASOF zostanie zignorowana.

Załóżmy, że element roboczy został sklasyfikowany pod ścieżką iteracji elementu Fabrikam Fiber\Release 1 i przypisany do elementu "Jamal Hartnett" przed 5.05.2022 r. Jednak element roboczy został niedawno przypisany do "Raisa Pokrovskaya" i przeniósł się do nowej ścieżki iteracji wydania 2. Poniższe przykładowe zapytanie zwraca elementy robocze przypisane do narzędzia Jamal Hartnett, ponieważ zapytanie jest oparte na stanie elementów roboczych od poprzedniej daty i godziny.

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-2022 00:00:00.0000000'

Uwaga

Jeśli nie określono czasu, WIQL używa północy. Jeśli strefa czasowa nie zostanie określona, WIQL używa strefy czasowej lokalnego komputera klienckiego.

Ustawianie kolejności sortowania (ORDER BY)

Możesz użyć ORDER BY klauzuli , aby posortować wyniki zapytania według jednego lub większej liczby pól w kolejności rosnącej lub malejącej.

Uwaga

Preferencje sortowania programu SQL Server w warstwie danych określają domyślną kolejność sortowania. Można jednak użyć asc parametrów lub desc , aby wybrać jawną kolejność sortowania.

Poniższy przykład sortuje elementy robocze najpierw według priorytetu w kolejności rosnącej (wartość domyślna), a następnie według daty utworzenia w kolejności malejącej (DESC).

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

Aby zwrócić łącza między elementami roboczymi, należy określić wartość FROM WorkItemLinks. Warunki filtrowania w klauzuli WHERE mogą mieć zastosowanie do linków lub do dowolnego elementu roboczego, który jest źródłem lub elementem docelowym łącza. Na przykład następujące zapytanie zwraca łącza między elementami listy prac produktu i ich aktywnymi elementami podrzędnymi.

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'
    )
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC
MODE (Recursive)

W poniższej tabeli przedstawiono podsumowanie różnic między zapytaniami elementów roboczych a zapytaniami dotyczącymi łączy między elementami roboczymi.

Klauzula

Elementy robocze

Łącza między elementami roboczymi

FROM

FROM WorkItems

FROM WorkItemLinks

WHERE

[FieldName] = Value

Specify one or more of the following:
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'

MODE

nie dotyczy

Określ jedną z następujących opcji:

  • MODE (MustContain): (Ustawienie domyślne) Zwraca tylko rekordy WorkItemLinkInfo, w których wszystkie kryteria źródła, elementu docelowego i linku są spełnione.
  • MODE (MayContain): zwraca rekordy WorkItemLinkInfo dla wszystkich elementów roboczych spełniających kryteria źródła i łącza, nawet jeśli żaden połączony element roboczy nie spełnia kryteriów docelowych.
  • MODE (DoesNotContain): Zwraca rekordy WorkItemLinkInfo dla wszystkich elementów roboczych, które spełniają źródło, tylko wtedy, gdy żaden połączony element roboczy nie spełnia kryteriów linku i celu.
  • MODE (Recursive): służy do obsługi zapytań drzewa([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). Typ łącza musi być topologią drzewa i kierunku do przodu. Zwraca rekordy WorkItemLinkInfo dla wszystkich elementów roboczych, które spełniają źródło, rekursywnie dla elementu docelowego. ORDER BY i ASOF nie są zgodne z zapytaniami drzewa.

RETURNS

WorkItemQueryResult

WorkItemLink

Można określić jedną z następujących nazw typów łączy systemowych.

Możesz określić jedną z nazw typów linków systemowych wymienionych poniżej lub niestandardowy typ linku zdefiniowany przy użyciu lokalnego procesu XML.

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

Aby uzyskać więcej informacji, zobacz Link type reference (Dokumentacja typu łącza).

Przykład zapytania typu drzewa

Poniższe zapytanie zwraca wszystkie typy elementów roboczych zdefiniowane w bieżącym projekcie. Zapytanie, jak pokazano na Edytor Power Query, jest wyświetlane, jak pokazano na poniższej ilustracji.

Zrzut ekranu przedstawiający Edytor Power Query, zapytanie drzewa, wszystkie elementy robocze i stany.

Równoważna składnia WIQL jest pokazana poniżej.

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)

Poniższe zapytanie zwraca wszystkie typy elementów roboczych zdefiniowane w bieżącym projekcie. Zapytanie, jak pokazano na Edytor Power Query, jest wyświetlane, jak pokazano na poniższej ilustracji.

Zrzut ekranu przedstawiający Edytor Power Query, zapytanie bezpośrednie, wszystkie elementy robocze i stany.

Równoważna składnia WIQL jest pokazana.

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)

Więcej przykładów zapytań

Poniższy typowy przykład zapytania WIQL używa nazw odwołań dla pól. Zapytanie wybiera elementy robocze (nie określono typu elementu roboczego) z priorytetem =1. Zapytanie zwraca identyfikator i tytuł zestawu zwracanego jako kolumny. Wyniki są sortowane według identyfikatora w kolejności rosnącej.

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

Wzorzec daty i godziny

Wzorzec daty i godziny określa się zgodnie z jednym z dwóch wzorców:

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

Przykładowe klauzule

Poniższe przykładowe instrukcje pokazują określone klauzule kwalifikacyjne.

Klauzula

Przykład

AND

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

OR

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND ( [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR [System.AssignedTo] = ''Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>' )

NOT

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'

EVER

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

UNDER

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AreaPath] UNDER 'Agile1\Area 0'

ORDER BY

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [System.Id] [asc | desc]

ASOF (Filtr czasu)

SELECT [System.Title] 
FROM workitems 
WHERE [System.IterationPath] = 'MyProject\Beta' 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>' 
ASOF '3/16/19 12:30'

Ciąg i zwykły tekst

Literały ciągu cudzysłowu (obsługiwane są cudzysłowy pojedyncze lub podwójne) w porównaniu z ciągiem lub polem zwykłego tekstu. Literały ciągu obsługują wszystkie znaki Unicode.

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

Możesz użyć operatora contains, aby wyszukać podciąg w dowolnym miejscu w wartości pola.

WHERE [System.Description] contains 'WIQL'

Obszar i iteracja (TreePath)

Możesz użyć UNDER operatora dla pól Area (Obszar) i Iteration Path (Ścieżka iteracji). Operator UNDER ocenia, czy wartość znajduje się w poddrzewie określonego węzła klasyfikacji. Na przykład poniższe wyrażenie zwróci wartość true, jeśli ścieżka obszaru to "MyProject\Server\Administration", "MyProject\Server\Administration\Feature 1", "MyProject\Server\Administration\Feature 2\SubFeature 5" lub jakikolwiek inny węzeł w poddrzewie.

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

Modyfikatory i operatory specjalne

W wyrażeniu zapytania można użyć niektórych modyfikatorów i operatorów specjalnych.

IN Użyj operatora , aby ocenić, czy wartość pola jest równa dowolnemu zestawowi wartości. Ten operator jest obsługiwany dla typów pól String, Integer, Double i DateTime. Zobacz poniższy przykład wraz z jego semantycznym odpowiednikiem.

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

Operator EVER służy do oceny, czy wartość pola jest równa, czy kiedykolwiek równa określonej wartości we wszystkich poprzednich poprawkach elementów roboczych. Typy pól String, Integer, Double i DateTime obsługują ten operator. Dla operatora istnieją alternatywne składnie EVER . Na przykład poniższe fragmenty kodu umożliwiają określenie, czy wszystkie elementy robocze były kiedykolwiek przypisane do narzędzia Jamal, Raise lub Christie.

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