Partilhar via


Queries - Create

Cria uma consulta ou move uma consulta.

Saiba mais sobre a sintaxe WIQL (Linguagem de Consulta de Item de Trabalho) aqui.

POST https://dev.azure.com/{organization}/{project}/_apis/wit/queries/{query}?api-version=7.1-preview.2
POST https://dev.azure.com/{organization}/{project}/_apis/wit/queries/{query}?validateWiqlOnly={validateWiqlOnly}&api-version=7.1-preview.2

Parâmetros de URI

Nome Em Obrigatório Tipo Description
organization
path True

string

O nome da organização do Azure DevOps.

project
path True

string

ID do projeto ou nome do projeto

query
path True

string

A ID pai ou caminho sob o qual a consulta deve ser criada.

api-version
query True

string

Versão da API a ser usada. Isso deve ser definido como '7.1-preview.2' para usar essa versão da api.

validateWiqlOnly
query

boolean

Se você quiser apenas validar sua consulta WIQL sem realmente criar uma, defina-a como true. O padrão é false.

Corpo da solicitação

Nome Tipo Description
_links

ReferenceLinks

Vincular referências a recursos REST relacionados.

children

QueryHierarchyItem[]

Os itens de consulta filho dentro de uma pasta de consulta.

clauses

WorkItemQueryClause

As cláusulas de uma consulta simples.

columns

WorkItemFieldReference[]

As colunas da consulta.

createdBy

IdentityReference

A identidade que criou o item de consulta.

createdDate

string

Quando o item de consulta foi criado.

filterOptions

LinkQueryMode

O modo de consulta de link.

hasChildren

boolean

Se essa for uma pasta de consulta, indica se ela contém filhos.

id

string

A ID do item de consulta.

isDeleted

boolean

Indica se esse item de consulta foi excluído. Definir isso como false em um item de consulta excluído o desmarcará. Desmarcando uma consulta ou pasta não trará de volta as alterações de permissão que foram aplicadas anteriormente a ela.

isFolder

boolean

Indica se esta é uma pasta de consulta ou uma consulta.

isInvalidSyntax

boolean

Indica se o WIQL dessa consulta é inválido. Isso pode ser devido à sintaxe inválida ou a um caminho de iteração/área não mais válido.

isPublic

boolean

Indica se esse item de consulta é público ou privado.

lastExecutedBy

IdentityReference

A identidade que executou a consulta pela última vez.

lastExecutedDate

string

Quando a consulta foi executada pela última vez.

lastModifiedBy

IdentityReference

A identidade que modificou o item de consulta pela última vez.

lastModifiedDate

string

Quando o item de consulta foi modificado pela última vez.

linkClauses

WorkItemQueryClause

A cláusula de consulta de link.

name

string

O nome do item de consulta.

path

string

O caminho do item de consulta.

queryRecursionOption

QueryRecursionOption

A opção de recursão para uso em uma consulta de árvore.

queryType

QueryType

O tipo de consulta.

sortColumns

WorkItemQuerySortColumn[]

As colunas de classificação da consulta.

sourceClauses

WorkItemQueryClause

As cláusulas de origem em uma consulta de link de árvore ou de um salto.

targetClauses

WorkItemQueryClause

As cláusulas de destino em uma consulta de link de árvore ou de um salto.

url

string

wiql

string

O texto WIQL da consulta

Respostas

Nome Tipo Description
200 OK

QueryHierarchyItem

operação bem-sucedida

Segurança

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Nome Description
vso.work_write Concede a capacidade de ler, criar e atualizar itens de trabalho e consultas, atualizar metadados do quadro, ler caminhos de área e iterações de outros itens de trabalho que acompanham metadados relacionados, executar consultas e receber notificações sobre eventos de item de trabalho por meio de ganchos de serviço.

Exemplos

Create a folder
Create a query
Move a query or folder

Create a folder

Sample Request

POST https://dev.azure.com/fabrikam/Fabrikam-Fiber-Git/_apis/wit/queries/{query}?api-version=7.1-preview.2

{
  "name": "Website team",
  "isFolder": true
}

Sample Response

