Dayanıklı İşlevler for Python'da tip güvenlikli serileştirmeye geçiş

Bu makale, Python programlama modelini kullanan mevcut bir Dayanıklı İşlevler uygulamasında tip güvenli (aynı zamanda tipe duyarlı) yük serializasyonunu nasıl benimseyebileceğinizi gösterir. Tür güvenli serileştirme, seri durumdan çıkarılan yükleri beklenen türe göre doğrular ve güvenilmeyen yüklerin seri durumdan çıkarılması riskini ortadan kaldıran güçlendirilmiş katı modu etkinleştirmenize olanak tanır.

Tip güvenli serileştirmenin benimsenmesi, Python kullanan her Dayanıklı İşlevler uygulaması için, güvenlik açısından hassas olmayan uygulamalar da dahil olmak üzere önerilen en iyi uygulamadır. SDK, saklanan verinin işaret ettiği türü sessizce yeniden oluşturmak yerine her yükü kodunuzun beklediği türe göre doğruladığı için, tip uyuşmazlığı hatalarını erken yakalamanıza yardımcı olur. Sıkı mod ayrıca uygulamanızı güvenilmemiş yük seri dışı kullanıma karşı güçlendirir ve bu da kodunuzu daha güvenli hale getirir. azure-functions SDK, katı modu en iyi uygulama olarak önerir ve bu makale, geriye dönük uyumlu adımlarla başlayarak onu kademeli olarak nasıl benimseyebileceğinizi adım adım açıklar.

Bu özellik, birlikte çalışan iki paket üzerinden sunulur:

  • azure-functions Merkezi serileştiricilere (df_dumps / df_loads) isteğe bağlı tip doğrulama ve sıkı tipleme desteği sağlar.
  • azure-functions-durable, tüm Dayanıklı İşlevler yük serileştirmesini bu seri hale getiriciler aracılığıyla yönlendirir ve expected_type parametresini ve otomatik tür keşfini düzenleme ve varlık API'lerine ekler.

Dayanıklı İşlevler'ın hangi verilerin kalıcı olduğu ve özel tiplerin nasıl serileştirildiği hakkında arka plan için bkz. Data persistence and serialization in Dayanıklı İşlevler.

Hangi değişiklikler

Bu özellikten önce Dayanıklı İşlevler, depolanan JSON içine gömülü __module__ ve __class__ alanlarını okuyup sınıfı bulmak için importlib.import_module() çağrısı yaparak özel nesne yüklerini seri durumdan çıkarıyordu. Yükteki sınıfın kodunuzun beklediği tiple eşleşip eşleşmediği kontrol edilmedi.

Tür güvenli serileştirme şunları ekler:

  • Bir yükü seri durumundan çıkaran orkestrasyon ve varlık API’lerinde isteğe bağlı bir expected_type argümanı.
  • Otomatik tür keşfi, v2 ile dekore edilmiş etkinlik ve alt orkestratör işlevlerinizin dönüş türü ek açıklamasını okur ve herhangi bir kod değişikliği yapmadan bunu expected_type olarak kullanır.
  • Katı mod; AZURE_FUNCTIONS_DURABLE_STRICT_TYPING ortam değişkeniyle etkinleştirilen, tür uyumsuzluklarını kesin hatalara dönüştüren ve özel nesneleri importlib.import_module() çağırmadan seri durumdan çıkaran bir mod.

Serileştirme formatı değişmemiştir. Yerleşik tipler yine de sade JSON'a seri hale gelir ve özel nesneler bu {"__class__", "__module__", "__data__"} konvensiyonu kullanmaya devam eder. Bu, gevşek modun tamamen geriye doğru uyumlu olduğu anlamına geliyor: mevcut geçmişler ve uçuş içi orkestrasyonlar eskisi gibi serilikten çıkarmaya devam ediyor.

Prerequisites

  • Python programlama modelini (v1 veya v2) kullanan mevcut bir Dayanıklı İşlevler uygulaması.

  • Merkezi df_dumps / df_loads serileştiricileri içeren aşağıdaki minimum paket sürümleri:

    Python sürümü Minimum azure-functions versiyon
    3.13 ve sonrası 2.2.0
    3.10 – 3.12 1.26.0

  • azure-functions-durable 1.6.0 veya daha sonra.

Note

Kurulu azure-functions paketi df_dumps / df_loads sağlamıyorsa, Dayanıklı İşlevler eski serileştirme işlem hattına geri döner. Sürekli JSON formatı aynı kalır, ancak expected_type argüman ve katı mod hiçbir etkisi yoktur. Tip doğrulamalı serileştirmeyi etkinleştirmek için önceki tablodaki sürümlere yükseltin.

