Python eklentisi

Python eklentisi, Python betiği kullanarak kullanıcı tanımlı bir işlev (UDF) çalıştırır. Python betiği, girişi olarak tablosal verileri alır ve tablosal çıkış üretir. Eklentinin çalışma zamanı, kümenin düğümlerinde çalıştırılan korumalı alanlarda barındırılır.

Syntax

T|evaluate [hint.distribution= (singleper_node | )] [hint.remote= (autolocal | )] python(output_schema,betiği [,script_parameters] [,external_artifacts][,spill_to_disk])

Söz dizimi kuralları hakkında daha fazla bilgi edinin.

Parametreler

Ad Tür Gerekli Açıklama
output_schema string ✔️ type Python kodu tarafından döndürülen tablosal verilerin çıkış şemasını tanımlayan değişmez değer. Biçim: typeof(ColumnName:ColumnType[, ...]). Örneğin, typeof(col1:string, col2:long). Giriş şemasını genişletmek için aşağıdaki söz dizimini kullanın: typeof(*, col1:string, col2:long).
Komut dosyası string ✔️ Yürütülecek geçerli Python betiği. Çok satırlı dizeler oluşturmak için bkz . Kullanım ipuçları.
script_parameters dynamic Python betiğine ayrılmış kargs sözlük olarak geçirilecek ad değeri çiftlerinin özellik paketi. Daha fazla bilgi için bkz . Ayrılmış Python değişkenleri.
hint.distribution string Eklentinin yürütülmesinin birden çok küme düğümüne dağıtılması için bir ipucu. single varsayılan değerdir. single betiğin tek bir örneğinin sorgu verilerinin tamamı üzerinde çalıştırılacağı anlamına gelir. per_node , Python bloğundan önceki sorgu dağıtılırsa betiğin bir örneğinin içerdiği veriler üzerinde her düğümde çalıştırılacağı anlamına gelir.
hint.remote string Bu ipucu yalnızca kümeler arası sorgular için geçerlidir. auto varsayılan değerdir. auto , sunucunun Python kodunun hangi kümede yürütülürse o kümede otomatik olarak karar aldığı anlamına gelir. Değeri yerel kümede Python kodunu yürütmeye zorlamak için local ayarlama. Python eklentisinin uzak kümede devre dışı bırakılması durumunda bu eklentiyi kullanın.
external_artifacts dynamic Bulut depolama alanından erişilebilen yapıtlar için ad ve URL çiftlerinden oluşan bir özellik paketi. Daha fazla bilgi için bkz. Dış yapıtları kullanma.
spill_to_disk bool Giriş tablosunu Python korumalı alanında seri hale getirmek için alternatif bir yöntem belirtir. Büyük tabloları seri hale getirmek için serileştirmeyi hızlandırmak ve korumalı alan bellek tüketimini önemli ölçüde azaltmak için true olarak ayarlayın. true varsayılan değerdir.

Ayrılmış Python değişkenleri

Aşağıdaki değişkenler Kusto Sorgu Dili ile Python kodu arasındaki etkileşim için ayrılmıştır.

  • df: DataFrame olarak pandas giriş tablosal verileri (yukarıdaki değerleriT).
  • kargs: python sözlüğü olarak script_parameters bağımsız değişkeninin değeri.
  • resultpandas: Python betiği tarafından oluşturulan ve değeri eklentiyi izleyen Kusto sorgu işlecine gönderilen tablosal veriler haline gelen DataFrame.

Eklentiyi etkinleştirme

Eklenti varsayılan olarak devre dışıdır. Başlamadan önce önkoşul listesini gözden geçirin. Eklentiyi etkinleştirmek ve Python görüntüsünün sürümünü seçmek için bkz . Kümenizde dil uzantılarını etkinleştirme.

Python korumalı alan görüntüsü

Python görüntüsünün sürümünü değiştirmek için bkz. Kümenizdeki Python dil uzantıları görüntüsünü değiştirme.

Farklı Python görüntülerine yönelik paketlerin listesini görmek için bkz. Python paket başvurusu.

Not

  • Varsayılan olarak, eklenti numpy'yinp ve pandas'ıpd olarak içeri aktarır. İsteğe bağlı olarak, gerektiğinde diğer modülleri içeri aktarabilirsiniz.
  • Bazı paketler, eklentinin çalıştırıldığı korumalı alan tarafından zorunlu kılınan sınırlamalarla uyumsuz olabilir.

