Partilhar via

Definir consultas básicas usando o OData Analytics

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

Você pode usar o Analytics for Azure DevOps para construir consultas OData para retornar dados nos quais está interessado. Você pode executar essas consultas em seu navegador ou em software cliente como Excel ou Power BI.

Este artigo concentra-se em consultas para recuperar conjuntos de entidades de controlo de trabalho dos Azure Boards, mas os princípios aplicam-se à consulta de outros conjuntos de entidades. Para obter mais informações, consulte Construir consultas OData para análise e referência de metadados para o Azure Boards Analytics.

Este tutorial mostra como:

  • Defina consultas que retornam contagens de itens, com ou sem seus dados.
  • Selecione esta opção para retornar dados para propriedades específicas.
  • Filtrar dados por propriedades específicas.
  • Retorna dados para propriedades de navegação como Identidade, Caminho de Área e Caminho de Iteração.
  • Utilize expand cláusulas e expand instruções aninhadas.
  • Intervalos de datas de consulta.
  • Use a opção orderby para classificar os resultados.

Nota

O serviço Analytics é automaticamente habilitado e suportado na produção para todos os serviços nos Serviços de DevOps do Azure. A integração do Power BI e o acesso ao feed OData do serviço Analytics estão geralmente disponíveis. Você é incentivado a usar o feed OData do Google Analytics e fornecer feedback.

Os dados disponíveis dependem da versão. A última versão suportada da API OData é v2.0, e a versão de 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. Você é incentivado a usar o feed OData do Google Analytics e fornecer feedback. Se você atualizar 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 da API OData é v2.0, e a versão de visualização mais recente é v4.0-preview. Para obter mais informações, consulte o artigo Controlo de Versões da API OData.

Pré-requisitos

Categoria Requerimentos
Níveis de acesso - Membro do projeto.
- Pelo menos acesso básico .
Permissões Por padrão, os membros do projeto têm permissão para consultar o Google Analytics e criar modos de exibição. 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

As consultas entre projetos falham quando o usuário que executa a consulta não tem acesso a todos os projetos. Para obter mais informações sobre requisitos, consulte Consultas de escopo do projeto e da organização.

Nota

As consultas OData neste artigo usam a URL de consulta definida para os Serviços de DevOps do Azure, https://analytics.dev.azure.com/. Substitua sua própria organização e nomes de projeto nas consultas para se familiarizar com a consulta OData.

Para um servidor local, você pode construir consultas semelhantes com uma URL baseada em seu servidor e coleção de projetos, https://<servername>/<ProjectCollectionName>/. Para obter mais informações, consulte Construir consultas OData para Analytics.

Obter uma contagem de itens

Para retornar apenas uma contagem de itens ou entidades definidas em uma organização ou projeto sem incluir outras informações, aplique a $apply=aggregate($count as Count) opção de consulta. As consultas a seguir retornam o número de projetos, itens de trabalho, caminhos de área e usuários em 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)

As consultas anteriores retornam resultados como o exemplo a seguir para projetos na fabrikam organização:

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

Obter uma contagem de itens e seus dados

Para devolver uma contagem de itens juntamente com os dados selecionados para os itens, especifique o parâmetro de consulta $count=true na instrução select. As consultas a seguir retornam uma contagem de itens de trabalho, caminhos de área e usuários definidos para um projeto, juntamente com 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.

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

Nota

Para retornar todas as propriedades definidas para um tipo de entidade especificado, você pode usar $count=true sem select nenhuma cláusula. No entanto, se não incluir uma cláusula $select ou $apply, receberá um aviso como VS403507: The specified query does not include a $select or $apply clause which is recommended for all queries. Details on recommended query patterns are available here: https://go.microsoft.com/fwlink/?linkid=861060. Para evitar esbarrar em limites de uso, inclua sempre uma cláusula $select ou $apply nas suas consultas.

Por exemplo, a consulta a seguir solicita a contagem e os nomes de usuário dos usuários no projeto Fabrikam Fibra :

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Users?$count=true&$select=UserName

A consulta retorna uma contagem de 5 utilizadores com os seus Nomes de Utilizador.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Users(UserName)",
  "@odata.count": 5,
  "value": [
    {
      "UserName": "Microsoft.VisualStudio.Services.TFS"
    },
    {
      "UserName": "fabrikamfiber1@hotmail.com"
    },
    {
      "UserName": "Jamal Hartnett"
    },
    {
      "UserName": "fabrikamfiber5@hotmail.com"
    },
    {
      "UserName": "fabrikamfiber2@hotmail.com"
    }
  ]
}

Selecionar 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 $select=WorkItemId,WorkItemType,Title,State cláusula à sua consulta.

A $select cláusula especifica os nomes de propriedade que correspondem aos campos nomeados. Os nomes de propriedade em consultas OData exigem atenção ao espaçamento e ao invólucro. Embora nomes de propriedades para exibição, como ID de Item de Trabalho, possam conter espaços, nomes formais de propriedades não podem conter espaços.

Para obter mais informações sobre nomes e rótulos de propriedade, consulte Referência de metadados para painéis do Azure. Para entender como as propriedades de campo personalizado são rotuladas, consulte Propriedades personalizadas.

A consulta de exemplo a seguir solicita as IDs, títulos e estados do item de trabalho para os três principais itens de trabalho no projeto Fabrikam Fibra.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State)",
  "value": [
    {
      "WorkItemId": 31,
      "Title": "About screen",
      "WorkItemType": "Task",
      "State": "New"
    },
    {
      "WorkItemId": 30,
      "Title": "Change background color",
      "WorkItemType": "Task",
      "State": "Active"
    },
    {
      "WorkItemId": 32,
      "Title": "Standardize on form factors",
      "WorkItemType": "Task",
      "State": "Active"
    }
  ]
}

Filtrar dados

Para filtrar um conjunto de entidades para retornar itens específicos, adicione uma $filter cláusula que especifique os critérios que os itens devem atender. A cláusula de filtro a seguir retorna apenas os tipos de item de trabalho Feature que estão no estado Em Andamento .

/WorkItems?$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

A consulta de exemplo a seguir especifica para retornar ID do Item de Trabalho, Tipo de Trabalho, Título e Estado somente dos itens de trabalho de Funcionalidade que estão no estado Em Andamento.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=WorkItemType eq 'Feature' and State eq 'In Progress'

Especificar várias cláusulas de filtro

Você pode usar and e or especificar vários filtros em uma única $select cláusula. Por exemplo, a consulta a seguir especifica vários campos de itens de trabalho dos tipos User Story, Bug ou Backlog Work do tipo personalizado que estão nos estados Novo, Confirmado ou Ativo . Use parênteses para agrupar cláusulas de filtro conforme necessário.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,Title,AssignedTo,State&$filter=(WorkItemType eq 'User Story' or WorkItemType eq 'Bug' or WorkItemType eq 'Backlog Work') and (State eq 'New' or State eq 'Committed' or State eq 'Active')

A consulta retorna dados como os seguintes resultados:


{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,Title,AssignedTo,State)",
  "value": [
    {
      "WorkItemId": 210,
      "Title": "Slow response on form",
      "State": "Active"
    },
    ...
    {
      "WorkItemId": 160,
      "Title": "Game store testing",
      "State": "New"
    }
  ]
}

Você também pode aplicar várias funções, como contains, startswithe endswith em $select cláusulas. Consulte Funções suportadas.

Propriedades do Caminho da Área de Consulta ou do Caminho de Iteração

Para consultar o AreaSK, IterationSK ou outras propriedades para um caminho de área específico ou caminho de iteração, use as consultas a seguir.

Retornar o AreaSK para um caminho de área específico

A consulta a seguir solicita a propriedade AreaSK definida para a área de caminho Fabrikam Fiber\Production Planning\Web. Para ver outras propriedades definidas para o conjunto de entidades Áreas , consulte Áreas.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/Areas?$filter=AreaPath eq 'Fabrikam Fiber\Production Planning\Web' &$select=AreaSK

A consulta retorna os seguintes dados.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikamprime/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#Areas(AreaSK)",
  "value": [
    {
      "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
    }
  ]
}

Retornar o IterationSK para um caminho de iteração específico

A consulta a seguir retorna a IterationSK propriedade definida para o Fabrikam Fiber\3Week Sprints\Sprint 3 caminho de iteração. Para ver outras propriedades definidas para o conjunto de entidades Iterações , consulte 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

Filtrar por propriedades de navegação

As propriedades de navegação representam relações entre tipos de entidade. Ao especificar uma propriedade de navegação como parte dos critérios de filtro, você deve especificar o caminho completo para a propriedade de navegação. Por exemplo, a cláusula a seguir filtra itens de trabalho com base em um Caminho de Iteração especificado para a Iteration propriedade de navegação.

/WorkItems?$filter=Iteration/IterationPath eq 'Project Name\Iteration 1'

Iteration é a propriedade de navegação e IterationPath é o campo de interesse. Iteration/IterationPath é o caminho completo para a IterationPath propriedade.

A consulta de exemplo a seguir solicita dados dos cinco principais itens de trabalho sob o Fabrikam Fiber\3Week Sprints\Sprint 3 caminho de iteração especificando o caminho completo para Iteration/IterationPath.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$top=5&$filter=Iteration/IterationPath eq 'Fabrikam Fiber\3Week Sprints\Sprint 3'&$select=WorkItemId, WorkItemType, Title, State&$orderby=WorkItemId asc

