Używanie sesji dynamicznych w Azure Container Apps

Azure Container Apps oferuje dynamiczne sesje, które zapewniają izolowane, bezpieczne konteksty, gdy konieczne jest uruchamianie kodu lub aplikacji oddzielnie od innych obciążeń. Sesje działają wewnątrz puli sesji, która zapewnia natychmiastowy dostęp do nowych i istniejących sesji. Te sesje są idealne w scenariuszach, w których dane wejściowe generowane przez użytkownika muszą być przetwarzane w kontrolowany sposób lub podczas integrowania usług innych firm, które wymagają wykonywania kodu w izolowanym środowisku. Nie musisz wdrażać zasobu aplikacji kontenera w celu korzystania z sesji dynamicznych, tworzenia puli sesji i wywoływania interfejsu API zarządzania.

W tym artykule pokazano, jak zarządzać sesjami dynamicznymi i korzystać z nich.

Punkt końcowy zarządzania i routing

Aplikacja wchodzi w interakcję z sesją przy użyciu interfejsu API do zarządzania pulą sesji. Aby zapoznać się z koncepcyjnym omówieniem sposobu kierowania żądań, zobacz Kluczowe pojęcia.

Aby uzyskać punkt końcowy zarządzania pulą sesji, zobacz Punkt końcowy zarządzania pulami sesji.

https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io

Aby uzyskać więcej informacji na temat zarządzania pulami sesji, zobacz Punkt końcowy zarządzania pulami sesji.

Uwierzytelnianie i autoryzacja interfejsu API zarządzania

Wszystkie żądania do interfejsu API zarządzania pulą sesji wymagają uwierzytelniania (AuthN) z użyciem tokenu Microsoft Entra oraz autoryzacji (AuthZ) poprzez rolę „Azure ContainerApps Session Executor” w puli sesji. Aby uzyskać szczegółowe informacje i przykłady, zobacz Uwierzytelnianie i autoryzacja.

Wysyłanie żądań do sesji

Aby wysłać żądanie do kontenera sesji, należy użyć punktu końcowego zarządzania jako punktu startowego dla żądania. Cokolwiek w ścieżce po punkcie końcowym zarządzania pulą bazową jest przekazywane do kontenera sesji.

Jeśli na przykład wykonasz wywołanie metody <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, żądanie jest kierowane do kontenera sesji na jego porcie docelowym pod adresem <TARGET_PORT>/api/uploadfile.

Przykładowe żądanie

W poniższym przykładzie pokazano, jak wysłać żądanie do sesji przy użyciu identyfikatora użytkownika jako unikatowego identyfikatora sesji.

Przed wysłaniem żądania zastąp symbole zastępcze między <> nawiasami wartościami specyficznymi dla żądania.

POST <POOL_MANAGEMENT_ENDPOINT>/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

To żądanie jest przekazywane do kontenera w sesji z identyfikatorem użytkownika.

Jeśli dla danego identyfikatora nie istnieje żadna sesja, Azure Container Apps automatycznie przydziela jedną z puli przed przekazaniem żądania.

W tym przykładzie kontener sesji odbiera żądanie na porcie docelowym pod adresem <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Identyfikatory

Aby wysłać żądanie HTTP do sesji, musisz podać identyfikator sesji w żądaniu. Identyfikator sesji jest przekazywany w parametrze ciągu zapytania o nazwie identifier w adresie URL podczas wysyłania żądania do sesji.

  • Jeśli sesja z identyfikatorem już istnieje, żądanie zostanie wysłane do istniejącej sesji.

  • Jeśli sesja z identyfikatorem nie istnieje, nowa sesja zostanie automatycznie przydzielona przed wysłaniem żądania.

Na poniższym diagramie pokazano, jak pula sesji kieruje żądania do istniejących sesji lub przydziela nową sesję w razie potrzeby.

Diagram przedstawiający pulę sesji, która kieruje żądania do istniejących sesji lub tworzy nowe sesje na podstawie identyfikatora.

Format identyfikatora

