Delen via

Uitgebreide databaseobjecten in Data API Builder

  • Artikel

Data API Builder bevat ondersteuning voor weergaven en opgeslagen procedures als alternatieven voor toewijzing aan databasetabellen of containers. Voor deze afzonderlijke databaseobjecten is een aangepaste configuratie vereist om naadloos toe te wijzen aan REST- of GraphQL-eindpunten. Sommige aangepaste configuratie is vereist voor het gebruik van Data API Builder met weergaven en opgeslagen procedures.

Dit artikel bevat een uitsplitsing van het gebruik van zowel weergaven als opgeslagen procedures met Data API Builder.

Weergaven

Weergaven kunnen worden gebruikt op dezelfde manier als een tabel kan worden gebruikt in Data API Builder. Gebruik weergeven moet worden gedefinieerd door het brontype voor de entiteit op te geven als view. Daarnaast moet de eigenschap key-fields worden opgegeven, zodat data-API-opbouwfunctie weet hoe het één item kan identificeren en retourneren, indien nodig.

Als u een weergave hebt, bijvoorbeeld dbo.vw_books_details deze kan worden weergegeven met behulp van de volgende dab opdracht:

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

Opmerking

--source.key-fields is verplicht voor weergaven bij het genereren van configuratie via de CLI.

Het bestand dab-config.json ziet er ongeveer als volgt uit:

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

Opmerking

Houd er rekening mee dat u de machtiging dienovereenkomstig moet configureren zodat de weergave kan worden bijgewerkt of niet. Als een weergave niet kan worden bijgewerkt, moet u alleen leestoegang tot de entiteit toestaan op basis van die weergave.

REST-ondersteuning voor weergaven

Een weergave, vanuit een REST-perspectief, gedraagt zich als een tabel. Alle REST-bewerkingen worden ondersteund.

GraphQL-ondersteuning voor weergaven

Een weergave, vanuit een GraphQL-perspectief, gedraagt zich als een tabel. Alle GraphQL-bewerkingen worden ondersteund.

Opgeslagen procedures

Opgeslagen procedures kunnen worden gebruikt als objecten met betrekking tot entiteiten die worden weergegeven door Data API Builder. Het gebruik van opgeslagen procedures moet worden gedefinieerd om aan te geven dat het brontype voor de entiteit stored-procedureis.

Opmerking

Data API Builder ondersteunt opgeslagen procedures voor relationele databases (d.w. MSSQL), maar niet voor niet-relationele databases (d.w.w.v. NoSQL).

Als u een opgeslagen procedure hebt, bijvoorbeeld dbo.stp_get_all_cowritten_books_by_author deze kan worden weergegeven met behulp van de volgende dab opdracht:

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"

Het bestand dab-config.json ziet er ongeveer als volgt uit:

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

De parameters definieert welke parameters moeten worden weergegeven en biedt ook standaardwaarden die moeten worden doorgegeven aan de opgeslagen procedureparameters, als deze parameters niet zijn opgegeven in de HTTP-aanvraag.

Beperkingen

  • Alleen de eerste resultatenset die door de opgeslagen procedure wordt geretourneerd, wordt gebruikt door Data API Builder.
  • Alleen de opgeslagen procedures waarvan de metagegevens voor de eerste resultatenset die worden beschreven door sys.dm_exec_describe_first_result_set worden ondersteund.
  • Voor zowel REST- als GraphQL-eindpunten: wanneer een opgeslagen procedureparameter zowel in het configuratiebestand als in de URL-querytekenreeks is opgegeven, heeft de parameter in de URL-queryreeks voorrang.
  • Entiteiten die worden ondersteund door een opgeslagen procedure, hebben niet alle mogelijkheden die automatisch worden geboden voor entiteiten die worden ondersteund door tabellen, verzamelingen of weergaven.
    • Opgeslagen procedure ondersteunde entiteiten bieden geen ondersteuning voor paginering, volgorde of filtering. Dergelijke entiteiten bieden ook geen ondersteuning voor het retourneren van items die zijn opgegeven door primaire-sleutelwaarden.
    • Autorisatieregels op veld-/parameterniveau worden niet ondersteund.

REST-ondersteuning voor opgeslagen procedures

Het REST-eindpuntgedrag, voor een entiteit met opgeslagen procedureondersteuning, kan worden geconfigureerd ter ondersteuning van een of meer HTTP-woorden (GET, POST, PUT, PATCH, DELETE). De REST-sectie van de entiteit ziet er ongeveer als volgt uit:

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

REST-aanvragen voor de entiteit mislukken met HTTP 405-methode niet toegestaan wanneer een HTTP-methode niet wordt gebruikt in de configuratie. Het uitvoeren van een PUT-aanvraag mislukt bijvoorbeeld met foutcode 405. Als de sectie methods is uitgesloten van de REST-configuratie van de entiteit, wordt de standaardmethode POST- afgeleid. Als u het REST-eindpunt voor deze entiteit wilt uitschakelen, configureert u "rest": false en eventuele REST-aanvragen voor de opgeslagen proceduretiteit mislukt met HTTP 404 Niet gevonden.

Als de opgeslagen procedure parameters accepteert, kunnen de parameters worden doorgegeven in de URL-querytekenreeks bij het aanroepen van het REST-eindpunt met het GET HTTP-woord. Bijvoorbeeld:

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

Opgeslagen procedures die worden uitgevoerd met andere HTTP-woorden, zoals POST, PUT, PATCH, DELETE, vereisen dat parameters worden doorgegeven als JSON in de aanvraagbody. Bijvoorbeeld:

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

{
  "author": "isaac asimov"
}

GraphQL-ondersteuning voor opgeslagen procedures

Uitvoering van opgeslagen procedures in GraphQL kan worden geconfigureerd met behulp van de graphql optie van een opgeslagen entiteit met ondersteunde procedures. Door de bewerking van de entiteit expliciet in te stellen, kunt u een opgeslagen procedure in het GraphQL-schema weergeven op een manier die overeenkomt met het gedrag van de opgeslagen procedure.

Opmerking

Voor GraphQL-moet een query-element aanwezig zijn in het schema. Als u alleen opgeslagen procedures weergeeft, moet u ervoor zorgen dat er ten minste één van deze procedures ondersteuning biedt voor de query bewerking, anders krijgt u een GraphQL-fout zoals The object type Query has to at least define one field in order to be valid.

Het instellen van een waarde voor de bewerking resulteert niet in het maken van een mutation bewerking.

Als u bijvoorbeeld de waarde query voor de optie operation gebruikt, wordt de opgeslagen procedure omgezet als een queryveld in het GraphQL-schema.

CLI-gebruik:

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"

Runtimeconfiguratie:

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

GraphQL-schemaonderdelen: type- en queryveld:

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

In het schema hebben zowel query- als mutatiebewerkingen voor opgeslagen procedures execute als voorvoegsel. Voor de vorige opgeslagen procedure wordt het veld met de exacte querynaam executeGetCowrittenBooksByAuthor. Het GraphQL-type dat wordt gegenereerd, is:

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

U kunt operation ook instellen op mutation zodat een mutatieveld de opgeslagen procedure in het GraphQL-schema vertegenwoordigt. De opdracht dab update kan worden gebruikt om de operationte wijzigen:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Runtimeconfiguratie:

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

Het GraphQL-schema dat wordt gegenereerd, is:

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

Als de opgeslagen procedure parameters accepteert, kunnen deze parameters worden doorgegeven als parameter van de query of mutatie. Bijvoorbeeld:

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

Verwante inhoud