Modelo de dados para Analytics

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

O modelo de dados de Análise do Azure DevOps consiste em conjuntos de entidades, cujos membros (entidades) contêm propriedades que você pode filtrar, agregar e resumir. Além disso, eles contêm propriedades de navegação que relacionam entidades entre si, fornecendo acesso a outras propriedades para seleção, filtragem e agrupamento.

Noções básicas sobre o modelo de dados do Analytics

O serviço de Análises fornece uma abordagem estruturada para acessar dados do Azure DevOps por meio de pontos de extremidade OData. Esse modelo de dados permite que você:

• Consultar dados de acompanhamento de trabalho: acessar itens de trabalho, áreas, iterações e metadados relacionados
• Analisar informações de pipeline: consultar dados de pipeline de construção e liberação
• Relatório sobre os resultados do teste: Acessar dados de execução e planejamento de teste
• Criar relatórios personalizados: criar relatórios do Power BI e outras soluções de análise

Namespaces de esquema

O modelo de dados do Analytics opera em dois namespaces de esquema:

• Microsoft.VisualStudio.Services.Analytics.Model
• Microsoft.VisualStudio.Services.Analytics

Esses namespaces organizam as entidades e definem sua estrutura, garantindo padrões consistentes de acesso a dados em diferentes recursos do Azure DevOps.

Conjuntos de entidades e tipos de entidade

Os tipos de entidade são chamados de tipos estruturados com uma chave. Eles definem as propriedades nomeadas e os relacionamentos de cada entidade. A chave de um EntityType se forma a partir de um subconjunto das propriedades primitivas, como, por exemplo, WorkItemId, PipelineId, ReleasePipelineId, e outras propriedades do tipo de entidade.

Os conjuntos de entidades são coleções nomeadas de entidades. Por exemplo, WorkItems é um conjunto de entidades que contém WorkItem entidades. A chave de uma entidade identifica exclusivamente a entidade dentro de um conjunto de entidades. Se vários conjuntos de entidades usarem o mesmo tipo de entidade, a mesma combinação de valores de chave poderá aparecer em mais de um conjunto de entidades e identificar entidades diferentes, uma por conjunto de entidades em que essa combinação de chaves aparece. Cada uma dessas entidades tem um entity-id diferente. Os conjuntos de entidades fornecem pontos de entrada no modelo de dados.

Os conjuntos de entidades são descritos em metadados OData e variam de acordo com o projeto. Você pode explorar a lista completa de conjuntos de entidades, tipos de entidade e propriedades solicitando os metadados OData para seu projeto. Para saber como, consulte Construir consultas OData para o Analytics.

Entidades compostas

As entidades compostas dão suporte a cenários específicos. O sistema os compõe de entidades mais simples, geralmente requer mais recursos de computação para gerar e pode retornar conjuntos de resultados maiores. Para obter o melhor desempenho e evitar limitações desnecessárias, certifique-se de consultar a entidade correta para seu cenário.

Por exemplo, WorkItemSnapshot combina WorkItemRevisions e Dates de modo que cada data tenha uma revisão para cada item de trabalho. Essa representação dá suporte a consultas OData que se concentram em dados de tendência para um conjunto filtrado de itens de trabalho. No entanto, você não deve usar essa entidade composta para consultar o estado atual dos itens de trabalho. Em vez disso, você deve usar a entidade WorkItems do conjunto para gerar uma consulta que execute mais rapidamente.

Da mesma forma, algumas entidades podem conter todos os valores históricos, enquanto outras podem conter apenas valores atuais. WorkItemRevisions Contém todo o histórico de itens de trabalho, que você não deve usar em cenários em que os valores atuais são de interesse.

Relações

Para gerar resultados de consulta mais complexos, você pode combinar entidades usando relações. Você pode empregar relações para expandir, filtrar ou resumir dados.

Algumas propriedades de navegação resultam em uma única entidade, enquanto outras resultam em uma coleção de entidades. O diagrama a seguir mostra entidades selecionadas e suas propriedades de navegação. Para maior clareza, algumas entidades e relacionamentos compostos foram omitidos.