Gevşek mod, sıkı modla karşılaştırıldığında

Tür güvenli serileştirmenin iki modu vardır.

Davranış Gevşek mod (varsayılan) Katı mod
Katılmayı Seç Sürekli aktif AZURE_FUNCTIONS_DURABLE_STRICT_TYPING değerini 1, true ya da yes olarak ayarlayın
Tür uyumsuzluğu Bir uyarı kaydediyor, sonra eski kod çözücüye geri dönüyor Zamlar TypeError
Özel nesne kod çözme importlib.import_module() kullanır (eski yol) expected_type.from_json() doğrudan çağırır; import_module hiçbir zaman çağırmaz
to_json / from_json Sözleşme Değişmemiş Simetrik olmalı ve yerel olarak JSON serileştirilebilir veri üretmelidir (bkz. Güncelleme to_json ve from_json)
Geriye doğru uyumlu Yes No. Kod değişiklikleri gerektirir

Gevşek mod hemen benimsenebilir çünkü doğru tipli yükler için davranış değişmez. Sıkı mod, kasıtlı ve güvenliği güçlendiren bir değişikliktir ve ardından gelen göç adımlarını gerektirir.

Aşamalı geçiş

Tip güvenli serileştirmeyi aşamalı olarak benimseyin. 1. ve 2. adımlar geriye dönük uyumlu ve kendi başına gönderilmesi güvenlidir. 3. ve 4. adımları ancak katı modu etkinleştirmeye hazır olduğunda tamamla.

Adım 1: Paketleri yükseltin

Uygulamanızın gereksinimlerini Ön Koşullar'daki minimum sürümlere güncelleyin. Örneğin, requirements.txtiçinde :

azure-functions>=2.2.0
azure-functions-durable>=1.6.0

Yükseltme yaptıktan sonra uygulamanız gevşek modda çalışmaya devam eder ve davranış değişikliği yoktur. Mevcut uygulamanızın çalışır durumda kalması için başka bir değişiklik yapmanıza gerek yok.

Adım 2: Gevşek mod tip doğrulamasını benimseyin

Gevşek modda, SDK'nın deserileştirilmiş yükleri doğrulayabilmesi ve herhangi bir uyumsuzluk durumunda uyarı kaydetmesini sağlamak için beklenen tipi sağla. Tipi üç şekilde sağlayabilir ve gerektiğinde karıştırabilirsiniz.

Faaliyetlere ve alt orkestratörlere dönüş tipi notalar ekleyin. Python v2 programlama modelinde, SDK dönüş açıklamasını otomatik olarak bulur ve sonucu doğrulamak için kullanır. Çağrı yeri değişikliğine gerek yok.

@myApp.activity_trigger(input_name="city")
def get_weather(city: str) -> WeatherReport:
    return WeatherReport(city=city, temperature_c=21)


@myApp.orchestration_trigger(context_name="context")
def orchestrator(context: df.DurableOrchestrationContext):
    # The WeatherReport return annotation on get_weather is discovered
    # automatically and used to validate the result.
    report = yield context.call_activity("get_weather", "Seattle")
    return report.temperature_c

expected_type değerini açıkça belirtin. Açık expected_type bir açıklama, keşfedilen bir açıklamadan önceliklidir. Bunu, dönüş türü somut bir sınıf olmadığında kullanın. Örneğin, list[Order] veya Optional[Order] gibi genel takma adlar otomatik olarak algılanamaz.

orders = yield context.call_activity("get_orders", customer_id, expected_type=list)

Argüman expected_type , şu düzenleme API'lerinde mevcuttur:

  • call_activity ve call_activity_with_retry
  • call_sub_orchestrator ve call_sub_orchestrator_with_retry
  • call_entity
  • wait_for_external_event
  • get_input

Ve bu varlık API'lerinde, DurableEntityContext aracılığıyla:

  • get_state
  • get_input

Tetikte orkestrasyon giriş tipini bildirin. context.get_input() girdiyi doğrulasın diye orchestration_trigger üzerinde input_type bağımsız değişkenini kullanın. get_input() üzerindeki bir çağrı konumu expected_type öncelik kazanır.

@myApp.orchestration_trigger(context_name="context", input_type=OrderRequest)
def orchestrator(context: df.DurableOrchestrationContext):
    request = context.get_input()  # validated against OrderRequest
    ...

Bu adımdan sonra uygulamanızı çalıştırın ve logger'ın azure.functions.DurableFunctions altında tür uyumsuzluğu uyarıları için kayıtları izleyin. Sıkı moda geçmeden önce uyarıları çöz. Bu adım sadece uyarılar eklediği için, kendi başına dağıtmak güvenlidir.

