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 dá suporte a várias funções OData. Funções sem suporte também são listadas. OData (Open Data Protocol) é um padrão ISO/IEC aprovado e OASIS que define as práticas recomendadas para criar e consumir APIs REST. Para saber mais, confira a documentação do OData.

Observação

O serviço de Análise é 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 de Análise estão em disponibilidade geral. Incentivamos você a usá-lo e nos enviar comentários. Os dados disponíveis dependem da versão. A versão mais recente com suporte é v2.0e a versão prévia mais recente é v4.0-preview. Para obter mais informações, consulte 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. Por fim, 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 de avanço 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 de item de trabalho e estado. 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 de 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))  

Há suporte para as seguintes transformações:

Transformação	Observações
aggregate	Permite a agregação usando um dos seguintes métodos $count, average, max, min, sum
compute	Permite adicionar propriedades calculadas
expand	Permite a expansão por propriedades especificadas
filter	Permite filtrar o conjunto de entradas. Dá suporte às mesmas expressões que $filter
groupby	Permite o agrupamento 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	Retornará true se o segundo valor de cadeia de caracteres de parâmetro for uma subcadeia de caracteres do primeiro valor de cadeia de caracteres de parâmetro; caso contrário, retornará false.
endswith	Retornará true se o primeiro valor de cadeia de caracteres de parâmetro terminar com o segundo valor de cadeia de caracteres de parâmetro; caso contrário, retornará false.
startswith	Retornará 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, retornará false.
length	Retorna o número de caracteres no valor do parâmetro.
indexof	Retorna a posição de caractere baseado 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 Nº caractere e terminando no último caractere (em que N é o segundo valor inteiro do 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 year 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 day do valor do parâmetro Date ou DateTimeOffset.
date	Retorna a parte de 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 no tempo possível como um valor DateTimeOffset.
mindatetime	Retorna o primeiro ponto no tempo possível 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 como 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 cadeia de caracteres:

/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
• Agregar dados
• Especificação do OData v4.0
• OData v4.0 Parte 2: Convenções de URL Mais Errata 02
• Extensão de agregação OData v4.0