Funkcje specyficzne dla bazy danych dla konstruktora interfejsu API danych

Artykuł
04/13/2024

Konstruktor interfejsu API danych umożliwia każdej bazie danych posiadanie własnych określonych funkcji. Ten artykuł zawiera szczegółowe informacje o funkcjach obsługiwanych dla każdej bazy danych.

Obsługa wersji bazy danych

Wiele tradycyjnych baz danych wymaga minimalnej wersji zgodnej z konstruktorem interfejsu API danych (DAB).

	Minimalna obsługiwana wersja
SQL Server	2016
MySQL	8
PostgreSQL	11

Z drugiej strony usługi bazy danych w chmurze platformy Azure działają z bazą danych DAB bez konieczności używania określonej wersji.

	Minimalna obsługiwana wersja
Azure SQL	n/d
Azure Cosmos DB for NoSQL	n/d
Azure Cosmos DB for PostgreSQL	n/d

Azure SQL i SQL Server

Istnieje kilka specyficznych właściwości, które są unikatowe dla języka SQL, w tym zarówno Azure SQL, jak i SQL Server.

SESSION_CONTEXT

Azure SQL i SQL Server obsługują korzystanie z SESSION_CONTEXT funkcji w celu uzyskania dostępu do tożsamości bieżącego użytkownika. Ta funkcja jest przydatna, gdy chcesz zastosować natywną obsługę zabezpieczeń na poziomie wiersza dostępnych w Azure SQL i SQL Server.

W przypadku Azure SQL i SQL Server konstruktor interfejsu API danych może wykorzystać możliwość SESSION_CONTEXT wysyłania metadanych określonych przez użytkownika do bazowej bazy danych. Takie metadane są dostępne dla konstruktora interfejsu API danych z powodu oświadczeń znajdujących się w tokenie dostępu. Następnie dane wysyłane do bazy danych mogą służyć do konfigurowania dodatkowego poziomu zabezpieczeń (na przykład przez skonfigurowanie zasad zabezpieczeń), aby dodatkowo uniemożliwić dostęp do danych w operacjach, takich jak SELECT, UPDATE, DELETE. Dane SESSION_CONTEXT są dostępne dla bazy danych podczas połączenia z bazą danych do momentu zamknięcia tego połączenia. Te same dane mogą być również używane w procedurze składowanej.

Aby uzyskać więcej informacji na temat ustawiania SESSION_CONTEXT danych, zobacz sp_set_session_context (Transact-SQL).

Skonfiguruj SESSION_CONTEXT przy użyciu options właściwości data-source sekcji w pliku konfiguracji. Aby uzyskać więcej informacji, zobacz data-source dokumentację konfiguracji.

{
  ...
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": true
    },
    "connection-string": "<connection-string>"
  },
  ...
}

Alternatywnie użyj argumentu --set-session-context z poleceniem dab init .

dab init --database-type mssql --set-session-context true

Wszystkie oświadczenia obecne w tokenie EasyAuth/JWT są wysyłane za pośrednictwem SESSION_CONTEXT obiektu do bazowej bazy danych. Wszystkie oświadczenia obecne w tokenie są tłumaczone na pary klucz-wartość przekazywane za pośrednictwem SESSION_CONTEXT zapytania. Te oświadczenia obejmują, ale nie są ograniczone do:

	Opis
`aud`	Grupy odbiorców
`iss`	Wystawca
`iat`	Wystawiony pod adresem
`exp`	Czas wygaśnięcia
`azp`	Identyfikator aplikacji
`azpacr`	Metoda uwierzytelniania klienta
`name`	Temat
`uti`	Unikatowy identyfikator tokenu

Aby uzyskać więcej informacji na temat oświadczeń, zobacz Tożsamość Microsoft Entra dokumentacja oświadczeń tokenu dostępu.

Te oświadczenia są tłumaczone na zapytanie SQL. W tym przykładzie obciętym pokazano, jak sp_set_session_context jest używany w tym kontekście:

