Hospedaje de puntos de conexión REST en data API Builder

Artículo
12/19/2024

Data API Builder proporciona una API web RESTful que permite acceder a tablas, vistas y procedimientos almacenados desde una base de datos conectada. Las entidades representan un objeto de base de datos en la configuración en tiempo de ejecución del generador de Data API. Se debe establecer una entidad en la configuración en tiempo de ejecución para que esté disponible en el punto de conexión de la API REST.

Llamada a un método de API rest

Para leer o escribir en un recurso (o entidad), cree una solicitud con el siguiente patrón:

{HTTP method} https://{base_url}/{rest-path}/{entity}

Nota

Todos los componentes de la ruta de acceso url, incluidas las entidades y los parámetros de consulta, distinguen mayúsculas de minúsculas.

Los componentes de una solicitud incluyen:

	Descripción
`{HTTP method}`	Método HTTP usado en la solicitud al generador de Data API
`{base_url}`	Dominio (o servidor localhost y puerto) que hospeda una instancia de Data API Builder
`{rest-path}`	Ruta de acceso base del punto de conexión de la API REST establecida en la configuración del entorno de ejecución.
`{entity}`	Nombre del objeto de base de datos tal como se define en la configuración del entorno de ejecución.

Esta es una solicitud GET de ejemplo en la entidad book que reside en la base del punto de conexión REST /api en un entorno de desarrollo local localhost:

GET https:/localhost:5001/api/Book

Métodos HTTP

Data API Builder usa el método HTTP en la solicitud para determinar qué acción realizar en la entidad designada de solicitud. Los siguientes verbos HTTP están disponibles, en función de los permisos establecidos para una entidad determinada.

Método	Descripción
`GET`	Obtener cero, uno o varios elementos
`POST`	Crear un nuevo elemento
`PATCH`	Actualice un elemento con nuevos valores si existe uno. De lo contrario, cree un nuevo elemento.
`PUT`	Reemplace un elemento por uno nuevo si existe uno. De lo contrario, cree un nuevo elemento.
`DELETE`	Eliminar un elemento

Ruta de acceso de rest

La ruta de acceso de rest designa la ubicación de la API REST del generador de DATA API. La ruta de acceso se puede configurar en la configuración en tiempo de ejecución y el valor predeterminado es /api. Para obtener más información, consulte configuración de la ruta de acceso REST.

Entidad

Entity es la terminología que se usa para hacer referencia a un recurso de API REST en el generador de API de datos. De forma predeterminada, el valor de ruta de dirección URL de una entidad es el nombre de entidad definido en la configuración del entorno de ejecución. El valor de ruta de acceso de la dirección URL de REST de una entidad se puede configurar dentro de la configuración de REST de la entidad. Para obtener más información, consulte la configuración de entidades.

Formato del conjunto de resultados

El resultado devuelto es un objeto JSON con este formato:

{
    "value": []    
}

Los elementos relacionados con la entidad solicitada están disponibles en la matriz value. Por ejemplo:

{
  "value": [
    {
      "id": 1000,
      "title": "Foundation"
    },
    {
      "id": 1001,
      "title": "Foundation and Empire"
    }
  ]
}

Nota

De forma predeterminada, solo se devuelven los primeros 100 elementos.

OBTENER

Con el método GET puede recuperar uno o varios elementos de la entidad deseada.

Parámetros de dirección URL

Los puntos de conexión rest permiten recuperar un elemento mediante su clave principal mediante parámetros de dirección URL. En el caso de las entidades con una sola clave principal, el formato es sencillo:

GET /api/{entity}/{primary-key-column}/{primary-key-value}

Para recuperar un libro con un identificador de 1001, usaría:

GET /api/book/id/1001

Para las entidades con claves principales compuestas, donde se usa más de una columna para identificar de forma única un registro, el formato de dirección URL incluye todas las columnas de clave en secuencia:

GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}

Si una entidad de books tiene una clave compuesta que consta de id1 y id2, obtendría un libro específico como este:

GET /api/books/id1/123/id2/abc

Por ejemplo:

Este es el aspecto de una llamada:

### Retrieve a book by a single primary key
GET /api/book/id/1001

### Retrieve an author by a single primary key
GET /api/author/id/501

### Retrieve a book by compound primary keys (id1 and id2)
GET /api/books/id1/123/id2/abc

### Retrieve an order by compound primary keys (orderId and customerId)
GET /api/orders/orderId/789/customerId/456

### Retrieve a product by compound primary keys (categoryId and productId)
GET /api/products/categoryId/electronics/productId/987

