Definir consultas básicas usando o OData Analytics

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

Usando o Analytics para Azure DevOps, você pode construir consultas básicas e filtradas para retornar dados de interesse. Você pode executar essas consultas diretamente no navegador ou no Power BI.

Este artigo se baseia nas informações fornecidas em Construir consultas OData para Análise e referência de metadados para Azure Boards Analytics. Além disso, as consultas neste artigo se concentram na recuperação de conjuntos de entidades de acompanhamento de trabalho, no entanto, os princípios se aplicam à consulta de outros conjuntos de entidades.

Neste artigo, você aprenderá a definir consultas que retornam os seguintes dados:

  • Contagem de itens (sem outros dados)
  • Contagem de itens e dados
  • Propriedades definidas para áreas ou caminhos de iteração
  • Colunas ou campos selecionados
  • Dados filtrados
  • Retornar dados para os campos Identidade, Caminho de Área e Caminho de Iteração
  • Filtrar por uma propriedade de navegação
  • Consultar um intervalo de datas
  • Aninhar instruções expand
  • Classificar resultados, opção ordenar por

Observação

O serviço do Analytics é habilitado automaticamente e tem suporte na produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço do Analytics estão em disponibilidade geral. Encorajamos você a usá-lo e nos dar feedback. Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0, e a versão prévia mais recente é v4.0-preview. Para obter mais informações, confira Sobre o controle de versão da API OData.

Observação

O serviço do Analytics é instalado automaticamente e tem suporte na produção para todas as novas coleções de projetos para Azure DevOps Server 2020 e versões posteriores. A integração do Power BI e o acesso ao feed OData do serviço do Analytics estão em disponibilidade geral. Encorajamos você a usá-lo e nos dar feedback. Se você atualizou de Azure DevOps Server 2019, poderá instalar o serviço do Analytics durante a atualização.

Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0, e a versão prévia mais recente é v4.0-preview. Para obter mais informações, confira Sobre o controle de versão da API OData.

Observação

O serviço do Analytics está em versão prévia para Azure DevOps Server 2019. Você pode habilitá-lo ou instalá-lo para uma coleção de projetos. A integração do Power BI e o acesso ao feed OData do serviço do Analytics estão em versão prévia. Encorajamos você a usá-lo e nos dar feedback.

Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0, e a versão prévia mais recente é v4.0-preview. Para obter mais informações, confira Sobre o controle de versão da API OData.

Pré-requisitos

Observação

Neste artigo, a URL de consulta OData é definida para Azure DevOps Services. Para construir uma consulta semelhante para um servidor local, consulte as diretrizes fornecidas em Construir consultas OData para o Analytics. Incentivamos você a ajustar as consultas fornecidas para sua organização e projeto para se familiarizar com a consulta de OData usando seu navegador.

Retornar uma contagem de itens (sem outros dados)

Para saber mais sobre o número de itens ou entidades definidos em uma organização ou projeto, especifique $apply=aggregate($count as Count) a opção de consulta. Por exemplo, as consultas a seguir retornam o número de projetos, itens de trabalho, Caminhos de Área e usuários definidos para uma organização.

https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Projects?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/WorkItems?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Areas?$apply=aggregate($count as Count)
https://analytics.dev.azure.com/{OrganizationName}/_odata/v4.0-preview/Users?$apply=aggregate($count as Count)

Dica

As consultas entre projetos falham quando o usuário que executa a consulta não tem acesso a todos os projetos. Leia mais sobre os requisitos em Consultas no escopo do Project e da organização.

Contagem de projetos

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Projects(Count)"
value	
   0	
     @odata.id	null
     Count	    28

Contagem de itens de trabalho

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#WorkItems(Count)"
value	
  0	
     @odata.id	null
     Count	    1166

Contagem de áreas

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    70

Contagem de usuários

@odata.context	"https://analytics.dev.azure.com/fabrikam/_odata/v4.0-preview/$metadata#Areas(Count)"
value	
  0	
     @odata.id	null
     Count	    16

Retornar uma contagem de itens e dados

Para retornar uma contagem de itens junto com dados selecionados para os itens, especifique a $count=true opção de consulta. Por exemplo, as consultas a seguir retornam uma contagem de itens de trabalho, Caminhos de Área e usuários definidos para um projeto junto com as propriedades especificadas. Para propriedades válidas, consulte Referência de metadados para Azure Boards Analytics e Data do calendário, Projeto e Referência de metadados do usuário para Azure DevOps Analytics.

Dica

