Размещение конечных точек REST в построителе API данных

Построитель API данных предоставляет веб-API RESTful, который позволяет получать доступ к таблицам, представлениям и хранимым процедурам из подключенной базы данных. Сущности представляют собой объект базы данных в конфигурации исполнения построителя Data API. Сущность должна быть задана в конфигурации среды выполнения, чтобы она была доступна в конечной точке REST API.

Вызов метода REST API

Чтобы читать или записывать в ресурс (или сущность), необходимо создать запрос, используя следующий шаблон.

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

К компонентам запроса относятся следующие компоненты:

Ниже приведен пример запроса GET для сущности book , размещенной в базе /api конечной точки REST в локальной среде localhostразработки:

GET https://localhost:5001/api/Book

Методы HTTP

Конструктор API данных использует HTTP-метод вашего запроса, чтобы определить, какие действия следует предпринять для указанной сущности. Доступны следующие http-команды, зависящие от разрешений, заданных для конкретной сущности.

Путь REST

Путь rest указывает расположение REST API построителя данных. Путь настраивается в конфигурации среды выполнения и по умолчанию используется для /api. Дополнительные сведения см. в разделе "Конфигурация пути REST".

Объект

Сущность — это терминология, используемая для ссылки на ресурс REST API в построителе данных. По умолчанию значение маршрута URL-адреса для сущности — это имя сущности, определенное в конфигурации среды выполнения. Значение пути URL-адреса REST сущности настраивается в параметрах REST сущности. Дополнительные сведения см. в разделе "Конфигурация сущностей".

Формат результирующего набора данных

Возвращенный результат представляет собой объект JSON с таким форматом:

{
    "value": []    
}

Элементы, связанные с запрошенной сущностью, доступны в массиве value . Рассмотрим пример.

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

ПОЛУЧАЙ

С помощью метода GET можно получить один или несколько элементов требуемой сущности.

Параметры URL-адреса

Конечные точки REST позволяют получить элемент по первичному ключу с помощью параметров URL-адреса. Для сущностей с одним первичным ключом формат прост:

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

Чтобы получить книгу с идентификатором 1001, используйте:

GET /api/book/id/1001

Для сущностей с составными первичными ключами, где для уникальной идентификации записи используется несколько столбцов, формат URL-адреса включает все ключевые столбцы в последовательности:

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

Если у сущности books есть составной ключ, который состоит из id1 и id2, вы получите определенную книгу следующим образом:

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

Рассмотрим пример.

Вот как будет выглядеть вызов:

### 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

Параметры запроса

Конечные точки REST поддерживают следующие параметры запроса (с учетом регистра) для управления возвращаемыми элементами:

• $select: возвращает только выбранные столбцы
• $filter: фильтрует возвращаемые элементы
• $orderby: определяет способ сортировки возвращаемых данных
• $first и $after: возвращает только верхние n элементы

Параметры запроса можно использовать вместе.

$select

Параметр $select запроса позволяет указать, какие поля должны быть возвращены. Рассмотрим пример.

### 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

Параметр $select запроса, также известный как проекция, используется для управления размером данных, возвращаемых в ответе API. $select уменьшает размер полезных данных, используя только необходимые столбцы, что может повысить производительность, свести к минимуму время синтаксического анализа, сократить использование пропускной способности и ускорить обработку данных. Эта оптимизация распространяется на базу данных. Там извлекаются только запрошенные столбцы.

$filter

Значение $filter параметра — это выражение предиката (выражение, возвращающее логический результат), использующее поля сущности. В ответ включаются только элементы, для которых выражение принимает значение True. Рассмотрим пример.

### 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

Операторы, поддерживаемые параметром $filter , :

Параметр $filter запроса в конструкторе API данных Azure может напоминать некоторым пользователям OData, и это связано с тем, что он был непосредственно вдохновлен возможностями фильтрации OData. Синтаксис почти идентичен, что облегчает работу для разработчиков, которые уже знакомы с OData, позволяя им быстро освоить и использовать его. Это сходство было намеренно, направленное на предоставление знакомых и мощных способов фильтрации данных по разным API.

