Queries - Create

参考

服务:: Work Item Tracking

API 版本:: 7.1

创建查询或移动查询。

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

具有可选参数:

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

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”才能使用此版本的 API。
validateWiqlOnly	query		boolean	如果只想验证 WIQL 查询而不实际创建一个查询，请将其设置为 true。默认值为 false。

请求正文

名称	类型	说明
_links	ReferenceLinks	链接对相关 REST 资源的引用。
children	QueryHierarchyItem[]	查询文件夹中的子查询项。
clauses	WorkItemQueryClause	平面查询的子句。
columns	WorkItemFieldReference[]	查询的列。
createdBy	IdentityReference	创建查询项的标识。
createdDate	string (date-time)	创建查询项时。
filterOptions	LinkQueryMode	链接查询模式。
hasChildren	boolean	如果这是查询文件夹，则指示它是否包含任何子级。
id	string (uuid)	查询项的 ID。
isDeleted	boolean	指示是否删除此查询项。在已删除的查询项上将其设置为 false 将取消删除。取消删除查询或文件夹不会返回以前应用于查询或文件夹的权限更改。
isFolder	boolean	指示这是查询文件夹还是查询。
isInvalidSyntax	boolean	指示此查询的 WIQL 是否无效。这可能是由于语法无效或不再有效的区域/迭代路径造成的。
isPublic	boolean	指示此查询项是公共的还是私有的。
lastExecutedBy	IdentityReference	上次运行查询的标识。
lastExecutedDate	string (date-time)	上次运行查询时。
lastModifiedBy	IdentityReference	上次修改查询项的标识。
lastModifiedDate	string (date-time)	上次修改查询项时。
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

类型: oauth2
流向: accessCode
授权 URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
令牌 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

作用域

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

示例

Create a folder

Create a query

Move a query or folder

Create a folder

示例请求

HTTP

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

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

示例响应

状态代码:: 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

示例请求

HTTP

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

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

示例响应

状态代码:: 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

示例请求

HTTP

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

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

示例响应

状态代码:: 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

Object

描述对标识的引用。

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

LinkQueryMode

枚举

链接查询模式。

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

LogicalOperation

枚举

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

值	说明
and
none
or

QueryHierarchyItem

Object

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

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

QueryRecursionOption

枚举

用于树查询的递归选项。

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

QueryType

枚举

查询的类型。

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

ReferenceLinks

Object

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

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

WorkItemFieldOperation

Object

描述工作项字段作。

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

WorkItemFieldReference

Object

对工作项中的字段的引用

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

WorkItemQueryClause

Object

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

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

WorkItemQuerySortColumn

Object

排序列。

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

通过

Queries - Create

URI 参数

请求正文

响应

安全性

oauth2

作用域

示例

Create a folder

示例请求

示例响应

Create a query

示例请求

示例响应

Move a query or folder

示例请求

示例响应

定义

IdentityReference

LinkQueryMode

LogicalOperation

QueryHierarchyItem

QueryRecursionOption

QueryType

ReferenceLinks

WorkItemFieldOperation

WorkItemFieldReference

WorkItemQueryClause

WorkItemQuerySortColumn