İş Öğesi Sorgulama Dili (WIQL) söz dizimi başvurusu

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

WiQL söz dizimini kullanarak sorguyu köprü olarak veya İş Öğesi Sorgu Dili (REST API) kullanırken tanımlayabilirsiniz.

WIQL, web portalı üzerinden sağlanan tüm işlevleri Query Editor ve birkaçını daha destekler. Döndürülecek alanları ve sorgu yan tümcelerinin mantıksal gruplandırmalarını belirtebilirsiniz. Önceki bir tarihten itibaren atamalara göre filtrelemek için bir yan tümce de kullanabilirsiniz ASOF .

Tip

Bu makalenin devamında AI kullanarak bu göreve yardımcı olabilirsiniz veya başlamak için Azure DevOps MCP Server ile yapay zeka yardımı sağlama konusuna bakın.

Important

WIQL söz dizimi, Wiql TARAFıNDAN Sorgu REST API'sini yürütmek için kullanılır. API, deyimine hangi alanları dahil SELECT ettiğinize bakılmaksızın yalnızca iş öğesi kimliklerini döndürür. Tam bilgi almak için (1) WIQL'den kimlikleri alın, sonra (2) İş öğelerinin kimliğini ve belirli alanları içeren listeyi alma yoluyla alın.

Prerequisites

Category Requirements
İzinler İş öğelerini görüntüleme veya Bu düğümdeki iş öğelerini görüntüleme izin İzin verolarak ayarlanır. Bu izinler genellikle her takım projesi için Okuyucular ve Katkıda Bulunanlar gruplarının üyelerine verilir. Daha fazla bilgi için bkz . İzinler ve gruplar.

Sorgu diline genel bakış

WIQL, aşağıdaki söz dizimi kod parçacığında gösterildiği gibi ve tabloda açıklandığı gibi beş bölümden oluşur. WIQL söz dizimi büyük/küçük harfe duyarlı değildir.

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

Wiql Editor Marketplace uzantısını yükleyerek Query Editor kullanarak sorgular oluşturabilir ve WIQL söz dizimini görüntüleyebilirsiniz. Ardından WIQL söz dizimini kopyalayıp değiştirebilir ve Boards'a eklenen Wiql Playground hub'ını kullanarak sorguyu çalıştırabilirsiniz.

Cümlecik Örnek/Açıklama
SELECT Her iş öğesi için döndürülecek alanları tanımlar. Kolay adı veya başvuru adını belirtebilirsiniz. Ad boşluk veya nokta içeriyorsa köşeli ayraç ([]) kullanın.
FROM Sorgunun iş öğelerini mi yoksa iş öğeleri arasındaki bağlantıları mı bulmasını istediğinizi gösterir.
- İş öğelerini döndürmek için kullanın FROM WorkItems .
- İş öğeleri arasındaki bağlantıları döndürmek için kullanın FROM workItemLinks . Daha fazla bilgi için bkz. İş öğeleri arasındaki bağlantılar için sorgular.
WHERE Sorgu için filtre ölçütlerini belirtir. Daha fazla bilgi için bkz . Filtreleme koşulları (WHERE).
ORDER BY Döndürülen iş öğelerinin sıralama düzenini belirtir. Bir veya daha fazla alan için Artan (Asc) veya Azalan (Desc) belirtebilirsiniz. Örneğin: ORDER BY [State] Asc, [Changed Date] Desc
ASOF Filtrenin uygulanacağı tarihi belirterek geçmiş sorguyu belirtir. Örneğin, bu sorgu 11 Şubat 2025'te Etkin olarak tanımlanan tüm kullanıcı hikayelerini döndürür. Tarih ve saat düzeninde sağlanan kılavuza göre tarihi belirtin.
ASOF '02-11-2025'

Note

Azure Boards için yapılan WIQL sorguları 32-K karakterden fazla olmamalıdır. Sistem, bu uzunluğu aşan sorgular oluşturmanıza veya çalıştırmanıza izin vermez.

Tarih ve saat düzeni

DateTime alanları için girdiğiniz tarih ve saat deseni, profiliniz aracılığıyla seçtiğiniz tarih ve saat düzeniyle eşleşmelidir. Seçiminizi görüntülemek veya değiştirmek için bkz . Kullanıcı tercihlerini ayarlama.

