Queries - Create

參考

服務:: Work Item Tracking

API 版本:: 7.1

建立查詢或移動查詢。

在這裡深入瞭解工作項目查詢語言（WIQL）語法，。

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

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

要求本文

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

回應

名稱	類型	Description
200 OK	QueryHierarchyItem	成功作業

安全性

oauth2

類型: oauth2
Flow: 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

範圍

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

定義

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

IdentityReference

Object

描述身分識別的參考。

名稱	類型	Description
_links	ReferenceLinks	此欄位包含圖表主旨的相關零或更多有趣連結。您可以叫用這些連結，以取得此圖表主題的其他關聯性或更詳細的資訊。
descriptor	string	描述元是在系統執行時參考圖表主旨的主要方式。此欄位會唯一識別帳戶和組織之間的相同圖表主題。
directoryAlias	string	已淘汰 - 查詢 IdentityRef “_links” 字典中參考的 Graph 使用者，即可擷取
displayName	string	這是圖形主體的非唯一顯示名稱。若要變更此欄位，您必須在來源提供者中變更其值。
id	string (uuid)
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	舊版後端相容性屬性。這是常數中的 WIT 特定值。除非用戶端以最新版本為目標，否則用戶端上將會隱藏（但存在）
profileUrl	string	已淘汰 - 未在 ToIdentityRef 的大部分預先存在實作中使用
uniqueName	string	已淘汰 - 請改用 Domain+PrincipalName
url	string	此 URL 是此圖表主體來源資源的完整路由。

LinkQueryMode

列舉型別

連結查詢模式。

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

LogicalOperation

列舉型別

分隔條件子句的邏輯運算符

值	Description
and
none
or

QueryHierarchyItem

Object

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

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

列舉型別

用於樹狀查詢的遞歸選項。

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

QueryType

列舉型別

查詢的類型。

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

ReferenceLinks

Object

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

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

WorkItemFieldOperation

Object

描述工作專案欄位作業。

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

WorkItemFieldReference

Object

工作專案中欄位的參考

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

WorkItemQueryClause

Object

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

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

WorkItemQuerySortColumn

Object

排序數據行。

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

其他資源