Identyfikator sesji jest ciągiem swobodnym, co oznacza, że można go zdefiniować w dowolny sposób, który odpowiada potrzebom aplikacji.

Identyfikator sesji jest ciągiem zdefiniowanym, który jest unikatowy w puli sesji. Jeśli tworzysz aplikację internetową, możesz użyć identyfikatora użytkownika jako identyfikatora sesji. Jeśli tworzysz czatbota, możesz użyć identyfikatora konwersacji.

Identyfikator musi być ciągiem o długości od 4 do 128 znaków i może zawierać tylko znaki alfanumeryczne i znaki specjalne z tej listy: |, -&^%$#(){}[];, <i .>

Pobieranie informacji o sesji

Możesz wysłać zapytanie do puli sesji, aby sprawdzić stan sesji, uzyskać szczegóły wygaśnięcia i wyświetlić listę wszystkich aktywnych sesji. Ta możliwość jest przydatna do monitorowania kondycji sesji, śledzenia użycia zasobów i implementowania niestandardowych procesów czyszczenia.

Otrzymaj pojedynczą sesję

Aby pobrać szczegółowe informacje o określonej sesji, użyj punktu końcowego getSession :

POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/.management/getSession?identifier=<SESSION_ID>&api-version=2024-02-02-preview
Authorization: Bearer <TOKEN>

Punkt getSession końcowy zwraca metadane sesji, w tym identyfikator sesji, bieżący czas wygaśnięcia i znacznik czasu tworzenia.

Schemat odpowiedzi SessionView

Pole Typ Wymagane Opis
identifier ciąg Yes Podany identyfikator sesji
etag ciąg Yes Nieprzejrzysty identyfikator wersji dla sesji. Tego identyfikatora można użyć do wykrywania zmian.
expiresAt Data i czas Yes Sygnatura czasowa UTC, kiedy sesja zostanie zakończona
createdAt Data i czas Nie. Sygnatura czasowa tworzenia sesji
lastAccessedAt Data i czas Nie. Sygnatura czasowa ostatniego żądania w tej sesji

Przykładowe żądanie i odpowiedź

curl -X POST "https://my-pool.env-id.westus2.azurecontainerapps.io/.management/getSession?identifier=user-123&api-version=2024-02-02-preview" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź pomyślna (HTTP 200):

{
  "identifier": "user-123",
  "etag": "a1b2c3d4",
  "expiresAt": "2026-04-30T14:30:00Z",
  "createdAt": "2026-04-30T13:30:00Z",
  "lastAccessedAt": "2026-04-30T14:29:00Z"
}

Wymień wszystkie sesje w puli

Aby pobrać listę wszystkich sesji w puli sesji, użyj punktu końcowego listSessions :

POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/.management/listSessions?skip=0&api-version=2024-02-02-preview
Authorization: Bearer <TOKEN>

Paginacja

Punkt końcowy listy obsługuje stronicowanie oparte na pomijaniu. Domyślnie każda strona zwraca maksymalnie 300 sesji. Użyj parametru skip zapytania, aby nawigować po wynikach.

Parametr Opis
skip Liczba sesji do pominięcia od początku (wartość domyślna: 0)
nextLink Pełny adres URL następnej strony wyników (uwzględniony w odpowiedzi, gdy istnieje więcej wyników)

Schemat odpowiedzi ApiCollectionEnvelope

Pole Typ Opis
value SessionView[] Tablica obiektów sesji
count liczba całkowita Liczba sesji na bieżącej stronie
nextLink ciąg Adres URL następnej strony (wartość null, jeśli nie ma więcej wyników)

Przykładowa pętla stronicowania

POOL_URL="https://my-pool.env-id.westus2.azurecontainerapps.io"
next_url="$POOL_URL/.management/listSessions?skip=0&api-version=2024-02-02-preview"

while [ -n "$next_url" ]; do
  response=$(curl -s -X POST "$next_url" \
    -H "Authorization: Bearer $TOKEN")

  echo "$response" | jq '.value[] | {identifier, expiresAt}'

  next_url=$(echo "$response" | jq -r '.nextLink // empty')
done

