Condividi tramite

Informazioni di riferimento sulla sintassi Work Item Query Language (WIQL)

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

È possibile usare la sintassi WIQL per definire una query come collegamento ipertestuale o quando si usa l'API REST (Work Item Query Language).

WIQL supporta tutte le funzioni disponibili tramite l'editor di query del portale Web e altri ancora. È possibile specificare i campi da restituire e il raggruppamento logico delle clausole di query. È anche possibile usare una ASOF clausola per filtrare in base alle assegnazioni a partire da una data precedente.

Important

La sintassi WIQL viene usata per eseguire l'API REST Query by Wiql. L'API restituisce solo ID elemento di lavoro, indipendentemente dai campi inclusi nell'istruzione SELECT . Per ottenere informazioni complete, (1) ottenere gli ID da WIQL, quindi (2) ottenere gli elementi di lavoro tramite Ottenere un elenco di elementi di lavoro per ID e per campi specifici.

Prerequisites

Category Requirements
Permissions Visualizzare gli elementi di lavoro o Visualizzare gli elementi di lavoro in questo nodo set di autorizzazioni su Consenti. Queste autorizzazioni vengono in genere concesse ai membri dei gruppi Lettori e Collaboratori per ogni progetto team. Per altre informazioni, vedere Autorizzazioni e gruppi.

Panoramica dei linguaggi di query

WIQL include cinque parti, come illustrato nel frammento di sintassi seguente e descritto nella tabella. La sintassi WIQL non fa distinzione tra maiuscole e minuscole.

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

Installando l'estensione Marketplace dell'editor Wiql, è possibile costruire query usando l'editor di query e visualizzare la sintassi WIQL. È quindi possibile copiare e modificare la sintassi WIQL ed eseguire la query usando l'hub Wiql Playground aggiunto a Boards.

Clausola Esempio/Descrizione
SELECT Identifica i campi da restituire per ogni elemento di lavoro. È possibile specificare il nome descrittivo o il nome di riferimento. Usare parentesi quadre ([]) se il nome contiene spazi vuoti o punti.
FROM Indica se si desidera che la query trovi elementi di lavoro o collegamenti tra elementi di lavoro.
- Usare FROM WorkItems per restituire gli elementi di lavoro.
- Usare FROM workItemLinks per restituire collegamenti tra elementi di lavoro. Per altre informazioni, vedere Query per i collegamenti tra elementi di lavoro.
WHERE Specifica i criteri di filtro per la query. Per altre informazioni, vedere Condizioni di filtro ().For more information, see Filter conditions (WHERE).
ORDER BY Specifica l'ordinamento degli elementi di lavoro restituiti. È possibile specificare Crescente (Asc) o Decrescente (Desc) per uno o più campi. Ad esempio: ORDER BY [State] Asc, [Changed Date] Desc
ASOF Specifica una query cronologica che indica una data di applicazione del filtro. Ad esempio, questa query restituisce tutte le storie utente definite come Attive il 11 febbraio 2025. Specificare la data in base alle indicazioni fornite in Data e ora.
ASOF '02-11-2025'

Note

Le query WIQL eseguite su Azure Boards non devono superare i 32 K caratteri. Il sistema non consente di creare o eseguire query che superano tale lunghezza.

Modello di data e ora

Il modello di data e ora immesso per i campi DateTime deve corrispondere a quello selezionato tramite il profilo. Per visualizzare o modificare la selezione, vedere Impostare le preferenze utente.

Screenshot che mostra le opzioni dell'elenco a discesa Modello di data nel riquadro Ora e impostazioni locali. Screenshot che mostra le opzioni dell'elenco a discesa Modello di tempo nel riquadro Ora e impostazioni locali.

Screenshot che mostra il riquadro Ora e impostazioni locali con i campi Modello di data e Ora.

I valori letterali virgolette singole o doppie sono supportati DateTime nei confronti. Devono essere nel formato .NET DateTime del computer client locale che esegue la query. A meno che non venga specificato un fuso orario, DateTime i valori letterali si trovano nel fuso orario del computer locale.

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

