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
startswith
e 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 $expand
o .
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 |