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

Расширенные объекты базы данных в построителе API данных

  • Статья

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

В этой статье описано, как использовать представления и хранимые процедуры с построителем API данных.

Представления

Представления можно использовать аналогично тому, как таблицу можно использовать в построителе API данных. Просмотр использования должен определяться путем указания исходного типа для сущности как view. Наряду с этим необходимо предоставить свойство key-fields, чтобы построитель данных знал, как он может определять и возвращать один элемент при необходимости.

Если у вас есть представление, например dbo.vw_books_details его можно предоставить с помощью следующей команды dab:

dab add BookDetail --source dbo.vw_books_details --source.type View --source.key-fields "id" --permissions "anonymous:read"

Примечание

--source.key-fields является обязательным для представлений при создании конфигурации с помощью интерфейса командной строки.

Файл dab-config.json будет похож на следующий пример:

"BookDetail": {
  "source": {
    "type": "view",
    "object": "dbo.vw_books_details",
    "key-fields": [ "id" ]
  },
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

Примечание

Обратите внимание, что необходимо настроить разрешение соответствующим образом с возможностью обновления представления или не. Если представление не является обновляемым, необходимо разрешить доступ только для чтения к сущности на основе этого представления.

Поддержка REST для представлений

Представление с точки зрения REST ведет себя как таблица. Поддерживаются все операции REST.

Поддержка GraphQL для представлений

Представление с точки зрения GraphQL ведет себя как таблица. Поддерживаются все операции GraphQL.

Хранимые процедуры

Хранимые процедуры можно использовать в качестве объектов, связанных с сущностями, предоставляемыми построителем API данных. Использование хранимой процедуры должно быть определено, указывая, что исходный тип для сущности stored-procedure.

Примечание

Построитель данных поддерживает хранимые процедуры для реляционных баз данных (т. е. MSSQL), но не для нереляционных баз данных (т. е. NoSQL).

Если у вас есть хранимая процедура, например dbo.stp_get_all_cowritten_books_by_author ее можно предоставить с помощью следующей команды dab:

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "get" --graphql.operation "query"

Файл dab-config.json будет похож на следующий пример:

"GetCowrittenBooksByAuthor": {
  "source": {
    "type": "stored-procedure",
    "object": "dbo.stp_get_all_cowritten_books_by_author",
    "parameters": {
      "searchType": "s"
    }
  },
  "rest": {
    "methods": [ "GET" ]
  },
  "graphql": {
    "operation": "query"
  },
  "permissions": [{
   "role": "anonymous",
    "actions": [ "execute" ]
  }]
}

parameters определяет, какие параметры следует предоставлять, а также предоставляет значения по умолчанию, передаваемые в параметры хранимой процедуры, если эти параметры не указаны в HTTP-запросе.

Ограничения

  • В построителе данных используется только первый результирующий набор, возвращаемый хранимой процедурой.
  • Поддерживаются только те хранимые процедуры, метаданные которых для первого результирующий набор, описанный sys.dm_exec_describe_first_result_set.
  • Для конечных точек REST и GraphQL: если параметр хранимой процедуры указан как в файле конфигурации, так и в строке запроса URL-адреса параметр в строке запроса URL-адреса имеет приоритет.
  • Сущности, поддерживаемые хранимой процедурой, не имеют всех возможностей, которые автоматически предоставляются для сущностей, поддерживаемых таблицами, коллекциями или представлениями.
    • Хранимые сущности, поддерживаемые хранимой процедурой, не поддерживают разбиение на страницы, упорядочивание или фильтрацию. Такие сущности не поддерживают возврат элементов, указанных значениями первичного ключа.
    • Правила авторизации уровня полей и параметров не поддерживаются.

Поддержка REST для хранимых процедур

Поведение конечной точки REST для хранимой процедуры резервной сущности можно настроить для поддержки одной или нескольких http-команд (GET, POST, PUT, PATCH, DELETE). В разделе REST сущности будет показан следующий пример:

"rest": {
  "methods": [ "GET", "POST" ]
}

Все запросы REST для сущности завершаются сбоем методе HTTP 405 not Allowed, если используется метод HTTP, не указанный в конфигурации. Например, выполнение запроса PUT завершается ошибкой с кодом ошибки 405. Если раздел methods исключен из конфигурации REST сущности, метод по умолчанию POST выводится. Чтобы отключить конечную точку REST для этой сущности, настройте "rest": false и все запросы REST в сущности хранимой процедуры завершается ошибкой с HTTP 404 Not Found.

Если хранимая процедура принимает параметры, параметры можно передать в строке запроса URL-адреса при вызове конечной точки REST с помощью команды HTTP GET. Например:

GET http://<dab-server>/api/GetCowrittenBooksByAuthor?author=isaac%20asimov

Хранимые процедуры, выполняемые с помощью других http-команд, таких как POST, PUT, PATCH, DELETE, требуют передачи параметров в виде JSON в тексте запроса. Например:

POST http://<dab-server>/api/GetCowrittenBooksByAuthor

{
  "author": "isaac asimov"
}

Поддержка GraphQL для хранимых процедур

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

Примечание

Для GraphQL в схеме требуется элемент Query. Если вы используете только хранимые процедуры, убедитесь, что у вас есть хотя бы одна из них, поддерживающая операцию query, в противном случае вы получите ошибку GraphQL, например The object type Query has to at least define one field in order to be valid.

При создании операции mutation не задано какое-либо значение.

Например, использование значения query для параметра operation приводит к разрешению хранимой процедуры в виде поля запроса в схеме GraphQL.

Использование ИНТЕРФЕЙСА командной строки:

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "GET" --graphql.operation "query"

Конфигурация среды выполнения:

"graphql": {
  "operation": "query"
}

Компоненты схемы GraphQL: тип и поле запроса:

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

В схеме операции запроса и изменения для хранимых процедур execute в качестве префикса. Для предыдущей хранимой процедуры будет создано точное поле имени запроса executeGetCowrittenBooksByAuthor. Созданный тип GraphQL:

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Кроме того, operation можно задать для mutation, чтобы поле мутации представляло хранимую процедуру в схеме GraphQL. Команду dab update можно использовать для изменения operation:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Конфигурация среды выполнения:

"graphql": {
  "operation": "mutation"
}

Созданная схема GraphQL:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Если хранимая процедура принимает параметры, эти параметры можно передать в качестве параметра запроса или мутации. Например:

query {
  executeGetCowrittenBooksByAuthor(author:"asimov")
   {
    id
    title
    pages
    year
  }
}

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