Azure Container Apps'de dinamik oturumları kullanma

Azure Container Apps dinamik sessions kod veya uygulamaları diğer iş yüklerinden ayrı olarak çalıştırmanız gerektiğinde yalıtılmış, güvenli bağlamlar sunar. Oturumlar, yeni ve mevcut oturumlara anında erişim sağlayan bir oturum havuzu içinde çalıştırılır. Bu oturumlar, kullanıcı tarafından oluşturulan girişin denetimli bir şekilde işlenmesi veya yalıtılmış bir ortamda kod yürütülmesini gerektiren üçüncü taraf hizmetleri tümleştirme senaryoları için idealdir. Dinamik oturumları kullanmak, bir oturum havuzu oluşturmak ve yönetim API'sini çağırmak için bir kapsayıcı uygulaması kaynağı dağıtmanız gerekmez.

Bu makalede dinamik oturumları yönetme ve bunlarla etkileşim kurma işlemleri gösterilmektedir.

Yönetim uç noktası ve yönlendirme

Uygulamanız, oturum havuzunun yönetim API'sini kullanarak bir oturumla etkileşim kurar. İsteklerin nasıl yönlendirildiğinden kavramsal bir genel bakış için bkz. Temel kavramlar.

Oturum havuzu yönetim uç noktasını almak için bkz. oturum havuzları yönetim uç noktası.

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

Oturum havuzlarını yönetme hakkında daha fazla bilgi için bkz. oturum havuzları yönetim uç noktası.

Yönetim API'sinde kimlik doğrulaması ve yetkilendirme

Oturum havuzu yönetim API'sine yönelik tüm istekler, oturum havuzundaki Azure ContainerApps Oturum Yürütücüsü rolü aracılığıyla Microsoft Entra belirteci ve yetkilendirme (AuthZ) ile kimlik doğrulaması (AuthN) gerektirir. Ayrıntılar ve örnekler için bkz. Kimlik doğrulaması ve yetkilendirme.

Oturuma istek gönderme

Oturumun kapsayıcısına istek göndermek için, isteğinizin kökü olarak yönetim uç noktasını kullanırsınız. Temel havuz yönetimi uç noktasını izleyen her şey oturum kapsayıcısına iletilir.

Örneğin, <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile çağrı yaparsanız, istek belirlenen hedef bağlantı noktasındaki <TARGET_PORT>/api/uploadfile oturum kapsayıcısına yönlendirilir.

Numune isteği

Aşağıdaki örnekte, benzersiz oturum tanımlayıcısı olarak kullanıcının kimliğini kullanarak oturuma istek gönderme gösterilmektedir.

İsteği göndermeden önce köşeli ayraçlar arasındaki <> yer tutucuları isteğinize özgü değerlerle değiştirin.

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

Bu istek, kullanıcının kimliğinin tanımlayıcısı ile oturumdaki kapsayıcıya iletilir.

Belirtilen tanımlayıcı için oturum yoksa, Azure Container Apps isteği iletmeden önce havuzdan otomatik olarak bir oturum ayırır.

Bu örnekte, kapsayıcı oturumun hedef bağlantı noktasındaki <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER> isteğini alır.

Tanımlayıcılar

Bir oturuma HTTP isteği göndermek için istekte bir oturum tanımlayıcısı sağlamanız gerekir. Oturuma istekte bulunurken oturum tanımlayıcısını URL'de adlı identifier sorgu dizesi parametresine geçirirsiniz.

  • Tanımlayıcıya sahip bir oturum zaten varsa, istek mevcut oturuma gönderilir.

  • Tanımlayıcıya sahip bir oturum yoksa, istek gönderilmeden önce otomatik olarak yeni bir oturum ayrılır.

Aşağıdaki diyagramda, bir oturum havuzunun istekleri mevcut oturumlara yönlendirmesi veya gerektiğinde yeni bir oturum ayırması gösterilmektedir.

Var olan oturumlara yönelik oturum havuzu yönlendirme isteklerini veya tanımlayıcıyı temel alan yeni oturumlar oluşturmayı gösteren diyagram.

Tanımlayıcı biçimi

Oturum tanımlayıcısı serbest biçimli bir dizedir; başka bir deyişle, bunu uygulamanızın gereksinimlerine uygun herhangi bir şekilde tanımlayabilirsiniz.

Oturum tanımlayıcısı, oturum havuzu içinde benzersiz olan, tanımladığınız bir dizedir. Web uygulaması oluşturuyorsanız oturum tanımlayıcısı olarak kullanıcının kimliğini kullanabilirsiniz. Sohbet botu oluşturuyorsanız konuşma kimliğini kullanabilirsiniz.

