RESTful interakciók az Azure Cosmos DB-vel

Cikk
07/19/2023

Az Azure Cosmos DB egy globálisan elosztott többmodelles adatbázis, amely támogatja a dokumentum-, gráf- és kulcsértékű adatmodelleket. A jelen szakaszban található tartalom dokumentum-erőforrások létrehozására, lekérdezésére és kezelésére használható az SQL API REST-en keresztüli használatával.

A cikk elolvasásával a következő kérdésekre válaszolhat:

Hogyan működnek a szabványos HTTP-metódusok az Azure Cosmos DB-erőforrásokkal?
Hogyan hozzon létre egy új erőforrást a POST használatával?
Hogyan regisztrálni egy tárolt eljárást a POST használatával?
Hogyan támogatja az Azure Cosmos DB az egyidejűség-vezérlést?
Milyen csatlakozási lehetőségek érhetők el a HTTPS-hez és a TCP-hez?

Ha információkat szeretne megtudni arról, hogyan hajthat végre CRUD-műveleteket adott erőforrásokon a REST használatával, tekintse meg az Azure Cosmos DB REST API-val végzett gyakori feladatok című témakört. Ha a CRUD-műveletek C# és REST használatával történő végrehajtására vonatkozó mintákat keres, tekintse meg a GitHubon található .NET-minta REST-ét .

Megjegyzés

CruD-műveleteket is végrehajthat Cosmos DB-erőforrásokon a Cosmos DB SDK-k használatával. Példákért lásd az Azure Cosmos DB-példákat. Az SDK letöltésére és dokumentációjára mutató hivatkozásokért lásd: Cosmos DB SDK-k.

A HTTP-parancsok áttekintése

Az Azure Cosmos DB-erőforrások a következő HTTP-parancsokat támogatják szabványos értelmezésükkel:

A POST egy új elemerőforrás létrehozását jelenti.
A GET azt jelenti, hogy beolvas egy meglévő elemet vagy egy hírcsatorna-erőforrást
A PUT azt jelenti, hogy lecserél egy meglévő elemerőforrást
A DELETE egy meglévő elemerőforrás törlését jelenti
A HEAD azt jelenti, hogy a GET sans a válasz hasznos adata (azaz csak a fejlécek)

Amint azt az alábbi HTTP-parancsdiagram szemlélteti, a POST csak hírcsatorna-erőforráson adható ki; A PUT és a DELETE csak elemerőforráson adható ki; A GET és a HEAD kibocsátható a hírcsatorna- vagy elemerőforrásokon.

Interakciós modell a standard HTTP-metódusokkal

Interakciós modell a szabványos HTTP-metódusokkal

Új erőforrás létrehozása POST HTTP-metódussal

Az interakciós modell jobb érzete érdekében vegyük fontolóra egy új erőforrás (más néven INSERT) létrehozását. Új erőforrás létrehozásához HTTP POST-kérést kell kiadnia a kérelem törzséhez, amely tartalmazza az erőforrásnak az erőforráshoz tartozó tárolócsatorna URI-jával szembeni ábrázolását. A kérelemhez az egyetlen szükséges tulajdonság az erőforrás azonosítója.

Egy új adatbázis létrehozásához például közzé kell tenni egy adatbázis-erőforrást (az azonosító tulajdonság egyedi névvel történő beállításával) a /dbs értékre. Hasonlóképpen, egy új gyűjtemény létrehozásához közzé kell tenni egy gyűjtési erőforrást a /dbs/_rid/colls/ és így tovább. A válasz tartalmazza a teljes mértékben véglegesített erőforrást a rendszer által létrehozott tulajdonságokkal, beleértve az erőforrás _self hivatkozását, amellyel más erőforrásokhoz navigálhat. Az egyszerű HTTP-alapú interakciós modell példájaként az ügyfél http-kérést adhat ki egy új adatbázis fiókon belüli létrehozásához.

