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
- Acesso: ser membro de um projeto com pelo menos acesso básico.
- Permissões: por padrão, os membros do projeto têm permissão para consultar o Analytics e criar exibições.
- Para obter mais informações sobre outros pré-requisitos relacionados à ativação de serviços e recursos e atividades gerais de rastreamento de dados, consulte Permissões e pré-requisitos para acessar o Analytics.
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 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 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) |
Team | TeamSK |
$expand=Teams($select=TeamName) |
Para especificar várias propriedades que precisam ser expandidas, especifique-as em uma única cláusula expand em 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 |