Фильтрация по датам

При фильтрации по полям date или datetime в построителе API данных используйте неквотируемый формат ISO 8601 (). Этот подход необходим для операторов, таких как ge, legtи lt.

Неправильный формат

$filter=Date ge '2025-01-01'         // quotes not allowed  
$filter=Date ge datetime'2025-01-01' // OData-style not supported  

Правильный формат

$filter=Date ge 2025-01-01T00:00:00Z and Date le 2025-01-05T00:00:00Z

Точные даты с or

Если фильтры диапазона вызывают проблемы, можно сопоставить точные даты:

$filter=ClassId eq 2 and (
  Date eq 2025-01-01T00:00:00Z or
  Date eq 2025-01-02T00:00:00Z or
  Date eq 2025-01-03T00:00:00Z
)

Пример кода

Совет: Всегда проверяйте полный UrlEncode$filter запрос перед отправкой.

GET https://localhost:5001/api/Entity?$filter=Date ge 2025-01-01T00:00:00Z and Date le 2025-01-05T00:00:00Z

using System;
using System.Net.Http;

var client = new HttpClient();
var baseUrl = "https://localhost:5001/api/Entity";

// Use DateTime objects
var start = new DateTime(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc);
var end = new DateTime(2025, 1, 5, 0, 0, 0, DateTimeKind.Utc);

// Format to ISO 8601 with UTC indicator and full precision
var startDate = start.ToString("o"); // "2025-01-01T00:00:00.0000000Z"
var endDate = end.ToString("o");     // "2025-01-05T00:00:00.0000000Z"

var filterExpression = $"Date ge {startDate} and Date le {endDate}";
var encodedFilter = Uri.EscapeDataString(filterExpression);
var url = $"{baseUrl}?$filter={encodedFilter}";

var response = await client.GetAsync(url);

const baseUrl = "https://localhost:5001/api/Entity";

// Use real Date objects
const start = new Date(Date.UTC(2025, 0, 1)); // months are 0-based
const end = new Date(Date.UTC(2025, 0, 5));

// Format to ISO 8601 with 'Z' for UTC
const startDate = start.toISOString(); // "2025-01-01T00:00:00.000Z"
const endDate = end.toISOString();     // "2025-01-05T00:00:00.000Z"

const filterExpression = `Date ge ${startDate} and Date le ${endDate}`;
const encodedFilter = encodeURIComponent(filterExpression);
const url = `${baseUrl}?$filter=${encodedFilter}`;

const response = await fetch(url);
const data = await response.json();

import requests
from urllib.parse import quote
from datetime import datetime, timezone

base_url = "https://localhost:5001/api/Entity"

# Use datetime objects with UTC timezone
start = datetime(2025, 1, 1, 0, 0, 0, tzinfo=timezone.utc)
end = datetime(2025, 1, 5, 0, 0, 0, tzinfo=timezone.utc)

# Format to ISO 8601 with 'Z'
start_date = start.isoformat().replace("+00:00", "Z")
end_date = end.isoformat().replace("+00:00", "Z")

filter_expression = f"Date ge {start_date} and Date le {end_date}"
encoded_filter = quote(filter_expression)

url = f"{base_url}?$filter={encoded_filter}"
response = requests.get(url)
print(response.json())

$orderby

Значение orderby параметра — это разделенный запятыми список выражений, используемых для сортировки элементов.

Каждое выражение orderby в значении параметра может включать суффикс desc, который запрашивает сортировку в порядке убывания, отделённый от выражения одним или несколькими пробелами.

Рассмотрим пример.

### 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

Параметр $orderby запроса ценен для сортировки данных непосредственно на сервере, а также легко обрабатывается на стороне клиента. Однако она становится полезной при сочетании с другими параметрами запроса, такими как $filter и $first. Этот параметр позволяет поддерживать стабильный и прогнозируемый набор данных по мере разбиения на страницы с помощью больших коллекций.