POST https://fabrikam.documents.azure.com/dbs  
{  
    "id":"MyDb"
}

Például egy új adatbázis POST létrehozásához egy adatbázis-erőforrást kell létrehoznia (az ID tulajdonság egyedi névvel történő beállításával) a értékre /dbs. Hasonlóképpen, egy új gyűjtemény POST létrehozásához gyűjtési erőforrást /dbs/_rid/colls/ kell létrehoznia, és így tovább. A válasz tartalmazza a teljes mértékben véglegesített erőforrást a rendszer által létrehozott tulajdonságokkal, beleértve az _self erőforrás hivatkozását, amellyel más erőforrásokhoz navigálhat. Az egyszerű HTTP-alapú interakciós modell példájaként az ügyfél http-kérést adhat ki egy új adatbázis fiókon belüli létrehozásához.

Az Azure Cosmos DB szolgáltatás egy sikeres válaszsal és egy állapotkóddal válaszol, amely az adatbázis sikeres létrehozását jelzi.

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

Tárolt eljárás regisztrálása POST HTTP-módszerrel

Egy másik példa egy erőforrás létrehozására és végrehajtására, fontolja meg egy egyszerű"HelloWorld" tárolt eljárást, amelyet teljes egészében JavaScriptben írtak.

function HelloWorld() {  
    var context = getContext();  
    var response = context.getResponse();  

    response.setBody("Hello, World");  
}

A tárolt eljárás regisztrálható egy gyűjteménybe a MyDb alatt, ha POST-t ad ki a következővel: /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");  
            }"  
}

Az Azure Cosmos DB szolgáltatás egy sikeres válaszsal és egy állapotkóddal válaszol, amely a tárolt eljárás sikeres regisztrációját jelzi.

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

Tárolt eljárás végrehajtása POST HTTP-módszerrel

Végül az előző példában szereplő tárolt eljárás végrehajtásához ki kell adni a POST tárolt eljárás erőforrásának (/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/) URI-ját az alább látható módon.

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA== HTTP/1.1

Az Azure Cosmos DB szolgáltatás a következő válaszsal válaszol.

HTTP/1.1 200 OK  
  
"Hello World"

Vegye figyelembe, hogy a POST HTTP-parancsot egy új erőforrás létrehozására, tárolt eljárás végrehajtására és SQL-lekérdezések kibocsátására használják. Az SQL-lekérdezés végrehajtásának szemléltetéséhez vegye figyelembe az alábbiakat.

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

A szolgáltatás az SQL-lekérdezés eredményeivel válaszol.

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}

A PUT, a GET és a DELETE HTTP-parancsok használata

Egy erőforrás mennyiségének cseréje vagy olvasása a kibocsátásra PUT (érvényes kérelemtörzsgel) és GET parancsok az erőforrás _self hivatkozására. Hasonlóképpen, ha töröl egy erőforrásösszeget, hogy egy igét adjon ki DELETE az erőforrás _self hivatkozásán. Érdemes rámutatni arra, hogy az Azure Cosmos DB erőforrásmodelljében az erőforrások hierarchikus szervezése megköveteli a kaszkádolt törlések támogatását, amely a tulajdonosi erőforrás törlésével a függő erőforrások törlését okozza. A függő erőforrások a tulajdonos erőforrásain kívül más csomópontokon is eloszthatók, így a törlés lazán történhet. A szemétgyűjtés mechanikájától függetlenül egy erőforrás törlésekor a kvóta azonnal felszabadul, és elérhető a használatához. Vegye figyelembe, hogy a hivatkozási integritást a rendszer megőrzi. Nem szúrhat be gyűjteményt például olyan adatbázisba, amely már nem létezik, és nem cseréli le vagy kérdezi le a gyűjtemény dokumentumait.

Ha erőforrásokat GET bocsát ki egy adatcsatornán, vagy lekérdez egy gyűjteményt, az akár több millió tételt is eredményezhet, így nem praktikus, hogy a kiszolgáló és az ügyfelek egyetlen ciklikus/ kérés- és válaszcsere részeként használják fel őket. Ennek megoldásához az Azure Cosmos DB lehetővé teszi az ügyfelek számára, hogy a nagy hírcsatornaoldalon lapoznak. Az ügyfelek az [x-ms-continuation] válaszfejlécet használhatják kurzorként a következő oldalra való navigáláshoz.

Optimista egyidejűség-vezérlés

A legtöbb webalkalmazás entitáscímke-alapú optimista egyidejűségi vezérlőre támaszkodik, hogy elkerülje a hírhedt "Elveszett frissítés" és "Elveszett törlés" problémákat. Az entitáscímke egy erőforráshoz társított HTTP-barát, logikai időbélyeg. A Cosmos DB natív módon támogatja az optimista egyidejűség-vezérlést azáltal, hogy biztosítja, hogy minden HTTP-válasz tartalmazza az adott erőforráshoz társított verziót (tartósan). Az egyidejűség-vezérlés ütközéseit a rendszer helyesen észleli a következő esetekben:

Ha két ügyfél egyidejűleg az erőforrás legújabb verziójával (az [if-match] kérelemfejlécen megadott) erőforráson ad ki mutációs kéréseket (PUT/DELETE parancsokkal), a Cosmos DB adatbázismotor a tranzakciós egyidejűség-vezérlés alá helyezi őket.
Ha egy ügyfél az erőforrás régebbi (az [if-match] kérelemfejlécen megadott) verziójával rendelkezik, a rendszer elutasítja a kérést.

Csatlakozási lehetőségek

A Cosmos DB egy logikai címzési modellt tesz elérhetővé, amelyben minden erőforrás rendelkezik a _self hivatkozás által azonosított logikai és stabil URI-vel. A régiók közötti elosztott tárolórendszerként a Cosmos DB különböző adatbázisfiókjaiban lévő erőforrások számos gépen particionálódnak, és minden partíció replikálva van a magas rendelkezésre állás érdekében. Az adott partícióregisztráló fizikai címek erőforrásait kezelő replikák. Bár a fizikai címek a hibák miatt idővel változnak, a logikai címek állandóak és állandóak maradnak. A logikai–fizikai címfordítás egy útválasztási táblában van tárolva, amely szintén belsőleg elérhető erőforrásként. A Cosmos DB két csatlakozási módot tesz elérhetővé:

Átjáró mód: Az ügyfelek védve vannak a logikai és a fizikai címek közötti fordítástól vagy az útválasztás részleteitől; egyszerűen a logikai URI-kkal foglalkoznak, és a RESTfully navigálnak az erőforrásmodellben. Az ügyfelek logikai URI használatával bocsátják ki a kéréseket, a peremhálózati gépek pedig lefordítják a logikai URI-t az erőforrást kezelő és a kérést továbbító replika fizikai címére. A peremhálózati gépek gyorsítótárazásával (és rendszeres frissítésével) az útválasztási táblázat rendkívül hatékony.
Közvetlen kapcsolati mód: Az ügyfelek közvetlenül kezelik az útválasztási táblát a folyamattérben, és rendszeres időközönként frissítik azt. Az ügyfél közvetlenül csatlakozhat a replikákkal, és megkerülheti a peremhálózati gépeket.

Kapcsolati mód	Protokoll	Részletek	Azure Cosmos DB SDK-k
Átjáró	HTTPS	Az alkalmazások közvetlenül csatlakoznak a peremcsomópontokhoz logikai URI-k használatával. Ez további hálózati ugrást von maga után.	REST API, .NET, Node.js, Java, Python, JavaScript
Közvetlen kapcsolat	HTTPS és TCP	Az alkalmazások közvetlenül hozzáférhetnek az útválasztási táblához, és végrehajthatják az ügyféloldali útválasztást, hogy közvetlenül csatlakozzanak a replikákkal.	.NET, Java