Quando l'ora viene omessa in un DateTime valore letterale e il dayPrecision parametro è uguale a false, si presuppone che l'ora sia zero (mezzanotte). L'impostazione predefinita per il dayPrecision parametro è false.

In alternativa, è possibile specificare il formato ISO 8601, valido indipendentemente dalle impostazioni locali. ISO 8601 rappresenta data e ora a partire dall'anno, seguito dal mese, dal giorno, dall'ora, dai minuti, dai secondi e dai millisecondi. Ad esempio, 2025-12-10 15:00:00.000 rappresenta il 10 dicembre 2025 alle 17:00 nell'ora locale. Un esempio di utilizzo del formato ISO 8601 è il seguente:

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

Campi personalizzati

È possibile aggiungere un campo personalizzato a una clausola di query. Con WIQL è necessario specificare il nome di riferimento per il campo personalizzato. Per i progetti che usano un modello di processo ereditato, i campi personalizzati vengono in genere etichettati con Custom. anteponibili al nome e gli spazi rimossi. Per esempio:

Nome amichevole Nome riferimento
Approver Custom.Approver
Request Type Custom.RequestType
Scope Estimate Custom.CustomEstimate

Per i progetti che utilizzano il modello di processo XML locale, il nome di riferimento viene definito dalle definizioni del tipo di elemento di lavoro XML.

Per altre informazioni, vedere Campi e attributi dell'elemento di lavoro.

Specificare le clausole di filtro (WHERE)

La WHERE clausola specifica i criteri di filtro. La query restituisce solo gli elementi di lavoro che soddisfano i criteri specificati. Ad esempio, la clausola di esempio WHERE seguente restituisce storie utente attive e assegnate all'utente.

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

È possibile controllare l'ordine in cui gli operatori logici vengono valutati racchiudendoli tra parentesi per raggruppare i criteri di filtro. Ad esempio, per restituire elementi di lavoro assegnati all'utente o chiusi, usare l'esempio seguente.

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

Condizioni di filtro

Ogni condizione di filtro è costituita da tre parti, ognuna delle quali deve essere conforme alle regole seguenti:

  • Campo: è possibile specificare il nome del riferimento o il nome descrittivo. Gli esempi seguenti sono la sintassi WIQL valida:
    • Nome riferimento: SELECT [System.AssignedTo] ...
    • Nome descrittivo con spazi: SELECT [Assigned To] ...
    • I nomi senza spazi non richiedono parentesi quadre: SELECT ID, Title ...
  • Operatore: i valori validi vengono specificati nella sezione Operatori più avanti in questo articolo.
  • Valore campo: è possibile specificare uno dei tre valori seguenti a seconda del campo specificato.
    • Un valore letterale deve corrispondere al tipo di dati del valore del campo.
    • Variabile o macro che indica un determinato valore. Ad esempio, @Me indica la persona che esegue la query. Per altre informazioni, vedere Macro e variabili.
    • Nome di un altro campo. Ad esempio, è possibile usare [Assigned to] = [Changed by] per trovare gli elementi di lavoro assegnati alla persona che ha modificato l'elemento di lavoro più di recente.

Per una descrizione e nomi di riferimento di tutti i campi definiti dal sistema, vedere Indice dei campi elemento di lavoro.

Operators

Le query usano espressioni logiche per qualificare i set di risultati. Queste espressioni logiche formano una o più operazioni congiunte.

Di seguito sono riportate alcune semplici operazioni di query:

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

La tabella seguente riepiloga tutti gli operatori supportati per i diversi tipi di campo. Per altre informazioni su ogni tipo di campo, vedere Campi e attributi dell'elemento di lavoro.

Gli =operatori , <>><, , >=, e <= funzionano come previsto. Ad esempio, System.ID > 100 esegue query per tutti gli elementi di lavoro con un ID valore maggiore di 100. System.ChangedDate > '01-01-25 12:00:00' query per tutti gli elementi di lavoro modificati dopo il 1° gennaio 2025.

Oltre a questi operatori di base, esistono alcuni comportamenti e operatori specifici per determinati tipi di campo.

Note