Przykładowa odpowiedź (HTTP 200):

{
  "value": [
    {
      "identifier": "user-123",
      "etag": "a1b2c3d4",
      "expiresAt": "2026-04-30T14:30:00Z"
    },
    {
      "identifier": "user-456",
      "etag": "e5f6a7b8",
      "expiresAt": "2026-04-30T14:31:00Z"
    }
  ],
  "count": 2,
  "nextLink": "https://my-pool.env-id.westus2.azurecontainerapps.io/.management/listSessions?skip=300"
}

Odpowiedzi na błędy

W przypadku wystąpienia błędu interfejs API zwraca ustrukturyzowaną odpowiedź o błędzie ze szczegółami, aby ułatwić diagnozowanie problemu.

{
  "error": {
    "code": "ErrorCode",
    "message": "Human-readable error description",
    "details": "Optional additional context",
    "target": "Field or parameter that caused the error",
    "traceId": "Request trace ID for debugging"
  }
}

Typowe kody błędów

Kod błędu Stan HTTP Opis Resolution
SessionWithIdentifierNotFound 400 Identyfikator sesji nie istnieje w tej puli sesji Sprawdź, czy identyfikator sesji jest poprawny, a sesja nie wygasła
SessionRequestValidationFailed 400 Brak wymaganych pól żądania lub ma nieprawidłowe parametry Sprawdź, czy parametry zapytania (identyfikator, pomiń, wersja interfejsu API) są prawidłowo sformatowane
SessionRequestNotSupported 400 Typ żądania nie jest rozpoznawany przez interfejs API Sprawdź, czy używasz obsługiwanego punktu końcowego i metody
InternalServerError 500 Wystąpił nieoczekiwany błąd po stronie serwera Spróbuj ponownie wysłać żądanie; jeśli błąd będzie się powtarzać, sprawdź identyfikator śladu w dziennikach.

Cykl życia sesji w praktyce

W miarę kontynuowania podejmowania wywołań do tej samej sesji sesja pozostaje przydzielona w puli. Gdy nie ma żadnych żądań do sesji po upływie okresu ochładzania, sesja zostanie automatycznie zniszczona.

Uwaga / Notatka

W rzadkich przypadkach, gdy żądanie rozszerzenia czasu wygaśnięcia w tle sesji zakończy się niepowodzeniem (na przykład jeśli kontener zostanie nieoczekiwanie wyjęty), sesja zostanie automatycznie usunięta z puli. W następnym żądaniu do tej sesji zostanie wyświetlony błąd "Nie znaleziono sesji". To oczyszczanie jest automatyczne i nie wymaga żadnej akcji ze swojej strony.

Zabezpieczenia

Model zabezpieczeń

Sesje dynamiczne są tworzone w celu uruchamiania niezaufanego kodu i aplikacji w bezpiecznym i izolowanym środowisku. Podczas gdy sesje są odizolowane od siebie, wszystkie elementy w ramach jednej sesji, w tym pliki i zmienne środowiskowe, są dostępne dla użytkowników sesji.

Skonfiguruj lub przekaż poufne dane do sesji tylko wtedy, gdy ufasz użytkownikom sesji.

Dostęp do sieci

Domyślnie sesje nie mogą wysyłać wychodzących żądań sieciowych. Dostęp sieciowy można kontrolować, konfigurując ustawienia stanu sieci w puli sesji.