Saat ve Yerel Ayar bölmesinde tarih düzeni açılan seçeneklerini gösteren ekran görüntüsü. Saat ve Yerel Ayar bölmesindeki Zaman Düzeni açılan seçeneklerini gösteren ekran görüntüsü.

Tarih deseni ve Saat deseni alanlarını içeren Saat ve Yerel Ayar bölmesini gösteren ekran görüntüsü.

Karşılaştırmalarda kullanılan tırnak (tek veya çift tırnak desteklenir) DateTime değişmez değerleri. Sorguyu çalıştıran yerel istemci bilgisayarın .NET DateTime biçiminde olmalıdır. Saat dilimi belirtilmediği sürece değişmez DateTime değerler yerel bilgisayarın saat dilimindedir.

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

Saat sabit değerde DateTime atlandığında ve dayPrecision parametre false değerine eşitse, saat sıfır (gece yarısı) olarak kabul edilir. parametresi için dayPrecision varsayılan ayar false'tur.

Alternatif olarak, yerel ayar ne olursa olsun geçerli olan ISO 8601 biçimini belirtebilirsiniz. ISO 8601 yılla başlayıp ay, gün, saat, dakikalar, saniyeler ve milisaniyelerle tarih ve saati temsil eder. Örneğin, 2025-12-10 15:00:00.000 10 Aralık 2025'i yerel saatle 15:00'te temsil eder. ISO 8601 biçimini kullanma örneği aşağıdaki gibidir:

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

Özel alanlar

Sorgu yan tümcesine özel alan ekleyebilirsiniz. WIQL ile özel alan için başvuru adını belirtmeniz gerekir. Devralınan işlem modeli kullanan projeler için özel alanlar genellikle adlarına ekli olarak Custom. etiketlenir ve boşluklar kaldırılır. Örneğin:

Dostça isim Başvuru adı
Approver Custom.Approver
Request Type Custom.RequestType
Scope Estimate Custom.CustomEstimate

Şirket içi XML işlem modelini kullanan projeler için başvuru adı XML iş öğesi türü tanımları tarafından tanımlanır.

Daha fazla bilgi için bkz . İş öğesi alanları ve öznitelikleri.

Filtre yan tümcelerini belirtme (WHERE)

WHERE yan tümcesi filtre ölçütlerini belirtir. Sorgu yalnızca belirtilen ölçütleri karşılayan iş öğelerini döndürür. Örneğin, aşağıdaki örnek WHERE yan tümcesi etkin olan ve size atanan kullanıcı öykülerini döndürür.

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

Filtre ölçütlerini gruplandırmak için, mantıksal işleçleri parantez içine alarak hangi sırada değerlendirileceklerini denetleyebilirsiniz. Örneğin, size atanmış veya kapattığınız iş öğelerini döndürmek için aşağıdaki örneği kullanın.

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

Filtre koşulları

Her filtre koşulu, her biri aşağıdaki kurallara uyması gereken üç bölümden oluşur:

  • Alan: Başvuru adını veya kolay adı belirtebilirsiniz. Aşağıdaki örnekler geçerli WIQL söz dizimidir:
    • Başvuru adı: SELECT [System.AssignedTo] ...
    • Boşluklu kolay ad: SELECT [Assigned To] ...
    • Boşluk içermeyen adlar köşeli ayraç gerektirmez: SELECT ID, Title ...
  • İşleç: Bu makalenin devamında İşleçler bölümünde geçerli değerler belirtilir.
  • Alan değeri: Belirtilen alana bağlı olarak aşağıdaki üç değerden birini belirtebilirsiniz.
    • Değişmez değer, alan değerinin veri türüyle eşleşmelidir.
    • Belirli bir değeri gösteren değişken veya makro. Örneğin, @Me sorguyu çalıştıran kişiyi gösterir. Daha fazla bilgi için bkz. Makrolar ve değişkenler.
    • Başka bir alanın adı. Örneğin, iş öğesini en son değiştiren kişiye atanmış iş öğelerini bulmak için kullanabilirsiniz [Assigned to] = [Changed by] .

Sistem tanımlı tüm alanların açıklaması ve başvuru adları için bkz . İş öğesi alan dizini.

Operators

