Partilhar via


Definir consultas básicas usando o OData Analytics

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

Usando o Analytics for 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 análise e referência de metadados para o Azure Boards Analytics. Além disso, as consultas neste artigo são focadas na recuperação de conjuntos de entidades de controle de trabalho, no entanto, os princípios se aplicam para consultar 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
  • Instruções de expansão de ninho
  • Ordenar resultados, opção ordenar por ordem

Nota

O serviço Analytics é automaticamente ativado e suportado na produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço Analytics estão geralmente disponíveis. Recomendamos a sua utilização e solicitamos que nos envie os seus comentários. Os dados disponíveis dependem da versão. A última versão suportada é v2.0, e a versão de pré-visualização mais recente é v4.0-preview. Para obter mais informações, consulte o artigo Controlo de Versões da API OData.

Nota

O serviço Analytics é instalado automaticamente e suportado na produção para todas as novas coleções de projetos para o Azure DevOps Server 2020 e versões posteriores. A integração do Power BI e o acesso ao feed OData do serviço Analytics estão geralmente disponíveis. Recomendamos a sua utilização e solicitamos que nos envie os seus comentários. Se tiver atualizado a partir do Azure DevOps Server 2019, poderá instalar o serviço Analytics durante a atualização.

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

Nota

O serviço Analytics está em pré-visualização para o Azure DevOps Server 2019. Pode ativá-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 Analytics estão em pré-visualização. Recomendamos a sua utilização e solicitamos que nos envie os seus comentários.

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

Pré-requisitos

  • Acesso: Ser membro de um projeto com pelo menos acesso Básico .
  • Permissões: por predefinição, os membros do projeto têm permissão para consultar o Analytics e criar vistas.
  • Para obter mais informações sobre outros pré-requisitos relacionados com a ativação de serviços e funcionalidades e atividades gerais de monitorização de dados, consulte Permissões e pré-requisitos para aceder ao Analytics.

Nota

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 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 definidas 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)

Gorjeta

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 do Project e do escopo 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 utilizadores

@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 obter 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 o Azure DevOps Analytics.

Gorjeta

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 a AreaSK ou IterationSK, ou 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 para retornar a AreaSK propriedade definida para o Fiber\Service Delivery\Internet Area Path 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 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 para 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 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 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"
    }
  ]
}

Devolver 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, Tipo de Item de Trabalho, Título e Estado dos itens de trabalho, adicione a seguinte cláusula à sua consulta. Esta cláusula especifica as propriedades que correspondem aos campos nomeados.

Nota

Os nomes de propriedade não contêm espaços. Sua consulta falhará se você adicionar espaços. As consultas OData requerem atenção tanto ao espaçamento quanto ao invólucro. Para entender como as propriedades de campo personalizado são rotuladas, consulte Referência de metadados para Painéis do Azure, Propriedades personalizadas.

Aqui especificamos para 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 os 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 para retornar 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, endswith startswithe muito mais. Consulte os recursos e cláusulas OData suportados, Funções suportadas.

Retornar dados para os campos Identidade, Caminho de Á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 declaração para retornar os dados de interesse. Estas propriedades estão frequentemente associadas a várias propriedades próprias. Por exemplo, com os campos Identidade, você pode especificar para retornar o nome de usuário ou o 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 incluir
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)
Equipa 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 vírgula.

$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 para 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 de navegação seguida de uma barra seguida do nome do campo para filtrar.

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 sob o caminho Fiber\Service Delivery\Voice Area da Fabrikam 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"

Gorjeta

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 de abril 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 ninho

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

Ordenar 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

Ordenar por Cláusula a incluir
ID 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óximos passos