Condividi tramite


Query per gli elementi di lavoro collegati

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

L'esecuzione di query sugli elementi di lavoro tra i collegamenti è molto simile all'uso di proprietà di navigazione tipiche. I collegamenti stessi sono tuttavia entità, quindi c'è una certa complessità aggiuntiva.

Esistono due modi per eseguire query per gli elementi di lavoro collegati. Il primo è la gerarchia padre/figlio e il secondo è la proprietà di navigazione Links.

In questo articolo si apprenderà quanto segue:

  • Come costruire una query per restituire elementi di lavoro collegati gerarchicamente (padre-figlio)
  • Come costruire una query per restituire elementi di lavoro collegati non gerarchici (correlati, diretti)

Nota

Il servizio Analytics viene abilitato e supportato automaticamente nell'ambiente di produzione per tutti i Servizi DevOps di Azure. L'integrazione di Power BI e l'accesso al feed OData del servizio di analisi sono disponibili a livello generale. Ti invitiamo a usarlo e a inviare commenti e suggerimenti. I dati disponibili dipendono dalla versione. La versione supportata più recente è v2.0e la versione di anteprima più recente è v4.0-preview. Per altre informazioni, vedere Controllo delle versioni dell'API OData.

Nota

Il servizio Analytics viene installato e supportato automaticamente nell'ambiente di produzione per tutte le nuove raccolte di progetti per Azure DevOps Server 2020 e versioni successive. L'integrazione di Power BI e l'accesso al feed OData del servizio di analisi sono disponibili a livello generale. Ti invitiamo a usarlo e a inviare commenti e suggerimenti. Se è stato eseguito l'aggiornamento da Azure DevOps Server 2019, è possibile installare il servizio Analytics durante l'aggiornamento.

I dati disponibili dipendono dalla versione. La versione supportata più recente è v2.0e la versione di anteprima più recente è v4.0-preview. Per altre informazioni, vedere Controllo delle versioni dell'API OData.

Nota

Il servizio Analytics è disponibile in anteprima per Azure DevOps Server 2019. È possibile abilitarlo o installarlo per una raccolta di progetti. L'integrazione di Power BI e l'accesso al feed OData del servizio di analisi sono disponibili in anteprima. Ti invitiamo a usarlo e a inviare commenti e suggerimenti.

I dati disponibili dipendono dalla versione. La versione supportata più recente è v2.0e la versione di anteprima più recente è v4.0-preview. Per altre informazioni, vedere Controllo delle versioni dell'API OData.

Nota

Gli esempi illustrati in questo articolo si basano su un URL di Azure DevOps Services. Per Azure DevOps Server, è necessario sostituire l'URL del server locale.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/

Gerarchia padre-figlio

È possibile includere elementi correlati tramite collegamenti padre/figlio usando $expand le proprietà Padre e Figlio.

Esempio: query padre-figlio

Per restituire informazioni sugli elementi figlio di un elemento, utilizzare $expand nella proprietà di navigazione Children . Il frammento di codice seguente richiede di restituire gli elementi figlio dell'ID elemento di lavoro 359 dal progetto Fabrikam Fiber.

Richiedi

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 359&$select=WorkItemId, Title, WorkItemType, State&$expand=Children($select=WorkItemId,Title, WorkItemType, State)

La risposta restituisce caratteristiche 479 e 480, che sono figli dell'epica 359.

Nota

La maggior parte delle query OData che richiedono informazioni sul collegamento all'elemento di lavoro restituirà risultati, ma anche un avviso. L'avviso è un promemoria per seguire le linee guida consigliate per le query descritte in Linee guida per le query di OData Analytics. Tuttavia, gli esempi di query forniti sono validi.

Response

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Children(WorkItemId,Title,WorkItemType,State))"
vsts.warnings@odata.type	"#Collection(String)"
@vsts.warnings	
0	"VS403508: Using the Parent, Children, Descendants or Revision properties in a filter or expand is not recommended. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."
value	
 0	
   WorkItemId	359
   Title	"Phase 1 - Customer access and engagement 5"
   WorkItemType	"Epic"
   State	"In Progress"
   Children	
      0	
        WorkItemId	480
        Title	"Customer Phone - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"
      1	
        WorkItemId	479
        Title	"Customer Web - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"