Sorgular, sonuç kümelerini nitelerken mantıksal ifadeler kullanır. Bu mantıksal ifadeler bir veya daha fazla birleştirilmiş işlemle oluşur.

Bazı basit sorgu işlemleri şunlardır:

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

Aşağıdaki tabloda, farklı alan türleri için desteklenen tüm işleçler özetlenmektedir. Her alan türü hakkında daha fazla bilgi için bkz . İş öğesi alanları ve öznitelikleri.

=, , <>, >, <, >=ve <= işleçleri beklendiği gibi çalışır. Örneğin, System.ID > 100 100'den büyük tüm iş öğeleri ID için sorgular. System.ChangedDate > '01-01-25 12:00:00' tüm iş öğeleri için sorgular 1 Ocak 2025'in öğlenden sonra değiştirildi.

Bu temel işleçlerin ötesinde, belirli alan türlerine özgü bazı davranışlar ve işleçler vardır.

Note

Kullanabileceğiniz operatörler, platformunuza ve sürümünüze bağlıdır. Daha fazla bilgi için bkz . Sorgu hızlı başvurusu.

Alan türü Desteklenen operatörler
Boolean = , <> , =[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
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

Mantıksal gruplandırmalar

İki yan tümceyi AND değerlendirmek için ve OR genel anlamda Boole terimlerini kullanabilirsiniz. Bir işleç belirtirken ve AND EVER terimlerini OR EVERWAS EVER kullanabilirsiniz. Mantıksal ifadeleri gruplandırabilir ve gerektiğinde daha fazla birleştirebilirsiniz. Aşağıdaki örneklerde gösterilmiştir.

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

kullanarak contains, underve in işleçlerini olumsuzlayabilirsiniznot. İşleci olumsuzlayamazsınız ever . Aşağıdaki örnek, alt ağacı altında atanmamış tüm iş öğelerini sorgular Fabrikam Fiber\Account Management.

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

Örnek sorgu, Hiç Atandı

Aşağıdaki Query Editor örnek, Jamal Hartnett'a atanmış olan tüm iş öğelerini bulur.

Ekli liste sorgusu Query Editor ekran görüntüsü hiç atandı.

Karşılık gelen WIQL söz dizimi aşağıdaki gibidir:

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

Makrolar veya değişkenler

Aşağıdaki tabloda, BIR WIQL sorgusunda kullanabileceğiniz makrolar veya değişkenler listelenir.

Macro Usage
@Me Kullanıcı diğer adlarını içeren bir alanda geçerli kullanıcının diğer adını otomatik olarak aramak için bu değişkeni kullanın. Örneğin, sütununu olarak, sütununu olarak ve FieldActivated Bysütununu Operator=Value@Meolarak ayarlarsanız açtığınız iş öğelerini bulabilirsiniz.
@CurrentIteration Seçili ekip bağlamını temel alarak seçili ekip için geçerli sprint'e atanan iş öğelerini otomatik olarak filtrelemek için bu değişkeni kullanın.
@Project Geçerli projedeki iş öğelerini aramak için bu değişkeni kullanın. Örneğin, sütununu olarak, sütununu olarak ve sütununu FieldTeam ProjectOperator= olarak ayarlarsanız, geçerli projedeki Value@Projecttüm iş öğelerini bulabilirsiniz.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Geçerli gün, hafta, ay, yıl veya bu değerlerden birine uzaklık temelinde alanları filtrelemek DateTime için bu makroları kullanın. Örneğin, sütunu FieldCreated DateOperator>=Value olarak ayarlarsanız@StartOfMonth - 3, son üç ay içinde oluşturulan tüm öğeleri bulabilirsiniz.
@Today Geçerli tarihle veya önceki bir tarihle ilişkili iş öğelerini aramak için bu değişkeni kullanın. Ayrıca, günleri çıkararak değişkeni değiştirebilirsiniz @Today . Örneğin, sütunu FieldActivated DateOperator>=Value olarak ayarlarsanız@Today - 7, geçen hafta etkinleştirilen tüm öğeleri bulabilirsiniz.
[Any] Belirli bir alan için tanımlanan herhangi bir değerle ilişkili iş öğelerini aramak için bu değişkeni kullanın.

@me Makro

@me makro, sorguyu çalıştıran kullanıcının Windows Tümleşik hesap adının yerini alır. Aşağıdaki örnekte makronun ve eşdeğer statik deyiminin nasıl kullanılacağı gösterilmektedir. Makro, gibi Assigned Tokimlik alanlarıyla kullanılmak üzere tasarlanmıştır.

WHERE  
   [System.AssignedTo] = @Me

@today Makro

Makroyu @today herhangi bir DateTime alanla kullanabilirsiniz. Bu makro, sorguyu çalıştıran yerel bilgisayarda geçerli tarihin gece yarısının yerini alır. Ayrıca, sırasıyla x gün sonrası @today+x ve y gün öncesi @today-yiçin tamsayı uzaklıkları belirtebilir @today veya @today kullanabilirsiniz. Makroyu @today kullanan bir sorgu, çalıştırıldığı saat dilimine bağlı olarak farklı sonuç kümeleri döndürebilir.

Aşağıdaki örneklerde bugünün 3/1/2025 olduğu varsayılır.

WHERE  
   [System.CreatedDate] = @today

Eşdeğeri:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Eşdeğeri:

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

@StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear makrolar

Makroları herhangi bir @StartOf... alanla kullanabilirsinizDateTime. Bu makro, sorguyu çalıştıran yerel bilgisayarda geçerli günün, haftanın başlangıcının, ayın başlangıcının veya yılın başlangıcının yerini alır.

Bu makrolar biçiminde (+/-)nn(y|M|w|d|h|m)bir değiştirici dize kabul eder. Makroya @Today benzer şekilde, artı veya eksi tamsayı uzaklıklarını belirtebilirsiniz. Zaman birimi niteleyicisi atlanırsa, varsayılan olarak işlevin doğal süresine ayarlanır. Örneğin @StartOfWeek("+1") ile @StartOfWeek("+1w") aynıdır. Artı/eksi (+/-) işareti atlanırsa, artı varsayılır.

Bu söz dizimi, değiştiricileri iç içe yerleştirmenize ve sorgunuzu iki kez kaydırmanıza olanak tanır. Örneğin, yan tümcesi Closed Date >= @StartOfYear - 1 geçen yıldan bu yana kapatılan iş öğelerini filtreler. olarak Closed Date >= @StartOfYear('+3M') - 1değiştirdiğinizde, geçen yılın ilk üç ayı içinde kapatılan iş öğelerini dışlar. Aşağıdaki WIQL söz dizimi aşağıdakileri gösterir:

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

Aşağıdaki örneklerde bugünün 5/4/2025 olduğu varsayılır.

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

Eşdeğeri:

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

And

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

Eşdeğeri:

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

Özel makrolar

WIQL ayrıca rastgele özel makroları da destekler. tarafından önekli herhangi bir @ dize özel makro olarak kabul edilir ve yerine geçer. Özel makronun değiştirme değeri, nesne modelindeki sorgu yönteminin bağlam parametresinden alınır. Aşağıdaki yöntem, makrolar için kullanılan API'dir:

public WorkItemCollection Query(string wiql, IDictionary context)

Bağlam parametresi makrolar için anahtar-değer çiftleri içerir. Örneğin, bağlam bir anahtar-değer çifti (project, MyProject) @project içeriyorsa WIQL'de ile MyProject değiştirilir. Bu değişiklik, iş öğesi sorgu oluşturucusunun Visual Studio @project makrosunu işleme şeklidir.

Geçmiş sorguları belirtme (ASOF)

Belirli bir ASOF tarih ve saatte tanımlandığı gibi belirtilen filtre koşullarını karşılayan iş öğelerini filtrelemek için sorgudaki bir yan tümceyi kullanabilirsiniz.

Note

Visual Studio'da sorgu oluşturucusunda ASOF sorguları oluşturamazsınız. ASOF yan tümcesi içeren bir sorgu dosyası (.wiq) oluşturur ve bunu Visual Studio yüklerseniz, ASOF yan tümcesi yoksayılır.

Bir iş öğesinin 05.05.2025'e kadar 'Jamal Hartnett' kapsamında sınıflandırıldığını Iteration PathFabrikam Fiber\Release 1 ve bu öğeye atandığını varsayalım. Ancak, iş öğesi kısa süre önce 'Raisa Pokrovskaya'ya atandı ve Sürüm 2'nin yeni bir yineleme yoluna taşındı. Aşağıdaki örnek sorgu Jamal Hartnett'e atanan iş öğelerini döndürür çünkü sorgu geçmiş bir tarih ve saat itibarıyla iş öğelerinin durumunu temel alır.

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

Zaman belirtilmezse, WIQL gece yarısını kullanır. Saat dilimi belirtilmezse, WIQL yerel istemci bilgisayarın saat dilimini kullanır.

Sıralama düzenini ayarlama (ORDER BY)

Bir sorgunun ORDER BY sonuçlarını artan veya azalan düzende bir veya daha fazla alana göre sıralamak için yan tümcesini kullanabilirsiniz.

Note

Veri katmanındaki SQL sunucusunun sıralama tercihleri, varsayılan sıralama düzenini belirler. Ancak, açık bir sıralama düzeni seçmek için veya asc parametrelerini kullanabilirsinizdesc.

Aşağıdaki örnek, iş öğelerini önce Priority artan düzende (varsayılan) ve ardından Created Date azalan düzende (DESC ) sıralar.

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

İş öğeleri arasındaki bağlantıları döndürmek için belirtin FROM WorkItemLinks. Yan tümcesindeki WHERE filtre koşulları, bağlantılara veya bağlantının kaynağı veya hedefi olan herhangi bir iş öğesine uygulanabilir. Aşağıdaki örnek, ve bunların etkin alt öğeleri arasındaki Product Backlog Items bağlantıları döndürür.

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)

