Použití dynamických relací v Azure Container Apps

Azure Container Apps dynamické sessions nabízejí izolované a zabezpečené kontexty, pokud potřebujete spouštět kód nebo aplikace odděleně od jiných úloh. Relace běží uvnitř fondu relací , který poskytuje okamžitý přístup k novým a existujícím relacím. Tyto relace jsou ideální pro scénáře, kdy je potřeba zpracovávat uživatelem generované vstupy řízeným způsobem nebo při integraci služeb třetích stran, které vyžadují spuštění kódu v izolovaném prostředí. Pro použití dynamických relací nemusíte nasazovat aplikaci kontejneru. Stačí vytvořit fond relací a zavolat jeho rozhraní API pro správu.

V tomto článku se dozvíte, jak spravovat dynamické relace a pracovat s nimi.

Koncový bod správy a směrování

Aplikace komunikuje s relací pomocí rozhraní API pro správu fondu relací. Koncepční přehled směrování požadavků najdete v tématu Klíčové koncepty.

Pokud chcete získat koncový bod správy fondu relací, podívejte se na koncový bod správy fondů relací.

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

Další informace o správě fondů relací najdete v tématu Koncový bod správy fondů relací.

Ověřování a autorizace rozhraní API pro správu

Všechny požadavky na rozhraní API pro správu fondu relací vyžadují ověřování (AuthN) s tokenem Microsoft Entra a autorizací (AuthZ) prostřednictvím role Azure ContainerApps Session Executor ve fondu relací. Podrobnosti a příklady najdete v tématu Ověřování a autorizace.

Odeslání požadavků do relace

Pokud chcete odeslat požadavek do kontejneru relace, použijete koncový bod správy jako kořen pro vaši žádost. Cokoli v cestě za koncovým bodem správy základního fondu je přesměrováno do kontejneru relace.

Například pokud zavoláte <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, požadavek se přesměruje do kontejneru relace na cílovém portu <TARGET_PORT>/api/uploadfile.

Ukázkový požadavek

Následující příklad ukazuje, jak odeslat požadavek do relace pomocí ID uživatele jako jedinečný identifikátor relace.

Před odesláním požadavku nahraďte zástupné symboly mezi <> hranatými závorkami hodnotami specifickými pro váš požadavek.

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

Tento požadavek se předá kontejneru v relaci s identifikátorem ID uživatele.

Pokud pro daný identifikátor neexistuje žádná relace, Azure Container Apps před odesláním požadavku automaticky přidělí jednu relaci z fondu.

V tomto příkladu kontejner relace obdrží požadavek na cílový port na adrese <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Identifikátory

Pokud chcete odeslat požadavek HTTP do relace, musíte v požadavku zadat identifikátor relace. Identifikátor relace předáte v parametru řetězce dotazu pojmenovaném identifier v adrese URL, když odešlete požadavek na relaci.

  • Pokud relace s identifikátorem již existuje, požadavek se odešle do existující relace.

  • Pokud relace s identifikátorem neexistuje, automaticky se přidělí nová relace ještě před odesláním požadavku.

Následující diagram znázorňuje, jak pool relací směruje požadavky na existující relace nebo v případě potřeby přiděluje novou relaci.

Diagram znázorňující požadavky na směrování fondu relací na existující relace nebo vytváření nových relací na základě identifikátoru

Formát identifikátoru

Identifikátor relace je řetězec volného tvaru, což znamená, že ho můžete definovat jakýmkoli způsobem, který vyhovuje potřebám vaší aplikace.

Identifikátor relace je řetězec, který definujete jedinečně v rámci fondu relací. Pokud vytváříte webovou aplikaci, můžete jako identifikátor relace použít ID uživatele. Pokud vytváříte chatovacího robota, můžete použít ID konverzace.

Identifikátor musí být řetězec, který má délku 4 až 128 znaků a může obsahovat pouze alfanumerické znaky a speciální znaky z tohoto seznamu: |, , , -&^%$, #(){}[];<a .>