Najlepsze rozwiązania

  • Bezpieczne identyfikatory: używaj identyfikatorów bezpiecznej sesji przez cały czas. Generowanie identyfikatorów sesji przy użyciu metod kryptograficznych w celu zapewnienia unikatowych i nieprzewidywalnych wartości. Unikaj używania identyfikatorów sekwencyjnych, które mogą być zgadywane przez osobę atakującą.
  • Użyj protokołu HTTPS: zawsze używaj protokołu HTTPS do szyfrowania danych przesyłanych. Chroni to identyfikatory sesji i wszelkie poufne dane wymieniane między klientem a serwerem przed przechwyceniem.
  • Ogranicz okres istnienia sesji: zaimplementuj limity czasu dla sesji. Na przykład poczekaj maksymalnie 15 minut braku aktywności, zanim sesja zostanie automatycznie zakończona. Pomaga to ograniczyć ryzyko spowodowane utratą lub nienadzorowanym urządzeniem.
  • Ogranicz widoczność sesji: ustaw ścisłe mechanizmy kontroli dostępu, aby upewnić się, że identyfikatory sesji są widoczne tylko dla puli sesji. Unikaj uwidaczniania identyfikatorów sesji w adresach URL lub dziennikach.
  • Regularnie wymieniaj poświadczenia sesji: okresowo przeglądaj i aktualizuj poświadczenia skojarzone z sesjami. Rotacja zmniejsza ryzyko nieautoryzowanego dostępu.

Dodatkowe wskazówki techniczne dotyczące niestandardowych sesji kontenerów

  • Korzystanie z bezpiecznych protokołów transmisji: zawsze używaj protokołu HTTPS do szyfrowania danych przesyłanych, w tym identyfikatorów sesji. Takie podejście chroni przed atakami typu man-in-the-middle.

  • Monitorowanie aktywności sesji: implementowanie rejestrowania i monitorowania w celu śledzenia działań sesji. Użyj tych dzienników, aby zidentyfikować nietypowe wzorce lub potencjalne naruszenia zabezpieczeń.

  • Weryfikowanie danych wejściowych użytkownika: traktuj wszystkie dane wejściowe użytkownika jako niebezpieczne. Użyj technik walidacji danych wejściowych i sanitarnych, aby chronić przed atakami polegającymi na wstrzyknięciu i zapewnić przetwarzanie tylko zaufanych danych.

Uwierzytelnianie i autoryzacja

Podczas wysyłania żądań do sesji przy użyciu interfejsu API zarządzania pulą uwierzytelnianie jest obsługiwane przy użyciu tokenów Microsoft Entra. Tylko tokeny Microsoft Entra z tożsamości należącej do roli Azure ContainerApps Session Executor na puli sesji są autoryzowane do wywoływania interfejsu API zarządzania pulą.

Aby przypisać rolę do tożsamości, użyj następującego polecenia Azure CLI:

az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <PRINCIPAL_ID> \
    --scope <SESSION_POOL_RESOURCE_ID>

Jeśli używasz integracji z dużym modelem językowym (LLM), platforma obsługuje generowanie tokenów i zarządzanie nimi. Upewnij się, że aplikacja jest skonfigurowana przy użyciu tożsamości zarządzanej z niezbędnymi przypisaniami ról w puli sesji.

Jeśli bezpośrednio korzystasz z punktów końcowych interfejsu API zarządzania puli zasobów, musisz wygenerować token i dołączyć go do nagłówka Authorization w żądaniach HTTP. Oprócz wymienionych wcześniej przypisań ról token musi zawierać oświadczenie odbiorców (aud) o wartości https://dynamicsessions.io.

Aby wygenerować token przy użyciu Azure CLI, uruchom następujące polecenie:

az account get-access-token --resource https://dynamicsessions.io

Ważne

Prawidłowy token służy do tworzenia i uzyskiwania dostępu do dowolnej sesji w puli. Zachowaj bezpieczeństwo tokenów i nie udostępniaj ich niezaufanym stronom. Użytkownicy końcowi nigdy nie powinni mieć bezpośredniego dostępu do tokenów. Udostępniaj tylko tokeny aplikacji i nigdy nie użytkownikom końcowym.

Ochrona identyfikatorów sesji

Identyfikator sesji jest poufnymi informacjami, którymi musisz zarządzać bezpiecznie. Aplikacja musi zapewnić, że każdy użytkownik lub podmiot ma dostęp tylko do własnych sesji.

Konkretne strategie, które uniemożliwiają nieprawidłowe użycie identyfikatorów sesji, różnią się w zależności od projektu i architektury aplikacji. Jednak aplikacja musi zawsze mieć pełną kontrolę nad tworzeniem i używaniem identyfikatorów sesji, aby złośliwy użytkownik nie mógł uzyskać dostępu do sesji innego użytkownika.