Tanımlayıcı, 4 ila 128 karakter uzunluğunda bir dize olmalıdır ve yalnızca bu listeden alfasayısal karakterler ve özel karakterler içerebilir: |, -, &, ^, %, $, #(, ){}[];<ve .>

Oturum bilgilerini alma

Oturum durumunu denetlemek, süre sonu ayrıntılarını almak ve tüm etkin oturumları listelemek için oturum havuzunuzu sorgulayabilirsiniz. Bu özellik oturum durumunu izlemek, kaynak kullanımını izlemek ve özel temizleme iş akışlarını uygulamak için kullanışlıdır.

Tek bir oturum al

Belirli bir oturumla ilgili ayrıntıları almak için uç noktayı kullanın 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>

Uç nokta getSession, oturum tanımlayıcısı, geçerli sona erme süresi ve oluşturulma zaman damgası dahil oturum meta verilerini döndürür.

SessionView yanıt şeması

Alan Türü Zorunlu Açıklama
identifier String Evet Sağladığınız oturum tanımlayıcısı
etag String Evet Oturum için opak sürüm tanımlayıcısı. Değişiklik algılama için bu tanımlayıcıyı kullanabilirsiniz.
expiresAt Tarih Saat Evet Oturumun sonlandırılacağı UTC zaman damgası
createdAt Tarih Saat Hayır Oturum oluşturulma tarih ve saati
lastAccessedAt Tarih Saat Hayır Bu oturuma yapılan son isteğin zaman damgası

Örnek istek ve yanıt

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"

Başarı yanıtı (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"
}

Havuzdaki tüm oturumları listeleme

Oturum havuzunuzdaki tüm oturumların listesini almak için uç noktayı kullanın listSessions :

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

Sayfalandırma

Liste uç noktası, atlama tabanlı sayfalandırmayı destekler. Varsayılan olarak, her sayfa en fazla 300 oturum döndürür. Sonuçlarda skip gezinmek için sorgu parametresini kullanın.

Parametre Açıklama
skip Baştan atlanacak oturum sayısı (varsayılan: 0)
nextLink Sonraki sonuç sayfası için tam URL (daha fazla sonuç olduğunda yanıta eklenir)

ApiCollectionEnvelope yanıt şeması

Alan Türü Açıklama
value SessionView[] Oturum nesneleri dizisi
count tamsayı Geçerli sayfadaki oturum sayısı
nextLink String Sonraki sayfanın URL'si (başka sonuç yoksa null)

Örnek sayfalandırma döngüsü

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

Örnek yanıt (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"
}

Hata yanıtları

Hata oluştuğunda API, sorunu tanılamanıza yardımcı olmak için ayrıntıları içeren yapılandırılmış bir hata yanıtı döndürür.

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

Sık karşılaşılan hata kodları

Hata Kodu HTTP durumu Açıklama Çözünürlük
SessionWithIdentifierNotFound 400 Oturum tanımlayıcısı bu oturum havuzunda yok Oturum tanımlayıcısının doğru olduğunu ve oturumun süresinin dolmadığını doğrulayın
SessionRequestValidationFailed 400 İstekte gerekli alanlar eksik veya geçersiz parametreler var Sorgu parametrelerinin (tanımlayıcı, atlama, api sürümü) düzgün biçimlendirildiğinden emin olun
SessionRequestNotSupported 400 İstek türü API tarafından tanınmıyor Desteklenen bir uç nokta ve yöntem kullandığınızı doğrulayın
InternalServerError beş yüz Beklenmeyen bir sunucu tarafı hatası oluştu İsteği yeniden deneyin; hata devam ederse günlüklerdeki traceId değerini denetleyin

Uygulamada oturum yaşam döngüsü

Aynı oturuma çağrı yapmaya devam ettikçe, oturum havuzda tahsis edilmiş olarak kalır. Bekleme süresi dolduktan sonra oturuma yönelik istek olmadığında oturum otomatik olarak yok edilir.

Uyarı

Nadir durumlarda, oturumun arka planda yapılan TTL uzantısı isteği başarısız olduğunda (örneğin, kapsayıcı beklenmedik bir şekilde sonlanırsa), oturum havuzdan otomatik olarak kaldırılır. Bir sonraki oturum isteğinizde "oturum bulunamadı" hatası görürsünüz. Bu temizleme otomatiktir ve sizin için hiçbir işlem gerektirmez.

Güvenlik

Güvenlik modeli

Dinamik oturumlar güvenli ve yalıtılmış bir ortamda güvenilmeyen kod ve uygulamaları çalıştıracak şekilde oluşturulur. Oturumlar birbirinden yalıtılmış olsa da, dosyalar ve ortam değişkenleri de dahil olmak üzere tek bir oturumdaki her şeye oturumun kullanıcıları tarafından erişilebilir.

Hassas verileri yalnızca oturumun kullanıcılarına güveniyorsanız yapılandırın veya oturuma yükleyin.

