Interakcje RESTful z usługą Azure Cosmos DB

Usługa Azure Cosmos DB to globalnie rozproszona wielomodelowa baza danych, która obsługuje modele danych dokumentów, grafów i klucz-wartość. Zawartość tej sekcji służy do tworzenia, wykonywania zapytań i zarządzania zasobami dokumentów przy użyciu interfejsu API SQL za pośrednictwem interfejsu API REST.

Czytając ten artykuł, możesz odpowiedzieć na następujące pytania:

  • Jak standardowe metody HTTP działają z zasobami usługi Azure Cosmos DB?
  • Jak mogę utworzyć nowy zasób przy użyciu funkcji POST?
  • Jak mogę zarejestrować procedurę składowaną przy użyciu funkcji POST?
  • Jak usługa Azure Cosmos DB obsługuje kontrolę współbieżności?
  • Jakie są opcje łączności dla protokołów HTTPS i TCP?

Jeśli szukasz informacji na temat wykonywania operacji CRUD na określonych zasobach przy użyciu interfejsu REST, zobacz Typowe zadania korzystające z interfejsu API REST usługi Azure Cosmos DB. Jeśli szukasz przykładów dotyczących wykonywania operacji CRUD przy użyciu języka C# i REST, zobacz przykład REST z platformy .NET w GitHub.

Uwaga

Operacje CRUD można również wykonywać na zasobach bazy danych Cosmos przy użyciu zestawów SDK Cosmos DB. Przykłady można znaleźć w temacie Przykłady usługi Azure Cosmos DB. Aby uzyskać linki do pobierania i dokumentacji zestawu SDK, zobacz zestawy SDK Cosmos DB.

Omówienie czasowników HTTP

Zasoby usługi Azure Cosmos DB obsługują następujące czasowniki HTTP ze standardową interpretacją:

  1. POST oznacza utworzenie nowego zasobu elementu.
  2. GET oznacza odczytywanie istniejącego elementu lub zasobu kanału informacyjnego
  3. PUT oznacza zastąpienie istniejącego zasobu elementu
  4. DELETE oznacza usunięcie istniejącego zasobu elementu
  5. HEAD oznacza, że polecenie GET usuwa ładunek odpowiedzi (czyli tylko nagłówki)

Jak pokazano na poniższym diagramie czasowników HTTP, post można wystawiać tylko względem zasobu kanału informacyjnego; PUT i DELETE można wystawiać tylko względem zasobu elementu; Polecenie GET i HEAD można wystawiać względem zasobów źródła danych lub elementów.

Interaction model using the standard HTTP methods

Model interakcji przy użyciu standardowych metod HTTP

Tworzenie nowego zasobu przy użyciu metody HTTP POST

Aby lepiej poznać model interakcji, rozważmy utworzenie nowego zasobu (aka INSERT). Aby utworzyć nowy zasób, musisz wydać żądanie HTTP POST z treścią żądania zawierającą reprezentację zasobu względem identyfikatora URI źródła danych kontenera, do którego należy zasób. Jedyną wymaganą właściwością żądania jest identyfikator zasobu.

Na przykład w celu utworzenia nowej bazy danych należy opublikować zasób bazy danych (ustawiając właściwość ID o unikatowej nazwie) względem /dbs. Podobnie, aby utworzyć nową kolekcję, publikujesz zasób kolekcji względem /dbs/_rid/colls/ itd. Odpowiedź zawiera w pełni zatwierdzony zasób z wygenerowanymi przez system właściwościami, w tym linkiem _self zasobu, za pomocą którego można przejść do innych zasobów. Jako przykład prostego modelu interakcji opartego na protokole HTTP klient może wysłać żądanie HTTP, aby utworzyć nową bazę danych na koncie.

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

Na przykład w celu utworzenia nowej bazy danych zasób POST bazy danych (ustawiając właściwość ID o unikatowej nazwie) na /dbswartość . Podobnie w celu utworzenia nowej kolekcji zasób kolekcji jest POST przeciwny /dbs/_rid/colls/ i tak dalej. Odpowiedź zawiera w pełni zatwierdzony zasób z wygenerowanymi przez system właściwościami, w tym _self linkiem zasobu, za pomocą którego można przechodzić do innych zasobów. Jako przykład prostego modelu interakcji opartego na protokole HTTP klient może wysłać żądanie HTTP, aby utworzyć nową bazę danych na koncie.

Usługa Azure Cosmos DB odpowiada z pomyślną odpowiedzią i kodem stanu wskazującym pomyślne utworzenie bazy danych.

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

Rejestrowanie procedury składowanej przy użyciu metody HTTP POST

Innym przykładem tworzenia i wykonywania zasobu jest prosta procedura składowana "HelloWorld" napisana całkowicie w języku JavaScript.

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

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

Procedurę składowaną można zarejestrować w kolekcji w obszarze MyDb, wydając post względem /dbs/_rid-db/colls/_rid-coll/sprocselementu .

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

Usługa Azure Cosmos DB odpowiada z pomyślną odpowiedzią i kodem stanu wskazującym pomyślną rejestrację procedury składowanej.

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

Wykonywanie procedury składowanej przy użyciu metody HTTP POST

Na koniec, aby wykonać procedurę składowaną w poprzednim przykładzie, należy wydać identyfikator POST URI zasobu procedury składowanej (/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/), jak pokazano poniżej.

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

Usługa Azure Cosmos DB odpowiada następującą odpowiedzią.

HTTP/1.1 200 OK  
  
"Hello World"  

