Funções e cláusulas OData suportadas

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

Este artigo aborda como o Analytics suporta várias funções OData. As 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.

Nota

O serviço Analytics é automaticamente ativado e suportado na produção para todos os Azure DevOps Services. A integração do Power BI e o acesso ao feed OData do serviço Analytics estão geralmente disponíveis. Recomendamos a sua utilização e solicitamos que nos envie os seus comentários. Os dados disponíveis dependem da versão. A última versão suportada é v2.0, e a versão de pré-visualização mais recente é v4.0-preview. Para obter mais informações, consulte o artigo Controlo de Versões da API OData.

Cláusulas suportadas

• $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 devolvidos. 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

É necessária uma sequência de transformações de conjunto, separadas por barras para a frente, 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, em seguida, agrupados por tipo e estado de 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))  

As seguintes transformações são suportadas:

Transformação	Notas
aggregate	Permite a agregação usando um dos seguintes métodos $count, average, , minmax,sum
compute	Permite adicionar propriedades calculadas
expand	Permite expansão por propriedades especificadas
filter	Permite filtrar o conjunto de entradas. Suporta as 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	Description
cast	Retorna a expressão da instância atual convertida para o tipo especificado.
contains	Retorna true se o segundo valor da cadeia de caracteres do parâmetro for uma substring do primeiro valor da cadeia de caracteres do parâmetro, caso contrário, ele retornará false.
endswith	Retorna true se o primeiro valor da cadeia de caracteres do parâmetro terminar com o segundo valor da cadeia de caracteres do parâmetro, caso contrário, ele retornará false.
startswith	Retorna true se o valor da cadeia de caracteres do primeiro parâmetro começar com o valor da cadeia de caracteres do segundo 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 de caractere baseada 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 substring do primeiro valor da cadeia de caracteres do parâmetro, começando no Nono caractere e terminando no último caractere (onde 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 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 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 tempo 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 point-in-time possível como um valor DateTimeOffset.
mindatetime	Retorna o ponto no tempo mais cedo 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)

Funcionalidades não suportadas

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

Artigos relacionados

• Consultar os dados de acompanhamento do seu trabalho
• Dados agregados
• 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