Funções e cláusulas OData suportadas

Serviços do Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Este artigo aborda como a Análise suporta várias funções OData. As funções não suportadas também estão listadas. O OData (Open Data Protocol) é uma norma ISO/IEC aprovada pelo OASIS que define as melhores práticas para criar e consumir APIs REST. Para saber mais, veja a documentação do OData.

Nota

O serviço DevOps do Azure é automaticamente ativado e suportado em produção para todos os Serviços do Azure DevOps. A integração do Power BI e o acesso ao feed OData do Serviço de Análise estão geralmente disponíveis. Encorajamo-lo a utilizá-lo e a dar-nos feedback. Os dados disponíveis dependem da versão. A versão suportada mais recente é v2.0e a versão de pré-visualização mais recente é v4.0-preview. Para obter mais informações, veja Controlo de versões da API OData.

Cláusulas suportadas

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

Quando são utilizadas várias cláusulas numa consulta, são aplicadas pela ordem especificada acima. A ordem das cláusulas na cadeia de consulta é ignorada. Por exemplo, na seguinte consulta, os itens de trabalho são agrupados e agregados pela primeira vez. Em seguida, os grupos são filtrados. Depois disso, os grupos filtrados são ordenados. Por fim, são devolvidos os primeiros cinco registos. A consulta devolve os cinco principais tipos de itens de trabalho utilizados pelo menos 100 vezes.

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

Suporte de extensões de agregação

É necessária uma sequência de transformações definidas, separadas por barras para a frente, para expressar que são aplicadas consecutivamente. O resultado de cada transformação é a entrada para a transformação seguinte. Por exemplo, na seguinte consulta, os itens de trabalho são filtrados e agrupados por tipo e estado do item de trabalho. Em seguida, os grupos são filtrados e agrupados novamente.

Nota

As extensões de agregação OData são relativamente novas e ainda não são totalmente suportadas por 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))  

São suportadas as seguintes transformações:

Transformação	Notas
aggregate	Permite a agregação com um dos seguintes métodos $count, , averagemax, , min,sum
compute	Permite adicionar propriedades calculadas
expand	Permite a expansão por propriedades especificadas
filter	Permite filtrar o conjunto de entrada. Suporta as mesmas expressões que $filter
groupby	Permite o agrupamento por propriedades

Para obter mais informações, veja Agregar dados de controlo de trabalho.

Funções suportadas

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

As funções OData são utilizadas numa $filter cláusula, mas não numa $select cláusula da forma como seriam utilizadas numa instrução SQL.

Por exemplo, pode especificar:

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

No entanto, não pode introduzir a seguinte cadeia:

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

Funcionalidades não suportadas

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

Artigos relacionados

• Consultar os dados de controlo de trabalho
• Agregar dados
• Especificação OData v4.0
• OData v4.0 Parte 2: Convenções de URL Mais Errata 02
• Extensão de Agregação OData v4.0