A consulta de exemplo anterior não retorna Iteration dados, porque Iteration é uma entidade relacionada. As propriedades de navegação como Identity, Area e Iteration não são diretamente acessíveis através de instruções $select. Você deve usar $expand declarações para retornar dados de entidades relacionadas.

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 00000&$expand=Iteration

A consulta de exemplo a seguir solicita informações associadas ao item de trabalho com ID 480, incluindo os dados expandidos Iteration.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration

A consulta retorna os seguintes dados, que incluem todos os campos da propriedade expandida Iteration .

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z"
      }
    }
  ]
}

Utilize o comando selecionar em instruções de expansão

Se uma propriedade expandida retornar mais dados do que você deseja, adicione uma $select instrução contra a propriedade.

/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=WorkItemId eq 00000&$expand=Iteration($select=Name,IterationPath)

Por exemplo, a consulta de exemplo a seguir seleciona apenas os dados IterationName e IterationPath da propriedade expandida Iteration.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath)

A consulta retorna os seguintes dados.

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3"
      }
    }
  ]
}

A tabela a seguir mostra como usar $expand e $select cláusulas para selecionar vários campos nas propriedades de navegação. Por exemplo, você usa $expand=AssignedTo($select=UserName) para retornar a propriedade Assigned to do campo Nome de usuário na Identity propriedade de navegação.

Campo Tipo Propriedade referenciada Cláusulas de exemplo
Data e Hora 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)
Projeto ProjectSK $expand=Project($select=ProjectName)
Equipa TeamSK $expand=Teams($select=TeamName)

Você pode especificar várias propriedades para expandir em uma única $expand cláusula usando uma lista delimitada por vírgula.

$expand=AssignedTo($select=UserName),Iteration($select=IterationPath),Area($select=AreaPath)

Usar instruções de expansão aninhadas

Você pode usar instruções OData $expand aninhadas. Por exemplo, a consulta a seguir utiliza instruções aninhadas $expand para mostrar o projeto ao qual uma iteração pertence.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($expand=Project)

A consulta retorna os seguintes dados:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration)",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "IterationSK": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationId": "cccccccc-2222-3333-4444-dddddddddddd",
        "IterationName": "Sprint 3",
        "Number": 276,
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "StartDate": "2025-12-04T00:00:00-12:00",
        "EndDate": "2025-12-25T23:59:59.999-12:00",
        "IterationLevel1": "Fabrikam Fiber",
        "IterationLevel2": "3Week Sprints",
        "IterationLevel3": "Sprint 3",
        "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": false,
        "AnalyticsUpdatedDate": "2025-10-22T17:28:14.7166667Z",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Você pode adicionar $select instruções, por exemplo, para retornar apenas o IterationName e o IterationPath de Iteration:

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$filter=WorkItemId eq 480&$select=WorkItemId,WorkItemType,Title,State&$expand=Iteration($select=IterationName,IterationPath;$expand=Project)

Esta consulta devolve os seguintes dados:

{
  "@odata.context": "https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/$metadata#WorkItems(WorkItemId,WorkItemType,Title,State,Iteration(IterationName,IterationPath,Project))",
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber",
          "AnalyticsUpdatedDate": "2025-10-28T20:27:13.5833333Z",
          "ProjectVisibility": "Private"
        }
      }
    }
  ]
}

Os resultados mostram apenas o IterationName e IterationPath de Iteration, e o Project como um objeto aninhado dentro dos resultados de Iteration.

Nota

Ao aninhar uma $expand cláusula dentro de uma $select instrução, você deve usar um ponto-e-vírgula ; antes do aninhado $expand para evitar um erro.

Consultar um intervalo de datas

A consulta de exemplo a seguir retorna itens de trabalho cuja última Data Alterada é maior ou igual a 1º de janeiro de 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-01-01Z

A consulta de exemplo a seguir retorna itens de trabalho cuja última Data Alterada ocorreu durante a semana de 31 de outubro a 7 de novembro de 2025.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_odata/v4.0-preview/WorkItems?$select=WorkItemId,WorkItemType,Title,State&$filter=ChangedDate ge 2025-10-31Z&ChangedDate le 2025-11-07Z

Ordenar os resultados

Especifique a $orderby opção para classificar seus resultados ou especifique a sequência para retornar os resultados. Você pode classificar em ordem crescente ou decrescente usando palavras-chave asc ou desc. A tabela a seguir mostra alguns exemplos.

Ordenar por Cláusula
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óximo passo

Projeto & consultas com escopo da organização

Conteúdo relacionado

  • Last updated on