Esempio: query da figlio a padre

Sostituendo Children with Parent nell'opzione $expand , è possibile recuperare l'antenati di un elemento.

La query seguente richiede di restituire l'elemento padre dell'ID elemento di lavoro 1048 dal progetto Fabrikam Fiber.

Richiedi

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,State&$expand=Parent($select=WorkItemId,Title,WorkItemType, State)&$filter=WorkItemId eq 1048

La risposta restituisce la funzionalità 480, che è l'elemento padre del backlog del prodotto 1048.

Response

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Parent(WorkItemId,Title,WorkItemType,State))"
vsts.warnings@odata.type	"#Collection(String)"
@vsts.warnings	
0	"VS403508: Using the Parent, Children, Descendants or Revision properties in a filter or expand is not recommended. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060."
value	
  0	
     WorkItemId	1048
     Title	"Support reset"
     WorkItemType	"Product Backlog Item"
     State	"New"
     Parent	
        WorkItemId	480
        Title	"Customer Phone - Phase 1"
        WorkItemType	"Feature"
        State	"In Progress"

Oltre alla gerarchia padre/figlio, gli elementi possono essere direttamente correlati ad altri elementi con tipi di collegamento come Correlati o Duplicati. La proprietà di navigazione Collegamenti consente di richiedere queste relazioni.

Per recuperare i collegamenti associati a un elemento, è possibile $expand utilizzare la proprietà di navigazione Collegamenti . In questo esempio vengono recuperati SourceWorkItemId, TargetWorkItemId e LinkTypeName per tutti i collegamenti associati all'elemento di lavoro 363.

Richiedi

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId%20eq%20363&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName)

Response

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName))",
    "value": [{
        "WorkItemId": 363,
        "Title": "Welcome back page",
        "WorkItemType": "Product Backlog Item",
        "State": "Done",
        "Links": [{
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 400,
            "LinkTypeName": "Related"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 470,
            "LinkTypeName": "Tested By"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 501,
            "LinkTypeName": "Related"
        }, {
            "SourceWorkItemId": 363,
            "TargetWorkItemId": 1079,
            "LinkTypeName": "Tested By"
        }
    }]
}

Esempio: Richiedere i dettagli degli elementi collegati

È possibile includere i dettagli degli elementi di lavoro collegati usando $expand nelle proprietà di navigazione TargetWorkItem o SourceWorkItem . In questo esempio vengono recuperati workItemId, Title e State dell'elemento di lavoro di destinazione per ogni collegamento.

Richiedi

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId%20eq%20103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$expand=TargetWorkItem($select=WorkItemId,Title,State))

Response

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 48,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 48,
                "Title": "Story 15",
                "State": "Resolved"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 50,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 50,
                "Title": "Story 17",
                "State": "Active"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 55,
            "LinkTypeName": "Child",
            "TargetWorkItem": {
                "WorkItemId": 55,
                "Title": "Story 22",
                "State": "New"
            }
        }, {
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

Potresti anche essere interessato a un particolare tipo di collegamento tra gli elementi. Specificare la proprietà LinkTypeName in una $filter clausola . Nell'esempio di query seguente vengono espansi tutti i collegamenti correlati e vengono filtrati tutti gli altri tipi di collegamento per l'elemento di lavoro 103.

Richiedi

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,WorkItemType,State&$filter=WorkItemId eq 103&$expand=Links($select=SourceWorkItemId,TargetWorkItemId,LinkTypeName;$filter=LinkTypeName eq 'Related';$expand=TargetWorkItem($select=WorkItemId,Title,State))

Response

{
    "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,WorkItemType,State,Links(SourceWorkItemId,TargetWorkItemId,LinkTypeName,TargetWorkItem(WorkItemId,Title,State)))",
    "value": [{
        "WorkItemId": 103,
        "Title": "Feature Y",
        "WorkItemType": "Feature",
        "State": "New",
        "Links": [{
            "SourceWorkItemId": 103,
            "TargetWorkItemId": 112,
            "LinkTypeName": "Related",
            "TargetWorkItem": {
                "WorkItemId": 112,
                "Title": "Some issue",
                "State": "Active"
            }
        }]
    }]
}

Passaggi successivi