Należy pamiętać, że czasownik POST HTTP jest używany do tworzenia nowego zasobu, do wykonywania procedury składowanej i do wystawiania zapytania SQL. Aby zilustrować wykonanie zapytania SQL, rozważ następujące kwestie.

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

Usługa odpowiada z wynikami zapytania 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} 

Używanie czasowników HTTP PUT, GET i DELETE

Zastępowanie lub odczytywanie kwoty zasobów do wystawiania PUT (z prawidłową treścią żądania) i czasowników GET względem linku _self zasobu odpowiednio. Podobnie usunięcie zasobu powoduje wystawienie DELETE czasownika względem łącza _self zasobu. Warto zwrócić uwagę, że hierarchiczna organizacja zasobów w modelu zasobów usługi Azure Cosmos DB wymaga obsługi kaskadowych usuwania, w których usunięcie zasobu właściciela powoduje usunięcie zasobów zależnych. Zasoby zależne mogą być dystrybuowane między inne węzły niż zasoby właściciela, więc usunięcie może się zdarzyć leniwie. Niezależnie od mechaniki odzyskiwania pamięci, po usunięciu zasobu przydział jest natychmiast zwalniany i jest dostępny do użycia. Należy pamiętać, że integralność referencyjna jest zachowywana przez system. Na przykład nie można wstawić kolekcji do bazy danych, która została usunięta lub zamieniona lub wykonać zapytanie o dokument kolekcji, która już nie istnieje.

Wystawianie pod GET kątem kanału informacyjnego zasobów lub wykonywanie zapytań dotyczących kolekcji może spowodować potencjalnie miliony elementów, co czyni je niepraktyczne dla obu serwerów w celu zmaterializowania ich i klientów do korzystania z nich w ramach pojedynczej wymiany żądań/ żądań i odpowiedzi. Aby rozwiązać ten problem, usługa Azure Cosmos DB umożliwia klientom stronicowanie dużej strony kanału informacyjnego naraz. Klienci mogą używać nagłówka odpowiedzi [x-ms-continuation] jako kursora, aby przejść do następnej strony.

Optymistyczna kontrola współbieżności

Większość aplikacji internetowych polega na kontrolce optymistycznej współbieżności opartej na tagach jednostek, aby uniknąć niesławnych problemów z "utraconymi aktualizacjami" i "Lost Delete". Tag jednostki jest przyjazny dla protokołu HTTP, logiczny znacznik czasu skojarzony z zasobem. Cosmos DB natywnie obsługuje optymistyczną kontrolę współbieżności, zapewniając, że każda odpowiedź HTTP zawiera wersję (trwałość) skojarzoną z określonym zasobem. Konflikty kontroli współbieżności są poprawnie wykrywane w następujących przypadkach:

  1. Jeśli dwóch klientów jednocześnie wystawia żądaniamutowania (za pośrednictwem czasowników PUT/DELETE) w zasobie z najnowszą wersją zasobu (określoną za pośrednictwem nagłówka żądania [if-match], aparat bazy danych bazy danych Cosmos podda je kontrolce współbieżności transakcyjnej.

  2. Jeśli klient przedstawia starszą wersję zasobu (określoną za pośrednictwem nagłówka żądania [if-match], jego żądanie zostanie odrzucone.

Opcje łączności

Cosmos DB uwidacznia model adresowania logicznego, w którym każdy zasób ma logiczny i stabilny identyfikator URI zidentyfikowany przez łącze _self. Jako rozproszony system magazynowania w różnych regionach zasoby w ramach różnych kont baz danych w usłudze Cosmos DB są partycjonowane na wielu maszynach, a każda partycja jest replikowana w celu zapewnienia wysokiej dostępności. Repliki zarządzające zasobami danej partycji rejestrują adresy fizyczne. Podczas gdy adresy fizyczne zmieniają się w czasie z powodu awarii, ich adresy logiczne pozostają stabilne i stałe. Tłumaczenie logiczne na adres fizyczny jest przechowywane w tabeli routingu, która jest również wewnętrznie dostępna jako zasób. Cosmos DB uwidacznia dwa tryby łączności:

  • Tryb bramy: Klienci są chronini przed tłumaczeniem między adresami logicznymi a fizycznymi lub szczegółami routingu; po prostu zajmują się logicznymi identyfikatorami URI i resTfully nawigują po modelu zasobów. Klienci wystawiają żądania przy użyciu logicznego identyfikatora URI i maszyn brzegowych tłumaczą logiczny identyfikator URI na fizyczny adres repliki, która zarządza zasobem i przekazuje żądanie. Dzięki buforowaniu maszyn brzegowych (i okresowe odświeżanie) tabela routingu jest niezwykle wydajna.

  • Tryb bezpośredniej łączności: Klienci bezpośrednio zarządzają tabelą routingu w przestrzeni procesów i okresowo je odświeżają. Klient może bezpośrednio łączyć się z replikami i pomijać maszyny brzegowe.

Tryb łączności Protokół Szczegóły Zestawy SDK usługi Azure Cosmos DB
Brama HTTPS Aplikacje łączą się bezpośrednio z węzłami brzegowymi przy użyciu logicznych identyfikatorów URI. Powoduje to dodatkowy przeskok sieciowy. Interfejs API REST, .NET, Node.js, Java, Python, JavaScript
Bezpośrednia łączność HTTPS i TCP Aplikacje mogą bezpośrednio uzyskiwać dostęp do tabeli routingu i wykonywać routing po stronie klienta, aby bezpośrednio łączyć się z replikami. .NET, Java

Zobacz też