Definir consultas básicas usando o OData Analytics

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

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

Os exemplos se concentram nos conjuntos de entidades de acompanhamento de trabalho do Azure Boards, mas os mesmos princípios se aplicam a outros conjuntos de entidades. Para obter mais informações, consulte Construir consultas OData para Analytics e Referência de metadados para Azure Boards Analytics.

Pré-requisitos

Obter uma contagem de itens

Para retornar apenas uma contagem sem outros dados, acrescente $apply=aggregate($count as Count) a qualquer URL do conjunto de entidades. Por exemplo, as consultas a seguir contabilizam projetos, itens de trabalho, caminhos de área e usuários 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 retorna:

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

Obter uma contagem de itens e seus dados

Para retornar uma contagem junto com os dados, adicione $count=true a uma consulta que inclua uma $select cláusula. As consultas a seguir retornam uma contagem mais propriedades selecionadas para itens de trabalho, caminhos de área e usuários em um 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 ver os nomes de propriedades válidos, consulte a referência de metadados para Azure Boards Analytics e a referência de metadados de data de calendário, projeto e usuário.

Por exemplo, a consulta a seguir retorna a contagem e os nomes de usuário 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 registros 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 retornar apenas as propriedades necessárias. Os nomes de propriedade diferenciam maiúsculas de minúsculas, não podem conter espaços e correspondem a nomes de campo de item de trabalho. Por exemplo, $select=WorkItemId,WorkItemType,Title,State retorna esses quatro campos.

Para pesquisas de nomes de propriedade, incluindo campos personalizados, consulte a referência de metadados do Azure Boards.

A consulta a seguir retorna a ID, o tipo, o título e o 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 retornar somente itens que correspondam a critérios específicos. Use operadores de comparação como eq, ne, gt, ge, lt e le, e combine condições com and e or. Por exemplo, a consulta a seguir retorna recursos que estão 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'

Combinar várias condições de filtro

Use parênteses para agrupar or condições em um filtro mais and amplo. A consulta a seguir retorna histórias de usuário, 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" }
  ]
}

Você também pode usar funções de cadeia de caracteres como contains, startswithe endswith em expressões de filtro. Para obter mais informações, consulte funções com suporte.

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

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

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

A consulta a seguir retorna o AreaSK caminho da Fabrikam Fiber\Production Planning\Web área. Para outras propriedades disponíveis, 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

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

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

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

Propriedades de navegação, como Iteration, Areae AssignedTo representam relações com outras entidades. Para filtrar um campo de uma entidade relacionada, use o caminho completo no formato NavigationProperty/Field. Por exemplo, Iteration/IterationPath faz referência ao IterationPath campo por meio da Iteration propriedade de navegação:

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

A consulta a seguir retorna os cinco principais itens de trabalho em uma 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

A filtragem por uma propriedade de navegação não inclui seus dados na resposta. Para retornar campos de uma entidade relacionada, use $expand. Sem $expand, você não pode acessar campos de propriedade de navegação por meio de $select.

A consulta a seguir retorna 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
      }
    }
  ]
}

Utilizar select em instruções de expansão

Para limitar os campos retornados de uma entidade expandida, adicione uma cláusula dentro da $expand usando a sintaxe $expand=Entity($select=Field1,Field2). A consulta a seguir se expande Iteration , mas retorna somente 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 a seguir mostra $expand com exemplos $select para tipos comuns de propriedades de navegação:

Para expandir várias propriedades de navegação em uma única consulta, use uma lista delimitada por vírgulas:

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

Utilize declaraçõ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 a seguir expande Iteration e, em seguida, expande Project dentro de Iteration para mostrar a qual projeto a 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)

Para combinar 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 retorna um erro. A consulta a seguir retorna somente IterationName e IterationPath de Iteration, além do aninhado Project:

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

Classificar resultados

Adicione $orderby para ordenar os resultados por uma ou mais propriedades. Classificação de resultados em ordem crescente por padrão; acrescentar desc para decrescente. Separe vários campos de classificação com vírgulas.

Próxima etapa

Conteúdo relacionado

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