Gli operatori disponibili dipendono dalla piattaforma e dalla versione. Per altre informazioni, vedere Informazioni di riferimento rapido sulle query.

Tipo di campo Operatori supportati
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

Raggruppamenti logici

È possibile usare i termini AND e OR nel senso booleano tipico per valutare due clausole. È possibile usare i termini AND EVER e OR EVER quando si specifica un WAS EVER operatore. È possibile raggruppare le espressioni logiche e unirle ulteriormente in base alle esigenze. Gli esempi seguenti illustrano.

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

È possibile negare gli containsoperatori , undere in usando not. Non è possibile negare l'operatore ever . Nell'esempio seguente vengono eseguite query per tutti gli elementi di lavoro non assegnati nel sottoalbero di Fabrikam Fiber\Account Management.

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

Query di esempio, mai assegnata a

Nell'esempio seguente dell'editor di query vengono trovati tutti gli elementi di lavoro che sono stati assegnati a Jamal Hartnett.

Screenshot di Editor di query, query elenco flat, mai assegnata.

La sintassi WIQL corrispondente è la seguente:

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

Macro o variabili

Nella tabella seguente sono elencate le macro o le variabili che è possibile usare all'interno di una query WIQL.

Macro Usage
@Me Usare questa variabile per cercare automaticamente l'alias dell'utente corrente in un campo contenente alias utente. Ad esempio, è possibile trovare elementi di lavoro aperti se si imposta la colonna su Field, la Activated By colonna su Operatore la = colonna su Value.@Me
@CurrentIteration Usare questa variabile per filtrare automaticamente gli elementi di lavoro assegnati allo sprint corrente per il team selezionato in base al contesto del team selezionato.
@Project Usare questa variabile per cercare gli elementi di lavoro nel progetto corrente. Ad esempio, è possibile trovare tutti gli elementi di lavoro nel progetto corrente se si imposta la Field colonna su Team Project, la Operator colonna su =e la Value colonna su @Project.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Utilizzare queste macro per filtrare DateTime i campi in base all'inizio del giorno corrente, della settimana, del mese, dell'anno o di un offset a uno di questi valori. Ad esempio, è possibile trovare tutti gli elementi creati negli ultimi tre mesi se si imposta la Field colonna su Created Date, la Operator colonna su >=e la Value colonna su @StartOfMonth - 3.
@Today Utilizzare questa variabile per cercare gli elementi di lavoro correlati alla data corrente o a una data precedente. È anche possibile modificare la @Today variabile sottraendo giorni. Ad esempio, è possibile trovare tutti gli elementi attivati nell'ultima settimana se si imposta la colonna su Field, la Activated Date colonna su Operatore la >= colonna su Value.@Today - 7
[Any] Utilizzare questa variabile per cercare gli elementi di lavoro correlati a qualsiasi valore definito per un campo specifico.

@me macro

La @me macro sostituisce il nome dell'account integrato di Windows dell'utente che esegue la query. Nell'esempio seguente viene illustrato come utilizzare la macro e l'istruzione statica equivalente. La macro è destinata all'uso con campi Identity, Assigned Toad esempio .

WHERE  
   [System.AssignedTo] = @Me

@today macro

È possibile utilizzare la @today macro con qualsiasi DateTime campo. Questa macro sostituisce la mezzanotte della data corrente nel computer locale che esegue la query. È anche possibile specificare @today+x o @today-y usare offset integer per x giorni dopo @today e y giorni prima @todayrispettivamente. Una query che utilizza la @today macro può restituire set di risultati diversi a seconda del fuso orario in cui viene eseguito.

Gli esempi seguenti presuppongono che oggi sia 1/3/2025.

WHERE  
   [System.CreatedDate] = @today

Equivale a:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Equivale a:

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

@StartOfDay, @StartOfWeek, @StartOfMonth@StartOfYear macro

È possibile utilizzare le @StartOf... macro con qualsiasi DateTime campo. Questa macro sostituisce la mezzanotte del giorno corrente, l'inizio della settimana, l'inizio del mese o l'inizio dell'anno nel computer locale che esegue la query.