Načtení informací o relaci

Můžete se dotazovat na fond relací a zkontrolovat stav relace, získat podrobnosti o vypršení platnosti a zobrazit seznam všech aktivních relací. Tato funkce je užitečná pro monitorování stavu relace, sledování využití prostředků a implementaci vlastních pracovních postupů čištění.

Získejte jednu relaci

Pokud chcete načíst podrobnosti o konkrétní relaci, použijte getSession koncový bod:

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

Koncový bod getSession vrátí metadata relace, která zahrnují identifikátor relace, aktuální čas vypršení platnosti a časové razítko vytvoření.

Schéma odpovědi SessionView

Pole Typ Povinné Popis
identifier řetězec Ano Identifikátor relace, který jste zadali
etag řetězec Ano Identifikátor neprůžné verze relace. Tento identifikátor můžete použít k detekci změn.
expiresAt Datum a čas Ano Časové razítko UTC, kdy se relace ukončí
createdAt Datum a čas Ne Časové razítko vytvoření relace
lastAccessedAt Datum a čas Ne Časové razítko posledního požadavku na tuto relaci

Příklad požadavku a odpovědi

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"

Odpověď na úspěch (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"
}

Výpis všech relací ve fondu

Pokud chcete načíst seznam všech relací ve fondu relací, použijte koncový bod listSessions:

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

Stránkování

Koncový bod seznamu podporuje stránkování založené na přeskočení. Ve výchozím nastavení vrátí každá stránka až 300 relací. skip K procházení výsledků použijte parametr dotazu.

Parametr Popis
skip Počet relací, které se mají přeskočit od začátku (výchozí hodnota: 0)
nextLink Úplná adresa URL další stránky výsledků (zahrnutá v odpovědi, pokud existuje více výsledků)

Schéma odpovědi ApiCollectionEnvelope

Pole Typ Popis
value SessionView[] Pole objektů relace
count integer Počet relací na aktuální stránce
nextLink řetězec Adresa URL další stránky (null, pokud žádné další výsledky)

Příklad cyklu stránkování

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

Příklad odpovědi (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"
}

Chybové odpovědi

Když dojde k chybě, rozhraní API vrátí strukturovanou chybovou odpověď s podrobnostmi, které vám pomůžou problém diagnostikovat.

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

Běžné kódy chyb

Kód chyby Stav HTTP Popis Resolution
SessionWithIdentifierNotFound 400 Identifikátor relace v tomto fondu relací neexistuje. Ověřte správnost identifikátoru relace a že relace nevypršela.
SessionRequestValidationFailed 400 Požadavek chybí požadovaná pole nebo má neplatné parametry. Zkontrolujte, jestli jsou parametry dotazu (identifikátor, skip, api-version) správně formátované.
SessionRequestNotSupported 400 Rozhraní API nerozpozná typ požadavku Ověřte, že používáte podporovaný koncový bod a metodu.
InternalServerError 500 Došlo k neočekávané chybě na straně serveru. Zkuste žádost zopakovat; pokud chyba přetrvává, zkontrolujte id trasování v protokolech.

Životní cyklus relace v praxi

Vzhledem k tomu, že budete dál volat stejnou relaci, zůstane relace přidělená ve fondu. Jakmile po uplynutí doby ochlazení přestanou existovat požadavky na relaci, relace se automaticky ukončí.

Poznámka:

Ve výjimečných případech, kdy dojde k selhání požadavku na prodloužení TTL relace na pozadí (například pokud se kontejner neočekávaně ukončí), je relace automaticky odstraněna z fondu. Při další žádosti o tuto relaci se zobrazí chyba "relace nebyla nalezena". Toto vyčištění je automatické a nevyžaduje žádnou akci na vaší straně.

Zabezpečení

Model zabezpečení

Dynamické relace jsou navrženy k tomu, aby spouštěly neověřený kód a aplikace v zabezpečeném a izolovaném prostředí. Relace jsou od sebe izolované, ale uživatelé relace mají k dispozici cokoli v rámci jedné relace, včetně souborů a proměnných prostředí.

