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

Статья
08/14/2024

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

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

Для чтения из ресурса (или сущности) создается запрос с помощью следующего шаблона:

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

Заметка

Все компоненты пути URL-адреса, включая сущности и параметры запроса, чувствительны к регистру.

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

	Описание
`{HTTP method}`	Метод HTTP, используемый в запросе к построителю API данных
`{base_url}`	Домен (или сервер localhost и порт), на котором размещается экземпляр построителя API данных
`{rest-path}`	Базовый путь конечной точки REST API в конфигурации среды выполнения
`{entity}`	Имя объекта базы данных, определенного в конфигурации среды выполнения.

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

GET https:/localhost:5001/api/Book

Методы HTTP

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

Метод	Описание
`GET`	Получение нуля, одного или нескольких элементов
`POST`	Создание нового элемента
`PATCH`	Обновите элемент с новыми значениями, если он существует. В противном случае создайте новый элемент
`PUT`	Замените элемент новым, если он существует. В противном случае создайте новый элемент
`DELETE`	Удаление элемента

Путь к 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"
    }
  ]
}

Заметка

По умолчанию возвращаются только первые 100 элементов.

ПОЛУЧИТЬ

С помощью метода 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

Заметка

Если любой из запрошенных полей не существует или недоступен из-за настроенных разрешений, возвращается 400 - Bad Request.

Параметр запроса $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, :

Оператор	Тип	Описание	Пример
`eq`	Сравнение	Равный	`title eq 'Hyperion'`
`ne`	Сравнение	Не равно	`title ne 'Hyperion'`
`gt`	Сравнение	Больше	`year gt 1990`
`ge`	Сравнение	Больше или равно	`year ge 1990`
`lt`	Сравнение	Менее	`year lt 1990`
`le`	Сравнение	Меньше или равно	`year le 1990`
`and`	Логический	Логические и	`year ge 1980 and year lt 1990`
`or`	Логический	Логические или	`year le 1960 or title eq 'Hyperion'`
`not`	Логический	Логическое отрицание	`not (year le 1960)`
`( )`	Группировка	Группирование приоритета	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Заметка

$filter — это аргумент с учетом регистра.

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

`$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 — это аргумент с учетом регистра.

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

`$first` и `$after`

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

GET /api/book?$first=5

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

Заметка

В построителе API данных Azure количество строк, возвращаемых по умолчанию, ограничено параметром в файле конфигурации. Пользователи могут переопределить это ограничение с помощью параметра $first для запроса дополнительных строк, но все еще настроено максимальное количество строк, которые могут быть возвращены в целом. Кроме того, существует ограничение на общее количество мегабайт, которые могут быть возвращены в одном ответе, который также можно настроить.

Если дополнительные элементы доступны за пределами указанного ограничения, ответ включает свойство 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, возвращается:

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

ЗАПЛАТА

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

УДАЛИТЬ

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

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

Например:

DELETE /api/book/id/2001

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

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

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

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

Тип базы данных	Уровень изоляции	Дополнительные сведения
SQL Azure (или) SQL Server	Чтение зафиксировано	SQL Azure
MySQL	Повторяемое чтение	MySQL
PostgreSQL	Чтение зафиксировано	PostgreSQL

OpenAPI
Справочник по конфигурации REST

Поделиться через

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

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

Методы HTTP

Путь к rest

Сущность

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

ПОЛУЧИТЬ

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

Например:

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

`$select`

`$filter`

`$orderby`

`$first` и `$after`

ПОМЕСТИТЬ

КЛАСТЬ

ЗАПЛАТА

УДАЛИТЬ

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

Обратная связь

Дополнительные ресурсы

Поделиться через

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

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

Методы HTTP

Путь к rest

Сущность

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

ПОЛУЧИТЬ

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

Например:

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

$select

$filter

$orderby

$first и $after

ПОМЕСТИТЬ

КЛАСТЬ

ЗАПЛАТА

УДАЛИТЬ

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

Связанное содержимое

Обратная связь

Дополнительные ресурсы

`$select`

`$filter`

`$orderby`

`$first` и `$after`