Ağ erişimi

Varsayılan olarak, oturumların giden ağ istekleri yapması engellenir. Oturum havuzunda ağ durumu ayarlarını yapılandırarak ağ erişimini denetleyebilirsiniz.

En iyi yöntemler

  • Güvenli tanımlayıcılar: Güvenli oturum tanımlayıcılarını her zaman kullanın. Benzersiz ve öngörülemeyen değerler sağlamak için şifreleme yöntemlerini kullanarak oturum tanımlayıcıları oluşturun. Saldırgan tarafından tahmin edilebilecek sıralı kimlikleri kullanmaktan kaçının.
  • HTTPS kullanma: Aktarımdaki verileri şifrelemek için her zaman HTTPS kullanın. Bu, oturum tanımlayıcılarını ve istemci ile sunucu arasında aktarılan hassas verilerin ele geçirilmesine karşı korur.
  • Oturum ömrünü sınırla: Oturumlar için zaman aşımları uygulayın. Örneğin, oturumun otomatik olarak sonlandırılabilmesi için en fazla 15 dakika etkinlik dışı kalma süresine izin verin. Bu, kayıp veya başka bir şekilde kontrol edilmeyen cihaz kaynaklı riskleri azaltmaya yardımcı olur.
  • Oturum görünürlüğünü sınırla: Oturum tanımlayıcılarının yalnızca oturum havuzuna görünür olmasını sağlamak için katı erişim denetimleri ayarlayın. Oturum kimliklerini URL'lerde veya günlüklerde açığa çıkarmaktan kaçının.
  • Oturum kimlik bilgilerini düzenli olarak döndürme: Oturumlarınızla ilişkili kimlik bilgilerini düzenli aralıklarla gözden geçirin ve güncelleştirin. Döndürme, yetkisiz erişim riskini azaltır.

Özel konteyner oturumları için ek rehberlik

  • Güvenli iletim protokollerini kullanın: Oturum tanımlayıcıları da dahil olmak üzere aktarımdaki verileri şifrelemek için her zaman HTTPS kullanın. Bu yaklaşım, ortadan saldırılara karşı koruma sağlar.

  • Oturum etkinliğini izleme: Oturum etkinliklerini izlemek için günlüğe kaydetme ve izleme işlemlerini gerçekleştirin. Olağan dışı desenleri veya olası güvenlik ihlallerini belirlemek için bu günlükleri kullanın.

  • Kullanıcı girişini doğrulama: Tüm kullanıcı girişlerini tehlikeli olarak değerlendirin. Ekleme saldırılarına karşı koruma sağlamak ve yalnızca güvenilir verilerin işlendiğinden emin olmak için giriş doğrulama ve sanitasyon tekniklerini kullanın.

Kimlik doğrulaması ve yetkilendirme

Havuz yönetimi API'sini kullanarak bir oturuma istek gönderdiğinizde kimlik doğrulaması Microsoft Entra belirteçleri kullanılarak işlenir. Oturum havuzundaki Azure ContainerApps Oturum Yürütücüsü rolüne ait bir kimlikten yalnızca Microsoft Entra belirteçleri havuz yönetimi API'sini çağırma yetkisine sahiptir.

Rolü bir kimliğe atamak için aşağıdaki Azure CLI komutunu kullanın:

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

Büyük bir dil modeli (LLM) çerçevesi tümleştirmesi kullanıyorsanız, çerçeve sizin için belirteç oluşturma ve yönetimi işler. Uygulamanın, oturum havuzunda gerekli rol atamalarıyla yönetilen bir kimlikle yapılandırıldığından emin olun.

Havuzun yönetim API'sinin uç noktalarını doğrudan kullanıyorsanız, bir belirteç oluşturmanız ve bunu Authorization HTTP isteklerinizin üst bilgisine eklemeniz gerekir. Daha önce bahsedilen rol atamalarına ek olarak, belirteç, aud değerine sahip bir hedef kitle talebi (https://dynamicsessions.io) içermelidir.

Azure CLI kullanarak belirteç oluşturmak için aşağıdaki komutu çalıştırın:

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

Önemli

Havuzdaki herhangi bir oturumu oluşturmak ve bu oturumlara erişmek için geçerli bir belirteç kullanılır. Belirteçlerinizi güvende tutun ve güvenilmeyen taraflarla paylaşmayın. Son kullanıcıların hiçbir zaman belirteçlere doğrudan erişimi olmamalıdır. Belirteçleri yalnızca uygulama için kullanılabilir hale getirin ve hiçbir zaman son kullanıcılar için kullanılamaz.

Oturum tanımlayıcılarını koruma