Nakonfigurujte nebo nahrajte citlivá data do relace pouze tehdy, pokud uživatelům relace důvěřujete.

Síťový přístup

Ve výchozím nastavení se relacím brání v provádění odchozích síťových požadavků. Síťový přístup můžete řídit konfigurací nastavení sítě ve sběrnici relací.

Osvědčené postupy

  • Zabezpečené identifikátory: Vždy používejte zabezpečené identifikátory relací . Generování identifikátorů relací pomocí kryptografických metod k zajištění jedinečných a nepředvídatelných hodnot Nepoužívejte sekvenční ID, která by mohla útočník odhadnout.
  • Použití HTTPS: K šifrování přenášených dat vždy používejte HTTPS. Tím se chrání identifikátory relací a veškerá citlivá data vyměňovaná mezi klientem a serverem před zachycením.
  • Omezit životnost relace: Implementujte časové limity pro relace. Můžete například povolit maximálně 15 minut nečinnosti, než se relace automaticky ukončí. To pomáhá zmírnit rizika z důvodu ztraceného nebo bezobslužného zařízení.
  • Omezit viditelnost relace: Nastavte přísné řízení přístupu, aby se zajistilo, že identifikátory relací budou viditelné pouze pro fond relací. Vyhněte se zveřejnění ID relací v adresách URL nebo protokolech.
  • Pravidelně vyměňujte přihlašovací údaje relace: Čas od času kontrolujte a aktualizujte přihlašovací údaje přidružené k relacím. Rotace snižuje riziko neoprávněného přístupu.

Další pokyny pro vlastní kontejnerové relace

  • Využijte zabezpečené přenosové protokoly: K šifrování přenášených dat, včetně identifikátorů relací, vždy používejte HTTPS. Tento přístup chrání před útoky typu man-in-the-middle.

  • Monitorování aktivity relace: Implementujte protokolování a monitorování pro sledování aktivit relací. Tyto protokoly použijte k identifikaci neobvyklých vzorů nebo potenciálních porušení zabezpečení.

  • Ověření vstupu uživatele: Zachází se všemi uživatelskými vstupy jako s nebezpečnými. K ochraně před útoky prostřednictvím injektáže použijte vstupní ověřování a techniky sanace a zajistěte, aby se zpracovávala pouze důvěryhodná data.

Autentizace a autorizace

Při odesílání požadavků do relace pomocí rozhraní API pro správu fondu se ověřování zpracovává pomocí tokenů Microsoft Entra. K volání rozhraní API pro správu fondů mají oprávnění pouze tokeny Microsoft Entra z identity patřící do role Azure ContainerApps Session Executor ve fondu relací.

Pokud chcete přiřadit roli identitě, použijte následující příkaz Azure CLI:

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

Pokud používáte integraci s velkým jazykovým modelem (LLM), rozhraní za vás zpracovává generování a správu tokenů. Ujistěte se, že je aplikace nakonfigurovaná s přiřazenou spravovanou identitou a nezbytnými rolemi přiřazenými k poolu relací.

Pokud používáte koncové body rozhraní API pro správu fondu přímo, musíte vygenerovat token a zahrnout ho do Authorization hlavičky požadavků HTTP. Kromě dříve zmíněných přiřazení rolí musí token obsahovat deklaraci cílové skupiny (aud) s hodnotou https://dynamicsessions.io.

Pokud chcete vygenerovat token pomocí Azure CLI, spusťte následující příkaz:

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

Důležité

Platný token slouží k vytvoření a přístupu k jakékoli relaci ve fondu. Zabezpečte tokeny a nesdílejte je s nedůvěryhodnými stranami. Koncoví uživatelé by nikdy neměli mít přímý přístup k tokenům. Zpřístupnit tokeny jenom aplikaci a nikdy koncovým uživatelům.

Ochrana identifikátorů relací

Identifikátor relace je citlivá informace, kterou musíte bezpečně spravovat. Vaše aplikace musí zajistit, aby každý uživatel nebo tenant měli přístup jenom k vlastním relacím.