$first и $after.

Параметр $first запроса ограничивает количество элементов, возвращаемых в одном запросе. Рассмотрим пример.

GET /api/book?$first=5

Этот запрос возвращает первые пять книг. Параметр $first запроса в построителе данных Azure аналогичен предложению TOP в SQL. Оба используются для ограничения количества записей, возвращаемых из запроса. Так же, как TOP в SQL позволяет указать количество строк, которые требуется извлечь, $first позволяет контролировать количество элементов, возвращаемых API. $first полезно при получении небольшого подмножества данных, например первых 10 результатов, без получения всего набора данных. Основным преимуществом является эффективность, так как она уменьшает объем передаваемых и обработанных данных.

Если дополнительные элементы доступны за пределами указанного предела, ответ содержит nextLink свойство:

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

Его nextLink можно использовать с параметром $after запроса для получения следующего набора элементов:

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

Этот подход продолжения использует разбиение на страницы на основе курсоров. Уникальный курсор — это ссылка на определенный элемент в наборе данных, определяющее, где продолжить извлечение данных в следующем наборе. В отличие от разбиения на страницы индекса, использующих смещения или индексы, разбиение на страницы на основе курсоров не зависит от пропуска записей. Продолжение курсора делает его более надежным с большими наборами данных или часто меняющимися данными. Вместо этого он обеспечивает гладкий и согласованный поток извлечения данных, начиная с того, где остался последний запрос, на основе предоставленного курсора.

Рассмотрим пример.

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

ПОСТ

Создайте новый элемент для указанной сущности. Рассмотрим пример.

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

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

Запрос POST создает новую книгу. Все поля, которые не допускают null-значение, должны быть предоставлены. При успешном выполнении возвращается полный объект сущности, включая любые поля NULL.

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

ПОСТАВИТЬ

PUT создает или заменяет элемент указанной сущности. Шаблон запроса:

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

Рассмотрим пример.

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

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

Если есть элемент с указанным первичным ключом 2001, предоставленные данные полностью заменяют этот элемент. Если вместо этого элемент с этим первичным ключом не существует, создается новый элемент.

В любом случае результат выглядит примерно так:

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

Заголовок If-Match: * HTTP-запроса

Заголовок If-Match: * HTTP гарантирует, что операция обновления выполняется только в том случае, если ресурс существует. Если ресурс не существует, операция завершится ошибкой с кодом состояния HTTP: 404 Not Found If-Match Если заголовок опущен, поведение по умолчанию — выполнить upsert, который создает ресурс, если он еще не существует.

Пример:

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

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

патч

PATCH создает или обновляет объект указанной сущности. Затронуты только указанные поля. Все поля, не указанные в тексте запроса, не затрагиваются. Если элемент с указанным первичным ключом не существует, создается новый элемент.

Шаблон запроса:

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

Рассмотрим пример.

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

{    
  "year": 1991
}

Результат выглядит примерно так:

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

Заголовок If-Match: * HTTP-запроса

Заголовок If-Match: * HTTP гарантирует, что операция обновления выполняется только в том случае, если ресурс существует. Если ресурс не существует, операция завершится ошибкой с кодом состояния HTTP: 404 Not Found If-Match Если заголовок опущен, поведение по умолчанию — выполнить upsert, который создает ресурс, если он еще не существует.

Пример:

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

{
    "year": 1991
}

Удалить

DELETE удаляет элемент указанной сущности. Шаблон запроса:

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

Рассмотрим пример.

DELETE /api/book/id/2001

В случае успешного выполнения результатом является пустой ответ с кодом состояния 204.

Транзакции базы данных для запросов REST API

Для обработки запросов POST, PUT, PATCH и DELETE API, построитель данных создает и выполняет запросы к базе данных в рамках транзакции.

В следующей таблице перечислены уровни изоляции, с которыми создаются транзакции для каждого типа базы данных.