Compartilhar via

Práticas recomendadas de análise

  • Artigo

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

O Analytics é a plataforma de relatórios para o Azure DevOps, que permite que você obtenha insights de seus dados e tome decisões controladas por dados. O Analytics é otimizado para acesso rápido de leitura e agregações baseadas em servidor e fornece várias ferramentas para visualizar e analisar seus dados. Neste artigo, compartilhamos algumas práticas recomendadas para usar o Analytics no Azure DevOps.

Pré-requisitos

  • Nível de acesso: você deve ser membro de um projeto com acesso básico ou superior.
  • Permissão: por padrão, os membros do projeto têm permissão para consultar o Analytics e criar vistas da propriedade.
  • 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.
  • Se você for um desenvolvedor de extensão, examine as diretrizes de consulta do OData Analytics.

Familiarize-se com os metadados do Analytics

Consulte os metadados do Analytics para obter familiaridade com os tipos de entidade, conjuntos de entidades, propriedades e listas enumeradas. Para obter mais informações, consulte Consultar o serviço de Análise, metadados OData do Analytics e Referência de entidades e propriedades para Azure Boards.

Estruture sua consulta para retornar os dados necessários

Para consultar o conjunto de dados mínimo necessário para criar seu relatório, siga estas práticas:

Escolha o conjunto de entidades para dar suporte ao seu relatório

Embora existam vários EntitySets compatíveis com o modelo de dados do Analytics, apenas alguns são usados para gerar relatórios.EntitySets Usado para criar relatórios se enquadram em três categorias:

  • Atual: Contém informações sobre a configuração atual do EntityTypes arquivo .EntitySet
  • Instantâneo: entidades compostas que combinam dados históricos e relacionados a datas. As entidades de instantâneo devem ser usadas para dar suporte a relatórios de agregação.
  • Revisão: Contém informações históricas. Por exemplo, WorkItemRevision mantém dados sobre o histórico de itens de trabalho.

Aqui está uma referência rápida para os EntityTypes a serem especificados para dar suporte a relatórios. Para obter uma descrição de cada um desses EntityTypes, consulte Modelo de dados para Analytics.

Dados do Azure DevOps Atual Instantâneo Revisão
Azure Boards WorkItems WorkItemSnapshot
WorkItemBoardSnapshot		 WorkItemRevisions
Azure Pipelines Pipelines
PipelineTasks		 ParallelPipelineJobsSnapshot
PipelineRuns, PipelineRunActivityResults
Azure Pipelines e testes TestResultsDaily TestRuns
Azure Test Plans Tests
TestConfiguration
TestPoints
WorkItems		 TestResultsDaily
TestPointHistorySnapshot

Especifique as partes da consulta na ordem em que são executadas

A ordem recomendada para as várias partes da consulta é especificá-las na ordem a seguir, que é a ordem em que são avaliadas. Para obter uma descrição de cada parte da consulta, consulte Consultar o serviço Analytics, Opções de consulta.

  1. $apply
  2. $filter
  3. $orderby
  4. $expand
  5. $select
  6. $skip
  7. $top

Todas as consultas devem conter uma $apply cláusula or $select , caso contrário, você poderá receber uma mensagem de aviso.

Limite as colunas solicitadas em sua consulta

Você especifica colunas de dados a serem retornadas usando a $select cláusula. Com a personalização, os itens de trabalho podem ter vários campos associados a eles. Quanto mais propriedades ou campos uma consulta referenciar, mais caro será processá-lo. Considere o relatório que você deseja gerar e certifique-se de solicitar apenas os campos necessários.

Por exemplo, para retornar os campos ID, Tipo de Item de Trabalho, Título e Estado para um conjunto filtrado de itens de trabalho, especifique a seguinte $select cláusula: $select=WorkItemId, WorkItemType, Title, State.

Para pesquisar a lista de propriedades e seus nomes de campo correspondentes, consulte Referência de entidades e propriedades para Azure Boards.

Criar consultas de visualização

Consultas de visualização são consultas que retornam um único registro ou um pequeno subconjunto de registros. Ao criar uma consulta de visualização, você pode refinar sua consulta para garantir que está solicitando os dados necessários. Começando com uma consulta mínima, você pode criar sua consulta para garantir que está especificando os registros desejados e os dados de coluna necessários.

Usando o apply=aggregate($count as Count), você pode identificar o número de registros que está solicitando. Por exemplo, a sintaxe a seguir consulta o número de itens de trabalho para o projeto Fabrikam Fiber .

https://analytics.dev.azure.com/content-learn/Content/_odata/v4.0-preview/WorkItems? $apply=aggregate($count as Count)

A resposta retorna um total de 1415 itens de trabalho.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam Fbier/_odata/v4.0-preview/$metadata#WorkItems(Count)",
   "value": [
  {
     "@odata.id": null,
   "Count": 1415
  }
  ]
}

Limitar as consultas aos projetos aos quais você tem acesso

As consultas de escopo do projeto retornam informações sobre um único projeto, enquanto as consultas de escopo da organização são projetadas para retornar informações que cruzam os limites do projeto. As consultas no escopo da organização exigem permissões de usuário mais amplas ou restrições de escopo cuidadosas para garantir que sua consulta não seja bloqueada devido à falta de permissões de projeto.

Se você tiver acesso a um ou mais projetos, mas não a todos os projetos, e enviar uma consulta no escopo da organização, receberá uma mensagem de erro.

"VS403496: The query results include data in one or more projects for which you do not have access. Add one or more projects filters to specify the project(s) you have access to in 'WorkItems' entity. If you're using $expand or navigation properties, project filter is required for those entities. More information can be found here: https://go.microsoft.com/fwlink/?LinkId=786441."

Para obter mais informações, consulte Consultas no escopo do projeto e da organização.

Revise mensagens de aviso e erro

O Google Analytics analisa cada consulta recebida em busca de violações às regras. Ele retorna mensagens de aviso quando detecta uma violação. Recomendamos que você revise essas mensagens para corrigir ou melhorar a estrutura da consulta.

Limitação de taxa

As consultas feitas ao Analytics para Azure DevOps Services estão sujeitas a limites de taxa. Se forem enviadas muitas consultas que solicitam o retorno de grandes quantidades de dados em um curto período de tempo, o serviço poderá estar sujeito a limitação. Para obter mais informações, consulte Taxa e limites de uso.

Você pode revisar o uso do serviço e de indivíduos acessando Configurações>da Organização Uso e exercitando os filtros. Por exemplo, a imagem a seguir mostra o uso de Jamal Hartnett para o serviço Analytics.

Captura de tela da página Uso para um único usuário e Analytics.