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 em seu navegador ou no Power BI.

Este artigo baseia-se nas informações fornecidas em Construir consultas OData para referência de Análise e Metadados para o Azure Boards Analytics. Além disso, as consultas neste artigo se concentram na recuperação de conjuntos de entidades de controle 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 da Área e Caminho de Iteração
  • Filtrar por uma propriedade de navegação
  • Consultar um intervalo de datas
  • Instruções de expansão de aninhamento
  • Classificar resultados, opção orderby

Observação

O serviço Analytics é automaticamente habilitado e suportado na produção para todos os Serviços de DevOps do Azure. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão disponíveis para o público em geral. Nós encorajamos você a usá-lo e nos dar feedback. Os dados disponíveis dependem da versão. A versão mais recente suportada é v2.0, e a versão de visualização mais recente é v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Observação

O serviço Analytics é automaticamente instalado e suportado na produção para todas as novas coleções de projetos do Azure DevOps Server 2020 e versões posteriores. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão disponíveis para o público em geral. Nós encorajamos você a usá-lo e nos dar feedback. Se você atualizou do Azure DevOps Server 2019, poderá instalar o serviço do Google Analytics durante a atualização.

Os dados disponíveis dependem da versão. A versão mais recente suportada é v2.0, e a versão de visualização mais recente é v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Observação

O serviço Analytics está em pré-visualização para o Azure DevOps Server 2019. Você pode habilitá-lo ou instalá-lo para uma coleção de projeto. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão em Pré-visualização. Nós encorajamos você a usá-lo e nos dar feedback.

Os dados disponíveis dependem da versão. A versão mais recente suportada é v2.0, e a versão de visualização mais recente é v4.0-preview. Para obter mais informações, consulte Controle de versão da API OData.

Pré-requisitos

  • Para exibir dados do Analytics e consultar o serviço, você precisa ser membro de um projeto com acesso básico ou superior. Por padrão, todos os membros do projeto recebem permissões para consultar Análise e definir exibições do Analytics.
  • Para saber mais sobre outros pré-requisitos relacionados à habilitação de serviço e recursos e atividades gerais de acompanhamento de dados, consulte Permissões e pré-requisitos para acessar o Analytics.

Observação

Neste artigo, a URL de consulta OData é definida para os Serviços de DevOps do Azure. Para construir uma consulta semelhante para um servidor local, consulte as orientações fornecidas em Construir consultas OData para o Google Analytics. Recomendamos que você ajuste as consultas fornecidas para sua organização e projeto para se familiarizar com a consulta 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 requisitos em Consultas de escopo do projeto 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 área

@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 os dados de seleção 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 obter propriedades válidas, consulte Referência de metadados para o Azure Boards Analytics e Data do calendário, Projeto e Referência de metadados do usuário para o Azure DevOps Analytics.

Dica

Se você não especificar as propriedades a serem retornadas, o Google 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 procurar o AreaSK ou IterationSK, ou outra propriedade de um Caminho de Área ou Caminho de Iteração, use as seguintes consultas.

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

A consulta a seguir especifica retornar a AreaSK propriedade definida para o Fabrikam Fiber\Service Delivery\InternetArea Path. Para especificar outras propriedades definidas para o conjunto de Areas entidades, consulte Referência de metadados para o Azure Boards Analytics, Areas.

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 seguintes dados.

{
  "@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 retornar a IterationSK propriedade definida para o Caminho de Iteração Fabrikam Fiber\Release 1\Sprint 3. Para especificar outras propriedades definidas para o conjunto de Iterations entidades, consulte Referência de metadados para o Azure Boards Analytics, Iterations.

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 seguintes dados.

{
  "@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 seguinte cláusula à sua consulta. Esta 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 invólucro. Para entender como as propriedades de campo personalizado são rotuladas, consulte Referência de metadados para quadros do Azure, propriedades personalizadas.

Aqui especificamos retornar os 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 Google Analytics retorna os seguintes dados.

@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 Recurso 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 Google Analytics retorna os seguintes dados.

  
@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 User Story, Bug e Backlog Work (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, endswithstartswithe muito mais. Consulte os recursos e cláusulas OData suportados, Funções suportadas.

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

As propriedades Select estão associadas às propriedades de navegação e não são diretamente acessíveis 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 campos de identidade, você pode especificar para retornar o nome de usuário ou o email do usuário.

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

Campos de tipo Propriedade referenciada Cláusulas de exemplo 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 de expansão dentro de uma lista delimitada por comman.

$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 dos critérios de filtro, você deve especificá-la no formato necessário.

Por exemplo, a cláusula a seguir especifica filtrar 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 para a iteração. Para usar outra entidade como filtro, coloque a propriedade navigation seguida de uma barra seguida do 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 voz da Fabrikam Fiber\Service Delivery\Voice Area 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

Não é possível usar a propriedade navigation diretamente em uma $select instrução. Em vez disso, você precisa usar $expando .

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 ao item de trabalho ID 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 seguintes dados.

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

Instruções de expansão de aninhamento

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 instruçõ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 IterationPath e que o Project é um objeto aninhado dentro do resultado JSON. Outro item importante a ser observado é a própria 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 os 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 descendente /WorkItems?$orderby=WorkItemId desc
Tipo e estado do item de trabalho /WorkItems?$orderby=WorkItemType,State

Próximas etapas