Konkrétní strategie, které brání zneužití identifikátorů relací, se liší v závislosti na návrhu a architektuře vaší aplikace. Vaše aplikace ale musí mít vždy úplnou kontrolu nad vytvářením a používáním identifikátorů relací, aby uživatel se zlými úmysly neměl přístup k relaci jiného uživatele.

Mezi příklady strategií patří:

  • Jedna relace na uživatele: Pokud vaše aplikace používá jednu relaci na uživatele, musí být každý uživatel bezpečně ověřen a aplikace musí používat jedinečný identifikátor relace pro každého přihlášeného uživatele.

  • Jedna relace na konverzaci agenta AI: Pokud vaše aplikace používá jednu relaci na každou konverzaci agenta AI, ujistěte se, že vaše aplikace používá jedinečný identifikátor relace pro každou konverzaci, který koncový uživatel nemůže nijak upravovat.

Důležité

Pokud se nepodaří zabezpečit přístup k relacím, může dojít ke zneužití nebo neoprávněnému přístupu k datům uloženým v relacích uživatelů.

Použití spravované identity

Spravovaná identita z Microsoft Entra ID umožňuje poolům relací kontejnerů a jejich relacím přístup k dalším chráněným prostředkům Microsoft Entra. Ve fondu relací jsou podporovány spravované identity přiřazené systémem i uživatelem.

Další informace o spravovaných identitách v Microsoft Entra ID najdete v tématu Spravované identity pro Azure prostředky.

Lze použít spravované identity s vlastními fondy relací kontejnerových platforem dvěma způsoby:

  • Ověřování vyžádáním image: Použijte spravovanou identitu k ověření v registru kontejneru k načtení image kontejneru.

  • Zdrojový přístup: V relaci použijte spravovanou identitu fondu relací pro přístup k dalším prostředkům chráněným Microsoft Entra. Vzhledem k tomu, že to má vliv na zabezpečení, je tato funkce ve výchozím nastavení zakázaná.

    Důležité

    Pokud povolíte přístup ke spravované identitě v rámci relace, může jakýkoli kód nebo programy spuštěné v relaci vytvářet tokeny Microsoft Entra pro spravovanou identitu fondu. Vzhledem k tomu, že relace obvykle spouštějí nedůvěryhodný kód, použijte tuto funkci s extrémní opatrností.

Pokud chcete povolit spravovanou identitu pro vlastní fond relací kontejneru, použijte Azure Resource Manager.

Logování

Dynamické relace Azure Container Apps se integrují s Azure Monitor a Log Analytics ke shromažďování logů vygenerovaných během běhu relace. Postup konfigurace je stejný pro interpret kódu a vlastní fondy relací pro kontejnery, ale dostupné kategorie protokolů se liší podle typu relace. Metriky vrácené prostřednictvím hlaviček odpovědí rozhraní API se nezapisují do Log Analytics.

Protokolování rozdílů podle typu relace

Pomocí následujících pokynů porovnejte chování protokolů a přejděte k podrobnostem, které odpovídají vašemu typu relace:

  • Relace interpreta kódu: Výstupy jsou vráceny ze spuštění (včetně stdout a stderr), ale tabulky AppEnvSession Log Analytics nejsou vygenerovány. Viz Protokolování relací interpreta kódu.
  • Vlastní relace kontejnerů: Tabulky Log Analytics AppEnvSession se vygenerují při zápisu kontejneru do stdout nebo stderr a logy platformy jsou k dispozici pro události a životní cyklus fondu. Podívejte se na Záznam vlastních relací kontejneru.
  • Common: Metriky vrácené hlavičkami odpovědi rozhraní API se do Log Analytics nezapisují.

Úplný seznam podporovaných kategorií sezení pro prostředek prostředí (Microsoft.App/managedEnvironments) najdete v části Podporované protokoly pro Microsoft.App/managedEnvironments.

Související obsah

  • Last updated on