Aşağıdaki tabloda, iş öğeleri arasındaki bağlantılar için iş öğesi sorguları ile sorgular arasındaki farklar özetlemektedir.

Cümlecik İş öğeleri İş öğeleri arasındaki bağlantılar
FROM FROM WorkItems FROM WorkItemLinks
WHERE [FieldName] = Value Aşağıdakilerden birini veya birkaçını belirtin:
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'
MODE uygulanamaz Aşağıdakilerden birini belirtin:
- MODE (MustContain): (Varsayılan) Yalnızca WorkItemLinkInfo kaynak, hedef ve bağlantı ölçütlerinin tümünün karşılandığı kayıtları döndürür.
- MODE (MayContain): Hiçbir bağlı iş öğesi hedef ölçütleri karşılamasa bile kaynak ve bağlantı ölçütlerini karşılayan tüm iş öğelerinin kayıtlarını döndürür WorkItemLinkInfo .
- MODE (DoesNotContain): Yalnızca bağlantılı iş öğesi bağlantıyı ve hedef ölçütleri karşılamazsa, kaynağı karşılayan tüm iş öğelerinin kayıtlarını döndürür WorkItemLinkInfo .
- MODE (Recursive): Ağaç sorguları[System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward' () için kullanın. Bağlantı türü Ağaç topolojisi ve ileri yönde olmalıdır. Kaynağı karşılayan tüm iş öğelerinin kayıtlarını, hedef için özyinelemeli olarak döndürür WorkItemLinkInfo . ORDER BY ve ASOF ağaç sorguları ile uyumlu değildir.
RETURNS WorkItemQueryResult WorkItemLink

Aşağıdaki sistem bağlantı türü adlarından birini belirtebilirsiniz.

Aşağıdaki sistem bağlantı türü adlarından birini veya şirket içi XML işlemiyle tanımlanan özel bağlantı türünü belirtebilirsiniz.

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

Daha fazla bilgi için bkz . Bağlantı türü başvurusu.

Ağaç türü sorgu örneği

Note

ORDER BY ve ASOF ağaç sorguları ile uyumlu değildir. Bu yan tümceleri ağaç sorgularına eklemeyin.

Aşağıdaki sorgu, geçerli projede tanımlanan tüm iş öğesi türlerini döndürür. Query Editor sorguyu aşağıdaki görüntüde gösterildiği gibi görüntüler.

Query Editor ekran görüntüsü, ağaç sorgusu, tüm iş öğeleri ve states.

Eşdeğer WIQL söz dizimi aşağıdaki gibidir:

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)

