Definir consultas básicas usando o OData Analytics

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

Use consultas Analytics OData para recuperar dados de acompanhamento de trabalho do Azure DevOps no seu navegador ou em ferramentas de cliente como Excel e Power BI. Este artigo aborda a contagem de itens, seleção de campos específicos com $select, filtragem com $filter, expansão das propriedades de navegação com $expand, consulta a intervalos de datas e ordenação com $orderby.

Os exemplos focam-se no rastreio de conjuntos de entidades do Azure Boards, mas os mesmos princípios aplicam-se a 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.

Pré-requisitos

Obter uma contagem de itens

Para devolver apenas uma contagem sem outros dados, adicione $apply=aggregate($count as Count) a qualquer URL definida por entidade. Por exemplo, as seguintes consultas contam projetos, itens de trabalho, caminhos de área e utilizadores em toda a 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)

A Projects consulta para a fabrikam organização devolve:

{
  "value": [
    {
      "Count": 16
    }
  ]
}

Obter uma contagem de itens e seus dados

Para devolver uma contagem juntamente com os dados, adicione $count=true a uma consulta que inclua uma $select cláusula. As consultas seguintes retornam uma contagem mais propriedades selecionadas para itens de trabalho, caminhos de área e utilizadores num projeto:

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

Para nomes válidos de propriedades, consulte a referência de metadados para Azure Boards Analytics e data do Calendário, Projeto e referência de metadados de utilizador.

Por exemplo, a consulta seguinte devolve a contagem e os nomes de utilizador no projeto Fabrikam Fiber :

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

A resposta inclui a contagem total em @odata.count e os registos correspondentes em value:

{
  "@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

Adicione uma $select cláusula para devolver apenas as propriedades de que precisa. Os nomes das propriedades são sensíveis a maiúsculas e minúsculas, não podem conter espaços e correspondem aos nomes dos campos dos itens de trabalho. Por exemplo, $select=WorkItemId,WorkItemType,Title,State devolve esses quatro campos.

Para consultas de nomes de propriedades, incluindo campos personalizados, veja Referência de Metadados para Azure Boards.

A consulta seguinte devolve o ID, tipo, título e estado dos 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

{
  "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

Adicione uma $filter cláusula para devolver apenas itens que cumpram critérios específicos. Use operadores de comparação como eq, ne, gt, ge, lt, e le, e , e combine condições com and e or. Por exemplo, a seguinte consulta devolve funcionalidades que estão em curso:

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'

Combinar múltiplas condições de filtro

Use parênteses para agrupar or as condições dentro de um filtro mais amplo and . A consulta seguinte devolve histórias de utilizador, bugs e um tipo personalizado em estados específicos:

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')

{
  "value": [
    { "WorkItemId": 210, "Title": "Slow response on form", "State": "Active" },
    ...
    { "WorkItemId": 160, "Title": "Game store testing", "State": "New" }
  ]
}

Também pode usar funções string como contains, startswith, e endswith em expressões de filtro. Para mais informações, consulte Funções suportadas.

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

Algumas consultas requerem a chave substituta (AreaSK ou IterationSK) em vez da cadeia de caminhos. Use os conjuntos de entidades Áreas ou Iterações para consultar a chave para um caminho específico.

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

A consulta seguinte devolve o AreaSK para o caminho de área Fabrikam Fiber\Production Planning\Web. Para outras propriedades disponíveis, veja Áreas.

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

{
  "value": [
    { "AreaSK": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
  ]
}

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

A consulta seguinte retorna o IterationSK para o caminho de iteração Fabrikam Fiber\Release 1\Sprint 3. Para outras propriedades disponíveis, veja 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

Propriedades de navegação como Iteration, Area, e AssignedTo representam relações com outras entidades. Para filtrar num campo de uma entidade relacionada, use o caminho completo no formato NavigationProperty/Field. Por exemplo, Iteration/IterationPath refere-se ao IterationPath campo através da Iteration propriedade de navegação:

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

A consulta seguinte devolve os cinco principais itens de trabalho numa iteração específica, usando o caminho de navegação completo:

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

Expandir dados de entidades relacionadas

Filtrar por uma propriedade de navegação não inclui os seus dados na resposta. Para devolver campos de uma entidade relacionada, use $expand. Sem $expand, não podes aceder aos campos de propriedades de navegação através de $select.

A seguinte consulta devolve o item 480 de trabalho com todos os campos da entidade 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

Como não $select é aplicado à Iteration expansão, a resposta inclui todos os Iteration campos:

{
  "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",
        "IterationName": "Sprint 3",
        "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",
        ...
        "Depth": 2,
        "IsEnded": false
      }
    }
  ]
}

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

Para limitar os campos devolvidos de uma entidade expandida, adicione uma cláusula $select dentro de $expand usando a sintaxe $expand=Entity($select=Field1,Field2). A seguinte consulta expande Iteration, mas retorna apenas IterationName e IterationPath:

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)

{
  "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 seguinte apresenta $expand com exemplos $select para tipos comuns de propriedades de navegação:

Para expandir múltiplas propriedades de navegação numa única consulta, use uma lista delimitada por vírgulas:

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

Usar instruções de expansão aninhadas

Para expandir uma propriedade de navegação dentro de uma entidade já expandida, aninhe um $expand dentro de outro. A consulta seguinte expande Iteration e depois expande Project dentro de Iteration para mostrar a que projeto pertence a iteração.

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)

Para combinar a expansão aninhada com $select, use um ponto e vírgula (;) para separar $select de $expand dentro dos parênteses. Sem o ponto e vírgula, a consulta devolve um erro. A consulta seguinte retorna apenas IterationName e IterationPath de Iteration, mais o Project aninhado:

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)

{
  "value": [
    {
      "WorkItemId": 480,
      "Title": "Add animated emoticons",
      "WorkItemType": "User Story",
      "State": "New",
      "Iteration": {
        "IterationName": "Sprint 3",
        "IterationPath": "Fabrikam Fiber\\3Week Sprints\\Sprint 3",
        "Project": {
          "ProjectSK": "bbbbbbbb-1111-2222-3333-cccccccccccc",
          "ProjectName": "Fabrikam Fiber"
        }
      }
    }
  ]
}

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 and ChangedDate le 2025-11-07Z

Ordenar os resultados

Adicione $orderby para ordenar resultados por uma ou mais propriedades. Os resultados são ordenados por ordem ascendente por defeito; adicione desc para ordem decrescente. Separe múltiplos campos de ordenação com vírgulas.

Próximo passo

Conteúdo relacionado

• Construir consultas OData para o Analytics
• Agregar dados usando Analytics.
• Referência de metadados para o Azure Boards Analytics
• Práticas recomendadas a serem usadas ao consultar o Google Analytics
• Funcionalidades OData suportadas
• OData v4.0 Parte 2: Convenções de URL e Errata 02