Sorgu ve güncelleştirme ilkesinden alım kullanma

  • Eklentiyi şu sorgularda kullanın:
  • Eklentiyi, kaynak tablosu akış alımı kullanılarak alınan bir güncelleştirme ilkesinin parçası olarak tanımlanan bir sorguda kullanamazsınız.

Örnekler

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart 

Sorgu sonucunu gösteren sinüs tanıtımının ekran görüntüsü.

print "This is an example for using 'external_artifacts'"
| evaluate python(
    typeof(File:string, Size:string), ```if 1:
    import os
    result = pd.DataFrame(columns=['File','Size'])
    sizes = []
    path = '.\\\\Temp'
    files = os.listdir(path)
    result['File']=files
    for file in files:
        sizes.append(os.path.getsize(path + '\\\\' + file))
    result['Size'] = sizes
    ```,
    external_artifacts = 
        dynamic({"this_is_my_first_file":"https://kustoscriptsamples.blob.core.windows.net/samples/R/sample_script.r",
                 "this_is_a_script":"https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py"})
)
File Boyut
this_is_a_script 120
this_is_my_first_file 105

Performans ipuçları

  • Eklentinin giriş veri kümesini gereken minimum miktara (sütunlar/satırlar) düşürün.
    • Kusto'nun sorgu diliyle mümkün olduğunda kaynak veri kümesindeki filtreleri kullanın.
    • Kaynak sütunların bir alt kümesi üzerinde hesaplama yapmak için eklentiyi çağırmadan önce yalnızca bu sütunları yansıtın.
  • Betiğinizdeki mantık dağıtılabilir olduğunda kullanın hint.distribution = per_node .
  • Mümkün olduğunda Python betiğinizin mantığını uygulamak için Kusto'nun sorgu dilini kullanın.

Kullanım ipuçları

  • Sorgu düzenleyicinizde Python betiğini içeren çok satırlı dizeler oluşturmak için, Python betiğinizi sık kullandığınız Python düzenleyicisinden kopyalayın (Jupyter, Visual Studio Code, PyCharm vb.), sorgu düzenleyicinize yapıştırın ve ardından ardışık üç ters köşe içeren satırların arasına betiğin tamamını ekleyin. Örnek:

    ```
    python code
    ```

  • externaldata Azure Blob depolama gibi bir dış konumda depoladığınız bir betiğin içeriğini almak için işlecini kullanın.