Aşağıdaki örnek, geçerli projede tanımlanan tüm iş öğesi türlerini döndürür. Query Editor sorguyu aşağıdaki görüntüde gösterildiği gibi görüntüler.

Query Editor ekran görüntüsü, doğrudan bağlantı sorgusu, tüm iş öğeleri ve states.

Eşdeğer WIQL söz dizimi aşağıdaki gibidir:

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)

Diğer sorgu örnekleri

Aşağıdaki tipik WIQL sorgu örneği, alanlar için başvuru adlarını kullanır. Sorgu, ile Priority=1iş öğelerini (iş öğesi türü belirtilmemiş) seçer. Sorgu, dönüş kümesinin ve ID sütunlarını döndürürTitle. Sonuçlar artan düzende sıralanır 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]

Tarih-saat düzeni

Tarih-saat desenini iki desenden birine göre belirtirsiniz:

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

Örnek yan tümceler

Aşağıdaki örnek deyimler belirli niteleme yan tümcelerini gösterir.

Cümlecik 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 (Zaman filtresi)
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'

Dize ve Düz Metin

Veya String alanıyla PlainText karşılaştırmada tırnak dizesi değişmez değerleri (tek veya çift tırnak desteklenir). Dize değişmez değerleri tüm Unicode karakterlerini destekler.

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

