Freigeben über

Erweiterte Datenbankobjekte im Daten-API-Generator

  • Artikel

Der Daten-API-Generator enthält Unterstützung für Ansichten und gespeicherte Prozeduren als Alternativen zur Zuordnung zu Datenbanktabellen oder -containern. Diese unterschiedlichen Datenbankobjekte erfordern eine benutzerdefinierte Konfiguration, um REST- oder GraphQL-Endpunkten nahtlos zuzuordnen. Für die Verwendung des Daten-API-Generators mit Ansichten und gespeicherten Prozeduren ist eine benutzerdefinierte Konfiguration erforderlich.

Dieser Artikel enthält eine Aufschlüsselung der Verwendung von Ansichten und gespeicherten Prozeduren mit dem Daten-API-Generator.

Ansichten

Ansichten können ähnlich wie eine Tabelle im Daten-API-Generator verwendet werden. Die Ansichtsverwendung muss durch Angeben des Quelltyps für die Entität als viewdefiniert werden. Außerdem muss die key-fields-Eigenschaft bereitgestellt werden, damit der Daten-API-Generator weiß, wie es bei Bedarf ein einzelnes Element identifizieren und zurückgeben kann.

Wenn Sie über eine Ansicht verfügen, z. B. dbo.vw_books_details sie mithilfe des folgenden dab Befehls verfügbar gemacht werden kann:

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

Hinweis

--source.key-fields ist für Ansichten beim Generieren der Konfiguration über die CLI obligatorisch.

Die dab-config.json Datei würde wie im folgenden Beispiel aussehen:

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

Hinweis

Beachten Sie, dass Sie die Berechtigung entsprechend konfigurieren sollten, damit die Ansicht aktualisierbar ist oder nicht. Wenn eine Ansicht nicht aktualisierbar ist, sollten Sie nur einen Lesezugriff auf die Entität basierend auf dieser Ansicht zulassen.

REST-Unterstützung für Ansichten

Eine Ansicht verhält sich aus REST-Sicht wie eine Tabelle. Alle REST-Vorgänge werden unterstützt.

GraphQL-Unterstützung für Ansichten

Eine Ansicht aus GraphQL-Perspektive verhält sich wie eine Tabelle. Alle GraphQL-Vorgänge werden unterstützt.

Gespeicherte Prozeduren

Gespeicherte Prozeduren können als Objekte verwendet werden, die mit Entitäten zusammenhängen, die vom Daten-API-Generator verfügbar gemacht werden. Die Verwendung der gespeicherten Prozedur muss definiert werden, um anzugeben, dass der Quelltyp für die Entität stored-procedureist.

Hinweis

Der Daten-API-Generator unterstützt gespeicherte Prozeduren für relationale Datenbanken (d. h. MSSQL), aber nicht für nicht relationale Datenbanken (d. h. NoSQL).

Wenn Sie über eine gespeicherte Prozedur verfügen, z. B. dbo.stp_get_all_cowritten_books_by_author kann sie mithilfe des folgenden dab Befehls verfügbar gemacht werden:

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"

Die dab-config.json Datei würde wie im folgenden Beispiel aussehen:

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

Die parameters definiert, welche Parameter verfügbar gemacht werden sollen, und stellt außerdem Standardwerte bereit, die an die Gespeicherten Prozedurparameter übergeben werden sollen, wenn diese Parameter nicht in der HTTP-Anforderung bereitgestellt werden.

Einschränkungen

  • Nur das erste von der gespeicherten Prozedur zurückgegebene Resultset wird vom Daten-API-Generator verwendet.
  • Nur die gespeicherten Prozeduren, deren Metadaten für das erste durch sys.dm_exec_describe_first_result_set beschriebene Resultset unterstützt werden.
  • Für REST- und GraphQL-Endpunkte: Wenn sowohl in der Konfigurationsdatei als auch in der URL-Abfragezeichenfolge ein gespeicherter Prozedurparameter angegeben wird, hat der Parameter in der URL-Abfragezeichenfolge Vorrang.
  • Entitäten, die von einer gespeicherten Prozedur unterstützt werden, verfügen nicht über alle Funktionen, die automatisch für Entitäten bereitgestellt werden, die von Tabellen, Sammlungen oder Ansichten unterstützt werden.
    • Gespeicherte Prozeduren unterstützen keine Paginierung, Sortierung oder Filterung. Diese Entitäten unterstützen auch die Rückgabe von Elementen, die durch Primärschlüsselwerte angegeben wurden.
    • Autorisierungsregeln auf Feld-/Parameterebene werden nicht unterstützt.

REST-Unterstützung für gespeicherte Prozeduren

Das REST-Endpunktverhalten für gespeicherte, gesicherte Prozeduren kann so konfiguriert werden, dass ein oder mehrere HTTP-Verben (GET, POST, PUT, PATCH, DELETE) unterstützt werden. Der REST-Abschnitt der Entität würde wie im folgenden Beispiel aussehen:

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

Alle REST-Anforderungen für die Entität schlagen mit HTTP 405-Methode nicht zulässig fehl, wenn eine in der Konfiguration nicht aufgeführte HTTP-Methode verwendet wird. Das Ausführen einer PUT-Anforderung schlägt z. B. mit dem Fehlercode 405 fehl. Wenn der abschnitt methods aus der REST-Konfiguration der Entität ausgeschlossen wird, wird die Standardmethode POST- abgeleitet. Um den REST-Endpunkt für diese Entität zu deaktivieren, konfigurieren Sie "rest": false und alle REST-Anforderungen für die gespeicherte Prozedurenentität schlägt mit HTTP 404 Not Foundfehl.

Wenn die gespeicherte Prozedur Parameter akzeptiert, können die Parameter beim Aufrufen des REST-Endpunkts mit dem GET HTTP-Verb in der URL-Abfragezeichenfolge übergeben werden. Zum Beispiel:

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

Gespeicherte Prozeduren, die mit anderen HTTP-Verben wie POST, PUT, PATCH, DELETE ausgeführt werden, erfordern die Übergabe von Parametern als JSON im Anforderungstext. Zum Beispiel:

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

{
  "author": "isaac asimov"
}

GraphQL-Unterstützung für gespeicherte Prozeduren

Die Ausführung gespeicherter Prozeduren in GraphQL kann mithilfe der Option graphql einer gespeicherten Entität konfiguriert werden. Durch das explizite Festlegen des Vorgangs der Entität können Sie eine gespeicherte Prozedur im GraphQL-Schema auf eine Weise darstellen, die sich an das Verhalten der gespeicherten Prozedur richtet.

Hinweis

GraphQL-erfordert, dass ein Query-Element im Schema vorhanden ist. Wenn Sie nur gespeicherte Prozeduren verfügbar machen, stellen Sie sicher, dass mindestens eine davon die query Operation unterstützt, andernfalls erhalten Sie einen GraphQL-Fehler wie The object type Query has to at least define one field in order to be valid.

Das Festlegen eines Werts für den Vorgang führt zur Erstellung eines mutation Vorgangs.

Beispielsweise führt die Verwendung des Werts query für die option operation dazu, dass die gespeicherte Prozedur als Abfragefeld im GraphQL-Schema aufgelöst wird.

CLI-Verwendung:

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"

Laufzeitkonfiguration:

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

GraphQL-Schemakomponenten: Typ und Abfragefeld:

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

Im Schema haben sowohl Abfrage- als auch Mutationsvorgänge für gespeicherte Prozeduren execute als Präfix. Für die vorherige gespeicherte Prozedur würde das generierte Feld für den exakten Abfragenamen executeGetCowrittenBooksByAuthor. Der generierte GraphQL-Typ lautet:

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

Alternativ kann operation auf mutation festgelegt werden, sodass ein Mutationsfeld die gespeicherte Prozedur im GraphQL-Schema darstellt. Der Befehl dab update kann verwendet werden, um die operationzu ändern:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Laufzeitkonfiguration:

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

Das generierte GraphQL-Schema lautet:

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

Wenn die gespeicherte Prozedur Parameter akzeptiert, können diese Parameter als Parameter der Abfrage oder Mutation übergeben werden. Zum Beispiel:

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

Verwandte Inhalte