Queste macro accettano una stringa di modifica con formato .(+/-)nn(y|M|w|d|h|m) Analogamente alla @Today macro, è possibile specificare offset di interi più o meno. Se il qualificatore di unità di tempo viene omesso, per impostazione predefinita viene impostato il periodo naturale della funzione. Ad esempio, @StartOfWeek("+1") è identico a @StartOfWeek("+1w"). Se il segno più/meno (+/-) viene omesso, si presuppone più.

Questa sintassi consente di annidare i modificatori e di sfalsare la query due volte. Ad esempio, la clausola Closed Date >= @StartOfYear - 1 filtra gli elementi di lavoro chiusi dall'anno precedente. Quando lo si modifica in Closed Date >= @StartOfYear('+3M') - 1, esclude gli elementi di lavoro chiusi entro i primi tre mesi dell'anno precedente. La sintassi WIQL seguente illustra:

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

Gli esempi seguenti presuppongono che oggi sia 4/5/2025.

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

Equivale a:

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

And

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

Equivale a:

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

Macro personalizzate

WIQL supporta anche macro personalizzate arbitrarie. Qualsiasi stringa preceduta da un oggetto @ viene considerata come una macro personalizzata e viene sostituita. Il valore di sostituzione per la macro personalizzata viene recuperato dal parametro di contesto del metodo di query nel modello a oggetti. Il metodo seguente è l'API usata per le macro:

public WorkItemCollection Query(string wiql, IDictionary context)

Il parametro di contesto contiene coppie chiave-valore per le macro. Ad esempio, se il contesto contiene una coppia chiave-valore di (project, MyProject), @project viene sostituita da MyProject in WIQL. Questa sostituzione è il modo in cui il generatore di query dell'elemento di lavoro gestisce la @project macro in Visual Studio.

Specificare query cronologiche (ASOF)

È possibile usare una ASOF clausola in una query per filtrare gli elementi di lavoro che soddisfano le condizioni di filtro specificate in base a una data e un'ora specifiche.

Note

Non è possibile creare ASOF query nel generatore di query in Visual Studio. Se si crea un file di query (.wiq) che include una ASOF clausola e quindi lo si carica in Visual Studio, la ASOF clausola viene ignorata.

Si supponga che un elemento di lavoro sia stato classificato in base Iteration PathFabrikam Fiber\Release 1 a e assegnato a "Jamal Hartnett" prima del 5/05/2025. Tuttavia, l'elemento di lavoro è stato recentemente assegnato a "Raisa Pokrovska" e spostato in un nuovo percorso di iterazione della versione 2. La query di esempio seguente restituisce gli elementi di lavoro assegnati a Jamal Hartnett perché la query si basa sullo stato degli elementi di lavoro a partire da una data e un'ora precedenti.

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

Se non viene specificata alcuna ora, WIQL usa mezzanotte. Se non viene specificato alcun fuso orario, WIQL usa il fuso orario del computer client locale.

Impostare l'ordinamento (ORDER BY)

È possibile utilizzare la ORDER BY clausola per ordinare i risultati di una query in base a uno o più campi in ordine crescente o decrescente.

Note

Le preferenze di ordinamento del server SQL nel livello dati determinano l'ordinamento predefinito. Tuttavia, è possibile usare i asc parametri o desc per scegliere un ordinamento esplicito.

Nell'esempio seguente gli elementi di lavoro vengono ordinati prima in Priority ordine crescente (impostazione predefinita) e quindi Created Date in ordine decrescente (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

Per restituire collegamenti tra elementi di lavoro, specificare FROM WorkItemLinks. Le condizioni di filtro nella WHERE clausola possono essere applicate ai collegamenti o a qualsiasi elemento di lavoro che sia l'origine o la destinazione di un collegamento. Nell'esempio seguente vengono restituiti i collegamenti tra Product Backlog Items e i relativi elementi figlio attivi.

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)

La tabella seguente riepiloga le differenze tra le query degli elementi di lavoro e le query per i collegamenti tra gli elementi di lavoro.