Alan değerinin contains herhangi bir yerinde alt dize aramak için işlecini kullanabilirsiniz.

WHERE [System.Description] contains 'WIQL'

Alan ve Yineleme (TreePath)

ve UNDER alanları için işlecini Area Path kullanabilirsinizIteration Path. işleci UNDER , bir değerin belirli bir sınıflandırma düğümünün alt ağacı içinde olup olmadığını değerlendirir. Örneğin, aşağıdaki ifade , , Area PathMyProject\Server\Administrationveya alt ağaç içindeki başka bir düğümse MyProject\Server\Administration\Feature 1MyProject\Server\Administration\Feature 2\SubFeature 5true olarak değerlendirilir.

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

Değiştiriciler ve özel işleçler

Sorgu ifadesinde bazı değiştiricileri ve özel işleçleri kullanabilirsiniz.

Bir alan değerinin IN herhangi bir değer kümesine eşit olup olmadığını değerlendirmek için işlecini kullanın. Bu işleç , , StringIntegerve Double alan türleri için DateTimedesteklenir. Aşağıdaki örnek ve semantik eşdeğeri bunu göstermektedir.

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

işleci EVER , iş öğelerinin tüm geçmiş düzeltmeleri boyunca bir alan değerinin belirli bir değere eşit olup olmadığını değerlendirmek için kullanılır. String, Integer, Doubleve DateTime alan türleri bu işleci destekler. İşleç için EVER alternatif söz dizimleri vardır. Örneğin, aşağıdaki kod parçacıkları tüm iş öğelerinin Jamal, Raisa veya Christie'ye atanıp atanmadığını sorgular.

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 yazmak, düzeltmek ve iyileştirmek için Copilot kullanma

WIQL sorguları oluşturmaya, düzeltmeye veya iyileştirmeye yardımcı olmak için yapay zeka yardımcısını (örneğin, GitHub Copilot veya diğer yardımcı pilotlar) kullanabilirsiniz. Copilot yetkili bir kaynak değil üretkenlik yardımı olarak değerlendirin ve üretim verilerine karşı çalıştırmadan önce her zaman oluşturulan sorguyu gözden geçirin ve test edin.

Rehberlik ve en iyi yöntemler:

  • Capabilities: Copilot düz dil gereksinimlerini WIQL'ye çevirebilir, söz dizimi hatalarını düzeltebilir (eşleşmeyen köşeli ayraçlar, eksik virgüller, yanlış anahtar sözcükler), SELECT listelerini kolay ve başvuru adları arasında dönüştürebilir, ASOF yan tümceleri veya tarih değişmez değerleri oluşturabilir ve sonuç kümelerini daraltmak veya genişletmek için yan tümce yeniden yazma önerilerinde bulunabilir.
  • Validate: Oluşturulan WIQL'i her zaman Query Editor veya güvenli bir test projesinde doğrulayın. Kullanmadan önce makroları (örneğin @Me, @Today) ve yerel ayara bağımlı tarih biçimlerini denetleyin.
  • Güvenlik: Gizli dizileri, erişim belirteçlerini veya özel bağlantı dizelerini hiçbir zaman istemlere yapıştırmayın. Copilot beslediğiniz örneklerdeki hassas değerleri kaldırın veya yeniden işlemden geçirin.
  • Performance: Copilot'dan sonuç yüklerini en aza indirmesini isteyin (yalnızca gerekli alanları döndürün), uygun WHERE filtrelerini ekleyin ve IN veya ilişkisiz LIKE aramalarının fazla geniş kapsamlı kullanımından kaçının. WIQL sorguları için 32-K karakter sınırını unutmayın.
  • Uç durumları gözden geçirme: Geçmiş (ASOF) sorgular, ağaç/bağlantı sorguları (FROM workItemLinks) ve WAS EVER/EVER düzeltmeleri taraan işleçler için davranışı onaylayın; bunlar daha karmaşık olabilir ve el ile ayarlanması gerekebilir.

Örnek - Düz İngilizceden WIQL oluşturma:

İstem: "'Fabrikam' projesinde atanan @Me ve son 30 gün içinde değiştirilen etkin Hatalar için Dönüş Kimliği ve Başlığı. ChangedDate desc ölçütüne göre sırala."

Copilot üretir:

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

Diğer WIQL oluşturma örnekleri

Yaygın senaryolarda WIQL oluşturmak Copilot için aşağıdaki gibi istemleri kullanın:

Scenario Komut istemi Önemli WIQL kavramları
Üst-alt öğe için ağaç sorgusu "Contoso projesindeki tüm Özellikleri ve alt Kullanıcı Öykülerini döndüren bir WIQL ağaç sorgusu yazın" FROM workItemLinks, [Source]/[Target] ön ekleri, TreeMode
Geçmiş anlık görüntüsü "Fabrikam'da 15 Ocak 2026'da Etkin olan tüm hataları gösteren WIQL yazın" ASOF '2026-01-15T00:00:00Z'
Tek atlamalı bağlantı sorgusu "Contoso projesinde ilgili iş öğeleriyle hataları döndür" FROM workItemLinks WHERE ... mode(MustContain)
WAS EVER işleci "Contoso'da Jamal'a atanmış kullanıcı hikayelerini bulun" [System.AssignedTo] WAS EVER 'Jamal'
Bileşik tarih aralıkları "Bu çeyrekte oluşturulan ancak son 14 gün içinde güncelleştirilmeyen iş öğelerini bulun" @Today - N Ile AND/NOT
Birden çok etiketli IN işleci "Contoso'da güvenlik, uyumluluk veya denetim etiketli iş öğelerini iade edin" [System.Tags] CONTAINS 'security'gruplandırma ile OR
Yalnızca ihtiyacınız olanı SEÇ "Sprint burndown grafiği için en düşük alanları döndürmek için bu sorguyu iyileştirin" Performans için alanları en aza indirme SELECT
Geçerli yineleme makros "Web ekibi için geçerli yinelemedeki tüm eksik görevler için WIQL yazın" @CurrentIteration('[Contoso]\\Web')

REST API ve AI ile WIQL sorgularını otomatikleştirme

İki aşamalı WIQL REST API işlemini otomatikleştirmek için Copilot gibi yapay zeka yardımcılarını kullanabilirsiniz:

  1. WIQL'inizle eşleşen iş öğesi kimliklerini almak için Wiql'e Göre SorguLA REST API'sini kullanın.
  2. Bu kimliklerin tüm ayrıntılarını getirmek için İş Öğelerini Al API'sini kullanın.

Yapay zeka size yardımcı olabilir:

  • WiQL'i düz dilden oluşturun, ardından iki API çağrısını kodda zincirleyin (örneğin, Python, PowerShell veya JavaScript).
  • Panolar veya raporlar için sonuçları biçimlendirin ve özetleyin.

Tip

REST API ayrıntıları için bkz. Wiql'e Göre Sorgulama (REST API).

Example: Python ve AI

Projedeki tüm etkin hataların başlıklarını ve durumlarını listelemek istediğinizi varsayalım.

Prompt to Copilot:
"Projemdeki tüm etkin hataların başlıklarını ve durumlarını listelemek için Azure DevOps REST API'sini kullanan Python kodu yazın. WIQL kullanarak kimlikleri alın, ardından bu kimliklerin ayrıntılarını getirin."

aşağıdaki gibi bir kod oluşturmak için Copilot kullanabilirsiniz:

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

İlgili içerik

  • Last updated on