Menggunakan sesi dinamis dalam Azure Container Apps

Azure Container Apps sesi dinamis menyediakan konteks terisolasi dan aman saat Anda perlu menjalankan kode atau aplikasi secara terpisah dari beban kerja lain. Sesi berjalan di dalam kumpulan sesi yang menyediakan akses langsung ke sesi baru dan yang sudah ada. Sesi ini sangat ideal untuk skenario di mana input yang dihasilkan pengguna perlu diproses dengan cara yang terkontrol atau ketika mengintegrasikan layanan pihak ketiga yang memerlukan kode eksekusi di lingkungan yang terisolasi. Anda tidak perlu menyebarkan sumber daya aplikasi kontainer untuk menggunakan sesi dinamis, membuat kumpulan sesi, dan memanggil API manajemennya.

Artikel ini memperlihatkan kepada Anda cara mengelola dan berinteraksi dengan sesi dinamis.

Titik akhir dan perutean manajemen

Aplikasi Anda berinteraksi dengan sesi menggunakan API manajemen kumpulan sesi. Untuk gambaran umum konseptual tentang bagaimana permintaan dirutekan, lihat Konsep utama.

Untuk mendapatkan titik akhir manajemen kumpulan sesi, lihat titik akhir manajemen kumpulan sesi.

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

Untuk informasi selengkapnya tentang mengelola kumpulan sesi, lihat titik akhir manajemen kumpulan sesi.

Autentikasi dan otorisasi API Manajemen

Semua permintaan ke API manajemen kumpulan sesi memerlukan autentikasi (AuthN) dengan token dan otorisasi Microsoft Entra (AuthZ) melalui peran Azure ContainerApps Session Executor pada kumpulan sesi. Untuk detail dan contohnya, lihat Autentikasi dan otorisasi.

Mengirim permintaan ke sesi

Untuk mengirim permintaan ke dalam kontainer sesi, Anda menggunakan titik akhir manajemen sebagai akar untuk permintaan Anda. Apa pun di jalur yang mengikuti titik akhir manajemen kumpulan dasar diteruskan ke kontainer sesi.

Misalnya, jika Anda melakukan panggilan ke <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, permintaan dirutekan ke kontainer sesi pada port targetnya di <TARGET_PORT>/api/uploadfile.

Permohonan sampel

Contoh berikut menunjukkan cara mengirim permintaan ke sesi menggunakan ID pengguna sebagai pengidentifikasi sesi unik.

Sebelum Anda mengirim permintaan, ganti placeholder di antara tanda kurung <> dengan nilai khusus untuk permintaan Anda.

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

Permintaan ini diteruskan ke kontainer dalam sesi dengan pengidentifikasi untuk ID pengguna.

Jika tidak ada sesi untuk pengidentifikasi yang diberikan, Azure Container Apps secara otomatis mengalokasikannya dari kumpulan sebelum meneruskan permintaan.

Dalam contoh ini, kontainer sesi menerima permintaan pada port target di <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Pengidentifikasi

Untuk mengirim permintaan HTTP ke sesi, Anda harus menyediakan pengidentifikasi sesi dalam permintaan. Anda meneruskan ID sesi dalam parameter string kueri bernama identifier di URL ketika Anda mengajukan permintaan ke sesi.

  • Jika sesi dengan pengidentifikasi sudah ada, permintaan dikirim ke sesi yang ada.

  • Jika sesi dengan pengidentifikasi tidak ada, sesi baru secara otomatis dialokasikan sebelum permintaan dikirim ke sesi tersebut.

Diagram berikut menunjukkan bagaimana kumpulan sesi merutekan permintaan ke sesi yang ada atau mengalokasikan sesi baru saat diperlukan.

Diagram menunjukkan kumpulan sesi yang mengarahkan permintaan ke sesi yang sudah ada atau membuat sesi baru berdasarkan pengidentifikasi.

Format pengidentifikasi

Pengidentifikasi sesi adalah string bentuk bebas, yang berarti Anda dapat menentukannya dengan cara apa pun yang sesuai dengan kebutuhan aplikasi Anda.

Pengidentifikasi sesi adalah string yang Anda tentukan unik dalam kumpulan sesi. Jika Anda membangun aplikasi web, Anda dapat menggunakan ID pengguna sebagai pengidentifikasi sesi. Jika Anda membuat chatbot, Anda dapat menggunakan ID percakapan.

Pengidentifikasi harus berupa string yang panjangnya 4 hingga 128 karakter dan hanya dapat berisi karakter alfanumerik dan karakter khusus dari daftar ini: |, , -, &^%$#(){}, [, ], ;, <, , dan .>

Respon terhadap kesalahan

Ketika kesalahan terjadi, API mengembalikan respons kesalahan terstruktur dengan detail untuk membantu Anda mendiagnosis masalah.

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

Kode kesalahan umum

Kode Kesalahan HTTP Status Deskripsi Resolution
SessionWithIdentifierNotFound 400 Pengidentifikasi sesi tidak ada di kumpulan sesi ini Verifikasi bahwa pengidentifikasi sesi sudah benar dan sesi belum kedaluwarsa
SessionRequestValidationFailed 400 Permintaan tidak memiliki bidang yang diperlukan atau memiliki parameter yang tidak valid Periksa parameter kueri (pengidentifikasi, skip, versi API) apakah diformat dengan benar
SessionRequestNotSupported 400 Jenis permintaan tidak dikenali oleh API Memverifikasi bahwa Anda menggunakan titik akhir dan metode yang didukung
InternalServerError 500 Terjadi kesalahan sisi server yang tidak terduga Coba lagi permintaan; jika kesalahan berlanjut, periksa traceId dalam log

Siklus Hidup Sesi dalam Praktiknya

Saat Anda terus melakukan panggilan ke sesi yang sama, sesi tetap dialokasikan di kumpulan. Setelah tidak ada permintaan ke sesi setelah periode cooldown berlalu, sesi secara otomatis dihancurkan.

Nota

Dalam kasus yang jarang terjadi, ketika permintaan ekstensi TTL latar belakang sesi gagal (misalnya, jika kontainer keluar secara tidak terduga), sesi secara otomatis dihapus dari kumpulan. Anda akan melihat kesalahan "sesi tidak ditemukan" pada permintaan Anda berikutnya ke sesi tersebut. Pembersihan ini otomatis dan tidak memerlukan tindakan pada bagian Anda.

Keamanan

Model keamanan

Sesi dinamis dibuat untuk menjalankan kode dan aplikasi yang tidak tepercaya di lingkungan yang aman dan terisolasi. Meskipun sesi diisolasi satu sama lain, apa pun dalam satu sesi, termasuk file dan variabel lingkungan, dapat diakses oleh pengguna sesi.

Hanya konfigurasikan atau unggah data sensitif ke sesi jika Anda mempercayai pengguna sesi.

Akses jaringan

Secara default, sesi dicegah membuat permintaan jaringan keluar. Anda dapat mengontrol akses jaringan dengan mengonfigurasi pengaturan status jaringan pada kumpulan sesi.

Praktik terbaik

  • Pengidentifikasi aman: Gunakan pengidentifikasi sesi yang aman setiap saat. Hasilkan pengidentifikasi sesi menggunakan metode kriptografi untuk memastikan nilai unik dan tidak dapat diprediksi. Hindari menggunakan ID berurutan yang dapat ditebak oleh penyerang.
  • Gunakan HTTPS: Selalu gunakan HTTPS untuk mengenkripsi data saat transit. Ini melindungi pengidentifikasi sesi dan data sensitif apa pun yang dipertukarkan antara klien dan server agar tidak disadap.
  • Batasi masa pakai sesi: Terapkan batas waktu untuk sesi. Misalnya, izinkan maksimum 15 menit tidak aktif sebelum sesi dihentikan secara otomatis. Ini membantu mengurangi risiko karena perangkat yang hilang atau tidak dijaga.
  • Membatasi visibilitas sesi: Atur kontrol akses yang ketat untuk memastikan bahwa pengidentifikasi sesi hanya terlihat oleh kumpulan sesi. Hindari mengekspos ID sesi di URL atau log.
  • Memutar kredensial sesi secara berkala: Tinjau dan perbarui kredensial yang terkait dengan sesi Anda secara berkala. Rotasi mengurangi risiko akses yang tidak sah.

Panduan tambahan untuk sesi kontainer kustom

  • Menggunakan protokol transmisi aman: Selalu gunakan HTTPS untuk mengenkripsi data saat transit, termasuk pengidentifikasi sesi. Pendekatan ini melindungi dari serangan man-in-the-middle.

  • Memantau aktivitas sesi: Menerapkan pengelogan dan pemantauan untuk melacak aktivitas sesi. Gunakan log ini untuk mengidentifikasi pola yang tidak biasa atau potensi pelanggaran keamanan.

  • Memvalidasi input pengguna: Perlakukan semua input pengguna sebagai berbahaya. Gunakan teknik validasi input dan sanitasi untuk melindungi dari serangan injeksi dan memastikan bahwa hanya data tepercaya yang diproses.

Autentikasi dan otorisasi

Saat Anda mengirim permintaan ke sesi menggunakan API manajemen kumpulan, autentikasi ditangani menggunakan token Microsoft Entra. Hanya token-token Microsoft Entra dari identitas yang memiliki peran Azure ContainerApps Session Executor pada kumpulan sesi yang berwenang untuk memanggil API manajemen kumpulan.

Untuk menetapkan peran ke identitas, gunakan perintah Azure CLI berikut:

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

Jika Anda menggunakan integrasi kerangka kerja model bahasa besar (LLM), kerangka kerja menangani pembuatan dan manajemen token untuk Anda. Pastikan bahwa aplikasi dikonfigurasi dengan identitas terkelola dengan penetapan peran yang diperlukan pada kumpulan sesi.

Jika Anda menggunakan titik akhir API manajemen kumpulan secara langsung, Anda harus membuat token dan menyertakannya di Authorization header permintaan HTTP Anda. Selain penetapan peran yang disebutkan sebelumnya, token perlu berisi klaim audiens (aud) dengan nilai https://dynamicsessions.io.

Untuk menghasilkan token menggunakan Azure CLI, jalankan perintah berikut:

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

Penting

Token yang valid digunakan untuk membuat dan mengakses sesi apa pun di dalam pool. Jaga keamanan token Anda dan jangan bagikan dengan pihak yang tidak tepercaya. Pengguna akhir tidak boleh memiliki akses langsung ke token. Hanya membuat token tersedia untuk aplikasi, dan tidak pernah untuk pengguna akhir.

Melindungi pengidentifikasi sesi

Pengidentifikasi sesi adalah informasi sensitif yang harus Anda kelola dengan aman. Aplikasi Anda perlu memastikan setiap pengguna atau penyewa hanya memiliki akses ke sesi mereka sendiri.

Strategi khusus yang mencegah penyalahgunaan pengidentifikasi sesi berbeda tergantung pada desain dan arsitektur aplikasi Anda. Namun, aplikasi Anda harus selalu memiliki kontrol penuh atas pembuatan dan penggunaan pengidentifikasi sesi sehingga pengguna berbahaya tidak dapat mengakses sesi pengguna lain.

Contoh strategi meliputi:

  • Satu sesi per pengguna: Jika aplikasi Anda menggunakan satu sesi per pengguna, setiap pengguna harus diautentikasi dengan aman, dan aplikasi Anda harus menggunakan pengidentifikasi sesi unik untuk setiap pengguna yang masuk.

  • Satu sesi per percakapan agen: Jika aplikasi Anda menggunakan satu sesi per percakapan agen AI, pastikan aplikasi Anda memastikan penggunaan pengidentifikasi sesi unik untuk setiap percakapan yang tidak dapat diubah oleh pengguna akhir.

Penting

Kegagalan untuk mengamankan akses ke sesi dapat mengakibatkan penyalahgunaan atau akses tidak sah ke data yang disimpan dalam sesi pengguna Anda.

Gunakan identitas terkelola

Identitas terkelola dari Microsoft Entra ID memungkinkan kumpulan sesi kontainer Anda dan sesinya untuk mengakses sumber daya lain yang dilindungi Microsoft Entra. Identitas terkelola yang ditetapkan sistem dan yang ditetapkan pengguna didukung dalam kumpulan sesi.

Untuk informasi selengkapnya tentang identitas terkelola di Microsoft Entra ID, lihat Managed identities untuk sumber daya Azure.

Ada dua cara untuk menggunakan identitas terkelola dengan kumpulan sesi kontainer kustom:

  • Autentikasi penarikan gambar: Gunakan identitas terkelola untuk mengautentikasi dengan registri kontainer untuk menarik gambar kontainer.

  • Akses Sumber Daya: Gunakan identitas terkelola dari kumpulan sesi untuk mengakses sumber daya lain yang dilindungi oleh Microsoft Entra. Karena implikasi keamanannya, kemampuan ini dinonaktifkan secara default.

    Penting

    Jika Anda mengaktifkan akses ke identitas terkelola dalam sesi, kode atau program apa pun yang berjalan dalam sesi dapat membuat token Microsoft Entra untuk identitas terkelola kumpulan. Karena sesi biasanya menjalankan kode yang tidak tepercaya, gunakan fitur ini dengan sangat hati-hati.

Untuk mengaktifkan identitas terkelola untuk kumpulan sesi kontainer kustom, gunakan Azure Resource Manager.

Penebangan kayu

Azure Container Apps sesi dinamis terintegrasi dengan Azure Monitor dan Log Analytics untuk mengumpulkan log yang dihasilkan selama eksekusi sesi. Langkah-langkah konfigurasi sama untuk penerjemah kode dan kumpulan sesi kontainer kustom, tetapi kategori log yang tersedia berbeda menurut jenis sesi. Metrik yang dikembalikan melalui header respons API tidak ditulis ke Log Analytics.

Perbedaan pencatatan log berdasarkan jenis sesi

Gunakan panduan berikut untuk membandingkan perilaku pengelogan dan lompat ke detail yang cocok dengan jenis sesi Anda:

  • Code interpreter sessions: Output dikembalikan dari eksekusi (termasuk stdout dan stderr), tetapi tabel appEnvSession Log Analytics tidak dipancarkan. Lihat Pengelogan sesi penerjemah kode.
  • Sesi kontainer kustom: Tabel Log Analytics AppEnvSession dihasilkan saat kontainer Anda menulis ke dalam stdout atau stderr, dan log platform tersedia untuk siklus hidup dan peristiwa kumpulan. Lihat Pencatatan sesi kontainer kustom.
  • Common: Metrik yang dikembalikan melalui header respons API tidak ditulis ke Log Analytics.

Untuk daftar lengkap kategori sesi yang didukung pada sumber daya lingkungan (Microsoft.App/managedEnvironments), lihat Log yang Didukung untuk Microsoft.App/managedEnvironments.

Konten terkait

  • Terakhir diperbarui pada