Hospedar pontos de extremidade REST no construtor de API de Dados

Artigo
08/14/2024

O Construtor de API de Dados fornece uma API Web RESTful que permite acessar tabelas, exibições e procedimentos armazenados de um banco de dados conectado. As entidades representam um objeto de banco de dados na configuração de runtime do Construtor de API de Dados. Uma entidade deve ser definida na configuração de runtime para que ela esteja disponível no ponto de extremidade da API REST.

Chamar um método de API REST

Para ler ou gravar em um recurso (ou entidade), você constrói uma solicitação usando o seguinte padrão:

{HTTP method} https://{base_url}/{rest-path}/{entity}

Nota

Todos os componentes do caminho da URL, incluindo entidades e parâmetros de consulta, diferenciam maiúsculas de minúsculas.

Os componentes de uma solicitação incluem:

	Descrição
`{HTTP method}`	O método HTTP usado na solicitação para o construtor de API de Dados
`{base_url}`	O domínio (ou servidor localhost e porta) que hospeda uma instância do construtor de API de Dados
`{rest-path}`	O caminho base do ponto de extremidade da API REST definido na configuração de runtime
`{entity}`	O nome do objeto de banco de dados conforme definido na configuração de runtime

Aqui está um exemplo de solicitação GET na entidade book que reside no /api base do ponto de extremidade REST em um ambiente de desenvolvimento local localhost:

GET https:/localhost:5001/api/Book

Métodos HTTP

O construtor de API de Dados usa o método HTTP em sua solicitação para determinar qual ação executar na entidade designada pela solicitação. Os verbos HTTP a seguir estão disponíveis, dependendo das permissões definidas para uma entidade específica.

Método	Descrição
`GET`	Obter zero, um ou mais itens
`POST`	Criar um novo item
`PATCH`	Atualize um item com novos valores se houver um. Caso contrário, crie um novo item
`PUT`	Substitua um item por um novo se existir. Caso contrário, crie um novo item
`DELETE`	Excluir um item

Caminho de repouso

O caminho restante designa o local da API REST do Construtor de API de Dados. O caminho é configurável na configuração de runtime e usa como padrão /api. Para obter mais informações, consulte de configuração do caminho REST.

Entidade

Entity é a terminologia usada para fazer referência a um recurso da API REST no construtor de API de Dados. Por padrão, o valor da rota de URL para uma entidade é o nome da entidade definido na configuração de runtime. O valor do caminho da URL REST de uma entidade é configurável dentro das configurações REST da entidade. Para obter mais informações, consulte de configuração de entidade.

Formato do conjunto de resultados

O resultado retornado é um objeto JSON com este formato:

{
    "value": []    
}

Os itens relacionados à entidade solicitada estão disponíveis na matriz value. Por exemplo:

{
  "value": [
    {
      "id": 1000,
      "title": "Foundation"
    },
    {
      "id": 1001,
      "title": "Foundation and Empire"
    }
  ]
}

Nota

Somente os primeiros 100 itens são retornados por padrão.

OBTER

Usando o método GET, você pode recuperar um ou mais itens da entidade desejada.

Parâmetros de URL

Os pontos de extremidade REST permitem que você recupere um item por sua chave primária usando parâmetros de URL. Para entidades com uma única chave primária, o formato é simples:

GET /api/{entity}/{primary-key-column}/{primary-key-value}

Para recuperar um livro com uma ID de 1001, você usaria:

GET /api/book/id/1001

Para entidades com chaves primárias compostas, em que mais de uma coluna é usada para identificar exclusivamente um registro, o formato de URL inclui todas as colunas de chave na sequência:

GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}

Se uma entidade books tiver uma chave composta que consiste em id1 e id2, você recuperará um livro específico como este:

GET /api/books/id1/123/id2/abc

Por exemplo:

Veja a aparência de uma chamada:

### Retrieve a book by a single primary key
GET /api/book/id/1001

### Retrieve an author by a single primary key
GET /api/author/id/501

### Retrieve a book by compound primary keys (id1 and id2)
GET /api/books/id1/123/id2/abc