EXEC sp_set_session_context 'aud', '<AudienceID>', @read_only = 1;
EXEC sp_set_session_context 'iss', 'https://login.microsoftonline.com/<TenantID>/v2.0', @read_only = 1;
EXEC sp_set_session_context 'iat', '1637043209', @read_only = 1;
...
EXEC sp_set_session_context 'azp', 'a903e2e6-fd13-4502-8cae-9e09f86b7a6c', @read_only = 1;
EXEC sp_set_session_context 'azpacr', 1, @read_only = 1;
..
EXEC sp_set_session_context 'uti', '_sSP3AwBY0SucuqqJyjEAA', @read_only = 1;
EXEC sp_set_session_context 'ver', '2.0', @read_only = 1;

Następnie można zaimplementować zabezpieczenia na poziomie wiersza przy użyciu danych sesji. Aby uzyskać więcej informacji, zobacz implementowanie zabezpieczeń na poziomie wiersza z kontekstem sesji.

Azure Cosmos DB

Istnieje kilka konkretnych właściwości, które są unikatowe dla różnych interfejsów API w usłudze Azure Cosmos DB.

Schemat w interfejsie API dla noSQL

Usługa Azure Cosmos DB for NoSQL jest niezależna od schematu. Aby używać konstruktora interfejsu API danych z interfejsem API dla NoSQL, należy utworzyć plik schematu GraphQL zawierający definicje typów obiektów reprezentujące model danych kontenera. Konstruktor interfejsu API danych oczekuje również, że definicje i pola typu obiektu GraphQL będą zawierać dyrektywę authorize schematu GraphQL, jeśli chcesz wymusić bardziej restrykcyjny dostęp do odczytu niż anonymous.

Na przykład ten plik schematu reprezentuje Book element w kontenerze. Ten element zawiera co najmniej title właściwości i Authors .

type Book @model(name:"Book"){
  id: ID
  title: String @authorize(roles:["metadataviewer","authenticated"])
  Authors: [Author]
}

Ten przykładowy schemat odpowiada następującej konfiguracji jednostki w pliku konfiguracji daB. Aby uzyskać więcej informacji, zobacz entities dokumentację konfiguracji.

{
  ...
  "Book": {
    "source": "Book",
    "permissions": [
      {
        "role": "anonymous",
        "actions": [ "read" ]
      },
      {
        "role": "metadataviewer",
        "actions": [ "read" ]
      }
    ]
  }
  ...
}

Dyrektywa @authorize z roles:["metadataviewer","authenticated"] ograniczeniem dostępu do title pola tylko użytkownikom z rolami metadataviewer i authenticated. W przypadku uwierzytelnionych żądań rola authenticated systemowa jest przypisywana automatycznie, eliminując potrzebę nagłówka X-MS-API-ROLE .

Jeśli uwierzytelnione żądanie musi zostać wykonane w kontekście metadataviewerelementu , powinien być dołączony do nagłówka żądania typu X-MS-API-ROLE ustawionego na metadataviewerwartość . Jeśli jednak wymagany jest dostęp anonimowy, należy pominąć autoryzowaną dyrektywę.

Dyrektywa @model jest używana do ustanowienia korelacji między tym typem obiektu GraphQL i odpowiednią nazwą jednostki w konfiguracji środowiska uruchomieniowego. Dyrektywa jest sformatowana jako: @model(name:"<Entity_Name>")

Bardziej szczegółowo można stosować dyrektywę @authorize w definicji typu najwyższego poziomu. Ta aplikacja ogranicza dostęp do typu i jego pól wyłącznie do ról określonych w dyrektywie.

type Series @model(name:"Series") @authorize(roles:["editor","authenticated"]) {
  id: ID
  title: String
  Books: [Book]
}

{
  "Book": {
    "source": "Series",
    "permissions": [
      {
        "role": "authenticated",
        "actions": [ "read" ]
      },
      {
        "role": "editor",
        "actions": [ "*" ]
      }
    ]
  }
}

Zapytania między kontenerami w interfejsie API dla noSQL

Operacje GraphQL między kontenerami nie są obsługiwane. Aparat odpowiada komunikatem o błędzie z informacją: Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

To ograniczenie można obejść, aktualizując model danych, aby przechowywać jednostki w tym samym kontenerze w formacie osadzonym. Aby uzyskać więcej informacji, zobacz modelowanie danych w usłudze Azure Cosmos DB for NoSQL.

Udostępnij za pośrednictwem