Tavsiye

Otomatik tip keşif yalnızca somut type nesneleri çözer. list[Order], dict[str, Order] ve Optional[Order] gibi genel takma adlar "tür bilgisi yok" olarak çözülür ve kod çözme yalnızca modül çözümlemesine geri döner. Bu şekiller için doğrulama ihtiyacınız olduğunda açıkça belirtin expected_type .

Adım 3: katı mod için to_json ve from_json öğelerini güncelleyin

Sıkı mod, özel tipler için sözleşmeyi değiştirir. Sıkı modda, to_json(), json.dumps'in sözlükler, listeler, dizeler, sayılar, Boole değerleri veya None gibi yerel olarak serileştirebildiği bir değer döndürmelidir. İç içe özel nesneleri nesne örnekleri olarak döndürmek yerine açıkça serileştirmeniz gerekir ve from_json() bunları aynı şekilde yeniden oluşturmalıdır.

Bu gereksinim, her iç içe yerleştirme düzeyinde depolanan yük verilerinden __module__ dizelerini kaldırır; böylece seri durumdan çıkarma işleminin artık yük verilerindeki tür adlarını çözümlemesi gerekmez.

class Order:
    def __init__(self, item, hat):
        self.item = item
        self.hat = hat

    @staticmethod
    def to_json(obj):
        return {
            "item": obj.item,
            "hat": Hat.to_json(obj.hat),   # explicit, not obj.hat
        }

    @staticmethod
    def from_json(data):
        return Order(
            item=data["item"],
            hat=Hat.from_json(data["hat"]),  # symmetric
        )

Dağıtım sırasında işlemde olan eski yükleri yönetin. Uygulamanız yükseltmeden önce gevşek modda yazılmış veri yüklerini hâlâ okuyabiliyorsa, from_json her iki biçimi de tolere edecek şekilde ayarlayın. Gevşek kodlu iç içe bir değer, zaten yeniden yapılandırılmış bir örnek olarak gelir (eski object_hook tetiklenir), buna karşılık katı kodlu bir değer düz bir sözlük olarak gelir.

    @staticmethod
    def from_json(data):
        hat_data = data["hat"]
        if isinstance(hat_data, Hat):
            hat = hat_data                 # loose-encoded: object already built
        else:
            hat = Hat.from_json(hat_data)  # strict-encoded: plain dict
        return Order(item=data["item"], hat=hat)

Adım 4: Katı modu etkinleştirin

Uygulama ayarını AZURE_FUNCTIONS_DURABLE_STRICT_TYPING1, true, veya yes (harf-duyarsız) olarak ayarlayın.

Yerel local.settings.json dosyanızda:

{
  "Values": {
    "AZURE_FUNCTIONS_DURABLE_STRICT_TYPING": "true"
  }
}

Ya da fonksiyon uygulamanızda bir uygulama ayarı olarak:

az functionapp config appsettings set --name <APP_NAME> --resource-group <RESOURCE_GROUP> --settings AZURE_FUNCTIONS_DURABLE_STRICT_TYPING=true

Sıkı modda:

  • Tür uyumsuzlukları, bir uyarıyı günlüğe yazmak yerine TypeError hatasına neden olur.
  • Özel nesneler doğrudan çağrı expected_type.from_json() ile seri dışı bırakılır, bu yüzden import_module asla kullanılmaz.
  • Özel bir nesneyi seri numarası olmadanexpected_type deserileştiren herhangi bir çağrı sitesi, artırır TypeError. Katı modu etkinleştirmeden önce, bu tür her çağrı noktasının 2. Adım'daki mekanizmalardan biri aracılığıyla bir tür belirtmesini sağlayın.
  • Etkinlik fonksiyonu girdileri özel nesneler olamaz. Aşağıdaki nota bakın.

Important

Sıkı modda, bir etkinlik fonksiyonunun girdisi özel bir nesne olamaz. Konak bir etkinliği çağırdığında, azure-functions etkinlik tetikleyicisi dönüştürücüsü girdiyi expected_type olmadan seri durumdan çıkarır; çünkü Functions worker, etkinliğin parametre türü ek açıklamasını dönüştürücüye iletmez. Bu nedenle özel nesne girişi bir ValueError'de başarısız olur. Bunun yerine etkinlik girdilerini, sözlükler, listeler, metinler, sayılar, Boole değerleri veya None gibi doğal olarak JSON ile serileştirilebilen değerler olarak geçirin. Özel bir nesne göndermeniz gerekiyorsa, çağrıdan önce onu to_json() yöntemiyle dönüştürün ve aktivitenin içinde from_json() ile yeniden oluşturun. Bu sınırlama yalnızca etkinlik girdileri için geçerlidir. Faaliyet dönüş değerleri, orkestrasyon ve varlık girdileri, varlık durumu ve harici olay yükleri, katı modda bir tür sağladığınızda özel türleri destekler.