### Retrieve a course by compound primary keys (departmentCode and courseNumber)
GET /api/courses/departmentCode/CS/courseNumber/101

Parámetros de consulta

Los puntos de conexión REST admiten los siguientes parámetros de consulta (distinguen mayúsculas de minúsculas) para controlar los elementos devueltos:

$select: devuelve solo las columnas seleccionadas.
$filter: filtra los elementos devueltos
$orderby: define cómo se ordenan los datos devueltos
$first y $after: devuelve solo los elementos de n principales.

Los parámetros de consulta se pueden usar juntos.

`$select`

El parámetro de consulta $select permitir especificar qué campos se deben devolver. Por ejemplo:

### Get all fields
GET /api/author

### Get only first_name field
GET /api/author?$select=first_name

### Get only first_name and last_name fields
GET /api/author?$select=first_name,last_name

Nota

Si alguno de los campos solicitados no existe o no es accesible debido a permisos configurados, se devuelve un 400 - Bad Request.

El parámetro de consulta $select, también conocido como "proyección", se usa para controlar el tamaño de los datos devueltos en una respuesta de API. Con solo las columnas necesarias, $select reduce el tamaño de la carga, lo que puede mejorar el rendimiento al minimizar el tiempo de análisis, reducir el uso del ancho de banda y acelerar el procesamiento de datos. Esta optimización se extiende a la base de datos. Allí solo se recuperan las columnas solicitadas.

`$filter`

El valor de la opción $filter es una expresión de predicado (una expresión que devuelve un resultado booleano) mediante los campos de la entidad. Solo los elementos en los que la expresión se evalúa como True se incluyen en la respuesta. Por ejemplo:

### Get books titled "Hyperion" (Equal to)
GET /api/book?$filter=title eq 'Hyperion'

### Get books not titled "Hyperion" (Not equal to)
GET /api/book?$filter=title ne 'Hyperion'

### Get books published after 1990 (Greater than)
GET /api/book?$filter=year gt 1990

### Get books published in or after 1990 (Greater than or equal to)
GET /api/book?$filter=year ge 1990

### Get books published before 1991 (Less than)
GET /api/book?$filter=year lt 1991

### Get books published in or before 1990 (Less than or equal to)
GET /api/book?$filter=year le 1990

### Get books published between 1980 and 1990 (Logical and)
GET /api/book?$filter=year ge 1980 and year le 1990

### Get books published before 1960 or titled "Hyperion" (Logical or)
GET /api/book?$filter=year le 1960 or title eq 'Hyperion'

### Get books not published before 1960 (Logical negation)
GET /api/book?$filter=not (year le 1960)

### Get books published in 1970 or later, and either titled "Foundation" or with more than 400 pages (Grouping)
GET /api/book?$filter=(year ge 1970 or title eq 'Foundation') and pages gt 400

Los operadores admitidos por la opción $filter son:

Operador	Tipo	Descripción	Ejemplo
`eq`	Comparación	Igual	`title eq 'Hyperion'`
`ne`	Comparación	No es igual	`title ne 'Hyperion'`
`gt`	Comparación	Mayor que	`year gt 1990`
`ge`	Comparación	Mayor o igual que	`year ge 1990`
`lt`	Comparación	Menos que	`year lt 1990`
`le`	Comparación	Menor o igual que	`year le 1990`
`and`	Lógico	Lógico y	`year ge 1980 and year lt 1990`
`or`	Lógico	Lógico o	`year le 1960 or title eq 'Hyperion'`
`not`	Lógico	Negación lógica	`not (year le 1960)`
`( )`	Agrupación	Agrupación de precedencia	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

Nota

$filter es un argumento sensible a mayúsculas y minúsculas.

El parámetro de consulta $filter en Azure Data API Builder podría recordar a algunos usuarios de OData y eso se debe a que se inspiró directamente en las funcionalidades de filtrado de OData. La sintaxis es casi idéntica, lo que facilita a los desarrolladores que ya están familiarizados con OData para recoger y usar. Esta similitud fue intencionada, destinada a proporcionar una forma familiar y eficaz de filtrar los datos entre diferentes API.

`$orderby`

El valor del parámetro orderby es una lista separada por comas de expresiones usadas para ordenar los elementos.

Cada expresión del valor del parámetro orderby puede incluir el sufijo desc para solicitar un orden descendente, separados de la expresión por uno o varios espacios.

Por ejemplo:

### Order books by title in ascending order
GET /api/book?$orderby=title

### Order books by title in ascending order
GET /api/book?$orderby=title asc

