Guia de protocolo OData

Este elemento define as propriedades disponíveis de uma determinada entidade, incluindo sua chave primária. Ele também pode conter informações sobre relacionamentos com outros tipos de esquema e, olhando para um exemplo - aCarMaker –, poderemos ver que não é muito diferente das descrições encontradas em outras tecnologias ORM, como JPA:

Aqui, nossoCarMaker tem apenas duas propriedades -Id areiaName - e uma associação a outroEntityType. O subelementoKey sdefine a chave primária da entidade como suaId property, e cada elementoProperty contém dados sobre a propriedade de uma entidade, como seu nome, tipo ou nulidade.

UmNavigationProperty é um tipo especial de propriedade que descreve um “ponto de acesso” para uma entidade relacionada.

Uma seleçãoAssociation descreve uma associação entre duas entidades, que inclui a multiplicidade em cada extremidade e, opcionalmente, uma restrição de integridade referencial:

Aqui, o elementoAssociation define uma relação um-para-muitos entre as entidadesCarModeleCarMaker, onde a primeira atua como a parte dependente.

O conceito de esquema final que vamos explorar é o elementoEntitySet, que representa uma coleção de entidades de um determinado tipo. Embora seja fácil considerá-los análogos a uma mesa - e em muitos casos, eles são apenas isso - uma analogia melhor é a de uma visualização. A razão para isso é quewe can have multiple EntitySet elements for the same EntityType, cada um representando um subconjunto diferente dos dados disponíveis.

O elementoEntityContainer, que é um elemento de esquema de nível superior, agrupa todos osEntitySets disponíveis:

Em nosso exemplo simples, temos apenas doisEntitySets, mas também podemos adicionar visualizações adicionais, comoForeignCarMakers ouHistoricCarMakers.

Podemosnavigate through a large dataset using the $top an $skip query options:

$top diz ao serviço que queremos apenas os primeiros 10 registros do conjunto de entidadesCarMakers. Um$skip, que é aplicado antes de$top, diz ao servidor para pular os primeiros 10 registros.

Geralmente é útil saber o tamanho de um determinadoEntity Set e, para esse propósito, podemos usar o sub-recurso$count:

Este recurso produz um documentotext/plain contendo o tamanho do conjunto correspondente. Aqui, devemos prestar atenção à versão OData específica suportada por um provedor. Enquanto OData V2 oferece suporte a$count como um sub-recurso de uma coleção, V4 permite que ele seja usado como um parâmetro de consulta. Nesse caso,$count é um booleano, portanto, precisamos alterar o URL de acordo:

Usamos a opção de consulta$filter paralimit the returned entities from a given Entity Set para aqueles que correspondem aos critérios fornecidos. O valor de$filter é uma expressão lógica que oferece suporte a operadores básicos, agrupamento e várias funções úteis. Por exemplo, vamos construir uma consulta que retorna todas as instâncias deCarMaker onde seu atributoName começa com a letra 'B':

Agora, vamos combinar alguns operadores lógicos para pesquisarCarModels para um determinadoYeareMaker:

Aqui, usamos o operador de igualdadeeq para especificar valores para as propriedades. Também podemos ver como usar propriedades de uma entidade relacionada na expressão.

By default, an OData query does not return data for related entities, que geralmente está OK. Podemos usar a opção de consulta$expand para solicitar que os dados de uma determinada entidade relacionada sejam incluídos em linha com o conteúdo principal.

Usando nosso domínio de amostra, vamos construir um URL que retorna dados de um determinado modeloand seu criador, evitando assim uma viagem de ida e volta adicional para o servidor:

O documento retornado agora inclui os dadosCarMaker como parte da entidade relacionada:

Usamos a opção de consulta $ select para informar o serviço OData que ele deve retornar apenas os valores para as propriedades especificadas. Isso é útil em cenários em que nossas entidades têm um grande número de propriedades, mas estamos interessados ​​apenas em algumas delas.

Vamos usar esta opção em uma consulta que retorna apenas as propriedadesNameeSku :

O documento resultante agora possui apenas as propriedades solicitadas:

Também podemos ver que mesmo entidades relacionadas foram omitidas. Para incluí-los, precisaríamos incluir o nome da relação na opção$select.

A opção$orderBy funciona muito bem como sua contraparte SQL. Usamos para especificarthe order in which we want the server to return a given set of entities. Em sua forma mais simples, seu valor é apenas uma lista de nomes de propriedades da entidade selecionada, informando opcionalmente a direção do pedido:

Esta consulta resultará em uma lista deCarModels ordenada por seus nomes e SKUs, nas direções crescente e decrescente, respectivamente.

Um detalhe importante aqui é o caso usado com a parte de direção de uma determinada propriedade: enquanto a especificação determina que o servidor deve suportar qualquer combinação de letras maiúsculas e minúsculas para as palavras-chaveascedesc, tambémmandates that client use only lowercase.

Esta opção define o formato de representação de dados que o servidor deve usar, que tem precedência sobre qualquer cabeçalho de negociação de conteúdo HTTP, comoAccept. Seu valor deve ser um tipo MIME completo ou um formato abreviado específico do formato.

Por exemplo,we can use json as an abbreviation for application/json:

Este URL instrui nosso serviço a retornar dados usando o formato JSON, em vez de XML, como vimos antes. Quando esta opção não estiver presente, o servidor usará o valor do cabeçalhoAccept, se houver. Quando nenhum deles estiver disponível, o servidor poderá escolher qualquer representação - geralmente XML ou JSON.

Com relação ao JSON especificamente, ele é fundamentalmente sem esquema. No entanto, OData 4.01 definea JSON schema for metadata endpoints também. Isso significa que agora podemos escrever clientes que podem se livrar totalmente do processamento XML, se optarem por fazê-lo.