Important

Sadece tüm uygulama örnekleri güncellendikten ve gevşek kodlanmış geçmişler taşıyan uçuş içi orkestrasyonlar tükendiğinde veya yöntemleriniz from_json her iki şekli de tolere ettiğinde (Adım 3) katı modu etkinleştirin. Yükseltmeden önce başlayan bir orkestrasyon, orijinal, gevşek kodlanmış geçmişini tekrar ediyor. Kodunuz o geçmişi katı modda çözemiyorsa, tekrar oynatma başarısız oluyor.

Mevcut orkestrasyonlar için versiyonlama sonuçları

Tip güvenli serileştirmeye geçmek, yük türleri eski uygulamadakilerden farklıysa çalışan orkestrasyonları bozar. Her orkestrasyon devam ettiğinde, depolanmış geçmişi tekrar oynatır. Bir kod çözme noktası artık önceki bir yükte depolanan türle eşleşmeyen bir tür bekliyorsa, katı mod geçmiş ilk kez yazıldığında mevcut olmayan bir TypeError hatası yükseltir ve bu yeni hata orkestrasyonu bozar. Bu uyumsuzluğu iki yaygın göç değişikliği ortaya çıkarır:

  • Daha önce birden fazla türü taşıyan bir yol. Eğer tek bir deserileştirme yolu, örneğin bir etkinlik sonucu, daha önce farklı nesne türleri döndürebiliyorsa ve siz şimdi bunu tek bir expected_type ile açıklıyorsanız, farklı bir tür kullanan saklanan yük artık bununla eşleşmez ve çözümlenemez.
  • Aktivite girdileri olarak kullanılan özel türler. Etkinlik girdileri katı modda özel nesne olamayacağı için, katı mod benimsendiğinde bu girdiler JSON serileştirilebilir değerlere değiştirilir, bu da çalışan örneklerin kaldığı yük şeklini değiştirir.

Daha genel olarak, bir yükün depolanmış tipini, bir çözümleme sitesinin beklediği türden farklı hale getiren herhangi bir değişiklik, aynı hataya yol açar. Örneğin, özel bir sınıfın örnekleri kalıcı olarak depolandıktan sonra sınıfı yeniden adlandırmak veya taşımak aynı uyumsuzluğa neden olur.

Güvenli bir şekilde taşınmak için şu yöntemlerden birini kullanın:

  • Önerilen: Dağıtımı orkestrasyon sürümlendirmesi ile bölün. Orkestrasyon sürümlendirmesiniStrict sürüm eşleştirme stratejisiyle kullanın; böylece yeni strict mode worker'larınız yalnızca yeni sürümde başlatılan orkestrasyonları işlesin. Bu en iyi uygulama, her iki sürümün de rolling upgrade sırasında bir arada var olmasını sağlar ve tekrar oynatma hatalarını önler.
  • Alternatif: önce boşaltın. Tüm uçuş içi orkestrasyonların bitmesine izin verin, sonra katı modu etkinleştirin.

Üretimde katı modu etkinleştirmeden önce, her özel nesne kod çözme sitesinin bir tür sağladığını ve özel sınıflarınızın görev örnekleri yüklerini sürdürdüğünde sahip oldukları aynı isim ve modülü tuttuğunu doğrulayın.

Çalışan orkestrasyonları etkileyen değişikliklerin güvenli bir şekilde dağıtılmasıyla ilgili daha kapsamlı bilgi için Dayanıklı İşlevler'ta Sürüm Oluşturma bölümüne bakın.

Güvenlik sağlamlaştırma

Sıkı mod, özel nesne yüklerinin seri durumdan çıkarılma biçimini daha sıkı hale getirir. Bir türü bulmak için depolanmış veya gelen bir veri yüküne gömülü modül ve sınıf adlarına güvenmek yerine, katı mod özel nesneleri kodunuzun sağladığı expected_type kullanarak yeniden oluşturur ve katı moddaki to_json() çıktısı modül adlarını hiçbir iç içe geçme düzeyinde kalıcı olarak saklamaz. Bu değişiklik, seri durumdan çıkarma sırasında yük verisinden keyfi tür adlarını çözme gereksinimini ortadan kaldırır; bu da yükte taşınan tür bilgisine güvenmeye kıyasla katmanlı savunma açısından bir iyileştirmedir.

Yükleriniz hassas veri içerebiliyorsa, ayrıca Hassas verilerle çalış seçeneğini inceleyin.

İlgili içerik

  • Last updated on