Noções básicas sobre relações de entidade

O modelo de dados do Analytics usa vários tipos de relações:

• Um para muitos: uma única entidade-mãe está relacionada a várias entidades-filha (por exemplo, uma Área está relacionada a muitos Itens de Trabalho)
• Muitos para um: várias entidades se relacionam a uma única entidade pai (por exemplo, muitos Itens de Trabalho para uma área)
• Um para um: uma única entidade está relacionada a exatamente uma outra entidade
• Muitos para muitos: várias entidades estão relacionadas a várias outras entidades (por exemplo, WorkItems to Tags)

Chaves de relacionamento

As relações entre entidades também são representadas como chaves estrangeiras para que ferramentas externas possam unir entidades. Essas propriedades têm o sufixo "SK" e são tipos de dados inteiros ou GUID. As propriedades de data têm propriedades de chave de data inteira correspondentes com o seguinte formato: AAAAMMDD.

Tipos de entidade de acompanhamento de trabalho e conjuntos de entidades

Os seguintes tipos de entidade e conjuntos de entidades são suportados com as versões de API indicadas. Para obter uma referência completa, consulte Referência de metadados de acompanhamento de trabalho para Azure Boards Analytics.

Principais entidades de acompanhamento de trabalho para relatórios

Ao criar relatórios, considere estes conjuntos de entidades primárias:

• Relatórios de estado atuais: Usar WorkItems para o status atual do item de trabalho
• Relatórios de tendências históricas: Usar WorkItemSnapshot para análise de tendências ao longo do tempo
• Controle detalhado de alterações: uso WorkItemRevisions para histórico abrangente
• Relatórios específicos do conselho: uso WorkItemBoardSnapshot para análise de quadro kanban

Práticas recomendadas para usar o modelo de dados do Analytics

Otimização de desempenho

1. Escolha a entidade certa: utilize entidades de estado atuais (WorkItems) para relatórios de estado e entidades instantâneas para tendências
2. Filtrar antecipadamente: aplicar filtros no nível da entidade em vez de após a recuperação de dados
3. Limitar intervalos de dados: use filtros de data para restringir consultas de dados históricos
4. Usar agregações apropriadas: aproveite as funções de agregação internas quando possível

Padrões de design de consulta

Consultas de estado atuais

/WorkItems?$filter=State ne 'Closed'&$select=WorkItemId,Title,State

Consultas de tendências históricas

/WorkItemSnapshot?$filter=DateSK ge 20241001&$select=WorkItemId,State,DateSK

Navegação de relacionamento

/WorkItems?$expand=Area($select=AreaPath),AssignedTo($select=UserName)

Armadilhas comuns a serem evitadas

• Usando entidades de revisão para o estado atual: não use WorkItemRevisions quando WorkItems for suficiente
• Relações de expansão excessiva: expanda apenas as propriedades de navegação necessárias
• Filtros ausentes: sempre filtre grandes conjuntos de entidades para melhorar o desempenho
• Ignorando entidades compostas: use entidades compostas como WorkItemSnapshot para análise de tendências

Considerações de versão

Diferentes versões de API fornecem diferentes funcionalidades:

• v1.0: Entidades básicas de acompanhamento de trabalho
• v2.0: processo adicionado e recursos de filtragem aprimorados
• v3.0-preview: Foram adicionadas as entidades de pipeline e teste
• v4.0-preview: entidades compostas aprimoradas e métricas de pipeline adicionais

Escolha a versão apropriada com base nos requisitos de relatório e nas entidades que você precisa acessar.

Artigos relacionados

• Diretrizes de consulta do OData Analytics
• Análise WIT
• Agregação de dados
• Explorando metadados OData do Analytics
• Acompanhamento de trabalho, processo e limites de projeto
• Design do conjunto de dados de exibições de análise
• Construir consultas OData para Análise
• Segurança e permissões de análise