Python beépülő modul

Cikk
01/23/2024

A Python beépülő modul egy felhasználó által definiált függvényt (UDF) futtat egy Python-szkripttel. A Python-szkript bemenetként táblázatos adatokat kap, és táblázatos kimenetet hoz létre. A beépülő modul futtatókörnyezetét tesztkörnyezetek üzemeltetik, és a fürt csomópontjain futnak.

Syntax

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

További információ a szintaxis konvenciókról.

Paraméterek

Név	Típus	Kötelező	Leírás
output_schema	`string`	✔️	A `type` Python-kód által visszaadott táblázatos adatok kimeneti sémáját meghatározó literál. Formátuma: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Például: `typeof(col1:string, col2:long)`. A bemeneti séma kiterjesztéséhez használja a következő szintaxist: `typeof(*, col1:string, col2:long)`.
Script	`string`	✔️	A végrehajtandó érvényes Python-szkript. A többsoros sztringek létrehozásához lásd: Használati tippek.
script_parameters	`dynamic`		A Python-szkriptnek fenntartott `kargs` szótárként átadandó névértékpárok tulajdonságcsomagja. További információ: Fenntartott Python-változók.
hint.distribution	`string`		Tipp a beépülő modul végrehajtásának több fürtcsomópont között való elosztásához. Az alapértelmezett érték `single`. `single` azt jelenti, hogy a szkript egyetlen példánya fut végig a teljes lekérdezési adatokon. `per_node` Azt jelenti, hogy ha a Python-blokkot megelőző lekérdezés el van terjesztve, a szkript egy példánya minden csomóponton, a benne lévő adatokon fog futni.
hint.remote	`string`		Ez a tipp csak fürtközi lekérdezések esetén releváns. Az alapértelmezett érték `auto`. `auto` azt jelenti, hogy a kiszolgáló automatikusan dönti el, hogy melyik fürtön fut a Python-kód. Az érték `local` beállításával kényszeríti a Python-kód végrehajtását a helyi fürtön. Akkor használja, ha a Python beépülő modul le van tiltva a távoli fürtön.
external_artifacts	`dynamic`		A felhőtárhelyről elérhető összetevőkhöz tartozó név- és URL-párok tulajdonságcsomagja. További információ: Külső összetevők használata.
spill_to_disk	`bool`		Egy alternatív módszert ad meg a bemeneti tábla Python-tesztkörnyezetbe való szerializálásához. A nagy táblák szerializálásához állítsa be úgy, hogy `true` felgyorsítsa a szerializálást, és jelentősen csökkentse a tesztkörnyezet memóriahasználatát. Az alapértelmezett szint a `true`.

Fenntartott Python-változók

Az alábbi változók a Kusto lekérdezésnyelv és a Python-kód közötti interakcióra vannak fenntartva.

df: A bemeneti táblázatos adatok (a fenti értékek T ) DataFrame-ként pandas .
kargs: A script_parameters argumentum értéke Python-szótárként.
result: A pandas Python-szkript által létrehozott DataFrame, amelynek értéke a beépülő modult követő Kusto lekérdezési operátornak küldött táblázatos adatokká válik.

A beépülő modul engedélyezése

A beépülő modul alapértelmezés szerint le van tiltva. A kezdés előtt tekintse át az előfeltételek listáját. A beépülő modul engedélyezéséhez és a Python-lemezkép verziójának kiválasztásához lásd: Nyelvi bővítmények engedélyezése a fürtön.

Python-tesztkörnyezet képe

A Python-lemezkép verziójának módosításáról a Python nyelvi bővítmények lemezképének módosítása a fürtön című témakörben olvashat.

A különböző Python-rendszerképekhez tartozó csomagok listájának megtekintéséhez tekintse meg a Python-csomagok referenciáját.

Megjegyzés

Alapértelmezés szerint a beépülő modul importálja a numpy-tnp-ként és pandas-tpd-ként. Igény szerint importálhat más modulokat is.
Egyes csomagok nem kompatibilisek a beépülő modult futtató tesztkörnyezet által kikényszerített korlátozásokkal.

Betöltés használata lekérdezési és frissítési szabályzatból

Használja a beépülő modult a következő lekérdezésekben:
- Egy frissítési szabályzat részeként definiálva, amelynek forrástábláját nem streamelési betöltéssel töltik be.
- Futtassa a parancs részeként, amely betölt egy lekérdezésből, például .set-or-append: .
Nem használhatja a beépülő modult egy frissítési szabályzat részeként definiált lekérdezésben, amelynek forrástáblája streamelési betöltéssel van betöltve.