{
  "id": "8a8c8212-15ca-41ed-97aa-1d6fbfbcd581",
  "name": "Website team",
  "path": "Shared Queries/Website team",
  "createdBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "createdDate": "2016-06-01T16:58:56.323Z",
  "lastModifiedBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "lastModifiedDate": "2016-06-01T16:58:56.323Z",
  "isFolder": true,
  "hasChildren": false,
  "isPublic": true,
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "html": {
      "href": "https://dev.azure.com/fabrikam/web/qr.aspx?pguid=6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c&qid=8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "parent": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/eb5c1e25-9b3e-4416-a833-e500122882c7"
    }
  },
  "url": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
}

Create a query

Sample Request

POST https://dev.azure.com/fabrikam/Fabrikam-Fiber-Git/_apis/wit/queries/{query}?api-version=7.1-preview.2

{
  "name": "All Bugs",
  "wiql": "Select [System.Id], [System.Title], [System.State] From WorkItems Where [System.WorkItemType] = 'Bug' order by [Microsoft.VSTS.Common.Priority] asc, [System.CreatedDate] desc"
}

Sample Response

{
  "id": "342f0f44-4069-46b1-a940-3d0468979ceb",
  "name": "All Bugs",
  "path": "Shared Queries/Website team/All Bugs",
  "createdBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "createdDate": "2016-06-01T16:58:56.64Z",
  "lastModifiedBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "lastModifiedDate": "2016-06-01T16:58:56.64Z",
  "queryType": "flat",
  "columns": [
    {
      "referenceName": "System.Id",
      "name": "ID",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Id"
    },
    {
      "referenceName": "System.Title",
      "name": "Title",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Title"
    },
    {
      "referenceName": "System.State",
      "name": "State",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.State"
    }
  ],
  "sortColumns": [
    {
      "field": {
        "referenceName": "Microsoft.VSTS.Common.Priority",
        "name": "Priority",
        "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/Microsoft.VSTS.Common.Priority"
      },
      "descending": false
    },
    {
      "field": {
        "referenceName": "System.CreatedDate",
        "name": "Created Date",
        "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.CreatedDate"
      },
      "descending": true
    }
  ],
  "wiql": "select [System.Id], [System.Title], [System.State] from WorkItems where [System.WorkItemType] = 'Bug' order by [Microsoft.VSTS.Common.Priority] asc, [System.CreatedDate] desc",
  "isPublic": true,
  "clauses": {
    "field": {
      "referenceName": "System.WorkItemType",
      "name": "Work Item Type",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.WorkItemType"
    },
    "operator": {
      "referenceName": "SupportedOperations.Equals",
      "name": "="
    },
    "value": "Bug"
  },
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/342f0f44-4069-46b1-a940-3d0468979ceb"
    },
    "html": {
      "href": "https://dev.azure.com/fabrikam/web/qr.aspx?pguid=6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c&qid=342f0f44-4069-46b1-a940-3d0468979ceb"
    },
    "parent": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "wiql": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/wiql/342f0f44-4069-46b1-a940-3d0468979ceb"
    }
  },
  "url": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/342f0f44-4069-46b1-a940-3d0468979ceb"
}

Move a query or folder

Sample Request

POST https://dev.azure.com/fabrikam/Fabrikam-Fiber-Git/_apis/wit/queries/{query}?api-version=7.1-preview.2

{
  "id": "8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
}

Sample Response

{
  "id": "8a8c8212-15ca-41ed-97aa-1d6fbfbcd581",
  "name": "Website",
  "path": "My Queries/Website",
  "createdBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "createdDate": "2016-06-01T16:58:56.323Z",
  "lastModifiedBy": {
    "displayName": "Jamal Hartnett",
    "url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "_links": {
      "avatar": {
        "href": "https://dev.azure.com/mseng/_apis/GraphProfile/MemberAvatars/aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
      }
    },
    "id": "d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d291b0c4-a05c-4ea6-8df1-4b41d5f39eff",
    "descriptor": "aad.YTkzODFkODYtNTYxYS03ZDdiLWJjM2QtZDUzMjllMjM5OTAz"
  },
  "lastModifiedDate": "2016-06-01T16:58:59.407Z",
  "isFolder": true,
  "hasChildren": true,
  "isPublic": false,
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "html": {
      "href": "https://dev.azure.com/fabrikam/web/qr.aspx?pguid=6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c&qid=8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
    },
    "parent": {
      "href": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/3c65fbc1-d427-48ce-9091-633dde9e27e2"
    }
  },
  "url": "https://dev.azure.com/fabrikam/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/_apis/wit/queries/8a8c8212-15ca-41ed-97aa-1d6fbfbcd581"
}

Definições

Nome Description
IdentityReference

Descreve uma referência a uma identidade.

LinkQueryMode

O modo de consulta de link.

LogicalOperation

Operador lógico que separa a cláusula condition

QueryHierarchyItem

Representa um item na hierarquia de consulta do item de trabalho. Isso pode ser uma consulta ou uma pasta.

QueryRecursionOption

A opção de recursão para uso em uma consulta de árvore.

QueryType

O tipo de consulta.

ReferenceLinks

A classe para representar uma coleção de links de referência REST.

WorkItemFieldOperation

Descreve uma operação de campo de item de trabalho.

WorkItemFieldReference

Referência a um campo em um item de trabalho

WorkItemQueryClause

Representa uma cláusula em uma consulta de item de trabalho. Isso mostra a estrutura de uma consulta de item de trabalho.

WorkItemQuerySortColumn

Uma coluna de classificação.

IdentityReference

Descreve uma referência a uma identidade.

Nome Tipo Description
_links

ReferenceLinks

Esse campo contém zero ou mais links interessantes sobre o assunto do grafo. Esses links podem ser invocados para obter relações adicionais ou informações mais detalhadas sobre esse assunto do grafo.

descriptor

string

O descritor é a principal maneira de referenciar o assunto do grafo enquanto o sistema está em execução. Esse campo identificará exclusivamente o mesmo assunto de grafo entre contas e organizações.

directoryAlias

string

Preterido – pode ser recuperado consultando o usuário do Graph referenciado na entrada "self" do dicionário IdentityRef "_links"

displayName

string

Esse é o nome de exibição não exclusivo do assunto do grafo. Para alterar esse campo, você deve alterar seu valor no provedor de origem.

id

string

imageUrl

string

Preterido – Disponível na entrada "avatar" do dicionário IdentityRef "_links"

inactive

boolean

Preterido – pode ser recuperado consultando o estado de associação do Graph referenciado na entrada "membershipState" do dicionário "_links" do GraphUser

isAadIdentity

boolean

Preterido – pode ser inferido do tipo de assunto do descritor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)

isContainer

boolean

Preterido – pode ser inferido do tipo de assunto do descritor (Descriptor.IsGroupType)

isDeletedInOrigin

boolean

name

string

Propriedade back-compat herdada. Esse foi o valor específico de WIT de Constantes. Será ocultado (mas existe) no cliente, a menos que ele esteja direcionando a versão mais recente

profileUrl

string

Preterido – não em uso na maioria das implementações preexistir de ToIdentityRef

uniqueName

string

Preterido – use Domain+PrincipalName em vez disso

url

string

Essa URL é a rota completa para o recurso de origem desta entidade de grafo.

LinkQueryMode

O modo de consulta de link.

Nome Tipo Description
linksOneHopDoesNotContain

string

Retorna itens de trabalho que satisfazem a origem, somente se nenhum item de trabalho vinculado atender aos critérios de link e de destino.

linksOneHopMayContain

string

Retorna itens de trabalho que atendem aos critérios de origem e link, mesmo que nenhum item de trabalho vinculado atenda aos critérios de destino.

linksOneHopMustContain

string

Retorna itens de trabalho em que os critérios de origem, destino e link são todos atendidos.

linksRecursiveDoesNotContain

string

linksRecursiveMayContain

string

Retorna itens de trabalho uma hierarquia de itens de trabalho que, por padrão, satisfazem a origem

linksRecursiveMustContain

string

workItems

string

Retorna uma lista simples de itens de trabalho.

LogicalOperation

Operador lógico que separa a cláusula condition

Nome Tipo Description
and

string

none

string

or

string

QueryHierarchyItem

Representa um item na hierarquia de consulta do item de trabalho. Isso pode ser uma consulta ou uma pasta.

Nome Tipo Description
_links

ReferenceLinks

Vincular referências a recursos REST relacionados.

children

QueryHierarchyItem[]

Os itens de consulta filho dentro de uma pasta de consulta.

clauses

WorkItemQueryClause

As cláusulas de uma consulta simples.

columns

WorkItemFieldReference[]

As colunas da consulta.

createdBy

IdentityReference

A identidade que criou o item de consulta.

createdDate

string

Quando o item de consulta foi criado.

filterOptions

LinkQueryMode

O modo de consulta de link.

hasChildren

boolean

Se essa for uma pasta de consulta, indica se ela contém filhos.

id

string

A ID do item de consulta.

isDeleted

boolean

Indica se esse item de consulta foi excluído. Definir isso como false em um item de consulta excluído o desmarcará. Desmarcando uma consulta ou pasta não trará de volta as alterações de permissão que foram aplicadas anteriormente a ela.

isFolder

boolean

Indica se esta é uma pasta de consulta ou uma consulta.

isInvalidSyntax

boolean

Indica se o WIQL dessa consulta é inválido. Isso pode ser devido à sintaxe inválida ou a um caminho de iteração/área não mais válido.

isPublic

boolean

Indica se esse item de consulta é público ou privado.

lastExecutedBy

IdentityReference

A identidade que executou a consulta pela última vez.

lastExecutedDate

string

Quando a consulta foi executada pela última vez.

lastModifiedBy

IdentityReference

A identidade que modificou o item de consulta pela última vez.

lastModifiedDate

string

Quando o item de consulta foi modificado pela última vez.

linkClauses

WorkItemQueryClause

A cláusula de consulta de link.

name

string

O nome do item de consulta.

path

string

O caminho do item de consulta.

queryRecursionOption

QueryRecursionOption

A opção de recursão para uso em uma consulta de árvore.

queryType

QueryType

O tipo de consulta.

sortColumns

WorkItemQuerySortColumn[]

As colunas de classificação da consulta.

sourceClauses

WorkItemQueryClause

As cláusulas de origem em uma consulta de link de árvore ou de um salto.

targetClauses

WorkItemQueryClause

As cláusulas de destino em uma consulta de link de árvore ou de um salto.

url

string

wiql

string

O texto WIQL da consulta

QueryRecursionOption

A opção de recursão para uso em uma consulta de árvore.

Nome Tipo Description
childFirst

string

Retorna itens de trabalho que atendem aos critérios de destino, mesmo que nenhum item de trabalho atenda aos critérios de origem e link.

parentFirst

string

Retorna itens de trabalho que satisfazem a origem, mesmo que nenhum item de trabalho vinculado atenda aos critérios de destino e link.

QueryType

O tipo de consulta.

Nome Tipo Description
flat

string

Obtém uma lista simples de itens de trabalho.

oneHop

string

Obtém uma lista de itens de trabalho e seus links diretos.

tree

string

Obtém uma árvore de itens de trabalho mostrando sua hierarquia de vínculo.

A classe para representar uma coleção de links de referência REST.

Nome Tipo Description
links

object

A exibição somente leitura dos links. Como os links de referência são somente leitura, só queremos expô-los como somente leitura.

WorkItemFieldOperation

Descreve uma operação de campo de item de trabalho.

Nome Tipo Description
name

string

Nome amigável da operação.

referenceName

string

Nome de referência da operação.

WorkItemFieldReference

Referência a um campo em um item de trabalho

Nome Tipo Description
name

string

O nome amigável do campo.

referenceName

string

O nome de referência do campo.

url

string

A URL REST do recurso.

WorkItemQueryClause

Representa uma cláusula em uma consulta de item de trabalho. Isso mostra a estrutura de uma consulta de item de trabalho.

Nome Tipo Description
clauses

WorkItemQueryClause[]

Cláusulas filho se a cláusula atual for um operador lógico

field

WorkItemFieldReference

Campo associado à condição

fieldValue

WorkItemFieldReference

Lado direito da condição quando uma comparação campo a campo

isFieldValue

boolean

Determina se essa é uma comparação de campo a campo

logicalOperator

LogicalOperation

Operador lógico que separa a cláusula condition

operator

WorkItemFieldOperation

O operador de campo

value

string

Lado direito da condição quando um campo para comparação de valor

WorkItemQuerySortColumn

Uma coluna de classificação.

Nome Tipo Description
descending

boolean

A direção a ser classificada por.

field

WorkItemFieldReference

Um campo de item de trabalho.