### Order books by title in descending order
GET /api/book?$orderby=title desc

### Order books by year of publication in ascending order, then by title in ascending order
GET /api/book?$orderby=year asc, title asc

### Order books by year of publication in descending order, then by title in ascending order
GET /api/book?$orderby=year desc, title asc

### Order books by number of pages in ascending order, then by title in descending order
GET /api/book?$orderby=pages asc, title desc

### Order books by title in ascending order, then by year of publication in descending order
GET /api/book?$orderby=title asc, year desc

Nota

$orderBy es un argumento sensible a mayúsculas y minúsculas.

El parámetro de consulta $orderby es valioso para ordenar datos directamente en el servidor y también se puede gestionar fácilmente en el lado del cliente. Sin embargo, resulta útil cuando se combina con otros parámetros de consulta, como $filter y $first. El parámetro permite a la paginación mantener un conjunto de datos estable y predecible a medida que se pagina a través de colecciones grandes.

`$first` y `$after`

El parámetro de consulta $first limita el número de elementos devueltos en una sola solicitud. Por ejemplo:

GET /api/book?$first=5

Esta solicitud devuelve los cinco primeros libros. El parámetro de consulta $first en Azure Data API Builder es similar a la cláusula TOP en SQL. Ambos se usan para limitar el número de registros devueltos desde una consulta. Igual que TOP en SQL permite especificar la cantidad de filas que se van a recuperar, $first permite controlar el número de elementos devueltos por la API. $first resulta útil cuando desea capturar un pequeño subconjunto de datos, como los primeros 10 resultados, sin recuperar todo el conjunto de datos. La principal ventaja es la eficacia, ya que reduce la cantidad de datos transmitidos y procesados.

Nota

En el generador de API de datos de Azure, el número de filas devueltas de forma predeterminada está limitado por un valor en el archivo de configuración. Los usuarios pueden invalidar este límite mediante el parámetro $first para solicitar más filas, pero todavía hay un número máximo configurado de filas que se pueden devolver en general. Además, hay un límite en el total de megabytes que se pueden devolver en una única respuesta, que también se puede configurar.

Si hay más elementos disponibles más allá del límite especificado, la respuesta incluye una propiedad nextLink:

{
    "value": [],
    "nextLink": "dab-will-generate-this-continuation-url"
}

El nextLink se puede usar con el parámetro de consulta $after para recuperar el siguiente conjunto de elementos:

GET /api/book?$first={n}&$after={continuation-data}

Este enfoque de continuación usa la paginación basada en cursores. Un cursor único es una referencia a un elemento específico del conjunto de datos, que determina dónde continuar recuperando datos en el siguiente conjunto. A diferencia de la paginación de índices que usan desplazamientos o índices, la paginación basada en cursores no se basa en omitir registros. La continuación del cursor hace que sea más confiable con grandes conjuntos de datos o datos que cambian con frecuencia. En su lugar, garantiza un flujo uniforme y coherente de recuperación de datos iniciando exactamente donde se dejó la última consulta, en función del cursor proporcionado.

Por ejemplo:

### Get the first 5 books explicitly
GET /api/book?$first=5

### Get the next set of 5 books using the continuation token
GET /api/book?$first=5&$after={continuation-token}

### Get the first 10 books, ordered by title
GET /api/book?$first=10&$orderby=title asc

### Get the next set of 10 books after the first set, ordered by title
GET /api/book?$first=10&$after={continuation-token}&$orderby=title asc

### Get books without specifying $first (automatic pagination limit)
GET /api/book

### Get the next set of books using the continuation token without specifying $first
GET /api/book?$after={continuation-token}

EXPONER

Cree un nuevo elemento para la entidad especificada. Por ejemplo:

POST /api/book
Content-type: application/json

{
  "id": 2000,
  "title": "Do Androids Dream of Electric Sheep?"
}

La solicitud POST crea un nuevo libro. Se deben proporcionar todos los campos que no admiten valores NULL. Si se ejecuta correctamente el objeto de entidad completa, incluidos los campos NULL, se devuelve:

{
  "value": [
    {
      "id": 2000,
      "title": "Do Androids Dream of Electric Sheep?",
      "year": null,
      "pages": null
    }
  ]
}

PONER

PUT crea o reemplaza un elemento de la entidad especificada. El patrón de consulta es:

PUT /api/{entity}/{primary-key-column}/{primary-key-value}

Por ejemplo:

PUT /api/book/id/2001
Content-type: application/json

{  
  "title": "Stranger in a Strange Land",
  "pages": 525
}

