Udostępnij za pośrednictwem

Rozwinięte obiekty bazy danych w konstruktorze interfejsu API danych

  • Artykuł

Konstruktor interfejsu API danych obsługuje widoki i procedury składowane jako alternatywy mapowania na tabele bazy danych lub kontenery. Te odrębne obiekty bazy danych wymagają konfiguracji niestandardowej, aby bezproblemowo mapować je na punkty końcowe REST lub GraphQL. Niektóre konfiguracje niestandardowe są wymagane do korzystania z konstruktora interfejsu API danych z widokami i procedurami składowanymi.

Ten artykuł zawiera podział sposobu korzystania zarówno z widoków, jak i procedur składowanych za pomocą konstruktora interfejsu API danych.

Widoki

Widoki mogą być używane podobnie do sposobu użycia tabeli w konstruktorze interfejsu API danych. Użycie widoku musi być zdefiniowane przez określenie typu źródłowego jednostki jako view. Oprócz tego należy podać właściwość key-fields, aby konstruktor interfejsu API danych wiedział, jak może identyfikować i zwracać pojedynczy element, jeśli jest to konieczne.

Jeśli masz widok, na przykład dbo.vw_books_details można go uwidocznić przy użyciu następującego polecenia dab:

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

Uwaga

--source.key-fields jest obowiązkowy dla widoków podczas generowania konfiguracji za pośrednictwem interfejsu wiersza polecenia.

Plik dab-config.json będzie podobny do następującego przykładu:

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

Uwaga

Należy pamiętać, że należy odpowiednio skonfigurować uprawnienie z możliwością aktualizowania widoku lub nie. Jeśli widok nie jest aktualizowalny, należy zezwolić tylko na dostęp do odczytu do jednostki w oparciu o ten widok.

Obsługa interfejsu REST dla widoków

Widok z perspektywy REST zachowuje się jak tabela. Wszystkie operacje REST są obsługiwane.

Obsługa języka GraphQL dla widoków

Widok z perspektywy GraphQL zachowuje się jak tabela. Obsługiwane są wszystkie operacje GraphQL.

Procedury składowane

Procedury składowane mogą być używane jako obiekty związane z jednostkami udostępnianymi przez konstruktora interfejsu API danych. Użycie procedury składowanej musi być zdefiniowane, określając, że typ źródłowy jednostki jest stored-procedure.

Uwaga

Konstruktor interfejsu API danych obsługuje procedury składowane dla relacyjnych baz danych (tj. MSSQL), ale nie dla nierelacyjnych baz danych (tj. NoSQL).

Jeśli masz procedurę składowaną, na przykład dbo.stp_get_all_cowritten_books_by_author można ją uwidocznić przy użyciu następującego polecenia 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"

Plik dab-config.json będzie podobny do następującego przykładu:

"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 definiuje, które parametry powinny być uwidocznione, a także udostępnia wartości domyślne, które mają być przekazywane do parametrów procedury składowanej, jeśli te parametry nie są podane w żądaniu HTTP.

Ograniczenia

  • Konstruktor interfejsu API danych używa tylko pierwszego zestawu wyników zwróconego przez procedurę składowaną.
  • Obsługiwane są tylko te procedury składowane, których metadane dla pierwszego zestawu wyników opisanego przez sys.dm_exec_describe_first_result_set są obsługiwane.
  • W przypadku punktów końcowych REST i GraphQL: jeśli parametr procedury składowanej jest określony zarówno w pliku konfiguracji, jak i w ciągu zapytania adresu URL, parametr w ciągu zapytania adresu URL ma pierwszeństwo.
  • Jednostki wspierane przez procedurę składowaną nie mają wszystkich funkcji automatycznie udostępnianych dla jednostek wspieranych przez tabele, kolekcje lub widoki.
    • Jednostki wspierane przez procedurę składowaną nie obsługują stronicowania, zamawiania ani filtrowania. Takie jednostki nie obsługują zwracania elementów określonych przez wartości klucza podstawowego.
    • Reguły autoryzacji na poziomie pola/parametru nie są obsługiwane.

Obsługa rest dla procedur składowanych

Zachowanie punktu końcowego REST dla jednostki opartej na procedurze składowanej można skonfigurować pod kątem obsługi jednego lub wielu zleceń HTTP (GET, POST, PUT, PATCH, DELETE). Sekcja REST jednostki będzie podobna do następującego przykładu:

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

Wszystkie żądania REST jednostki kończą się niepowodzeniem z metoda HTTP 405 Niedozwolona, gdy używana jest metoda HTTP, która nie jest wymieniona w konfiguracji. Na przykład wykonanie żądania PUT kończy się niepowodzeniem z kodem błędu 405. Jeśli sekcja methods zostanie wykluczona z konfiguracji REST jednostki, zostanie wywnioskowana domyślna metoda POST. Aby wyłączyć punkt końcowy REST dla tej jednostki, skonfiguruj "rest": false i wszystkie żądania REST w jednostce procedury składowanej kończą się niepowodzeniem z powodu niepowodzenia http 404 Nie znaleziono.

Jeśli procedura składowana akceptuje parametry, parametry można przekazać w ciągu zapytania adresu URL podczas wywoływania punktu końcowego REST za pomocą czasownika HTTP GET. Na przykład:

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

Procedury składowane wykonywane przy użyciu innych czasowników HTTP, takich jak POST, PUT, PATCH, DELETE, wymagają przekazania parametrów jako JSON w treści żądania. Na przykład:

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

{
  "author": "isaac asimov"
}

Obsługa języka GraphQL dla procedur składowanych

Wykonywanie procedury składowanej w języku GraphQL można skonfigurować przy użyciu graphql opcji jednostki opartej na procedurze składowanej. Jawne ustawienie operacji jednostki umożliwia reprezentowanie procedury składowanej w schemacie GraphQL w sposób zgodny z zachowaniem procedury składowanej.

Uwaga

GraphQL wymaga, element Query musi znajdować się w schemacie. Jeśli uwidaczniasz tylko procedury składowane, upewnij się, że co najmniej jedna z nich obsługuje operację query. W przeciwnym razie zostanie wyświetlony błąd GraphQL, taki jak The object type Query has to at least define one field in order to be valid.

Nie ustawia żadnej wartości dla operacji powoduje utworzenie operacji mutation.

Na przykład użycie wartości query dla opcji operation powoduje, że procedura składowana jest rozpoznawana jako pole zapytania w schemacie GraphQL.

Użycie interfejsu wiersza polecenia:

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"

Konfiguracja środowiska uruchomieniowego:

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

Składniki schematu GraphQL: typ i pole zapytania:

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

W schemacie operacje zapytań i mutacji dla procedur składowanych mają execute jako prefiks. W przypadku poprzedniej procedury składowanej wygenerowane dokładnie pole nazwy zapytania będzie executeGetCowrittenBooksByAuthor. Typ graphQL, który jest generowany, to:

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

Alternatywnie można ustawić operation na mutation, aby pole mutacji reprezentuje procedurę składowaną w schemacie GraphQL. Za pomocą polecenia dab update można zmienić operation:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Konfiguracja środowiska uruchomieniowego:

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

Schemat GraphQL, który jest generowany, to:

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

Jeśli procedura składowana akceptuje parametry, te parametry można przekazać jako parametr zapytania lub mutacji. Na przykład:

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

Powiązana zawartość

  • Dokumentacja konfiguracji
  • Instalowanie interfejsu wiersza polecenia