Se você não especificar as propriedades a serem retornadas, o Analytics retornará todas as propriedades definidas para o tipo de entidade especificado.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/WorkItems?$count=true&$select=WorkItemId,Title,WorkItemType 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Areas?$count=true&$select=AreaName,AreaPath 
https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/v4.0-preview/Users?$count=true&$select=UserName,UserEmail

Propriedades de áreas ou iterações

Para pesquisar a AreaSK propriedade or IterationSKou outra propriedade de um Caminho de Área ou Caminho de Iteração, use as consultas a seguir.

Retornar o AreaSK para um caminho de área específico

A consulta a seguir especifica o retorno da AreaSK propriedade definida para o Caminho da Área da Internet Fiber\Service Delivery\da Fabrikam. Para especificar outras propriedades definidas para o conjunto de Areas entidades, consulte Referência de metadados para Azure Boards Analytics, Áreas.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Service Delivery\Internet' &$select=AreaSK

A consulta retorna os dados a seguir.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "637dc203-0549-4415-9663-b6358ac27d21"
    }
  ]
}

Retornar o IterationSK para um caminho de iteração específico

A consulta a seguir especifica o retorno da IterationSK propriedade definida para o Caminho de Iteração da Fabrikam Fiber\Release 1\Sprint 3. Para especificar outras propriedades definidas para o conjunto de Iterations entidades, consulte Referência de metadados para Azure Boards Analytics, Iterações.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Iterations?$filter=IterationPath eq 'Fabrikam Fiber\Release 1\Sprint 3' &$select=IterationSK

A consulta retorna os dados a seguir.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Iterations(IterationSK)",
  "value": [
    {
      "IterationSK": "862e961a-ac7a-4fcc-9ebc-8afd0c12fed5"
    }
  ]
}

Retornar propriedades ou campos específicos

Para retornar propriedades específicas ou campos de item de trabalho, adicione uma $select cláusula que especifique os nomes de propriedade.

Por exemplo, para retornar a ID do Item de Trabalho, o Tipo de Item de Trabalho, o Título e o Estado dos itens de trabalho, adicione a cláusula a seguir à sua consulta. Essa cláusula especifica as propriedades que correspondem aos campos nomeados.

Observação

Os nomes de propriedade não contêm espaços. Sua consulta falhará se você adicionar espaços. As consultas OData exigem atenção ao espaçamento e ao uso de maiúsculas e minúsculas. Para entender como as propriedades de campo personalizado são rotuladas, consulte Referência de metadados para Azure Boards, Propriedades personalizadas.

Aqui, especificamos o retorno dos três principais itens de trabalho.

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$top=3

O Analytics retorna os dados a seguir.

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
   0	
      WorkItemId    462
      Title         "Test case"
      WorkItemType  "Test Case"
      State         "Design"
   1	
      WorkItemId	   491
      Title          "Change color settings"
      WorkItemType   "Shared Steps"
      State          "Active"
   2	
      WorkItemId	   461
      Title          "Test impediment"
      WorkItemType   "Impediment"
      State          "Open"

.

Filtrar seus dados

Para filtrar um conjunto de entidades para retornar itens selecionados, especifique uma $filter cláusula que especifique os critérios que os itens devem atender. Com base na última consulta, aqui adicionamos uma cláusula de filtro para retornar apenas os tipos de item de trabalho Feature que estão no estado Em Andamento .

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=State eq 'In Progress'

https://analytics.dev.azure.com/fabrikam/Fabrikam Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'&$select=WorkItemId,Title,AssignedTo,State

O Analytics retorna os dados a seguir.

  
@odata.context	"https://analytics.dev.azure.com/kelliott/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,State)"
value	
  0	
      WorkItemId	380
      Title	"Refresh web look, feel, performance factors"
      State	"In Progress"
  1	
      WorkItemId	480
      Title	"Customer Phone - Phase 1"
      State	"In Progress"
  2	
      WorkItemId	493
      Title	"Change initial view"
      State	"In Progress"
  3	
      WorkItemId	479
      Title	"Customer Web - Phase 1"
      State	"In Progress"
  4	
      WorkItemId	551
      Title	"Mobile feedback"
      State	"In Progress"

Especificar várias cláusulas de filtro

Você pode usar AND e OR especificar várias cláusulas de filtro.

Por exemplo, a consulta a seguir especifica o retorno de itens de trabalho do tipo História de Usuário, Bug e Trabalho de Lista de Pendências (um tipo de item de trabalho personalizado) que estão nos estados Novo, Confirmado ou Ativo. Use parênteses para agrupar cláusulas de filtro conforme necessário.