Si hay un elemento con la clave principal especificada 2001, los datos proporcionados reemplazan completamente ese elemento. Si en su lugar no existe un elemento con esa clave principal, se crea un nuevo elemento.

En cualquier caso, el resultado es similar a:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": null,
      "pages": 525
    }
  ]
}

Encabezado de solicitud HTTP de `If-Match: *`

El encabezado HTTP If-Match: * garantiza que la operación de actualización se realice solo si el recurso existe. Si el recurso no existe, se producirá un error en la operación con el código de estado HTTP: 404 Not Found. Si el encabezado If-Match se omite, el comportamiento predeterminado es realizar un upsert, que crea el recurso si aún no existe.

Ejemplo de :

PUT /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
  "title": "Stranger in a Strange Land",
  "pages": 525
}

Nota

Si especifica un valor distinto de * en el encabezado If-Match, data API Builder devolverá un error de 400 Bad Request, ya que no se admite la coincidencia basada en ETag.

PARCHE

PATCH crea o actualiza el elemento de la entidad especificada. Solo se ven afectados los campos especificados. No se verán afectados todos los campos especificados en el cuerpo de la solicitud. Si no existe un elemento con la clave principal especificada, se crea un nuevo elemento.

El patrón de consulta es:

PATCH /api/{entity}/{primary-key-column}/{primary-key-value}

Por ejemplo:

PATCH /api/book/id/2001
Content-type: application/json

{    
  "year": 1991
}

El resultado es algo parecido a:

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": 1991,
      "pages": 525
    }
  ]
}

El encabezado de solicitud HTTP `If-Match: *`

El encabezado HTTP If-Match: * garantiza que operación de actualización se realicesolo si el recurso existe. Si el recurso no existe, se producirá un error en la operación con el código de estado HTTP: 404 Not Found. Si el encabezado If-Match se omite, el comportamiento predeterminado es realizar un upsert, que crea el recurso si aún no existe.

Ejemplo de :

PATCH /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
    "year": 1991
}

Nota

Si especifica un valor distinto de * en el encabezado If-Match, data API Builder devolverá un error de 400 Bad Request, ya que no se admite la coincidencia basada en ETag.

BORRAR

DELETE elimina el elemento de la entidad especificada. El patrón de consulta es:

DELETE /api/{entity}/{primary-key-column}/{primary-key-value}

Por ejemplo:

DELETE /api/book/id/2001

Si se ejecuta correctamente, el resultado es una respuesta vacía con el código de estado 204.

Transacciones de base de datos para solicitudes de API REST

Para procesar solicitudes POST, PUT, PATCH y DELETE API; El generador de API de datos construye y ejecuta las consultas de base de datos en una transacción.

En la tabla siguiente se enumeran los niveles de aislamiento con los que se crean las transacciones para cada tipo de base de datos.

Tipo de base de datos	Nivel de aislamiento	Más información
Azure SQL (o) SQL Server	Lectura confirmada	Azure SQL
MySQL	Lectura repetible	mySQL
PostgreSQL	Lectura confirmada	PostgreSQL

Compartir a través de

Hospedaje de puntos de conexión REST en data API Builder

Llamada a un método de API rest

Métodos HTTP

Ruta de acceso de rest

Entidad

Formato del conjunto de resultados

OBTENER

Parámetros de dirección URL

Por ejemplo:

Parámetros de consulta

`$select`

`$filter`

`$orderby`

`$first` y `$after`

EXPONER

PONER

Encabezado de solicitud HTTP de `If-Match: *`

PARCHE

El encabezado de solicitud HTTP `If-Match: *`

BORRAR

Transacciones de base de datos para solicitudes de API REST

Comentarios

Recursos adicionales

Compartir a través de

Hospedaje de puntos de conexión REST en data API Builder

Llamada a un método de API rest

Métodos HTTP

Ruta de acceso de rest

Entidad

Formato del conjunto de resultados

OBTENER

Parámetros de dirección URL

Por ejemplo:

Parámetros de consulta

$select

$filter

$orderby

$first y $after

EXPONER

PONER

Encabezado de solicitud HTTP de If-Match: *

PARCHE

El encabezado de solicitud HTTP If-Match: *

BORRAR

Transacciones de base de datos para solicitudes de API REST

Contenido relacionado

Comentarios

Recursos adicionales

`$select`

`$filter`

`$orderby`

`$first` y `$after`

Encabezado de solicitud HTTP de `If-Match: *`

El encabezado de solicitud HTTP `If-Match: *`