Interacciones RESTful con Azure Cosmos DB
Azure Cosmos DB es una base de datos multimodelo distribuida globalmente que admite los modelos de datos de documento, gráfico y clave-valor. El contenido de esta sección es para crear, consultar y administrar recursos de documento mediante la API de SQL a través de REST.
Al leer este artículo, puede responder a las siguientes preguntas:
- ¿Cómo funcionan los métodos HTTP estándar con los recursos de Azure Cosmos DB?
- ¿Cómo se puede crear un nuevo recurso mediante POST?
- ¿Cómo se puede registrar un procedimiento almacenado mediante POST?
- ¿Cómo admite Azure Cosmos DB el control de simultaneidad?
- ¿Cuáles son las opciones de conectividad para HTTPS y TCP?
Si busca información sobre cómo realizar operaciones CRUD en recursos específicos mediante REST, consulte Tareas comunes mediante la API rest de Azure Cosmos DB. Si busca ejemplos sobre cómo realizar operaciones CRUD mediante C# y REST, consulte el ejemplo REST de .NET en GitHub.
Nota
También puede realizar operaciones CRUD en recursos de Cosmos DB mediante los SDK de Cosmos DB. Para obtener ejemplos, consulte Ejemplos de Azure Cosmos DB. Para obtener vínculos a las descargas y documentación del SDK, consulte SDK de Cosmos DB.
Información general de verbos HTTP
Los recursos de Azure Cosmos DB admiten los siguientes verbos HTTP con su interpretación estándar:
- POST significa crear un nuevo recurso de elementos.
- GET significa leer un elemento existente o un recurso de fuente.
- PUT significa reemplazar un recurso de elementos existentes.
- DELETE significa eliminar un recurso de elementos existentes.
- HEAD significa GET sans the response payload (es decir, solo los encabezados)
Como se ilustra en el siguiente diagrama de verbos HTTP, POST solo puede emitirse contra un recurso de fuentes; PUT y DELETE solo pueden emitirse contra un recurso de elementos; GET y HEAD pueden emitirse contra recursos de fuentes o elementos.
Modelo de interacción con los métodos HTTP estándar
Creación de un nuevo recurso usando el método HTTP POST
A fin de obtener una mejor percepción para el modelo de interacción, consideremos el caso de crear un recurso nuevo (alias INSERT). Para crear un nuevo recurso, es necesario emitir una solicitud HTTP POST con el cuerpo de la solicitud que contiene la representación del recurso en el URI de la fuente del contenedor a la que pertenece el recurso. La única propiedad necesaria para la solicitud es el identificador del recurso.
Por ejemplo, para crear una nueva base de datos, se publica un recurso de base de datos (estableciendo la propiedad ID con un nombre único) en /dbs. Del mismo modo, para crear una nueva colección, se publica un recurso de colección en /dbs/_rid/colls/ etc. La respuesta contiene el recurso totalmente confirmado con las propiedades generadas por el sistema, incluido el vínculo _self del recurso mediante el que puede navegar a otros recursos. Como ejemplo del modelo de interacción simple basado en HTTP, un cliente puede emitir una solicitud HTTP para crear una nueva base de datos dentro de una cuenta.
POST https://fabrikam.documents.azure.com/dbs
{
"id":"MyDb"
}
Por ejemplo, para crear una nueva base de datos, se establece POST un recurso de base de datos (estableciendo la propiedad ID con un nombre único) en /dbs. Del mismo modo, para crear una nueva colección, se usa POST un recurso de recopilación en /dbs/_rid/colls/ y así sucesivamente. La respuesta contiene el recurso totalmente confirmado con las propiedades generadas por el sistema, incluido el vínculo del recurso mediante el _self que puede navegar a otros recursos. Como ejemplo del modelo de interacción simple basado en HTTP, un cliente puede emitir una solicitud HTTP para crear una nueva base de datos dentro de una cuenta.
El servicio Azure Cosmos DB responde con una respuesta correcta y un código de estado que indica la creación correcta de la base de datos.
HTTP/1.1 201 Created
Content-Type: application/json
x-ms-request-charge: 4.95
...
{
"id": "MyDb",
"_rid": "UoEi5w==",
"_self": "dbs/UoEi5w==/",
"_ts": 1407370063,
"_etag": "00000100-0000-0000-0000-54b636600000",
"_colls": "colls/",
"_users": "users/"
}
Registro de un procedimiento almacenado mediante el método HTTP POST
Como otro ejemplo de la creación y ejecución de un recurso, considere un procedimiento almacenado "HelloWorld" simple creado completamente en JavaScript.
function HelloWorld() {
var context = getContext();
var response = context.getResponse();
response.setBody("Hello, World");
}
El procedimiento almacenado se puede registrar en una colección en MyDb mediante la emisión de un POST en /dbs/_rid-db/colls/_rid-coll/sprocs.
POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs HTTP/1.1
{
"id": "HelloWorld",
"body": "function HelloWorld() {
var context = getContext();
var response = context.getResponse();
response.setBody("Hello, World");
}"
}
El servicio Azure Cosmos DB responde con una respuesta correcta y un código de estado que indica el registro correcto del procedimiento almacenado.
HTTP/1.1 201 Created
Content-Type: application/json
x-ms-request-charge: 4.95
...
{
"body": "function HelloWorld() {
var context = getContext();
var response = context.getResponse();
response.setBody("Hello, World");
}",
"id": "HelloWorld"
"_rid": "UoEi5w+upwABAAAAAAAAgA==",
"_ts" : 1421227641
"_self": "dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/",
"_etag": "00002100-0000-0000-0000-50f71fda0000"
}
Ejecución de un procedimiento almacenado mediante el método HTTP POST
Por último, para ejecutar el procedimiento almacenado en el ejemplo anterior, debe emitir un POST con el URI del recurso de procedimiento almacenado (/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/), como se muestra a continuación.
POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA== HTTP/1.1
El servicio Azure Cosmos DB responde con la siguiente respuesta.
HTTP/1.1 200 OK
"Hello World"
Tenga en cuenta que el verbo HTTP POST se usa para la creación de un recurso nuevo, para ejecutar un procedimiento almacenado y para emitir una consulta SQL. Para ilustrar la ejecución de la consulta SQL, considere lo siguiente.
POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/docs HTTP/1.1
...
x-ms-documentdb-isquery: True
x-ms-documentdb-query-enable-scan: True
Content-Type: application/query+json
...
{"query":"SELECT f.LastName AS Name, f.Address.City AS City FROM Families f WHERE f.id='AndersenFamily' OR f.Address.City='NY'"}
El servicio responde con los resultados de la consulta SQL.
HTTP/1.1 200 Ok
...
x-ms-activity-id: 83f9992c-abae-4eb1-b8f0-9f2420c520d2
x-ms-item-count: 2
x-ms-session-token: 4
x-ms-request-charge: 3.1
Content-Type: application/json1
{"_rid":"UoEi5w+upwA=","Documents":[{"Name":"Andersen","City":"Seattle"},{"Name":"Wakefield","City":"NY"}],"_count":2}
Uso de los verbos HTTP PUT, GET y DELETE
Reemplazar o leer un recurso equivale a emitir PUT (con un cuerpo de solicitud válido) y verbos GET en el vínculo _self del recurso, respectivamente. Del mismo modo, la eliminación de un recurso equivale a emitir un DELETE verbo en el vínculo _self del recurso. Vale la pena señalar que la organización jerárquica de recursos en el modelo de recursos de Azure Cosmos DB requiere la compatibilidad con eliminaciones en cascada, donde la eliminación del recurso propietario provoca la eliminación de los recursos dependientes. Los recursos dependientes se pueden distribuir a través de otros nodos aparte de los recursos del propietario, de modo que la eliminación puede producirse lentamente. Sin considerar la mecánica de la recopilación de elementos no usados, después de la eliminación de un recurso, la cuota se libera instantáneamente y está disponible para su uso. Tenga en cuenta que el sistema mantiene la integridad referencial. Por ejemplo, no se puede insertar una recopilación en una base de datos que se eliminó ni reemplazar o consultar un documento de una recopilación que ya no existe.
La emisión de un GET objeto en una fuente de recursos o la consulta de una colección puede dar lugar a millones de elementos, por lo que no resulta práctico que ambos servidores los materialicen y los clientes los consuman como parte de un único intercambio de ida y vuelta/ solicitud y respuesta. Para solucionar esto, Azure Cosmos DB permite a los clientes paginar a través de la página de fuente grande a la vez. Los clientes pueden usar el encabezado de respuesta [x-ms-continuation] como un cursor para navegar a la página siguiente.
Control de simultaneidad optimista
La mayoría de las aplicaciones web dependen de una etiqueta de identidad basada en el control de concurrencia optimista para evitar los desastrosos problemas de "Actualización perdida" y "Eliminación perdida". La etiqueta de entidad es una marca de tiempo HTTP lógica y fácil de usar asociada con un recurso. Cosmos DB admite de forma nativa el control de simultaneidad optimista asegurándose de que cada respuesta HTTP contiene la versión (duraderamente) asociada al recurso específico. Los conflictos del control de concurrencia se detectan correctamente para los siguientes casos:
Si dos clientes emiten simultáneamente solicitudes de mutación (mediante verbos PUT/DELETE) en un recurso con la versión más reciente del recurso (especificada mediante el encabezado de solicitud [if-match], el motor de base de datos de Cosmos DB los somete al control de simultaneidad transaccional.
Si un cliente se presenta con una versión más antigua del recurso (especificado mediante el encabezado de solicitud [if-match]), la solicitud se rechaza.
Opciones de conectividad
Cosmos DB expone un modelo de direccionamiento lógico donde cada recurso tiene un URI lógico y estable identificado por su vínculo de _self . Como sistema de almacenamiento distribuido distribuido entre regiones, los recursos de varias cuentas de base de datos de Cosmos DB se particionan entre numerosas máquinas y cada partición se replica para lograr una alta disponibilidad. Las réplicas que administran los recursos de una partición dada registran las direcciones físicas. Aun cuando las direcciones físicas cambian en el tiempo debido a errores, sus direcciones lógicas se mantienen estables y constantes. El traslado de la dirección lógica a física se mantiene en una tabla de enrutamiento que también esta disponible de manera interna como un recurso. Cosmos DB expone dos modos de conectividad:
Modo de puerta de enlace: los clientes están protegidos del traslado entre las direcciones lógicas a físicas o los detalles del enrutamiento; simplemente tratan las URI lógicas y navegan de modo RESTful en el modelo de recursos. Los clientes emiten las solicitudes usando una URI lógica y las máquinas perimetrales trasladan la URI a la dirección física de la réplica que administra el recurso y reenvía la solicitud. Con las máquinas perimetrales que ponen en la memoria caché (y periódicamente actualizan) la tabla de enrutamiento, el enrutamiento es sumamente eficaz.
Modo de conectividad directa: los clientes administran directamente la tabla de enrutamiento en su espacio de proceso y la actualizan periódicamente. El cliente puede conectarse directamente con las réplicas y omitir las máquinas perimetrales.
| Modo de conectividad | Protocolo | Detalles | SDK de Azure Cosmos DB |
|---|---|---|---|
| Puerta de enlace | HTTPS | Las aplicaciones se conectan directamente con los nodos perimetrales usando las URI lógicas. Esto significa un salto adicional de la red. | API REST, .NET, Node.js, Java, Python, JavaScript |
| Conectividad directa | HTTPS y TCP | Las aplicaciones pueden tener acceso de manera directa a la tabla de enrutamiento y realizar el enrutamiento del cliente para que se conecte directamente con las réplicas. | .NET, Java |