Além disso, você pode aplicar várias funções, como contains, startswith, endswith e muito mais. Consulte os recursos e cláusulas do OData com suporte, Funções com suporte.

Retornar dados para os campos Identidade, Caminho de Área e Caminho de Iteração

As propriedades selecionadas estão associadas a propriedades de navegação e não podem ser acessadas diretamente usando a $select instrução. Você deve usar uma $expand instrução para retornar os dados de interesse. Essas propriedades são frequentemente associadas a várias propriedades próprias. Por exemplo, com os campos Identidade, você pode especificar o retorno do nome de usuário ou do e-mail do usuário.

A tabela a seguir fornece exemplos de como expandir várias dessas propriedades.

Campos de tipo Propriedade referenciada Exemplos de cláusulas a serem incluídas
Datetime DateSK $expand=CreatedDate($select=Date) ou
$expand=CreatedDate($select=WeekStartingDate)
Identidade UserSK $expand=AssignedTo($select=UserName) ou
$expand=AssignedTo($select=UserEmail)
Área AreaSK $expand=Area($select=AreaName) ou
$expand=Area($select=AreaPath)
Iteração IterationSK $expand=Iteration($select=IterationName) ou
$expand=Iteration($select=IterationPath) ou
$expand=Iteration($select=StartDate)
Project ProjectSK $expand=Project($select=ProjectName)
Equipe TeamSK $expand=Teams($select=TeamName)

Para especificar várias propriedades que precisam ser expandidas, especifique-as em uma única cláusula expand dentro de uma lista delimitada por vírgulas.

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Filtrar por uma propriedade de navegação

Ao especificar uma propriedade de navegação como parte de seus critérios de filtro, você deve especificá-la no formato necessário.

Por exemplo, a cláusula a seguir especifica a filtragem de itens de trabalho com base na Iteração 1 definida para o projeto.

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Neste exemplo, Iteration é o nome da propriedade de navegação e IterationPath corresponde ao caminho completo da iteração. Para usar outra entidade como filtro, coloque a propriedade navigation seguida por uma barra seguida pelo nome do campo a ser filtrado.

E aqui está a consulta OData completa:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Aqui está outro exemplo que solicita que os cinco principais itens de trabalho no Caminho da Área de Fibra da Fabrikam\Entrega de Serviços\Voz sejam retornados.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Area/AreaPath eq 'Fabrikam Fiber\Service Delivery\Voice'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)"
value	
  0	
     WorkItemId	361
     Title        "Hello World Web Site"
     WorkItemType	"Product Backlog Item"
     State        "Removed"
  1	
     WorkItemId	362
     Title        "Resume"
     WorkItemType	"Product Backlog Item"
     State        "New"
  2	
     WorkItemId	363
     Title        "Welcome back page"
     WorkItemType	"Product Backlog Item"
     State        "Done"
  3	
     WorkItemId	365
     Title        "Pause"
     WorkItemType	"Feature"
     State        "New"
  4	
     WorkItemId	374
     Title        "Fix performance issues"
     WorkItemType	"Task"
     State        "To Do"

Dica

Você não pode usar a propriedade de navegação diretamente em uma $select instrução. Em vez disso, você precisa usar $expand.

O exemplo de filtragem anterior para o Caminho de Iteração não retorna o caminho de iteração porque ele está contido em uma entidade relacionada. Para retornar dados em uma entidade relacionada, adicione uma $expand instrução:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration

E aqui está um exemplo que retorna informações atribuídas à ID de item de trabalho 480.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&&$expand=Iteration
   
@odata.context	"https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)"
value	
  0	
      WorkItemId           480
      Title                "Customer Phone - Phase 1"
      WorkItemType	       "Feature"
      State	               "In Progress"
      Iteration	
          ProjectSK	       "56af920d-393b-4236-9a07-24439ccaa85c"
          IterationSK	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationId	       "c7063041-ff3a-4d7f-bb46-c433c7030d59"
          IterationName	   "Sprint 1"
          Number	            55297
          IterationPath	    "Fabrikam Fiber\\Release 1\\Sprint 1"
          StartDate	        "2022-01-17T00:00:00-08:00"
          EndDate	            "2022-02-04T23:59:59.999-08:00"
          IterationLevel1	    "Fabrikam Fiber"
          IterationLevel2	    "Release 1"
          IterationLevel3	    "Sprint 1"
          IterationLevel4	    null
          IterationLevel5	    null
          IterationLevel6	    null
          IterationLevel7	    null
          IterationLevel8	    null
          IterationLevel9	    null
          IterationLevel10	null
          IterationLevel11	null
          IterationLevel12	null
          IterationLevel13	null
          IterationLevel14	null
          Depth	            2
          IsEnded	        	true
      AnalyticsUpdatedDate	"2022-01-18T22:18:58.17Z"

