REST API (np. dla Azure SQL)

REST API dla Azure SQL umożliwia zarządzanie zasobami bazy danych bez korzystania z konsoli administracyjnej.

REST API a zarządzanie zasobami Azure SQL

REST API dla Azure SQL jest interfejsem HTTP służącym przede wszystkim do zarządzania zasobami usługi w chmurze Microsoft Azure. Operacje są wykonywane przez Azure Resource Manager, czyli warstwę zarządzania zasobami platformy Azure. Dzięki temu można programowo tworzyć, odczytywać, modyfikować i usuwać między innymi serwery logiczne Azure SQL, bazy danych, pule elastyczne oraz wybrane ustawienia tych zasobów. REST API pozwala zastąpić ręczne działania w Azure Portal albo polecenia wydawane w konsoli administracyjnej.

Każdy zasób jest identyfikowany przez pełny identyfikator zasobu Azure, obejmujący identyfikator subskrypcji, grupę zasobów, dostawcę Microsoft.Sql, typ zasobu i jego nazwę. Typowy adres ma postać https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/databases/{databaseName}?api-version={apiVersion}. Parametr api-version wskazuje wersję kontraktu API, dlatego powinien być dobierany zgodnie z dokumentacją konkretnej operacji, a nie zmieniany przypadkowo.

Warstwa zarządzania i warstwa danych

Ważne jest rozróżnienie między wywołaniem REST API Azure SQL a wykonywaniem zapytań SQL wewnątrz bazy. Interfejs zarządzania Azure Resource Manager działa w płaszczyźnie kontroli i służy do obsługi konfiguracji oraz cyklu życia zasobów. Samo utworzenie bazy, zmiana jej parametrów lub pobranie informacji o stanie nie oznacza wykonania zapytania SELECT na tabelach. Dane przechowywane w bazie należą do płaszczyzny danych i są obsługiwane przez protokoły oraz narzędzia przeznaczone do komunikacji z silnikiem SQL.

Żądanie REST może na przykład pobrać właściwości bazy danych, takie jak jej nazwa, stan, poziom usługi, model cenowy lub konfiguracja kopii zapasowych, o ile dana właściwość jest dostępna w określonej wersji API. Do zmiany zasobu zwykle używa się metod HTTP takich jak GET, PUT, PATCH i DELETE. Metoda PUT może służyć do utworzenia albo pełnego zdefiniowania zasobu, natomiast PATCH jest używana do częściowej aktualizacji właściwości. Zakres obsługiwanych pól zależy od typu zasobu i wersji interfejsu.

Autoryzacja, żądanie i odpowiedź

Do wywołania interfejsu zarządzania potrzebny jest token dostępu OAuth 2.0 wydany dla platformy Microsoft identity. Token przekazuje się w nagłówku Authorization jako schemat Bearer. Tożsamość wykonująca operację musi mieć odpowiednie uprawnienia kontroli dostępu opartej na rolach Azure, czyli Azure RBAC, w zakresie subskrypcji, grupy zasobów albo konkretnego zasobu. Sam token nie gwarantuje dostępu do każdego serwera lub każdej bazy, ponieważ wynik zależy również od przypisanej roli i jej zakresu.

Żądania najczęściej używają nagłówka Content-Type: application/json, a dane wejściowe przekazywane przy tworzeniu lub aktualizacji zasobu mają strukturę JSON. Odpowiedź zawiera kod statusu HTTP oraz, zależnie od operacji, obiekt opisujący zasób albo szczegóły błędu. Kod 200 oznacza pomyślne wykonanie żądania, 201 wskazuje na utworzenie zasobu, a 202 informuje, że operacja została przyjęta do wykonania asynchronicznego. W przypadku odpowiedzi 202 klient powinien odczytać wskazany adres monitorowania i sprawdzać stan operacji, zamiast zakładać, że zmiana została już zakończona.

Kontrola operacji i diagnostyka połączenia

Automatyzacja oparta na REST API wymaga poprawnego złożenia kilku niezależnych elementów: adresu endpointu, identyfikatora subskrypcji, nazwy grupy zasobów, nazwy serwera logicznego, nazwy bazy, wersji API, tokenu oraz treści JSON. Błąd w jednym z tych pól może powodować odpowiedź 400 Bad Request, 401 Unauthorized albo 403 Forbidden. Kod 401 zwykle wskazuje na brak tokenu, jego wygaśnięcie lub nieprawidłowy zakres, natomiast 403 oznacza brak wymaganych uprawnień do wskazanego zakresu zasobu.

Podczas analizy problemu należy rozdzielić błąd warstwy zarządzania od błędu połączenia z samym silnikiem SQL. Nieprawidłowy identyfikator zasobu lub brak roli Azure RBAC może uniemożliwić zmianę konfiguracji, ale nie musi oznaczać awarii bazy. Z kolei niedostępność portu, błędny adres serwera logicznego, reguły zapory albo niepoprawne dane uwierzytelniające dla połączenia z bazą dotyczą innej ścieżki komunikacji niż wywołanie REST do management.azure.com. Przy diagnostyce warto zapisać metodę HTTP, pełny typ zasobu bez sekretów, używaną wersję API, kod odpowiedzi oraz identyfikator korelacyjny zwrócony przez usługę. Azure SQL w zastosowaniach administracyjnych wymaga więc sprawdzenia zarówno poprawności żądania REST, jak i uprawnień oraz dostępności samego zasobu.