Host REST endpoints no construtor de API de dados

O construtor de API de dados fornece uma API Web RESTful que permite acessar tabelas, exibições e procedimentos armazenados a partir de um banco de dados conectado. As entidades representam um objeto de banco de dados na configuração de tempo de execução do Data API builder. Uma entidade deve ser definida na configuração de tempo de execução para que 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), construa uma solicitação usando o seguinte padrão:

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

Os componentes de uma solicitação incluem:

Aqui está um exemplo de solicitação GET na entidade book que reside sob a base de ponto de extremidade REST /api 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 seguintes verbos HTTP estão disponíveis, dependendo das permissões definidas para uma entidade específica.

Caminho de descanso

O caminho restante designa o local da API REST do construtor de API de dados. O caminho é configurável na configuração de tempo de execução e assume como padrão /api. Para mais informações, consulte a configuração do caminho REST .

Entidade

Entity é a terminologia usada para fazer referência a um recurso de API REST no Data API builder. Por padrão, o valor de rota de URL para uma entidade é o nome da entidade definido na configuração de tempo de execução. O valor do caminho de URL REST de uma entidade é configurável dentro das configurações REST da entidade. Para mais informações, consulte a 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"
    }
  ]
}

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 um ID de 1001, você deve usar:

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 em 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ê recuperaria um livro específico como este:

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

Por exemplo:

Veja como seria 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 suportam os seguintes parâmetros de consulta (diferencia maiúsculas de minúsculas) para controlar os itens retornados:

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

Os parâmetros de consulta podem ser usados juntos.

$select

O parâmetro query $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

O parâmetro de consulta $select, também conhecido como "projeção", é usado para controlar o tamanho dos dados retornados em uma resposta de API. Com apenas as colunas necessárias, o $select reduz o tamanho da carga útil, o que pode melhorar o desempenho minimizando o tempo de análise, reduzindo o uso de largura de banda e acelerando o processamento de dados. Esta otimização estende-se à base de dados. Lá, apenas 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 booleano) usando os campos da entidade. Apenas 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 apoiados pela opção $filter são:

O parâmetro de consulta $filter no Azure Data API Builder 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, tornando mais fácil para os desenvolvedores que já estão familiarizados com OData pegar e usar. Essa semelhança foi intencional, com o objetivo de 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, que deve ser 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

O parâmetro de consulta $orderby é valioso para classificar dados diretamente no servidor, facilmente manipulados também no lado do cliente. No entanto, torna-se ú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 através 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

Este pedido devolve os cinco primeiros livros. O parâmetro de consulta $first no Azure Data API Builder é 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 especificar 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 o conjunto de dados inteiro. A principal vantagem é a eficiência, pois reduz a quantidade de dados transmitidos e processados.

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

{
    "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 a recuperar 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-o mais fiável com grandes conjuntos de dados ou dados que mudam frequentemente. Em vez disso, ele 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}

PUBLICAR

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 anulados devem ser fornecidos. Se for 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
    }
  ]
}

COLOCAR

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
    }
  ]
}

O cabeçalho de solicitação HTTP If-Match: *

O cabeçalho HTTP If-Match: * garante que a operação de atualização seja executada somente se o recurso existir. Se o recurso não existir, a operação falhará com o código de status HTTP: 404 Not Found. Se o cabeçalho If-Match for omitido, o comportamento padrão é executar um upsert, que cria o recurso se ele ainda não existir.

Exemplo:

PUT /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

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

REMENDO

PATCH cria ou atualiza o item da entidade especificada. Apenas 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
    }
  ]
}

O cabeçalho de solicitação HTTP If-Match: *

O cabeçalho HTTP If-Match: * garante que a operação de atualização seja executada apenas se o recurso existir. Se o recurso não existir, a operação falhará com o código de status HTTP: 404 Not Found. Se o cabeçalho If-Match for omitido, o comportamento padrão é executar um upsert, que cria o recurso se ele ainda não existir.

Exemplo:

PATCH /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
    "year": 1991
}

SUPRIMIR

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 for bem-sucedida, o resultado será uma resposta vazia com o código de status 204.

Transações de banco de dados para solicitações de 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.

Conteúdo relacionado

• OpenAPI
• Referência de configuração REST