### Retrieve an order by compound primary keys (orderId and customerId)
GET /api/orders/orderId/789/customerId/456

### Retrieve a product by compound primary keys (categoryId and productId)
GET /api/products/categoryId/electronics/productId/987

### Retrieve a course by compound primary keys (departmentCode and courseNumber)
GET /api/courses/departmentCode/CS/courseNumber/101

Parâmetros de consulta

Os pontos de extremidade REST dão suporte aos seguintes parâmetros de consulta (diferenciam maiúsculas de minúsculas) para controlar os itens retornados:

$select: retorna apenas as colunas selecionadas
$filter: filtra os itens retornados
$orderby: define como os dados retornados são classificados
$first e $after: retorna apenas os principais itens de n

Os parâmetros de consulta podem ser usados juntos.

`$select`

O parâmetro de consulta $select permitir especificar quais campos devem ser retornados. Por exemplo:

### Get all fields
GET /api/author

### Get only first_name field
GET /api/author?$select=first_name

### Get only first_name and last_name fields
GET /api/author?$select=first_name,last_name

Nota

Se qualquer um dos campos solicitados não existir ou não estiver acessível devido a permissões configuradas, um 400 - Bad Request será retornado.

O parâmetro de consulta $select, também conhecido como "projeção", é usado para controlar o tamanho dos dados retornados em uma resposta à API. Com apenas as colunas necessárias, $select reduz o tamanho da carga, o que pode melhorar o desempenho minimizando o tempo de análise, reduzindo o uso da largura de banda e acelerando o processamento de dados. Essa otimização se estende ao banco de dados. Lá, somente as colunas solicitadas são recuperadas.

`$filter`

O valor da opção $filter é uma expressão de predicado (uma expressão que retorna um resultado booliano) usando os campos da entidade. Somente os itens em que a expressão é avaliada como True são incluídos na resposta. Por exemplo:

### Get books titled "Hyperion" (Equal to)
GET /api/book?$filter=title eq 'Hyperion'

### Get books not titled "Hyperion" (Not equal to)
GET /api/book?$filter=title ne 'Hyperion'

### Get books published after 1990 (Greater than)
GET /api/book?$filter=year gt 1990

### Get books published in or after 1990 (Greater than or equal to)
GET /api/book?$filter=year ge 1990

### Get books published before 1991 (Less than)
GET /api/book?$filter=year lt 1991

### Get books published in or before 1990 (Less than or equal to)
GET /api/book?$filter=year le 1990

### Get books published between 1980 and 1990 (Logical and)
GET /api/book?$filter=year ge 1980 and year le 1990

### Get books published before 1960 or titled "Hyperion" (Logical or)
GET /api/book?$filter=year le 1960 or title eq 'Hyperion'

### Get books not published before 1960 (Logical negation)
GET /api/book?$filter=not (year le 1960)

### Get books published in 1970 or later, and either titled "Foundation" or with more than 400 pages (Grouping)
GET /api/book?$filter=(year ge 1970 or title eq 'Foundation') and pages gt 400

Os operadores compatíveis com a opção $filter são:

Operador	Tipo	Descrição	Exemplo
`eq`	Comparação	Igual	`title eq 'Hyperion'`
`ne`	Comparação	Não é igual a	`title ne 'Hyperion'`
`gt`	Comparação	Maior que	`year gt 1990`
`ge`	Comparação	Maior ou igual a	`year ge 1990`
`lt`	Comparação	Menor que	`year lt 1990`
`le`	Comparação	Menor ou igual a	`year le 1990`
`and`	Lógico	Lógico e	`year ge 1980 and year lt 1990`
`or`	Lógico	Lógico ou	`year le 1960 or title eq 'Hyperion'`
`not`	Lógico	Negação lógica	`not (year le 1960)`
`( )`	Agrupamento	Agrupamento de precedência	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Nota

$filter é um argumento que diferencia maiúsculas de minúsculas.