Clausola Elementi di lavoro Collegamenti tra elementi di lavoro
FROM FROM WorkItems FROM WorkItemLinks
WHERE [FieldName] = Value Specificare una o più delle opzioni seguenti:
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'
MODE non applicabile Specificare uno dei seguenti elementi:
- MODE (MustContain): (impostazione predefinita) Restituisce solo WorkItemLinkInfo i record in cui sono soddisfatti tutti i criteri di origine, destinazione e collegamento.
- MODE (MayContain): restituisce WorkItemLinkInfo i record per tutti gli elementi di lavoro che soddisfano i criteri di origine e collegamento, anche se nessun elemento di lavoro collegato soddisfa i criteri di destinazione.
- MODE (DoesNotContain): restituisce WorkItemLinkInfo i record per tutti gli elementi di lavoro che soddisfano l'origine, solo se nessun elemento di lavoro collegato soddisfa i criteri di collegamento e di destinazione.
- MODE (Recursive): usare per le query albero ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). Il tipo di collegamento deve essere topologia ad albero e direzione in avanti. Restituisce WorkItemLinkInfo i record per tutti gli elementi di lavoro che soddisfano l'origine, in modo ricorsivo per la destinazione. ORDER BY e ASOF non sono compatibili con le query albero.
RETURNS WorkItemQueryResult WorkItemLink

È possibile specificare uno dei nomi dei tipi di collegamento di sistema seguenti.

È possibile specificare uno dei nomi dei tipi di collegamento di sistema seguenti o un tipo di collegamento personalizzato definito con il processo XML locale.

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

Per altre informazioni, vedere Informazioni di riferimento sul tipo di collegamento.

Esempio di query del tipo di albero

Note

ORDER BY e ASOF non sono compatibili con le query albero. Non includere queste clausole nelle query albero.

La query seguente restituisce tutti i tipi di elemento di lavoro definiti nel progetto corrente. L'editor di query visualizza la query come illustrato nell'immagine seguente.

Screenshot di Editor di query, query ad albero, tutti gli elementi di lavoro e gli stati.

La sintassi WIQL equivalente è la seguente:

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)

Nell'esempio seguente vengono restituiti tutti i tipi di elemento di lavoro definiti nel progetto corrente. L'editor di query visualizza la query come illustrato nell'immagine seguente.

Screenshot di Editor di query, query direct-link, tutti gli elementi di lavoro e gli stati.

La sintassi WIQL equivalente è la seguente:

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)

Altri esempi di query

Nell'esempio di query WIQL seguente vengono usati nomi di riferimento per i campi. La query seleziona gli elementi di lavoro (nessun tipo di elemento di lavoro specificato) con un oggetto Priority=1. La query restituisce e IDTitle del set restituito come colonne. I risultati vengono ordinati ID in base all'ordine crescente.

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

Modello di data e ora

Specificare il modello di data e ora in base a uno dei due modelli seguenti:

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

Clausole di esempio

Le istruzioni di esempio seguenti mostrano clausole di qualificazione specifiche.

Clausola 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 (Filtro ora)
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'

Stringa e testo non crittografato

I valori letterali stringa tra virgolette singole o doppie sono supportati in un confronto con un String campo o PlainText . I valori letterali stringa supportano tutti i caratteri Unicode.

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

È possibile usare l'operatore contains per cercare una sottostringa in qualsiasi punto del valore del campo.

WHERE [System.Description] contains 'WIQL'

Area e iterazione (TreePath)

È possibile usare l'operatore UNDER per i Area Path campi e Iteration Path . L'operatore UNDER valuta se un valore si trova all'interno del sottoalbero di un nodo di classificazione specifico. Ad esempio, l'espressione seguente restituisce true se l'oggetto Area Path è MyProject\Server\Administration, MyProject\Server\Administration\Feature 1, MyProject\Server\Administration\Feature 2\SubFeature 5o qualsiasi altro nodo all'interno del sottoalbero.

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

Modificatori e operatori speciali

È possibile usare alcuni modificatori e operatori speciali in un'espressione di query.

Utilizzare l'operatore IN per valutare se un valore di campo è uguale a un set di valori. Questo operatore è supportato per i Stringtipi di campo , IntegerDouble, e DateTime . L'esempio seguente e il relativo equivalente semantico illustrano questo argomento.

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

