Dela via

Expanderade databasobjekt i Data API Builder

  • Artikel

Data API Builder innehåller stöd för vyer och lagrade procedurer som alternativ till mappning till databastabeller eller containrar. Dessa distinkta databasobjekt kräver anpassad konfiguration för att smidigt mappa till REST- eller GraphQL-slutpunkter. Viss anpassad konfiguration krävs för att använda Data API Builder med vyer och lagrade procedurer.

Den här artikeln innehåller en översikt över hur du använder både vyer och lagrade procedurer med Data API Builder.

Visningar

Vyer kan användas på liknande sätt som en tabell kan användas i Data API Builder. Visa användning måste definieras genom att ange källtypen för entiteten som view. Tillsammans med det måste egenskapen key-fields anges, så att Data API-byggare vet hur den kan identifiera och returnera ett enda objekt om det behövs.

Om du har en vy, till exempel dbo.vw_books_details den kan exponeras med hjälp av följande dab kommando:

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

Observera

--source.key-fields är obligatoriskt för vyer vid generering av konfiguration via CLI.

Filen dab-config.json skulle se ut som i följande exempel:

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

Observera

Observera att bör du konfigurera behörigheten i enlighet med vyns möjlighet att vara uppdaterbar eller inte. Om en vy inte är uppdaterad bör du endast tillåta läsåtkomst till entiteten baserat på den vyn.

REST-stöd för vyer

En vy, ur ett REST-perspektiv, fungerar som en tabell. Alla REST-åtgärder stöds.

GraphQL-stöd för vyer

En vy, ur ett GraphQL-perspektiv, fungerar som en tabell. Alla GraphQL-åtgärder stöds.

Lagrade procedurer

Lagrade procedurer kan användas som objekt som är relaterade till entiteter som exponeras av Data API Builder. Användning av lagrad procedur måste definieras som anger att källtypen för entiteten är stored-procedure.

Observera

Data API Builder stöder lagrade procedurer för relationsdatabaser (t.ex. MSSQL), men inte för icke-relationsdatabaser (dvs. NoSQL).

Om du har en lagrad procedur, till exempel dbo.stp_get_all_cowritten_books_by_author kan den exponeras med hjälp av följande dab kommando:

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"

Filen dab-config.json skulle se ut som i följande exempel:

"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 definierar vilka parametrar som ska exponeras och tillhandahåller även standardvärden som ska skickas till parametrarna för lagrad procedur, om dessa parametrar inte anges i HTTP-begäran.

Begränsningar

  • Endast den första resultatuppsättningen som returneras av den lagrade proceduren används av Data API Builder.
  • Endast de lagrade procedurer vars metadata för den första resultatuppsättningen som beskrivs av sys.dm_exec_describe_first_result_set stöds.
  • För både REST- och GraphQL-slutpunkter: när en lagrad procedurparameter anges både i konfigurationsfilen och i URL-frågesträngen har parametern i URL-frågesträngen företräde.
  • Entiteter som backas upp av en lagrad procedur har inte alla funktioner som automatiskt tillhandahålls för entiteter som backas upp av tabeller, samlingar eller vyer.
    • Lagrade procedurstödda entiteter stöder inte sidnumrering, ordning eller filtrering. Sådana entiteter stöder inte heller returnering av objekt som anges av primärnyckelvärden.
    • Auktoriseringsregler på fält-/parameternivå stöds inte.

REST-stöd för lagrade procedurer

REST-slutpunktsbeteendet, för en lagrad procedurstödd entitet, kan konfigureras för att stödja ett eller flera HTTP-verb (GET, POST, PUT, PATCH, DELETE). REST-avsnittet i entiteten skulle se ut som i följande exempel:

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

Rest-begäranden för entiteten misslyckas med HTTP 405-metoden tillåts inte när en HTTP-metod som inte anges i konfigurationen används. Det går till exempel inte att köra en PUT-begäran med felkoden 405. Om avsnittet methods undantas från entitetens REST-konfiguration härleds standardmetoden POST-. Om du vill inaktivera REST-slutpunkten för den här entiteten konfigurerar du "rest": false och eventuella REST-begäranden på den lagrade proceduren misslyckas med HTTP 404 Hittades inte.

Om den lagrade proceduren accepterar parametrar kan parametrarna skickas i URL-frågesträngen när du anropar REST-slutpunkten med GET HTTP-verb. Till exempel:

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

Lagrade procedurer som körs med andra HTTP-verb som POST, PUT, PATCH, DELETE kräver att parametrar skickas som JSON i begärandetexten. Till exempel:

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

{
  "author": "isaac asimov"
}

GraphQL-stöd för lagrade procedurer

Lagrad procedurkörning i GraphQL kan konfigureras med hjälp av alternativet graphql för en lagrad procedur som backas upp. När du uttryckligen anger åtgärden för entiteten kan du representera en lagrad procedur i GraphQL-schemat på ett sätt som överensstämmer med beteendet för den lagrade proceduren.

Observera

GraphQL-kräver att ett frågeelement finns i schemat. Om du bara exponerar lagrade procedurer måste du ha minst en av dem som stöder query-åtgärden, annars får du ett GraphQL-fel som The object type Query has to at least define one field in order to be valid.

Om du inte anger något värde för åtgärden skapas en mutation åtgärd.

Om du till exempel använder värdet query för alternativet operation resulterar det i att den lagrade proceduren matchas som ett frågefält i GraphQL-schemat.

CLI-användning:

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"

Körningskonfiguration:

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

GraphQL-schemakomponenter: typ och frågefält:

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

I schemat har både fråge- och mutationsåtgärder för lagrade procedurer execute som prefix. För den tidigare lagrade proceduren skulle det exakta frågenamnsfältet som genererades vara executeGetCowrittenBooksByAuthor. Den GraphQL-typ som genereras är:

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

Alternativt kan operation anges till mutation så att ett mutationsfält representerar den lagrade proceduren i GraphQL-schemat. Kommandot dab update kan användas för att ändra operation:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Körningskonfiguration:

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

GraphQL-schemat som genereras är:

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

Om den lagrade proceduren accepterar parametrar kan dessa parametrar skickas som parameter för frågan eller mutationen. Till exempel:

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

Relaterat innehåll