Python beépülő modul
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ékekT
) DataFrame-kéntpandas
.kargs
: A script_parameters argumentum értéke Python-szótárként.result
: Apandas
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
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/python
hogy 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/python
talá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ódustsandbox_utils
, és hívja meg annak metódusátinstall()
a zip-fájl nevével.
- Adja meg a
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 |
Kapcsolódó tartalom
A Python beépülő modult használó UDF-függvényekre további példákat a Functions könyvtárban talál.
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.
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ékekT
) DataFrame-kéntpandas
.kargs
: A script_parameters argumentum értéke Python-szótárként.result
: Apandas
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
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
Kapcsolódó tartalom
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.
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: