Queries - Create

参考

Service:: Work Item Tracking

API Version:: 7.1-preview.2

创建查询或移动查询。

在此处详细了解工作项查询语言 (WIQL) 语法。

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

With optional parameters:

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

URI 参数

名称	在	必需	类型	说明
organization	path	True	string	Azure DevOps 组织的名称。
project	path	True	string	项目 ID 或项目名称
query	path	True	string	要在其中创建查询的父 ID 或路径。
api-version	query	True	string	要使用的 API 版本。应将其设置为“7.1-preview.2”才能使用此版本的 API。
validateWiqlOnly	query		boolean	如果只想验证 WIQL 查询而不实际创建一个查询，请将其设置为 true。默认值为 false。

请求正文

名称	类型	说明
_links	ReferenceLinks	链接对相关 REST 资源的引用。
children	QueryHierarchyItem[]	查询文件夹中的子查询项。
clauses	WorkItemQueryClause	平面查询的子句。
columns	WorkItemFieldReference[]	查询的列。
createdBy	IdentityReference	创建查询项的标识。
createdDate	string	创建查询项时。
filterOptions	LinkQueryMode	链接查询模式。
hasChildren	boolean	如果这是查询文件夹，则指示它是否包含任何子级。
id	string	查询项的 ID。
isDeleted	boolean	指示是否删除此查询项。在已删除的查询项上将其设置为 false 将取消删除。取消删除查询或文件夹不会带回以前应用于该查询或文件夹的权限更改。
isFolder	boolean	指示这是查询文件夹还是查询。
isInvalidSyntax	boolean	指示此查询的 WIQL 是否无效。这可能是由于语法无效或不再有效的区域/迭代路径。
isPublic	boolean	指示此查询项是公共的还是私有的。
lastExecutedBy	IdentityReference	上次运行查询的标识。
lastExecutedDate	string	上次运行查询时。
lastModifiedBy	IdentityReference	上次修改查询项的标识。
lastModifiedDate	string	上次修改查询项时。
linkClauses	WorkItemQueryClause	链接查询子句。
name	string	查询项的名称。
path	string	查询项的路径。
queryRecursionOption	QueryRecursionOption	用于树查询的递归选项。
queryType	QueryType	查询的类型。
sortColumns	WorkItemQuerySortColumn[]	查询的排序列。
sourceClauses	WorkItemQueryClause	树或单跃点链接查询中的源子句。
targetClauses	WorkItemQueryClause	树或单跃点链接查询中的目标子句。
url	string
wiql	string	查询的 WIQL 文本

响应

名称	类型	说明
200 OK	QueryHierarchyItem	成功的操作

安全性

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

名称	说明
vso.work_write	授予读取、创建和更新工作项和查询、更新板元数据、读取区域和迭代路径、其他工作项跟踪相关元数据、执行查询以及通过服务挂钩接收有关工作项事件的通知的能力。

示例

Create a folder

Create a query

Move a query or folder

Create a folder

Sample Request

HTTP

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

Status code:: 201

{
  "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

HTTP

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

Status code:: 201

{
  "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

HTTP

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

Status code:: 200

{
  "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"
}

定义

名称	说明
IdentityReference	描述对标识的引用。
LinkQueryMode	链接查询模式。
LogicalOperation	分隔条件子句的逻辑运算符
QueryHierarchyItem	表示工作项查询层次结构中的项。这可以是查询或文件夹。
QueryRecursionOption	用于树查询的递归选项。
QueryType	查询的类型。
ReferenceLinks	表示 REST 引用链接集合的类。
WorkItemFieldOperation	描述工作项字段操作。
WorkItemFieldReference	对工作项中的字段的引用
WorkItemQueryClause	表示工作项查询中的子句。这显示了工作项查询的结构。
WorkItemQuerySortColumn	排序列。

IdentityReference

描述对标识的引用。

名称	类型	说明
_links	ReferenceLinks	此字段包含有关图形主题的零个或多个相关链接。可以调用这些链接来获取有关此图主题的其他关系或更多详细信息。
descriptor	string	描述符是在系统运行时引用图形主题的主要方式。此字段将唯一标识帐户和组织中的同一图形主题。
directoryAlias	string	已弃用 - 可通过查询 IdentityRef“_links”字典的“self”条目中引用的 Graph 用户来检索
displayName	string	这是图形主题的非唯一显示名称。若要更改此字段，必须在源提供程序中更改其值。
id	string
imageUrl	string	已弃用 - 在 IdentityRef“_links”字典的“头像”条目中可用
inactive	boolean	已弃用 - 可以通过查询 GraphUser“_links”字典的“membershipState”条目中引用的 Graph 成员身份状态来检索
isAadIdentity	boolean	已弃用 - 可以从描述符的主题类型推断 (描述符.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	已弃用 - 可以从描述符的主题类型推断 (描述符.IsGroupType)
isDeletedInOrigin	boolean
name	string	旧版后兼容属性。这是常量中特定于 WIT 的值。将隐藏 (但客户端上存在) ，除非它们面向最新版本
profileUrl	string	已弃用 - 未在 ToIdentityRef 的大多数预先存在的实现中使用
uniqueName	string	已弃用 - 改用 Domain+PrincipalName
url	string	此 URL 是此图主题的源资源的完整路由。

LinkQueryMode

链接查询模式。

名称	类型	说明
linksOneHopDoesNotContain	string	仅当没有链接的工作项满足链接和目标条件时，才返回满足源的工作项。
linksOneHopMayContain	string	返回满足源和链接条件的工作项，即使没有链接的工作项满足目标条件。
linksOneHopMustContain	string	返回所有满足源、目标和链接条件的工作项。
linksRecursiveDoesNotContain	string
linksRecursiveMayContain	string	返回默认满足源的工作项层次结构的工作项
linksRecursiveMustContain	string
workItems	string	返回工作项的平面列表。

LogicalOperation

分隔条件子句的逻辑运算符

名称	类型	说明
and	string
none	string
or	string

QueryHierarchyItem

表示工作项查询层次结构中的项。这可以是查询或文件夹。

名称	类型	说明
_links	ReferenceLinks	将引用链接到相关的 REST 资源。
children	QueryHierarchyItem[]	查询文件夹中的子查询项。
clauses	WorkItemQueryClause	平面查询的子句。
columns	WorkItemFieldReference[]	查询的列。
createdBy	IdentityReference	创建查询项的标识。
createdDate	string	创建查询项时。
filterOptions	LinkQueryMode	链接查询模式。
hasChildren	boolean	如果这是查询文件夹，则指示它是否包含任何子级。
id	string	查询项的 ID。
isDeleted	boolean	指示是否删除此查询项。在已删除的查询项上将其设置为 false 将取消删除。取消删除查询或文件夹不会带回以前应用于该查询或文件夹的权限更改。
isFolder	boolean	指示这是查询文件夹还是查询。
isInvalidSyntax	boolean	指示此查询的 WIQL 是否无效。这可能是由于语法无效或不再有效的区域/迭代路径造成的。
isPublic	boolean	指示此查询项是公共的还是私有的。
lastExecutedBy	IdentityReference	上次运行查询的标识。
lastExecutedDate	string	上次运行查询时。
lastModifiedBy	IdentityReference	上次修改查询项的标识。
lastModifiedDate	string	上次修改查询项时。
linkClauses	WorkItemQueryClause	链接查询子句。
name	string	查询项的名称。
path	string	查询项的路径。
queryRecursionOption	QueryRecursionOption	用于树查询的递归选项。
queryType	QueryType	查询的类型。
sortColumns	WorkItemQuerySortColumn[]	查询的排序列。
sourceClauses	WorkItemQueryClause	树或单跃点链接查询中的 source 子句。
targetClauses	WorkItemQueryClause	树或单跃点链接查询中的目标子句。
url	string
wiql	string	查询的 WIQL 文本

QueryRecursionOption

用于树查询的递归选项。

名称	类型	说明
childFirst	string	返回满足目标条件的工作项，即使没有工作项满足源和链接条件。
parentFirst	string	返回满足源的工作项，即使没有链接的工作项满足目标和链接条件。

QueryType

查询的类型。

名称	类型	说明
flat	string	获取工作项的平面列表。
oneHop	string	获取工作项及其直接链接的列表。
tree	string	获取显示其链接层次结构的工作项树。

ReferenceLinks

表示 REST 引用链接集合的类。

名称	类型	说明
links	object	链接的只读视图。由于引用链接是只读的，因此我们只想将其公开为只读。

WorkItemFieldOperation

描述工作项字段操作。

名称	类型	说明
name	string	操作的友好名称。
referenceName	string	操作的引用名称。

WorkItemFieldReference

对工作项中的字段的引用

名称	类型	说明
name	string	字段的友好名称。
referenceName	string	字段的引用名称。
url	string	资源的 REST URL。

WorkItemQueryClause

表示工作项查询中的子句。这显示了工作项查询的结构。

名称	类型	说明
clauses	WorkItemQueryClause[]	如果 current 子句是逻辑运算符，则为子子句
field	WorkItemFieldReference	与条件关联的字段
fieldValue	WorkItemFieldReference	字段与字段比较时条件的右侧
isFieldValue	boolean	确定此字段是否为字段与字段的比较
logicalOperator	LogicalOperation	分隔条件子句的逻辑运算符
operator	WorkItemFieldOperation	字段运算符
value	string	字段与值比较时条件的右侧

WorkItemQuerySortColumn

排序列。

名称	类型	说明
descending	boolean	排序依据的方向。
field	WorkItemFieldReference	工作项域。

通过

Queries - Create

URI 参数

请求正文

响应

安全性

oauth2

Scopes

示例

Create a folder

Sample Request

Sample Response

Create a query

Sample Request

Sample Response

Move a query or folder

Sample Request

Sample Response

定义

IdentityReference

LinkQueryMode

LogicalOperation

QueryHierarchyItem

QueryRecursionOption

QueryType

ReferenceLinks

WorkItemFieldOperation

WorkItemFieldReference

WorkItemQueryClause

WorkItemQuerySortColumn

其他资源