Compartilhar via

Definir consultas básicas usando o OData Analytics

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

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

Este artigo se concentra em consultas para recuperar conjuntos de entidades de acompanhamento de trabalho do Azure Boards, mas os princípios se aplicam à consulta de outros conjuntos de entidades. Para obter mais informações, consulte Construir consultas OData para Analytics e Referência de metadados para Azure Boards Analytics.

Este tutorial mostra como:

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

Observação

O serviço de Análise é habilitado automaticamente e tem suporte na produção de todos os serviços no Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço de Análise estão disponíveis em geral. Você é incentivado a usar o feed OData do Analytics e fornecer comentários.

Os dados disponíveis dependem da versão. A versão mais recente com suporte da API OData é v2.0e a versão de 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 de Análise estão disponíveis em geral. Você é incentivado a usar o feed OData do Analytics e fornecer comentários. Se você atualizar do Azure DevOps Server 2019, poderá instalar o serviço de Análise durante a atualização.

Os dados disponíveis dependem da versão. A versão mais recente com suporte da API OData é v2.0e a versão de 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

Categoria Requisitos
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 Analytics e criar visualizaçõ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

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 os requisitos, consulte o Project e as consultas no escopo da organização.

Observação

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

Para um servidor local, você pode construir consultas semelhantes com uma URL com base no servidor e na coleção de projetos. https://<servername>/<ProjectCollectionName>/ Para obter mais informações, consulte Construct OData queries for 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 opção $apply=aggregate($count as Count) 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 retornar uma contagem de itens junto com os dados selecionados para os itens, especifique a opção $count=true de consulta em uma select instrução. As consultas a seguir retornam uma contagem de itens de trabalho, caminhos de área e usuários definidos para um projeto, juntamente 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.

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

Observação

Para retornar todas as propriedades definidas para um tipo de entidade especificado, você pode usar $count=true sem select cláusula. No entanto, se você 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 atingir limites de uso, inclua sempre uma cláusula $select ou $apply em suas consultas.

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

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

A consulta retorna uma contagem de usuários com seus 5.

{
  "@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 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 à 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 uso de maiúsculas e minúsculas. Embora nomes de exibição de propriedade como A ID do Item de Trabalho possam conter espaços, os nomes de propriedades formais não podem conter espaços.

Para obter mais informações sobre nomes de propriedades e rótulos, consulte Referência de metadados para Azure Boards. Para entender como as propriedades de campo personalizadas 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 Fiber.

https://analytics.dev.azure.com/fabrikam/Fabrikam%20Fiber/_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/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 especifica os critérios que os itens devem atender. A cláusula de filtro seguinte retorna apenas os tipos de item de trabalho de 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 a ID do Item de Trabalho, o Tipo de Item de Trabalho, o Título e o Estado apenas dos itens de trabalho do tipo Feature 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 História do Usuário, Bug ou trabalho de backlog de 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 as funções com suporte.

Propriedades do caminho de área de consulta ou do caminho de iteração

Para pesquisar as propriedades AreaSK, IterationSK ou outras propriedades para um caminho de área ou caminho de iteração específico, 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 do 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 dados a seguir.

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

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

A consulta a seguir retorna a IterationSK propriedade definida para o caminho da Fabrikam Fiber\3Week Sprints\Sprint 3 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 de seus 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 os dados dos cinco principais itens de trabalho sob o caminho da Fabrikam Fiber\3Week Sprints\Sprint 3 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, pois Iteration é uma entidade relacionada. Propriedades de propriedades de navegação como Identity, Area, e Iteration não são diretamente acessíveis ao usar 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

O exemplo de consulta a seguir solicita informações associadas ao ID do item de trabalho 480, incluindo 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 dados a seguir, 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"
      }
    }
  ]
}

Utilizar select em instruções de expansão

Se uma propriedade expandida retornar mais dados do que você deseja, adicione uma $select declaraçã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 dados a seguir.

{
  "@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 em propriedades de navegação. Por exemplo, você usa $expand=AssignedTo($select=UserName) para retornar a propriedade Atribuído a do campo Nome de Usuário na propriedade de navegação Identity.

Campo Tipo Propriedade referenciada Cláusulas de exemplo
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)
Projeto ProjectSK $expand=Project($select=ProjectName)
Equipe 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írgulas.

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

Utilize declarações de expansão aninhadas

Você pode usar instruções OData $expand aninhadas. Por exemplo, a consulta a seguir usa instruções aninhadas $expand para exibir o projeto em que uma iteração está.

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 somente o IterationName e 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)

Essa 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,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 Project como um objeto aninhado dentro dos Iteration resultados.

Observação

Ao aninhar uma cláusula $expand dentro de uma instrução $select, você deve usar um ponto e vírgula ; antes da cláusula interna $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

Classificar resultados

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

Classificar por Cláusula
{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

Próxima etapa

Consultas no escopo do projeto e da organização

Conteúdo relacionado

  • Last updated on