Usar operações de consulta OData em solicitações REST do SharePoint
Dica
Antes de começar, confira os seguintes recursos:
O serviço REST do SharePoint oferece suporte a uma ampla variedade de operadores de cadeia de caracteres OData que permitem que você selecione, filtre e organize os dados solicitados.
Dica
O serviço REST do SharePoint Online (e o SharePoint 2016 e posterior no local) dá suporte à combinação de várias solicitações em uma única chamada para o serviço usando a opção de consulta $batch do OData. Para obter detalhes e links de amostras de código, confira Fazer solicitações em lote com APIs REST.
Selecione os campos para retornar
Use a opção de consulta $select para especificar quais campos retornar para uma determinada lista, item de lista ou outro objeto SharePoint representados por um conjunto de entidade. Você pode usar $select=* para retornar todos os campos disponíveis.
Observação
Em geral, se você não especificar a opção de consulta $select, o serviço REST retorna todos os campos disponíveis por padrão. No entanto, em alguns casos, alguns objetos do SharePoint incluem propriedades que exigem muitos recursos para recuperação; para otimizar o desempenho do serviço REST, essas propriedades não foram incluídas na consulta padrão e devem ser solicitadas explicitamente. Por exemplo, a propriedade SPWeb.EffectiveBasePermissions não é retornada por padrão e deve ser solicitada explicitamente usando a opção de consulta $select.
Também é possível especificar que a solicitação retorna campos projetados de outras listas e os valores das pesquisas. Para fazer isso, especifique o nome do campo em ambas as opções de consulta $select e $expand. Por exemplo:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$select=Title,Products/Name&$expand=Products/Name
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Não há suporte para expansão em massa e seleção dos itens relacionados.
Selecionar itens para retornar
Use a opção $filter para selecionar quais itens para retornar da consulta. Operadores de consulta de OData com suporte no serviço REST do SharePoint listam a comparação de consulta de filtro de opções e funções que você pode usar com o serviço REST do SharePoint.
Consulta campos de pesquisa de valor único
Campos de pesquisa de valor único são representados por dois campos separados no serviço REST do SharePoint: um campo que representa o valor real do campo e outro que representa o nome do campo. Você pode executar consultas no valor do campo de pesquisa como faria com qualquer outro campo desse tipo de dados. Por exemplo, se o valor do campo de pesquisa é uma cadeia de caracteres, você pode usar as opções de comparação de cadeia de caracteres em sua consulta.
Consulta para os usuários
No serviço REST do SharePoint, os usuários são representados por seu nome amigável (de exibição) e não pela combinação alias ou domínio\alias. Portanto, você precisa construir consultas de usuário em nomes amigáveis dos usuários.
Observação
As consultas de usuários com base em associação não são suportadas. Não há suporte para o uso do operador Current para fazer consultas usando a ID do usuário atual.
Consulta de campos de pesquisa de vários valores e usuários
Como os campos de pesquisa de vários valores retornam como uma cadeia de caracteres de vários valores, não é possível consultá-los de forma alguma (por exemplo, não há suporte para um equivalente ao elemento Includes ou NotIncludes).
Classificar itens devolvidos
Use a opção de consulta $orderby para especificar como classificar os itens em seu conjunto de retorno de consulta. Para classificar por vários campos, especifique uma lista de campos separados por vírgula. Você também pode especificar se deseja classificar os itens em ordem crescente ou decrescente acrescentando a palavra-chave asc ou desc à sua consulta.
Passe pelos itens retornados
Use as opções de consulta $top e $skiptoken para selecionar um subconjunto de itens que, de outra forma, seria retornado pela sua consulta.
Observação
A opção de consulta $skip não funciona com consultas para itens de lista do SharePoint.
A opção $top permite que você selecione os primeiros n itens do retorno definidos para retornar. Por exemplo, o URI a seguir solicita o retorno de apenas os dez primeiros itens no provável conjunto de retorno:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$top=10`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
A opção de consulta $skiptoken permite pular itens até alcançar o item especificado e, então, retornar o restante.
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$skiptoken=Paged=TRUE%26p_ID=5`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Observação
Quando usar essas opções de consulta, leve em consideração que a paginação no OData é ordinal. Por exemplo, suponha que você está implementando um botão próxima página para exibir itens de lista do SharePoint. Você usa o serviço REST para habilitar o botão para retornar os itens 1 até 20 quando clicado e, em seguida, os itens 21 até 40 e assim por diante. Entretanto, suponha que outro usuário exclua os itens 4 e 18 entre cliques do próximo botão. Nesse caso, o posicionamento ordinal dos itens restantes é redefinido e, na verdade, exibir itens 21 a 40 ignora mais de dois itens.
Operadores de consulta do OData compatíveis no serviço REST do SharePoint
| Com suporte | Sem suporte |
|---|---|
| Comparações numéricas (lt le gt ge eq ne) | Operadores aritméticos (add, sub, mul, div, mod) Funções matemáticas básicas (arredondar, piso, teto) |
| Comparações de cadeia de caracteres startswith( {Col to query},'{string to check}' ) substringof( '{string to check}', {Col to query} ) eq ne |
endswith, replace, substring, tolower, toupper, trim, concat |
| Funções de data e hora day(), month(), year(), hour(), minute(), second() | Operador DateTimeRangesOverlap Consultar se uma data e hora caem em um padrão de data e hora recorrente |
A figura a seguir mostra as opções de consulta do OData compatíveis.
Opções de consulta de OData com suporte