O parâmetro de consulta $filter no Construtor de API de Dados do Azure pode lembrar alguns usuários do OData e isso porque ele foi diretamente inspirado pelos recursos de filtragem do OData. A sintaxe é quase idêntica, facilitando que os desenvolvedores que já estão familiarizados com o OData peguem e usem. Essa similaridade foi intencional, destinada a fornecer uma maneira familiar e poderosa de filtrar dados em diferentes APIs.

`$orderby`

O valor do parâmetro orderby é uma lista separada por vírgulas de expressões usadas para classificar os itens.

Cada expressão no valor do parâmetro orderby pode incluir o sufixo desc para solicitar uma ordem decrescente, separada da expressão por um ou mais espaços.

Por exemplo:

### Order books by title in ascending order
GET /api/book?$orderby=title

### Order books by title in ascending order
GET /api/book?$orderby=title asc

### Order books by title in descending order
GET /api/book?$orderby=title desc

### Order books by year of publication in ascending order, then by title in ascending order
GET /api/book?$orderby=year asc, title asc

### Order books by year of publication in descending order, then by title in ascending order
GET /api/book?$orderby=year desc, title asc

### Order books by number of pages in ascending order, then by title in descending order
GET /api/book?$orderby=pages asc, title desc

### Order books by title in ascending order, then by year of publication in descending order
GET /api/book?$orderby=title asc, year desc

Nota

$orderBy é um argumento que diferencia maiúsculas de minúsculas.

O parâmetro de consulta $orderby é valioso para classificar dados diretamente no servidor, facilmente manipulados no lado do cliente também. No entanto, ele se torna útil quando combinado com outros parâmetros de consulta, como $filter e $first. O parâmetro permite que a paginação mantenha um conjunto de dados estável e previsível à medida que você pagina por meio de grandes coleções.

`$first` e `$after`

O parâmetro de consulta $first limita o número de itens retornados em uma única solicitação. Por exemplo:

GET /api/book?$first=5

Essa solicitação retorna os cinco primeiros livros. O parâmetro de consulta $first no Construtor de API de Dados do Azure é semelhante à cláusula TOP no SQL. Ambos são usados para limitar o número de registros retornados de uma consulta. Assim como TOP no SQL permite que você especifique a quantidade de linhas a serem recuperadas, $first permite controlar o número de itens retornados pela API. $first é útil quando você deseja buscar um pequeno subconjunto de dados, como os primeiros 10 resultados, sem recuperar todo o conjunto de dados. A principal vantagem é a eficiência, pois reduz a quantidade de dados transmitidos e processados.

Nota

No construtor de API de Dados do Azure, o número de linhas retornadas por padrão é limitado por uma configuração no arquivo de configuração. Os usuários podem substituir esse limite usando o parâmetro $first para solicitar mais linhas, mas ainda há um número máximo configurado de linhas que podem ser retornadas no geral. Além disso, há um limite no total de megabytes que pode ser retornado em uma única resposta, que também é configurável.

Se mais itens estiverem disponíveis além do limite especificado, a resposta incluirá uma propriedade nextLink:

{
    "value": [],
    "nextLink": "dab-will-generate-this-continuation-url"
}

O nextLink pode ser usado com o parâmetro de consulta $after para recuperar o próximo conjunto de itens:

GET /api/book?$first={n}&$after={continuation-data}

Essa abordagem de continuação usa paginação baseada em cursor. Um cursor exclusivo é uma referência a um item específico no conjunto de dados, determinando onde continuar recuperando dados no próximo conjunto. Ao contrário da paginação de índice que usa deslocamentos ou índices, a paginação baseada em cursor não depende de ignorar registros. A continuação do cursor torna-a mais confiável com grandes conjuntos de dados ou com a alteração frequente de dados. Em vez disso, garante um fluxo suave e consistente de recuperação de dados iniciando exatamente onde a última consulta parou, com base no cursor fornecido.

Por exemplo:

### Get the first 5 books explicitly
GET /api/book?$first=5

### Get the next set of 5 books using the continuation token
GET /api/book?$first=5&$after={continuation-token}

### Get the first 10 books, ordered by title
GET /api/book?$first=10&$orderby=title asc

### Get the next set of 10 books after the first set, ordered by title
GET /api/book?$first=10&$after={continuation-token}&$orderby=title asc

### Get books without specifying $first (automatic pagination limit)
GET /api/book

### Get the next set of books using the continuation token without specifying $first
GET /api/book?$after={continuation-token}

POSTAR

Crie um novo item para a entidade especificada. Por exemplo:

POST /api/book
Content-type: application/json

{
  "id": 2000,
  "title": "Do Androids Dream of Electric Sheep?"
}

A solicitação POST cria um novo livro. Todos os campos que não podem ser anuláveis devem ser fornecidos. Se bem-sucedido, o objeto de entidade completo, incluindo quaisquer campos nulos, será retornado:

{
  "value": [
    {
      "id": 2000,
      "title": "Do Androids Dream of Electric Sheep?",
      "year": null,
      "pages": null
    }
  ]
}

PÔR

PUT cria ou substitui um item da entidade especificada. O padrão de consulta é:

PUT /api/{entity}/{primary-key-column}/{primary-key-value}

Por exemplo:

PUT /api/book/id/2001
Content-type: application/json

{  
  "title": "Stranger in a Strange Land",
  "pages": 525
}

Se houver um item com a chave primária especificada 2001, os dados fornecidos substituirão completamente esse item. Se, em vez disso, um item com essa chave primária não existir, um novo item será criado.

Em ambos os casos, o resultado é algo como:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": null,
      "pages": 525
    }
  ]
}

REMENDO

PATCH cria ou atualiza o item da entidade especificada. Somente os campos especificados são afetados. Todos os campos não especificados no corpo da solicitação não são afetados. Se um item com a chave primária especificada não existir, um novo item será criado.

O padrão de consulta é:

PATCH /api/{entity}/{primary-key-column}/{primary-key-value}

Por exemplo:

PATCH /api/book/id/2001
Content-type: application/json

{    
  "year": 1991
}

O resultado é algo como:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": 1991,
      "pages": 525
    }
  ]
}

EXCLUIR

DELETE exclui o item da entidade especificada. O padrão de consulta é:

DELETE /api/{entity}/{primary-key-column}/{primary-key-value}

Por exemplo:

DELETE /api/book/id/2001

Se bem-sucedido, o resultado será uma resposta vazia com o código de status 204.

Transações de banco de dados para solicitações da API REST

Para processar solicitações de API POST, PUT, PATCH e DELETE; O Construtor de API de Dados constrói e executa as consultas de banco de dados em uma transação.

A tabela a seguir lista os níveis de isolamento com os quais as transações são criadas para cada tipo de banco de dados.

Tipo de banco de dados	Nível de isolamento	Mais informações
SQL do Azure (ou) SQL Server	Leitura confirmada	do SQL do Azure
MySQL	Leitura repetível	MySQL
PostgreSQL	Leitura confirmada	postgreSQL

OpenAPI
referência de configuração REST

Compartilhar via

Hospedar pontos de extremidade REST no construtor de API de Dados

Chamar um método de API REST

Métodos HTTP

Caminho de repouso

Entidade

Formato do conjunto de resultados

OBTER

Parâmetros de URL

Por exemplo:

Parâmetros de consulta

`$select`

`$filter`

`$orderby`

`$first` e `$after`

POSTAR

PÔR

REMENDO

EXCLUIR

Transações de banco de dados para solicitações da API REST

Comentários

Recursos adicionais

Compartilhar via

Hospedar pontos de extremidade REST no construtor de API de Dados

Chamar um método de API REST

Métodos HTTP

Caminho de repouso

Entidade

Formato do conjunto de resultados

OBTER

Parâmetros de URL

Por exemplo:

Parâmetros de consulta

$select

$filter

$orderby

$first e $after

POSTAR

PÔR

REMENDO

EXCLUIR

Transações de banco de dados para solicitações da API REST

Conteúdo relacionado

Comentários

Recursos adicionais

`$select`

`$filter`

`$orderby`

`$first` e `$after`