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 參數

名稱	位於	必要	類型	Description
organization	path	True	string	Azure DevOps 組織的名稱。
project	path	True	string	專案識別碼或專案名稱
query	path	True	string	要在其中建立查詢的父識別碼或路徑。
api-version	query	True	string	要使用的 API 版本。這應該設定為 '7.1-preview.2'，以使用此版本的 API。
validateWiqlOnly	query		boolean	如果您只想驗證 WIQL 查詢而不實際建立，請將它設定為 true。預設值為 false。

要求本文

名稱	類型	Description
_links	ReferenceLinks	連結相關 REST 資源的參考。
children	QueryHierarchyItem[]	查詢資料夾內的子查詢專案。
clauses	WorkItemQueryClause	一般查詢的子句。
columns	WorkItemFieldReference[]	查詢的資料行。
createdBy	IdentityReference	建立查詢專案的身分識別。
createdDate	string	建立查詢專案時。
filterOptions	LinkQueryMode	連結查詢模式。
hasChildren	boolean	如果這是查詢資料夾，表示它是否包含任何子系。
id	string	查詢專案的識別碼。
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 文字

回應

名稱	類型	Description
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

名稱	Description
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"
}

定義

名稱	Description
IdentityReference	描述身分識別的參考。
LinkQueryMode	連結查詢模式。
LogicalOperation	分隔線件子句的邏輯運算子
QueryHierarchyItem	表示工作專案查詢階層中的專案。這可以是查詢或資料夾。
QueryRecursionOption	用於樹狀結構查詢的遞迴選項。
QueryType	查詢的類型。
ReferenceLinks	表示 REST 參考連結集合的類別。
WorkItemFieldOperation	描述工作專案欄位作業。
WorkItemFieldReference	工作專案中欄位的參考
WorkItemQueryClause	表示工作專案查詢中的子句。這會顯示工作專案查詢的結構。
WorkItemQuerySortColumn	排序資料行。

IdentityReference

描述身分識別的參考。

名稱	類型	Description
_links	ReferenceLinks	此欄位包含有關圖表主旨的零個或多個有趣連結。您可以叫用這些連結來取得其他關聯性，或取得此圖表主體的詳細資訊。
descriptor	string	描述項是在系統執行時參考圖形主旨的主要方式。此欄位可唯一識別帳戶和組織之間的相同圖表主旨。
directoryAlias	string	已淘汰 - 藉由查詢 IdentityRef 「_links」字典之「self」專案中參考的 Graph 使用者，即可擷取
displayName	string	這是圖表主旨的非唯一顯示名稱。若要變更此欄位，您必須在來源提供者中變更其值。
id	string
imageUrl	string	已淘汰 - 可在 IdentityRef 「_links」字典的「avatar」專案中使用
inactive	boolean	已淘汰 - 您可以查詢 GraphUser 「_links」字典的「membershipState」專案中參考的 Graph 成員資格狀態來擷取
isAadIdentity	boolean	已被取代 - 可以從描述元的主旨類型推斷 (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	已被取代 - 可以從描述元的主旨類型推斷 (Descriptor.IsGroupType)
isDeletedInOrigin	boolean
name	string	舊版 back-compat 屬性。這是來自常數的 WIT 特定值。將會隱藏 (，但除非用戶端以最新版本為目標，否則用戶端上存在)
profileUrl	string	已淘汰 - 不在 ToIdentityRef 的大多數既有實作中使用
uniqueName	string	已淘汰 - 請改用 Domain+PrincipalName
url	string	此 URL 是此圖表主體來源資源的完整路由。

LinkQueryMode

連結查詢模式。

名稱	類型	Description
linksOneHopDoesNotContain	string	只有在沒有連結的工作專案符合連結和目標準則時，才會傳回滿足來源的工作專案。
linksOneHopMayContain	string	傳回滿足來源和連結準則的工作專案，即使沒有連結的工作專案符合目標準則也一樣。
linksOneHopMustContain	string	傳回滿足來源、目標和連結準則的工作專案。
linksRecursiveDoesNotContain	string
linksRecursiveMayContain	string	傳回工作專案依預設滿足來源的工作專案階層
linksRecursiveMustContain	string
workItems	string	傳回工作專案的一般清單。

LogicalOperation

分隔線件子句的邏輯運算子

名稱	類型	Description
and	string
none	string
or	string

QueryHierarchyItem

表示工作專案查詢階層中的專案。這可以是查詢或資料夾。

名稱	類型	Description
_links	ReferenceLinks	連結相關 REST 資源的參考。
children	QueryHierarchyItem[]	查詢資料夾內的子查詢專案。
clauses	WorkItemQueryClause	一般查詢的子句。
columns	WorkItemFieldReference[]	查詢的資料行。
createdBy	IdentityReference	建立查詢專案的身分識別。
createdDate	string	建立查詢專案時。
filterOptions	LinkQueryMode	連結查詢模式。
hasChildren	boolean	如果這是查詢資料夾，表示它是否包含任何子系。
id	string	查詢專案的識別碼。
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 文字

QueryRecursionOption

用於樹狀結構查詢的遞迴選項。

名稱	類型	Description
childFirst	string	傳回符合目標準則的工作專案，即使沒有工作專案符合來源和連結準則也一樣。
parentFirst	string	傳回滿足來源的工作專案，即使沒有任何連結的工作專案符合目標和連結準則也一樣。

QueryType

查詢的類型。

名稱	類型	Description
flat	string	取得工作專案的一般清單。
oneHop	string	取得工作專案及其直接連結的清單。
tree	string	取得顯示其連結階層的工作專案樹狀結構。

ReferenceLinks

表示 REST 參考連結集合的類別。

名稱	類型	Description
links	object	連結的唯讀檢視。因為參考連結是唯讀的，所以我們只想要將它們公開為唯讀。

WorkItemFieldOperation

描述工作專案欄位作業。

名稱	類型	Description
name	string	作業的易記名稱。
referenceName	string	作業的參考名稱。

WorkItemFieldReference

工作專案中欄位的參考

名稱	類型	Description
name	string	欄位的易記名稱。
referenceName	string	欄位的參考名稱。
url	string	資源的 REST URL。

WorkItemQueryClause

表示工作專案查詢中的子句。這會顯示工作專案查詢的結構。

名稱	類型	Description
clauses	WorkItemQueryClause[]	如果目前子句是邏輯運算子，子子句
field	WorkItemFieldReference	與條件相關聯的欄位
fieldValue	WorkItemFieldReference	欄位與欄位比較時的條件右側
isFieldValue	boolean	判斷這是欄位比較的欄位
logicalOperator	LogicalOperation	分隔線件子句的邏輯運算子
operator	WorkItemFieldOperation	欄位運算子
value	string	當欄位與值比較時，條件的右側

WorkItemQuerySortColumn

排序資料行。

名稱	類型	Description
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

其他資源