Örnek

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate python(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart 

Dış Yapıtları Kullanma

Bulut depolamadan dış yapıtlar betik için kullanılabilir hale getirilebilir ve çalışma zamanında kullanılabilir.

Dış yapıtlar özelliği tarafından başvuruda bulunulur URL'ler:

Not

Yönetilen Kimlikler kullanarak dış yapıtların kimliğini doğrularken, kullanımın SandboxArtifacts küme düzeyinde yönetilen kimlik ilkesinde tanımlanması gerekir.

Yapıtlar, betiğin yerel geçici bir dizinden .\Temp(. ) tüketmesi için kullanılabilir hale getirilir. Özellik paketinde sağlanan adlar yerel dosya adları olarak kullanılır. Bkz. Örnekler.

Dış paketlere başvurma hakkında bilgi için bkz. Python eklentisi için paketleri yükleme.

Dış yapıt önbelleği yenileniyor

Sorgularda kullanılan dış yapıt dosyaları kümenizde önbelleğe alınır. Bulut depolamadaki dosyalarınızda güncelleştirmeler yapıyorsanız ve kümenizle hemen eşitleme gerektiriyorsanız.clear cluster cache external-artifacts komutunu kullanabilirsiniz. Bu komut önbelleğe alınan dosyaları temizler ve izleyen sorguların yapıtların en son sürümüyle çalışmasını sağlar.

Python eklentisi için paketleri yükleme

Aşağıdaki nedenlerle paketleri kendiniz yüklemeniz gerekebilir:

  • Paket özeldir ve sizindir.
  • Paket geneldir ancak eklentinin temel görüntüsüne dahil değildir.

Paketleri aşağıdaki gibi yükleyin:

Önkoşullar

  1. Paketleri barındırmak için tercihen kümenizle aynı yerde bir blob kapsayıcısı oluşturun. Örneğin, https://artifactswestus.blob.core.windows.net/pythonkümenizin Batı ABD'de olduğunu varsayarsak.

  2. Bu konuma erişime izin vermek için kümenin belirtme çizgisi ilkesini değiştirin.

    • Bu değişiklik Için AllDatabasesAdmin izinleri gerekir.

    • Örneğin, içinde https://artifactswestus.blob.core.windows.net/pythonbulunan bir bloba erişimi etkinleştirmek için aşağıdaki komutu çalıştırın:

    .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
    

Paketleri yükleme

  1. PyPi veya diğer kanallardaki genel paketler için paketi ve bağımlılıklarını indirin.

    • Yerel Windows Python ortamınızdaki bir cmd penceresinde şunu çalıştırın:
    pip wheel [-w download-dir] package-name.
    
  2. Gerekli paketi ve bağımlılıklarını içeren bir zip dosyası oluşturun.

    • Özel paketler için paketin klasörünü ve bağımlılıklarının klasörlerini sıkıştırın.
    • Genel paketler için, önceki adımda indirilen dosyaları sıkıştırın.

    Not

    • Python altyapısı ve korumalı alan çalışma zamanı platformuyla uyumlu paketi indirdiğinizden emin olun (şu anda Windows'da 3.6.5)
    • Dosyaların üst klasörlerini değil kendilerinin .whl sıkıştırdığından emin olun.
    • Temel korumalı alan görüntüsünde aynı sürüme sahip paketler için dosyaları atlayabilirsiniz .whl .
  3. Sıkıştırılmış dosyayı yapıtlar konumundaki bir bloba yükleyin (1. adımdan).

  4. Eklentiyi çağırın python .

    • Parametreyi external_artifacts ad ve zip dosyasına (SAS belirteci de dahil olmak üzere blobun URL'si) başvuru içeren bir özellik paketiyle belirtin.
    • Satır içi python kodunuzda, öğesini içeri aktarın Zipackagesandbox_utils ve zip dosyasının adıyla yöntemini çağırın install() .

Örnek

Sahte veri oluşturan Faker paketini yükleyin.

range ID from 1 to 3 step 1 
| extend Name=''
| evaluate python(typeof(*), ```if 1:
    from sandbox_utils import Zipackage
    Zipackage.install("Faker.zip")
    from faker import Faker
    fake = Faker()
    result = df
    for i in range(df.shape[0]):
        result.loc[i, "Name"] = fake.name()
    ```,
    external_artifacts=bag_pack('faker.zip', 'https://artifacts.blob.core.windows.net/kusto/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
ID Name
1 Gary Tapia
2 Emma Evans
3 Ashley Bowen

Python eklentisini kullanan UDF işlevlerine daha fazla örnek için İşlevler kitaplığına bakın.

Python eklentisi, Python betiği kullanarak kullanıcı tanımlı bir işlev (UDF) çalıştırır. Python betiği, girdi olarak tablosal verileri alır ve tablosal çıkış üretir.

Syntax

T|evaluate [hint.distribution= (single | per_node)] [hint.remote= (auto | local)] python(output_schema,betiği [,script_parameters] [,spill_to_disk])

Söz dizimi kuralları hakkında daha fazla bilgi edinin.

Parametreler

Ad Tür Gerekli Açıklama
output_schema string ✔️ type Python kodu tarafından döndürülen tablosal verilerin çıkış şemasını tanımlayan değişmez değer. Biçim: typeof(ColumnName:ColumnType[, ...]). Örneğin, typeof(col1:string, col2:long). Giriş şemasını genişletmek için aşağıdaki söz dizimini kullanın: typeof(*, col1:string, col2:long).
Komut dosyası string ✔️ Yürütülecek geçerli Python betiği. Çok satırlı dizeler oluşturmak için bkz . Kullanım ipuçları.
script_parameters dynamic Python betiğine ayrılmış kargs sözlük olarak geçirilecek ad değeri çiftlerinden oluşan bir özellik paketi. Daha fazla bilgi için bkz . Ayrılmış Python değişkenleri.
hint.distribution string Eklentinin yürütülmesinin birden çok küme düğümüne dağıtılması için bir ipucu. single varsayılan değerdir. single betiğin tek bir örneğinin sorgu verilerinin tamamı üzerinde çalıştırılacağı anlamına gelir. per_node , Python bloğundan önceki sorgu dağıtılırsa betiğin bir örneğinin içerdiği veriler üzerinde her düğümde çalıştırılacağı anlamına gelir.
hint.remote string Bu ipucu yalnızca kümeler arası sorgular için geçerlidir. auto varsayılan değerdir. auto , sunucunun Python kodunun hangi kümede yürütülürse otomatik olarak karar aldığı anlamına gelir. değeri local , yerel kümede Python kodunu yürütmeye zorlar olarak ayarlayın. Python eklentisinin uzak kümede devre dışı bırakılması durumunda bu eklentiyi kullanın.
spill_to_disk bool Giriş tablosunu Python korumalı alanında seri hale getirmek için alternatif bir yöntem belirtir. Büyük tabloları seri hale getirmek için serileştirmeyi hızlandırmak ve korumalı alan bellek tüketimini önemli ölçüde azaltmak için true olarak ayarlayın. true varsayılan değerdir.

Ayrılmış Python değişkenleri

Aşağıdaki değişkenler Kusto Sorgu Dili ile Python kodu arasındaki etkileşim için ayrılmıştır.

  • df: DataFrame olarak pandas giriş tablosal verileri (yukarıdaki değerleriT).
  • kargs: python sözlüğü olarak script_parameters bağımsız değişkeninin değeri.
  • resultpandas: Python betiği tarafından oluşturulan ve değeri eklentiyi izleyen Kusto sorgu işlecine gönderilen tablosal veriler haline gelen DataFrame.

Eklentiyi etkinleştirme

Eklenti varsayılan olarak devre dışıdır. Başlamadan önce KQL veritabanınızda Python eklentisini etkinleştirin .

Python korumalı alanı görüntüsü

Farklı Python görüntülerine yönelik paketlerin listesini görmek için bkz. Python paket başvurusu.

Not

  • Varsayılan olarak, eklenti numpy'yinp ve pandas'ıpd olarak içeri aktarır. İsteğe bağlı olarak, gerektiğinde diğer modülleri içeri aktarabilirsiniz.
  • Bazı paketler eklentinin çalıştırıldığı korumalı alan tarafından uygulanan sınırlamalarla uyumsuz olabilir.

Sorgu ve güncelleştirme ilkesinden alımı kullanma

  • Eklentiyi aşağıdaki sorgularda kullanın:
  • Eklentiyi, kaynak tablosu akış alımı kullanılarak alınan bir güncelleştirme ilkesinin parçası olarak tanımlanan bir sorguda kullanamazsınız.

Örnekler

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart 

Sorgu sonucunu gösteren sinüs tanıtımını gösteren ekran görüntüsü.

Performans ipuçları

  • Eklentinin giriş veri kümesini gereken minimum miktara (sütunlar/satırlar) düşürün.
    • Mümkün olduğunda Kusto'nun sorgu diliyle kaynak veri kümesindeki filtreleri kullanın.
    • Kaynak sütunların bir alt kümesi üzerinde hesaplama yapmak için eklentiyi çağırmadan önce yalnızca bu sütunları yansıtın.
  • Betiğinizdeki mantık dağıtılabilir olduğunda kullanın hint.distribution = per_node .
  • Mümkün olduğunda Python betiğinizin mantığını uygulamak için Kusto'nun sorgu dilini kullanın.

Kullanım ipuçları

  • Sorgu düzenleyicinizde Python betiğini içeren çok satırlı dizeler oluşturmak için, Python betiğinizi sık kullandığınız Python düzenleyicisinden (Jupyter, Visual Studio Code, PyCharm vb.) kopyalayın, sorgu düzenleyicinize yapıştırın ve ardından tam betiği ardışık üç ters köşe içeren satırlar arasına alın. Örnek:

    ```
    python code
    ```

  • externaldata Azure Blob depolama gibi bir dış konumda depoladığınız bir betiğin içeriğini almak için işlecini kullanın.

Örnek

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate python(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart 

Python eklentisini kullanan UDF işlevlerine daha fazla örnek için İşlevler kitaplığına bakın.

Bu özellik desteklenmez.