Interazioni RESTful con Azure Cosmos DB
Azure Cosmos DB è un database multimodello distribuito a livello globale che supporta i modelli di dati document, graph e key-value. Il contenuto di questa sezione consiste nel creare, eseguire query e gestire le risorse del documento usando l'API SQL tramite REST.
Leggendo questo articolo, è possibile rispondere alle domande seguenti:
- Come funzionano i metodi HTTP standard con le risorse di Azure Cosmos DB?
- Come si crea una nuova risorsa con POST?
- Come si registra una stored procedure con POST?
- In che modo Azure Cosmos DB supporta il controllo di concorrenza?
- Quali sono le opzioni di connettività per HTTPS e TCP?
Per informazioni su come eseguire operazioni CRUD su risorse specifiche usando REST, vedere Attività comuni usando l'API REST di Azure Cosmos DB. Se si stanno cercando esempi su come eseguire operazioni CRUD usando C# e REST, vedere l'esempio REST da .NET in GitHub.
Nota
È anche possibile eseguire operazioni CRUD nelle risorse di Cosmos DB usando gli SDK cosmos DB. Per esempi, vedere Esempi di Azure Cosmos DB. Per i collegamenti ai download e alla documentazione dell'SDK, vedere SDK di Cosmos DB.
Panoramica dei verbi HTTP
Le risorse di Azure Cosmos DB supportano i verbi HTTP seguenti con l'interpretazione standard:
- POST significa creare una nuova risorsa elemento.
- GET significa leggere un elemento esistente o una risorsa feed
- PUT significa sostituire una risorsa elemento esistente
- DELETE significa eliminare una risorsa elemento esistente
- HEAD significa GET sans il payload della risposta ( ovvero, solo le intestazioni)
Come illustrato nel diagramma dei verbi HTTP seguente, POST può essere rilasciato solo su una risorsa del feed; PUT e DELETE possono essere rilasciati solo su una risorsa elemento; GET e HEAD possono essere rilasciati su risorse di feed o elemento.
Modello di interazione che usa i metodi HTTP standard
Creare una nuova risorsa con il metodo HTTP POST
Per acquisire maggiore familiarità con il modello di interazione, si consideri l'eventualità di creare una nuova risorsa (INSERT). Per creare una nuova risorsa, è necessario inviare una richiesta HTTP POST con il corpo della richiesta contenente la rappresentazione della risorsa rispetto all'URI del feed del contenitore a cui appartiene la risorsa. L'unica proprietà necessaria per la richiesta è l'ID della risorsa.
Ad esempio, per creare un nuovo database, si pubblica una risorsa di database (impostando la proprietà ID con un nome univoco) su /dbs. Analogamente, per creare una nuova raccolta, si pubblica una risorsa di raccolta su /dbs/_rid/colls/ e così via. La risposta contiene la risorsa completamente commit con le proprietà generate dal sistema, incluso il collegamento _self della risorsa usando la quale è possibile passare ad altre risorse. Come esempio del semplice modello di interazione basato su HTTP, un client può inviare una richiesta HTTP per creare un nuovo database all'interno di un account.
POST https://fabrikam.documents.azure.com/dbs
{
"id":"MyDb"
}
Ad esempio, per creare un nuovo database, si POST usa una risorsa di database (impostando la proprietà ID con un nome univoco) su /dbs. Analogamente, per creare una nuova raccolta, si POST esegue una risorsa di raccolta su /dbs/_rid/colls/ e così via. La risposta contiene la risorsa completamente commit con le proprietà generate dal sistema, incluso il _self collegamento della risorsa usando la quale è possibile passare ad altre risorse. Come esempio del semplice modello di interazione basato su HTTP, un client può inviare una richiesta HTTP per creare un nuovo database all'interno di un account.
Il servizio Azure Cosmos DB risponde con una risposta riuscita e un codice di stato che indica la corretta creazione del database.
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/"
}
Registrare una stored procedure con il metodo HTTP POST
Per un altro esempio di creazione ed esecuzione di una risorsa, valutare la seguente stored procedure scritta interamente in JavaScript.
function HelloWorld() {
var context = getContext();
var response = context.getResponse();
response.setBody("Hello, World");
}
La stored procedure può essere registrata in una raccolta in MyDb emettendo un POST su /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");
}"
}
Il servizio Azure Cosmos DB risponde con una risposta riuscita e un codice di stato che indica la corretta registrazione della stored procedure.
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"
}
Eseguire una stored procedure con il metodo HTTP POST
Infine, per eseguire la stored procedure nell'esempio precedente, è necessario eseguire un POST oggetto sull'URI della risorsa della stored procedure (/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/) come illustrato di seguito.
POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA== HTTP/1.1
Il servizio Azure Cosmos DB risponde con la risposta seguente.
HTTP/1.1 200 OK
"Hello World"
Si noti che il verbo HTTP POST può essere usato per creare una nuova risorsa, per eseguire una stored procedure e per inviare una query SQL. Per illustrare l'esecuzione della query SQL, considerare quanto segue.
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'"}
Il servizio risponde con i risultati della query 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 dei verbi HTTP PUT, GET e DELETE
La sostituzione o la lettura di una risorsa equivale a emettere PUT (con un corpo della richiesta valido) e i verbi GET rispettivamente rispetto al collegamento _self della risorsa. Analogamente, l'eliminazione di una risorsa equivale a emettere un DELETE verbo rispetto al collegamento _self della risorsa. Vale la pena sottolineare che l'organizzazione gerarchica delle risorse nel modello di risorse di Azure Cosmos DB richiede il supporto per le eliminazioni a catena in cui l'eliminazione della risorsa proprietario causa l'eliminazione delle risorse dipendenti. Le risorse dipendenti possono essere distribuite su nodi diversi da quelli delle risorse proprietarie e pertanto l'eliminazione potrebbe avvenire in modo differito. A prescindere dal meccanismo di garbage collection, nel momento in cui una risorsa viene eliminata, la quota viene istantaneamente liberata e resa disponibile per l'uso. Si noti che l'integrità referenziale viene conservata da parte del sistema. Ad esempio, non è possibile inserire una raccolta in un database che è stato eliminato o sostituito né eseguire query su un documento di una raccolta che non esiste più.
L'emissione di un GET oggetto su un feed di risorse o una query su una raccolta può comportare potenziali milioni di elementi, rendendo quindi impraticabile che entrambi i server li materializzino e i client per usarli come parte di un singolo round-round/request/response exchange. Per risolvere questo problema, Azure Cosmos DB consente ai client di impaginare la pagina di feed di grandi dimensioni in fase di esecuzione. I client possono usare l'intestazione di risposta [x-ms-continuation] come cursore per passare alla pagina successiva.
Controllo della concorrenza ottimistica
La maggior parte delle applicazioni Web si affida al controllo della concorrenza ottimistica basato su tag di entità per evitare i fastidiosi problemi legati alla perdita di aggiornamenti o alla perdita di eliminazioni. Il tag di entità è un timestamp logico e compatibile con HTTP associato a una risorsa. Cosmos DB supporta in modo nativo il controllo di concorrenza ottimistica assicurandosi che ogni risposta HTTP contenga la versione (duramente) associata alla risorsa specifica. I conflitti del controllo della concorrenza vengono correttamente rilevati nei casi seguenti:
Se due client emettono simultaneamente richieste di modifica (tramite verbi PUT/DELETE) in una risorsa con la versione più recente della risorsa (specificata tramite l'intestazione della richiesta [if-match]), il motore di database Cosmos DB li applica al controllo di concorrenza transazionale.
Se un client presenta una versione non aggiornata della risorsa (specificata tramite l'intestazione di richiesta [if-match]), la richiesta verrà rifiutata.
Opzioni di connettività
Cosmos DB espone un modello di indirizzamento logico in cui ogni risorsa ha un URI logico e stabile identificato dal relativo collegamento _self . Come sistema di archiviazione distribuito in aree, le risorse in vari account di database in Cosmos DB vengono partizionate in numerosi computer e ogni partizione viene replicata per la disponibilità elevata. Le repliche che gestiscono le risorse di una determinata partizione effettuano la registrazione di indirizzi fisici. Anche se gli indirizzi fisici cambiano nel corso del tempo a causa di errori, i relativi indirizzi logici restano stabili e costanti. La traduzione da indirizzo fisico a logico viene mantenuta in una tabella di routing disponibile anche internamente come risorsa. Cosmos DB espone due modalità di connettività:
Modalità gateway: I client vengono schermati dalla traduzione tra indirizzi logici a indirizzi fisici o i dettagli del routing; si tratta semplicemente di URI logici e REST in modo da esplorare il modello di risorsa. I client emettono le richieste usando l'URI logico e i computer perimetrali convertono l'URI logico nell'indirizzo fisico della replica che gestisce la risorsa e inoltra la richiesta. Con la memorizzazione nella cache dei computer perimetrali (e periodicamente l'aggiornamento) della tabella di routing, il routing è estremamente efficiente.
Modalità connettività diretta: i client gestiscono direttamente la tabella di routing nel proprio spazio di elaborazione e la aggiornano periodicamente. Un client può connettersi direttamente alle repliche e ignorare i computer perimetrali.
| Modalità di connettività | Protocollo | Dettagli | Azure Cosmos DB SDK |
|---|---|---|---|
| Gateway | HTTPS | Le applicazioni si connettono direttamente con i nodi perimetrali usando URI logici. Ciò determina un hop di rete aggiuntivo | API REST, .NET, Node.js, Java, Python, JavaScript |
| Connettività diretta | HTTPS e TCP | Le applicazioni possono accedere direttamente alla tabella di routing ed eseguire il routing lato client per connettersi direttamente con le repliche. | .NET, Java |