Példák

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

Képernyőkép a szinusz bemutatóról, amelyen a lekérdezés eredménye látható.

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

Fájl	Méret
this_is_a_script	120
this_is_my_first_file	105

Teljesítménnyel kapcsolatos tippek

Csökkentse a beépülő modul bemeneti adatkészletét a minimálisan szükséges mennyiségre (oszlopok/sorok).
- Ha lehetséges, használjon szűrőket a forrásadatkészleten a Kusto lekérdezési nyelvével.
- Ha a forrásoszlopok egy részhalmazán szeretne számítást végezni, csak ezeket az oszlopokat vetje ki a beépülő modul meghívása előtt.
Akkor használja hint.distribution = per_node , ha a szkript logikája terjeszthető.
- A bemeneti adathalmaz particionálásához használhatja a partíciókezelőt is.
Amikor csak lehetséges, használja a Kusto lekérdezési nyelvét a Python-szkript logikájának implementálásához.

Használati tippek

A Python-szkriptet tartalmazó többsoros sztringek lekérdezésszerkesztőben való létrehozásához másolja a Python-szkriptet kedvenc Python-szerkesztőjéből (Jupyter, Visual Studio Code, PyCharm stb.), illessze be a lekérdezésszerkesztőbe, majd helyezze a teljes szkriptet a három egymást követő háttérrendszert tartalmazó sorok közé. Például:

```
python code
```
externaldata Az operátorral beszerezheti egy külső helyen, például az Azure Blob Storage-ban tárolt szkript tartalmát.

Példa

    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

Külső összetevők használata

A felhőbeli tárolóból származó külső összetevők elérhetővé tehetők a szkript számára, és futásidőben használhatók.

A külső összetevők tulajdonsága által hivatkozott URL-címeknek a következőknek kell lenniük:

A fürt feliratszabályzata tartalmazza.
Nyilvánosan elérhető helyen, vagy adja meg a szükséges hitelesítő adatokat a tárolási kapcsolati sztringekben leírtak szerint.

Megjegyzés

Ha külső összetevőket hitelesít felügyelt identitásokkal, a SandboxArtifacts használatot a fürtszintű felügyelt identitásszabályzatban kell meghatározni.

Az összetevők elérhetővé válnak a szkript számára, hogy egy helyi ideiglenes könyvtárból .\Temp( . A tulajdonságcsomagban megadott nevek a helyi fájlnevek. Lásd: Példák.

A külső csomagokra való hivatkozással kapcsolatos információkért lásd: Csomagok telepítése a Python beépülő modulhoz.

Külső összetevő-gyorsítótár frissítése

A lekérdezésekben használt külső összetevőfájlok gyorsítótárazva vannak a fürtön. Ha a felhőtárhelyen frissíti a fájlokat, és azonnali szinkronizálást igényel a fürttel, használhatja a .clear fürtgyorsítótár külső összetevők parancsát. Ez a parancs törli a gyorsítótárazott fájlokat, és biztosítja, hogy a későbbi lekérdezések az összetevők legújabb verziójával fussanak.

Csomagok telepítése a Python beépülő modulhoz

Előfordulhat, hogy saját maga kell telepítenie a csomag(oka)t a következő okok miatt:

A csomag privát, és a sajátja.
A csomag nyilvános, de nem szerepel a beépülő modul alaprendszerképében.

Telepítse a csomagokat az alábbiak szerint:

Előfeltételek

Hozzon létre egy blobtárolót a csomagok üzemeltetéséhez, lehetőleg ugyanabban a helyen, mint a fürt. Tegyük fel például, https://artifactswestus.blob.core.windows.net/pythonhogy a fürt az USA nyugati régiójában található.
Módosítsa a fürt feliratozási szabályzatát , hogy engedélyezze az adott helyhez való hozzáférést.
- Ehhez a módosításhoz AllDatabasesAdmin engedély szükséges.
- Ha például engedélyezni szeretné a hozzáférést a(z) fájlban https://artifactswestus.blob.core.windows.net/pythontalálható blobhoz, futtassa a következő parancsot:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
```

Csomagok telepítése

A PyPi-ban vagy más csatornákon elérhető nyilvános csomagok esetében töltse le a csomagot és annak függőségeit.
- A helyi Windows Python-környezetben található parancsmagablakban futtassa a következőt:
```
pip wheel [-w download-dir] package-name.
```
Hozzon létre egy zip-fájlt, amely tartalmazza a szükséges csomagot és annak függőségeit.
- Privát csomagok esetén tömörítse a csomag mappáját és a függőségei mappáit.
- Nyilvános csomagok esetén tömörítse az előző lépésben letöltött fájlokat.
Megjegyzés
- Győződjön meg arról, hogy letölti a Python-motorral és a tesztkörnyezeti futtatókörnyezet platformjával kompatibilis csomagot (jelenleg 3.6.5 Windows rendszeren)
- Győződjön meg arról, hogy maguk tömörítik a fájlokat, nem pedig a .whl szülőmappájukat.
- Kihagyhatja .whl azokat a csomagokat, amelyek már léteznek ugyanazzal a verzióval az alap tesztkörnyezet lemezképében.
Töltse fel a tömörített fájlt egy blobba az összetevők helyén (az 1. lépésből).
Hívja meg a beépülő modult python .
- Adja meg a external_artifacts paramétert egy nevű tulajdonságcsomaggal, és hivatkozzon a zip-fájlra (a blob URL-címe, beleértve egy SAS-jogkivonatot).
- A beágyazott Python-kódban importálja Zipackage a metódust sandbox_utils , és hívja meg annak metódusát install() a zip-fájl nevével.

Példa

Telepítse a hamis adatokat létrehozó Faker-csomagot .

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 (Azonosító)	Name
1	Gary Tapia
2	Emma Evans
3	Ashley Bowen

A Python beépülő modult használó UDF-függvényekre további példákat a Functions könyvtárban talál.

Syntax

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

További információ a szintaxis konvenciókról.

Paraméterek

Név	Típus	Kötelező	Leírás
output_schema	`string`	✔️	A `type` Python-kód által visszaadott táblázatos adatok kimeneti sémáját meghatározó literál. Formátuma: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Például: `typeof(col1:string, col2:long)`. A bemeneti séma kiterjesztéséhez használja a következő szintaxist: `typeof(*, col1:string, col2:long)`.
Script	`string`	✔️	A végrehajtandó érvényes Python-szkript. A többsoros sztringek létrehozásához lásd: Használati tippek.
script_parameters	`dynamic`		A Python-szkriptnek fenntartott `kargs` szótárként átadandó névértékpárok tulajdonságcsomagja. További információ: Fenntartott Python-változók.
hint.distribution	`string`		Tipp a beépülő modul végrehajtásának több fürtcsomópont között való elosztásához. Az alapértelmezett érték `single`. `single` azt jelenti, hogy a szkript egyetlen példánya fut végig a teljes lekérdezési adatokon. `per_node` Azt jelenti, hogy ha a Python-blokkot megelőző lekérdezés el van terjesztve, a szkript egy példánya minden csomóponton, a benne lévő adatokon fog futni.
hint.remote	`string`		Ez a tipp csak fürtközi lekérdezések esetén releváns. Az alapértelmezett érték `auto`. `auto` azt jelenti, hogy a kiszolgáló automatikusan dönti el, hogy melyik fürtön fut a Python-kód. Az érték `local` beállításával kényszeríti a Python-kód végrehajtását a helyi fürtön. Akkor használja, ha a Python beépülő modul le van tiltva a távoli fürtön.
spill_to_disk	`bool`		Egy alternatív módszert ad meg a bemeneti tábla Python-tesztkörnyezetbe való szerializálásához. A nagy táblák szerializálásához állítsa be úgy, hogy `true` felgyorsítsa a szerializálást, és jelentősen csökkentse a tesztkörnyezet memóriahasználatát. Az alapértelmezett szint a `true`.

Fenntartott Python-változók

Az alábbi változók a Kusto lekérdezésnyelv és a Python-kód közötti interakcióra vannak fenntartva.

df: A bemeneti táblázatos adatok (a fenti értékek T ) DataFrame-ként pandas .
kargs: A script_parameters argumentum értéke Python-szótárként.
result: A pandas Python-szkript által létrehozott DataFrame, amelynek értéke a beépülő modult követő Kusto lekérdezési operátornak küldött táblázatos adatokká válik.

A beépülő modul engedélyezése

A beépülő modul alapértelmezés szerint le van tiltva. Mielőtt hozzákezd, engedélyezze a Python beépülő modult a KQL-adatbázisban.

Python-tesztkörnyezet képe

A különböző Python-rendszerképekhez tartozó csomagok listájának megtekintéséhez tekintse meg a Python-csomagok referenciáját.

Megjegyzés

Alapértelmezés szerint a beépülő modul importálja a numpy-tnp-ként és pandas-tpd-ként. Igény szerint importálhat más modulokat is.
Egyes csomagok nem kompatibilisek a beépülő modult futtató tesztkörnyezet által kikényszerített korlátozásokkal.

Betöltés használata lekérdezési és frissítési szabályzatból

Használja a beépülő modult a következő lekérdezésekben:
- Egy frissítési szabályzat részeként definiálva, amelynek forrástábláját nem streamelési betöltéssel töltik be.
- Futtassa a parancs részeként, amely betölt egy lekérdezésből, például .set-or-append: .
Nem használhatja a beépülő modult egy frissítési szabályzat részeként definiált lekérdezésben, amelynek forrástáblája streamelési betöltéssel van betöltve.

Példák

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

Képernyőkép a szinusz bemutatóról, amelyen a lekérdezés eredménye látható.

Teljesítménnyel kapcsolatos tippek

Csökkentse a beépülő modul bemeneti adatkészletét a minimálisan szükséges mennyiségre (oszlopok/sorok).
- Ha lehetséges, használjon szűrőket a forrásadatkészleten a Kusto lekérdezési nyelvével.
- Ha a forrásoszlopok egy részhalmazán szeretne számítást végezni, csak ezeket az oszlopokat vetje ki a beépülő modul meghívása előtt.
Akkor használja hint.distribution = per_node , ha a szkript logikája terjeszthető.
- A bemeneti adathalmaz particionálásához használhatja a partíciókezelőt is.
Amikor csak lehetséges, használja a Kusto lekérdezési nyelvét a Python-szkript logikájának implementálásához.

Használati tippek

A Python-szkriptet tartalmazó többsoros sztringek lekérdezésszerkesztőben való létrehozásához másolja a Python-szkriptet kedvenc Python-szerkesztőjéből (Jupyter, Visual Studio Code, PyCharm stb.), illessze be a lekérdezésszerkesztőbe, majd helyezze a teljes szkriptet a három egymást követő háttérrendszert tartalmazó sorok közé. Például:

```
python code
```
externaldata Az operátorral beszerezheti egy külső helyen, például az Azure Blob Storage-ban tárolt szkript tartalmát.

Példa

    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

A Python beépülő modult használó UDF-függvényekre további példákat a Functions könyvtárban talál.

Ez a képesség nem támogatott.

Python beépülő modul

Syntax

Paraméterek

Fenntartott Python-változók

A beépülő modul engedélyezése

Python-tesztkörnyezet képe

Betöltés használata lekérdezési és frissítési szabályzatból

Példák

Teljesítménnyel kapcsolatos tippek

Használati tippek

Példa

Külső összetevők használata

Külső összetevő-gyorsítótár frissítése

Csomagok telepítése a Python beépülő modulhoz

Előfeltételek

Csomagok telepítése

Példa

Syntax

Paraméterek

Fenntartott Python-változók

A beépülő modul engedélyezése

Python-tesztkörnyezet képe

Betöltés használata lekérdezési és frissítési szabályzatból

Példák

Teljesítménnyel kapcsolatos tippek

Használati tippek

Példa

Visszajelzés

Visszajelzés

További források

Python beépülő modul

Syntax

Paraméterek

Fenntartott Python-változók

A beépülő modul engedélyezése

Python-tesztkörnyezet képe

Betöltés használata lekérdezési és frissítési szabályzatból

Példák

Teljesítménnyel kapcsolatos tippek

Használati tippek

Példa

Külső összetevők használata

Külső összetevő-gyorsítótár frissítése

Csomagok telepítése a Python beépülő modulhoz

Előfeltételek

Csomagok telepítése

Példa

Kapcsolódó tartalom

Syntax

Paraméterek

Fenntartott Python-változók

A beépülő modul engedélyezése

Python-tesztkörnyezet képe

Betöltés használata lekérdezési és frissítési szabályzatból

Példák

Teljesítménnyel kapcsolatos tippek

Használati tippek

Példa

Kapcsolódó tartalom

Visszajelzés

Visszajelzés

További források