RESTful-interakciók az Azure Cosmos DB-vel

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

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

  • Hogyan működnek a szabványos HTTP-metódusok az Azure Cosmos DB-erőforrásokkal?
  • Hogyan új erőforrást létrehozni 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 kapcsolati lehetőségek állnak rendelkezésre a HTTPS és a TCP protokollhoz?

Ha arra kíváncsi, hogyan hajthat végre CRUD-műveleteket adott erőforrásokon a REST használatával, tekintse meg az Azure Cosmos DB REST API-t használó gyakori feladatokat. 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 .NET-mintából származó REST-et GitHub.

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 tekintse meg az Azure Cosmos DB-példákat. Az SDK letöltési és dokumentációs hivatkozásait a Cosmos DB SDK-kban találja.

A HTTP-műveletek áttekintése

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

  1. A POST azt jelenti, hogy új elemerőforrást hoz létre.
  2. A GET egy meglévő elem vagy hírcsatorna-erőforrás beolvasását jelenti
  3. A PUT azt jelenti, hogy lecserél egy meglévő elemerőforrást
  4. A DELETE egy meglévő elemerőforrás törlését jelenti
  5. A HEAD azt jelenti, hogy a GET sans a válasz hasznos adatát (azaz csak a fejléceket)

Az alábbi HTTP-műveletek ábráján látható módon a POST csak hírcsatorna-erőforráshoz adható ki; A PUT és a DELETE csak elemerőforráshoz adható ki; A GET és a HEAD kibocsátható a hírcsatorna- vagy elemerőforrásokhoz is.

Interaction model using the standard HTTP methods

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 tekintsük át 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 az erőforrást tartalmazó kérelemtörzshöz azon tárolócsatorna URI-ja alapján, amelyhez az erőforrás tartozik. A kéréshez az egyetlen szükséges tulajdonság az erőforrás azonosítója.

Új adatbázis létrehozásához például postán kell elküldenie egy adatbázis-erőforrást (az azonosító tulajdonság egyedi névvel való beállításával) a /dbs értékre. Hasonlóképpen, új gyűjtemény létrehozásához postáz egy gyűjteményerő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"
}  

Egy új adatbázis POST létrehozásához például egy adatbázis-erőforrást kell használnia (az azonosító tulajdonság egyedi névvel való beállításával) a következőre /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 sikeres választ és az adatbázis sikeres létrehozását jelző állapotkóddal válaszol.

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-metódussal

Egy másik példa egy erőforrás létrehozására és végrehajtására, tekintsünk egy egyszerű "HelloWorld" tárolt eljárást, amely teljes egészében JavaScriptben van megírva.

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

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

A tárolt eljárás regisztrálható egy gyűjteményben a MyDb alatt egy POST-fájl /dbs/_rid-db/colls/_rid-coll/sprocskiadásával.

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 sikeres választ és a tárolt eljárás sikeres regisztrációját jelző állapotkóddal válaszol.

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-metódussal

Végül az előző példában szereplő tárolt eljárás végrehajtásához ki kell adnia egy POST hibát a tárolt eljárás erőforrásának (/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/) URI-ja ellen, 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-parancs egy új erőforrás létrehozására, tárolt eljárás végrehajtására és SQL-lekérdezés kiadására szolgál. 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

Erőforrás mennyiségének PUT lecserélése vagy olvasása (érvényes kérelemtörzsgel) és GET parancsok az erőforrás _self hivatkozásán. Hasonlóképpen, ha töröl egy erőforrást, akkor egy parancsot kell kiadnia 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 rendszerezése szükségessé teszi a kaszkádolt törlések támogatását, ahol a tulajdonosi erőforrás törlése a függő erőforrások törlését okozza. A függő erőforrások a tulajdonosi erőforrásoktól eltérő csomópontokon is eloszthatók, így a törlés szakaszosan történhet. A szemétgyűjtés mechanikájától függetlenül az erőforrások törlésekor a kvóta azonnal felszabadul, és használatra kész. Vegye figyelembe, hogy a hivatkozási integritást a rendszer megőrzi. Nem szúrhat be például olyan gyűjteményt egy adatbázisba, amely már nem létezik, és nem cseréli le vagy kérdezi le a már nem létező gyűjtemény dokumentumait.

Egy erőforrás-adatcsatorna ellen történő kibocsátás GET vagy egy gyűjtemény lekérdezése akár több millió tételt is eredményezhet, így nem praktikus, hogy a kiszolgáló és az ügyfelek egyetlen roundtrip/ kérés- és válaszcsere részeként használják fel őket. Ennek megoldása érdekében az Azure Cosmos DB lehetővé teszi az ügyfelek számára, hogy egyszerre több lapra tördeljék a nagy hírcsatorna lapjait. 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ég-vezérlésre 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). A rendszer helyesen észleli az egyidejűség-vezérlés ütközéseit a következő esetekben:

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

  2. Ha egy ügyfél az erőforrás egy régebbi (az [if-match] kérelemfejlécen megadott) verziójával rendelkezik, a rendszer elutasítja a kérését.

Csatlakozási lehetőségek

A Cosmos DB egy logikai címzési modellt tesz elérhetővé, amelyben minden erőforrás rendelkezik egy logikai és stabil URI-val, amelyet a _self hivatkozás azonosít. A régiók között elosztott tárolórendszerként a Cosmos DB különböző adatbázisfiókjaiban lévő erőforrások számos gépen vannak particionálva, és minden partíció replikálva van a magas rendelkezésre állás érdekében. Egy adott partíció fizikai címeinek 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ázatban van tárolva, amely szintén belsőleg elérhető erőforrásként. A Cosmos DB két kapcsolati módot tesz elérhetővé:

  • Átjáró mód: Az ügyfelek védve vannak a logikai címek é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 RESTfully módon 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ákhoz, é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 az élcsomó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 elvégezhetik az ügyféloldali útválasztást, hogy közvetlenül csatlakozzanak a replikákhoz. .NET, Java

Lásd még: