Compartir a través de

Objetos de base de datos expandidos en data API Builder

  • Artículo

Data API Builder incluye compatibilidad con vistas y procedimientos almacenados como alternativas a la asignación a tablas o contenedores de base de datos. Estos distintos objetos de base de datos requieren una configuración personalizada para asignar sin problemas a los puntos de conexión REST o GraphQL. Se requiere alguna configuración personalizada para usar data API Builder con vistas y procedimientos almacenados.

En este artículo se incluye un desglose de cómo usar las vistas y los procedimientos almacenados con data API Builder.

Vistas

Las vistas se pueden usar de forma similar a cómo se puede usar una tabla en data API Builder. Para definir el uso de la vista, especifique el tipo de origen de la entidad como view. Además de que se debe proporcionar la propiedad key-fields, de modo que data API builder sepa cómo puede identificar y devolver un solo elemento, si es necesario.

Si tiene una vista, por ejemplo, dbo.vw_books_details se puede exponer mediante el siguiente comando dab:

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

Nota

--source.key-fields es obligatorio para las vistas al generar la configuración a través de la CLI.

El archivo dab-config.json sería similar al ejemplo siguiente:

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

Nota

Tenga en cuenta que debe configurar el permiso según corresponda con la capacidad de que la vista sea actualizable o no. Si una vista no es actualizable, solo debe permitir el acceso de lectura a la entidad en función de esa vista.

Compatibilidad con REST para vistas

Una vista, desde una perspectiva rest, se comporta como una tabla. Se admiten todas las operaciones REST.

Compatibilidad de GraphQL con vistas

Una vista, desde una perspectiva de GraphQL, se comporta como una tabla. Se admiten todas las operaciones de GraphQL.

Procedimientos almacenados

Los procedimientos almacenados se pueden usar como objetos relacionados con las entidades expuestas por data API Builder. El uso del procedimiento almacenado debe definirse especificando que el tipo de origen de la entidad es stored-procedure.

Nota

Data API Builder admite procedimientos almacenados para bases de datos relacionales (es decir, MSSQL), pero no para bases de datos no relacionales (es decir, NoSQL).

Si tiene un procedimiento almacenado, por ejemplo, dbo.stp_get_all_cowritten_books_by_author se puede exponer mediante el siguiente comando 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"

El archivo dab-config.json sería similar al ejemplo siguiente:

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

El parameters define qué parámetros se deben exponer y también proporciona valores predeterminados que se pasarán a los parámetros del procedimiento almacenado, si esos parámetros no se proporcionan en la solicitud HTTP.

Limitaciones

  • Solo el generador de Data API usa el primer conjunto de resultados devuelto por el procedimiento almacenado.
  • Solo se admiten los procedimientos almacenados cuyos metadatos para el primer conjunto de resultados descrito por sys.dm_exec_describe_first_result_set.
  • Para los puntos de conexión REST y GraphQL: cuando se especifica un parámetro de procedimiento almacenado tanto en el archivo de configuración como en la cadena de consulta url, el parámetro de la cadena de consulta url tiene prioridad.
  • Las entidades respaldadas por un procedimiento almacenado no tienen todas las funcionalidades proporcionadas automáticamente para las entidades respaldadas por tablas, colecciones o vistas.
    • Las entidades respaldadas por procedimientos almacenados no admiten paginación, ordenación ni filtrado. Ni estas entidades admiten la devolución de elementos especificados por los valores de clave principal.
    • No se admiten reglas de autorización de nivel de campo o parámetro.

Compatibilidad con REST para procedimientos almacenados

El comportamiento del punto de conexión REST, para la entidad respaldada por procedimientos almacenados, se puede configurar para admitir uno o varios verbos HTTP (GET, POST, PUT, PATCH, DELETE). La sección REST de la entidad sería similar al ejemplo siguiente:

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

Las solicitudes REST de la entidad producen un error con método HTTP 405 No permitido cuando se usa un método HTTP que no aparece en la configuración. Por ejemplo, al ejecutar una solicitud PUT se produce un error con el código de error 405. Si la sección methods se excluye de la configuración de REST de la entidad, se deduce el método predeterminado POST. Para deshabilitar el punto de conexión REST para esta entidad, configure "rest": false y las solicitudes REST en la entidad de procedimiento almacenado produzcan un error con HTTP 404 No encontrado.

Si el procedimiento almacenado acepta parámetros, los parámetros se pueden pasar en la cadena de consulta url al llamar al punto de conexión REST con el verbo HTTP de GET. Por ejemplo:

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

Los procedimientos almacenados que se ejecutan con otros verbos HTTP como POST, PUT, PATCH, DELETE requieren que los parámetros se pasen como JSON en el cuerpo de la solicitud. Por ejemplo:

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

{
  "author": "isaac asimov"
}

Compatibilidad de GraphQL con procedimientos almacenados

La ejecución de procedimientos almacenados en GraphQL se puede configurar mediante la opción graphql de una entidad respaldada por procedimientos almacenados. Establecer explícitamente la operación de la entidad permite representar un procedimiento almacenado en el esquema GraphQL de una manera que se alinea con el comportamiento del procedimiento almacenado.

Nota

GraphQL requiere un elemento Query que esté presente en el esquema. Si solo expone procedimientos almacenados, asegúrese de tener al menos uno de ellos que admitan la operación de query; de lo contrario, obtendrá un error de GraphQL como The object type Query has to at least define one field in order to be valid.

No establecer ningún valor para la operación da como resultado la creación de una operación de mutation.

Por ejemplo, si se usa el valor query para la opción operation, el procedimiento almacenado se resuelve como un campo de consulta en el esquema GraphQL.

Uso de la CLI:

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"

Configuración en tiempo de ejecución:

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

Componentes de esquema de GraphQL: tipo y campo de consulta:

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

En el esquema, las operaciones de consulta y mutación para los procedimientos almacenados tienen execute como prefijo. Para el procedimiento almacenado anterior, el campo de nombre de consulta exacto generado sería executeGetCowrittenBooksByAuthor. El tipo graphQL que se genera es:

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

Como alternativa, operation se puede establecer en mutation para que un campo de mutación represente el procedimiento almacenado en el esquema GraphQL. El comando dab update se puede usar para cambiar el operation:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Configuración en tiempo de ejecución:

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

El esquema de GraphQL que se genera es:

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

Si el procedimiento almacenado acepta parámetros, esos parámetros se pueden pasar como parámetros de la consulta o mutación. Por ejemplo:

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

Contenido relacionado