Oturum tanımlayıcısı, güvenli bir şekilde yönetmeniz gereken hassas bilgilerdir. Uygulamanızın her kullanıcının veya kiracının yalnızca kendi oturumlarına erişimi olduğundan emin olması gerekir.

Oturum tanımlayıcılarının kötüye kullanılmasını engelleyen belirli stratejiler, uygulamanızın tasarımına ve mimarisine bağlı olarak farklılık gösterir. Ancak, kötü niyetli bir kullanıcının başka bir kullanıcının oturumuna erişememeleri için uygulamanızın oturum tanımlayıcıları oluşturma ve kullanma üzerinde her zaman tam denetime sahip olması gerekir.

Örnek stratejiler şunlardır:

  • Kullanıcı başına bir oturum: Uygulamanız kullanıcı başına bir oturum kullanıyorsa, her kullanıcının kimliğinin güvenli bir şekilde doğrulanması ve uygulamanızın oturum açmış her kullanıcı için benzersiz bir oturum tanımlayıcısı kullanması gerekir.

  • Aracı konuşması başına bir oturum: Uygulamanız yapay zeka aracısı konuşması başına bir oturum kullanıyorsa, uygulamanızın son kullanıcı tarafından değiştirilmeyecek her konuşma için benzersiz bir oturum tanımlayıcısı kullandığından emin olun.

Önemli

Oturumlara erişimin güvenliğinin sağlanamaması, kullanıcılarınızın oturumlarında depolanan verilere yanlış veya yetkisiz erişime neden olabilir.

Yönetilen kimlik kullanma

Microsoft Entra ID'nin yönetilen kimliği, kapsayıcı oturum havuzlarınızın ve bunların oturumlarının diğer Microsoft Entra korumalı kaynaklara erişmesine olanak tanır. Oturum havuzunda hem sistem tarafından atanan hem de kullanıcı tarafından atanan yönetilen kimlikler desteklenir.

Microsoft Entra ID'de yönetilen kimlikler hakkında daha fazla bilgi için bkz. Azure kaynakları için yönetilen kimlikler.

Yönetilen kimlikleri özel kapsayıcı oturum havuzlarıyla kullanmanın iki yöntemi vardır.

  • Görüntü çekme kimlik doğrulaması: Kapsayıcı görüntüsünü çekmek için kapsayıcı kayıt defteriyle kimlik doğrulaması yapmak için yönetilen kimliği kullanın.

  • Kaynak erişimi: Diğer Microsoft Entra korumalı kaynaklara erişmek için oturum havuzunun yönetilen kimliğini bir oturumda kullanın. Güvenlik etkilerinden dolayı, bu özellik varsayılan olarak devre dışı bırakılır.

    Önemli

    Bir oturumda yönetilen kimliğe erişimi etkinleştirirseniz, oturumda çalışan tüm kodlar veya programlar havuzun yönetilen kimliği için Microsoft Entra belirteçler oluşturabilir. Oturumlar genellikle güvenilmeyen kod çalıştırdığından bu özelliği çok dikkatli kullanın.

Özel kapsayıcı oturum havuzu için yönetilen kimliği etkinleştirmek için Azure Resource Manager kullanın.

Ağaç kesimi

Azure Container Apps dinamik oturumları, oturum yürütülmesi sırasında yayılan günlükleri toplamak için Azure İzleyici ve Log Analytics ile tümleşir. Yapılandırma adımları kod yorumlayıcı ve özel kapsayıcı oturum havuzları için aynıdır, ancak kullanılabilir günlük kategorileri oturum türüne göre farklılık gösterir. API yanıt üst bilgileri aracılığıyla döndürülen ölçümler Log Analytics'e yazılmaz.

Oturum türüne göre farklılıkları kaydetme

Günlüğe kaydetme davranışını karşılaştırmak ve oturum türünüzle eşleşen ayrıntılara atlamak için aşağıdaki kılavuzu kullanın:

  • Code yorumlayıcı oturumları: Çıkışlar yürütmeden elde edilir (stdout ve stderr dahil), ancak AppEnvSession Log Analytics tabloları çıkarılmaz. Bkz: Kod yorumlayıcı oturumlarının günlüğe kaydedilmesi.
  • Özel kapsayıcı oturumları: Kapsayıcınız stdout veya stderr yazdığında AppEnvSession Log Analytics tabloları oluşturulur ve platform kayıtları havuz yaşam döngüsü ve olayları için mevcuttur. Bkz. Özel kapsayıcı oturumlarını günlüğe kaydetme.
  • Common: API yanıt üst bilgileri aracılığıyla döndürülen ölçümler Log Analytics'e yazılmaz.

Ortam kaynağında desteklenen oturum kategorilerinin tam listesi için (Microsoft.App/managedEnvironments), Microsoft.App/managedEnvironments için desteklenen günlükler bölümüne bakın.

İlgili içerik

  • Last updated on