L'operatore EVER viene usato per valutare se un valore di campo è uguale o uguale a un determinato valore in tutte le revisioni precedenti degli elementi di lavoro. I Stringtipi di campo , IntegerDouble, e DateTime supportano questo operatore. Esistono sintassi alternative per l'operatore EVER . Ad esempio, i frammenti di codice seguenti eseguono una query se tutti gli elementi di lavoro sono stati assegnati a Jamal, Raisa o 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>'
    )

Usare Copilot per scrivere, correggere e ottimizzare WIQL

È possibile usare un assistente di intelligenza artificiale (ad esempio, GitHub Copilot o altri copiloti) per creare, correggere o ottimizzare le query WIQL. Considerare Copilot come un aiuto per la produttività, non un'origine autorevole, ed esaminare e testare sempre qualsiasi query generata prima di eseguirla sui dati di produzione.

Linee guida e procedure consigliate:

  • Funzionalità: Copilot può convertire i requisiti in linguaggio normale in WIQL, correggere gli errori di sintassi (parentesi non corrispondenti, virgole mancanti, parole chiave non corrette), convertire elenchi SELECT tra nomi descrittivi e di riferimento, generare ASOF clausole o valori letterali di data e suggerire riscritture delle clausole per restringere o ampliare i set di risultati.
  • Convalida: convalidare sempre WIQL generato nell'editor di query o in un progetto di test sicuro. Controllare le macro (ad esempio @Me, @Today) e i formati di data dipendenti dalle impostazioni locali prima dell'uso.
  • Sicurezza: non incollare mai segreti, token di accesso o stringhe di connessione private nelle richieste. Rimuovere o redigire eventuali valori sensibili negli esempi inseriti in Copilot.
  • Prestazioni: chiedere a Copilot di ridurre al minimo i payload dei risultati (restituire solo i campi necessari), aggiungere filtri WHERE appropriati ed evitare un uso eccessivamente ampio di IN ricerche o non associate LIKE . Tenere presente il limite di 32 K caratteri per le query WIQL.
  • Esaminare i casi perimetrali: verificare il comportamento per le query cronologiche (ASOF), le query albero/collegamento (FROM workItemLinks) e WAS EVER/EVER gli operatori che analizzano le revisioni, che possono essere più complessi e potrebbero richiedere l'ottimizzazione manuale.

Esempio: generare WIQL dall'inglese normale:

Prompt: "Return ID and Title for active Bugs assigned to in project 'Fabrikam' and modified in the last 30 days.Prompt: "Return ID and Title for active Bugs assigned to @Me in project 'Fabrikam' and modified in the last 30 days. Ordina per ChangedDate desc."

Copilot produce:

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

Automatizzare le query WIQL con l'API REST e l'intelligenza artificiale

È possibile usare gli assistenti di intelligenza artificiale, ad esempio Copilot, per automatizzare il processo dell'API REST WIQL in due passaggi:

  1. Usare l'API REST Query by Wiql per recuperare gli ID degli elementi di lavoro corrispondenti a WIQL.
  2. Usare l'API Recupera elementi di lavoro per recuperare i dettagli completi per tali ID.

L'intelligenza artificiale consente di:

  • Generare WIQL dal linguaggio normale, quindi concatenare le due chiamate API nel codice ( ad esempio Python, PowerShell o JavaScript).
  • Formattare e riepilogare i risultati per dashboard o report.

Tip

Per informazioni dettagliate sull'API REST, vedere Query by Wiql (REST API).

Esempio: Automatizzare WIQL con Python e intelligenza artificiale

Si supponga di voler elencare i titoli e gli stati di tutti i bug attivi in un progetto.

Richiedi conferma a Copilot:
"Scrivere codice Python che usa l'API REST di Azure DevOps per elencare i titoli e gli stati di tutti i bug attivi nel progetto. Usare WIQL per ottenere gli ID, quindi recuperare i dettagli per tali ID."

È possibile usare Copilot per generare codice simile al seguente:

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

Contenuti correlati

  • Last updated on