Como você pode ver, o Caminho de Iteração é expandido no resultado e todos os dados de iteração são retornados. Provavelmente são mais dados do que você deseja.

Para retornar menos dados, adicione uma $select instrução na iteração também:

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 10000&$expand=Iteration($select=Name,IterationPath)

Em seguida, ele retorna os dados a seguir.

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration,Iteration(Name,IterationPath))",
  "value":[
    {
      "WorkItemId":10000,
      "WorkItemType":"Task",
      "Title":"Some title",
      "State":"Completed",
      "Iteration":{
        "Name":"Sprint 55",
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55"
      }
    }
  ]
}

Consultar um intervalo de datas

O exemplo a seguir retorna itens de trabalho cuja Data Alterada é maior que igual a 1º de janeiro de 2021.

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-01-01Z

O exemplo a seguir retorna itens de trabalho cuja Data Alterada ocorre durante a semana de 26 a 30 de abril de 2021.

https://analytics.dev.azure.com{OrganizationName}/{ProjectName}/_odata/{version}/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2021-04-26Z&ChangedDate le 2021-04-30Z

Aninhar instruções expand

No OData, você pode aninhar $expand instruções. Por exemplo, você pode escrever a instrução de consulta anterior para exibir o projeto do qual a iteração faz parte:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($expand=Project)

Ele retorna o seguinte JSON:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database",
      "WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46",
        "Name":"Sprint 55",
        "Number":13021,
        "IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "StartDate":"2013-09-23T00:00:00Z",
        "EndDate":"2013-10-11T00:00:00Z",
        "IterationLevel1":"Fabrikam",
        "IterationLevel2":" Sprints",
        "IterationLevel3":"Sprint 55",
        "Level":2,
        "IsDeleted":false,
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Você também pode combinar $expand e $select declarações. Por exemplo, você pode alterar a consulta anterior para retornar apenas o Nome da Iteração e o Caminho da Iteração:

/WorkItems?$filter=WorkItemId eq 10000&$expand=Iteration($select=IterationId,IterationPath;$expand=Project)

Ele retorna o seguinte JSON:

{
  "@odata.context":"https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata#WorkItems(Iteration(IterationId,IterationPath,Project))",
  "value":[
    {
      "WorkItemId":10000,
      "Revision":3,
      "Watermark":283397,
      "Title":"Production deployment and testing for Entitlement API v2 and Subscriber database","WorkItemType":"Task",
      "ChangedDate":"2014-07-10T19:29:58.41Z",
      "CreatedDate":"2014-04-19T22:44:58.31Z",
      "State":"Completed",
      "Reason":"Completed",
      "Priority":2,
      "CompletedWork":10.0,
      "OriginalEstimate":20.0,
      "Count":1,
      "Iteration":{
        "IterationId":"7a2c246e-fc62-41af-ad18-62332017bc46","IterationPath":"Fabrikam\\Sprints\\Sprint 55",
        "Project":{
          "ProjectId":"b924d696-3eae-4116-8443-9a18392d8544",
          "ProjectName":"Fabrikam",
          "IsDeleted":false
        }
      }
    }
  ]
}

Observe que o resultado aqui mostra apenas o IterationId e o IterationPath e que o Project é um objeto aninhado dentro do resultado JSON. Outro item importante a ser observado é o próprio URL. Ao usar uma $select instrução e uma $expand cláusula, você deve usar um ponto-e-vírgula (;) antes do $expand. Qualquer outra coisa resultará em um erro.

Classificar resultados, orderby opção

Especifique a $orderby opção para classificar seus resultados ou especifique a sequência na qual os resultados são retornados. Você pode classificar em ordem crescente ou decrescente usando palavras-chave asc ou desc, respectivamente. Alguns exemplos são mostrados

Classificar por Cláusula a incluir
{1>ID<1} do item de trabalho /WorkItems?$orderby=WorkItemId
ID do item de trabalho decrescente /WorkItems?$orderby=WorkItemId desc
Tipo e estado do item de trabalho /WorkItems?$orderby=WorkItemType,State

Próximas etapas