Funções e cláusulas OData com suporte

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

Este artigo aborda como o Analytics oferece suporte a várias funções OData. Funções não suportadas também são listadas. OData (Open Data Protocol) é um padrão OASIS aprovado pela ISO/IEC que define as melhores práticas para criar e consumir APIs REST. Para obter mais informações, consulte a documentação do OData.

Observação

O serviço do Analytics é habilitado automaticamente e tem suporte na produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço do Analytics estão em disponibilidade geral. Encorajamos você a usá-lo e nos dar feedback. Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0, e a versão prévia mais recente é v4.0-preview. Para obter mais informações, confira Sobre o controle de versão da API OData.

Cláusulas com suporte

• $apply
• $compute
• $count
• $expand
• $filter
• $orderby
• $select
• $skip
• $top

Quando várias cláusulas são usadas em uma consulta, elas são aplicadas na ordem especificada acima. A ordem das cláusulas na cadeia de caracteres de consulta é ignorada. Por exemplo, na consulta a seguir, os itens de trabalho são primeiro agrupados e agregados. Em seguida, os grupos são filtrados. Depois disso, os grupos filtrados são classificados. Finalmente, os cinco primeiros registros são retornados. A consulta retorna os cinco principais tipos de item de trabalho usados pelo menos 100 vezes.

WorkItems?$filter=Count ge 100&$apply=groupby((WorkItemType), aggregate($count as Count))&$orderby=Count&top=5

Suporte a extensões de agregação

É preciso uma sequência de transformações de conjunto, separadas por barras, para expressar que elas são aplicadas consecutivamente. O resultado de cada transformação é a entrada para a próxima transformação. Por exemplo, na consulta a seguir, os itens de trabalho são filtrados e agrupados por tipo e estado de item de trabalho. Em seguida, os grupos são filtrados e agrupados novamente.

Observação

As extensões de agregação OData são relativamente novas e ainda não têm suporte total em algumas ferramentas de cliente.

Workitems?$apply=filter(State ne 'Closed')/groupby((WorkItemType, State), aggregate($count as Count))/filter(Count gt 100)/groupby((State),aggregate(Count with max as MaxCount))  

As seguintes transformações são suportadas:

Transformação	Observações
aggregate	Permite a agregação usando um dos seguintes métodos$count: average, , minmax, ,sum
compute	Permite adicionar propriedades calculadas
expand	Permite a expansão por propriedades especificadas
filter	Permite filtrar o conjunto de entradas. Suporta as mesmas expressões que $filter
groupby	Permite agrupar por propriedades

Para obter mais informações, consulte Agregar dados de acompanhamento de trabalho.

Funções suportadas

Função canônica	Descrição
cast	Retorna a expressão da conversão da instância atual para o tipo especificado.
contains	Retorna true se o segundo valor da cadeia de caracteres de parâmetro for uma subcadeia de caracteres do primeiro valor da cadeia de caracteres de parâmetro, caso contrário, ele retornará false.
endswith	Retorna true se o primeiro valor da cadeia de caracteres de parâmetro terminar com o segundo valor da cadeia de caracteres de parâmetro, caso contrário, ele retornará false.
startswith	Retorna true se o primeiro valor de cadeia de caracteres de parâmetro começar com o segundo valor de cadeia de caracteres de parâmetro, caso contrário, ele retornará false.
length	Retorna o número de caracteres no valor do parâmetro.
indexof	Retorna a posição do caractere com base em zero da primeira ocorrência do segundo valor de parâmetro no primeiro valor de parâmetro ou -1 se o segundo valor de parâmetro não ocorrer no primeiro valor de parâmetro.
substring	Retorna uma subcadeia de caracteres do primeiro valor de cadeia de caracteres de parâmetro, começando no enésimo caractere e terminando no último caractere (em que N é o valor inteiro do segundo parâmetro).
tolower	Retorna o valor da cadeia de caracteres do parâmetro de entrada com todos os caracteres maiúsculos convertidos em minúsculas.
toupper	Retorna o valor da cadeia de caracteres do parâmetro de entrada com todos os caracteres minúsculos convertidos em maiúsculas.
trim	Retorna o valor da cadeia de caracteres do parâmetro de entrada com todos os caracteres de espaço em branco à esquerda e à direita.
year	Retorna o componente de ano do valor do parâmetro Date ou DateTimeOffset.
month	Retorna o componente month do valor do parâmetro Date ou DateTimeOffset.
day	Retorna o componente de dia do valor do parâmetro Date ou DateTimeOffset.
date	Retorna a parte da data do valor do parâmetro DateTimeOffset.
time	Retorna a parte de hora do valor do parâmetro DateTimeOffset.
totaloffsetminutes	Retorna o número assinado de minutos na parte de deslocamento de fuso horário do valor do parâmetro DateTimeOffset.
now	Retorna o ponto atual no tempo (data e hora com fuso horário) como um valor DateTimeOffset.
maxdatetime	Retorna o último ponto possível no tempo como um valor DateTimeOffset.
mindatetime	Retorna o ponto mais antigo possível no tempo como um valor DateTimeOffset.

As funções OData são usadas em uma $filter cláusula, mas não em uma $select cláusula da maneira que seriam usadas em uma instrução SQL.

Por exemplo, você pode especificar:

/WorkItems?$filter=toupper(Title) eq 'HELP' 

No entanto, você não pode inserir a seguinte string:

/WorkItems?$select=WorkItemId,State,toupper(Title)

Recursos sem suporte

• bottomcount
• bottomsum
• bottompercent
• $crossjoin
• concat
• countdistinct
• from
• isdefined
• $rollup
• $search
• topcount
• topsum
• toppercent

Artigos relacionados

• Consultar seus dados de acompanhamento de trabalho
• Agregação de dados
• Especificação OData v4.0
• OData v4.0 Parte 2: Convenções de URL mais a Errata 02
• Extensão de agregação OData v4.0