Przykładowe strategie obejmują:

  • Jedna sesja na użytkownika: jeśli aplikacja używa jednej sesji na użytkownika, każdy użytkownik musi być bezpiecznie uwierzytelniony, a aplikacja musi używać unikatowego identyfikatora sesji dla każdego zalogowanego użytkownika.

  • Jedna sesja na konwersację agenta: jeśli aplikacja używa jednej sesji na konwersację agenta sztucznej inteligencji, upewnij się, że aplikacja używa unikatowego identyfikatora sesji dla każdej konwersacji, której nie można modyfikować przez użytkownika końcowego.

Ważne

Brak bezpiecznego dostępu do sesji może spowodować nieprawidłowe użycie lub nieautoryzowany dostęp do danych przechowywanych w sesjach użytkowników.

Korzystanie z tożsamości zarządzanej

Tożsamość zarządzana z Microsoft Entra ID umożliwia pulom sesji kontenerów i ich sesjom dostęp do zasobów chronionych przez Microsoft Entra. Tożsamości zarządzane przypisane przez system i przypisane przez użytkownika są obsługiwane w puli sesji.

Aby uzyskać więcej informacji na temat tożsamości zarządzanych w Microsoft Entra ID, zobacz Zarządzane tożsamości dla zasobów Azure.

Istnieją dwa sposoby używania tożsamości zarządzanych z niestandardowymi pulami sesji kontenerów:

  • Uwierzytelnianie ściągania obrazu: użyj tożsamości zarządzanej, aby uwierzytelnić się w rejestrze kontenerów, aby ściągnąć obraz kontenera.

  • Dostęp do zasobów: Skorzystaj z zarządzanej tożsamości puli sesji, aby uzyskać dostęp do innych zasobów chronionych przez Microsoft Entra. Ze względu na jego implikacje dotyczące zabezpieczeń ta funkcja jest domyślnie wyłączona.

    Ważne

    Jeśli włączysz dostęp do tożsamości zarządzanej w sesji, każdy kod lub programy uruchamiane w tej sesji mogą tworzyć tokeny Microsoft Entra dla tożsamości zarządzanej puli. Ponieważ sesje zwykle uruchamiają niezaufany kod, należy użyć tej funkcji z wyjątkową ostrożnością.

Aby włączyć tożsamość zarządzaną dla niestandardowej puli sesji kontenera, użyj Azure Resource Manager.

Przemysł drzewny

Azure Container Apps dynamiczne sesje integrują się z Azure Monitor i Log Analytics w celu zbierania dzienników generowanych podczas sesji. Kroki konfiguracji są takie same w przypadku interpretera kodu i niestandardowych pul sesji kontenera, ale dostępne kategorie dzienników różnią się od typu sesji. Metryki zwracane za pośrednictwem nagłówków odpowiedzi interfejsu API nie są zapisywane w Log Analytics.

Rejestrowanie różnic według typu sesji

Skorzystaj z poniższych wskazówek, aby porównać zachowanie rejestrowania i przejść do szczegółów pasujących do typu sesji:

  • Sesje interpretatora kodu: Wyniki są zwracane z procesu wykonania (w tym stdout i stderr), ale tabele Log Analytics AppEnvSession nie są wygenerowane. Zobacz Rejestrowanie sesji interpretera kodu.
  • Niestandardowe sesje kontenerów: Tabele Log Analytics AppEnvSession są generowane, gdy kontener zapisuje w stdout lub stderr, a logi platformy są dostępne dla cyklu życia i zdarzeń puli. Zobacz Rejestrowanie niestandardowych sesji kontenera.
  • Common: Metryki zwracane za pośrednictwem nagłówków odpowiedzi interfejsu API nie są zapisywane w Log Analytics.

Aby uzyskać pełną listę obsługiwanych kategorii sesji w zasobie środowiska (Microsoft.App/managedEnvironments), zobacz Obsługiwane dzienniki dla Microsoft. App/managedEnvironments.

Treści powiązane

  • Last updated on