Python beépülő modul

Szolgáltatások váltása a Verzió legördülő listával. További információ a navigációról.
A következőre vonatkozik: ✅ Microsoft Fabric ✅ Azure Data Explorer

A Python beépülő modul egy felhasználó által definiált függvényt (UDF) futtat Egy Python-szkript használatával. A Python-szkript bemenetként táblázatos adatokat kap, és táblázatos kimenetet hoz létre.

Szemantika

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ó szintaxiskonvenciá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. A formátum a következő: 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).
forgatókönyv	string	✔️	A végrehajtandó érvényes Python-szkript. Többsoros sztringek létrehozásához tekintse meg a használati tippeket.
script_parameters	dynamic		A Python-szkriptnek fenntartott kargs szótárként átadandó névértékpárok tulajdonságtáskáját. További információ: Fenntartott Python-változók.
hint.distribution	string		Egy tipp a beépülő modul végrehajtásának több tesztkörnyezetben való elosztásához. Az alapértelmezett érték a single. single Azt jelenti, hogy a szkript egyetlen példánya fut végig a teljes lekérdezési adatokon egyetlen tesztkörnyezetben. per_node Azt jelenti, hogy ha a Python-blokk előtti lekérdezést partíciókra osztja el, az egyes partíciók párhuzamosan futnak a saját tesztkörnyezetében.
hint.remote	string		Ez a tipp csak a fürtök közötti lekérdezések esetében releváns. Az alapértelmezett érték a auto. auto azt jelenti, hogy a kiszolgáló automatikusan dönti el, hogy melyik fürtben hajtja végre a Python-kódot. 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. Használja, ha a Python beépülő modul le van tiltva a távoli fürtön.
external_artifacts	dynamic		A OneLake Storage-ból elérhető összetevőkhöz tartozó név- és URL-párok tulajdonságcsomagja. További információ a külső összetevők használatáról.
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 érték true.

Fenntartott Python-változók

A kusto lekérdezési nyelv és a Python-kód közötti interakcióhoz a következő változók 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 adatok lesznek.

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-csomagreferenciát.

Megjegyzés:

• Alapértelmezés szerint a beépülő modul np-ként és pandas-ként importálja a numpy-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 az üzenetsoros betöltés betölti.
  • Futtassa egy lekérdezésből betöltésre szolgáló parancs részeként, 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élda

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).
  • Lehetőség szerint 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, a beépülő modul meghívása előtt csak ezeket az oszlopokat vetje ki.
• Használja hint.distribution = per_node , ha a szkript logikája terjeszthető.
  • A bemeneti adathalmaz particionálásához a partíciókezelőt is használhatja.
• 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

• Ha többsoros sztringeket szeretne létrehozni a Python-szkriptet tartalmazó lekérdezésszerkesztőben, 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
```

• A külsőadat-operátor használatával szerezze be egy külső helyen, például az Azure Blob Storage-ban tárolt szkript tartalmát.

Példa a Python-szkript külső adatainak olvasására

    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 OneLake Storage-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.

Az összetevők elérhetővé válnak, hogy a szkript egy helyi ideiglenes könyvtárból legyen beolvasva. .\Temp A tulajdonságcsomagban megadott nevek a helyi fájlnevek. Lásd a példát.

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őbeli tárolóban 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

Telepítse a csomagokat az alábbiak szerint:

Előfeltétel

• Hozzon létre egy lakehouse-t a csomagok üzemeltetéséhez, lehetőleg ugyanabban a munkaterületen, mint az eventhouse.

Csomagok telepítése

1. A PyPi-ban vagy más csatornákon elérhető nyilvános csomagok esetén töltse le a csomagot és annak függőségeit.

   • A helyi Windows Python-környezetben található parancsablakból futtassa a következőt:

   pip wheel [-w download-dir] package-name.
   

2. 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:

   • Mindenképpen töltse le a Python-motorral és a tesztkörnyezeti futtatókörnyezet platformjához kompatibilis csomagot (jelenleg 3.10.8 vagy 3.11.7 Windows rendszeren)
   • Ügyeljen arra, hogy a fájlokat ne a .whl szülőmappájukba, hanem magukba tömörítse.
   • Kihagyhatja .whl azokat a csomagokat, amelyek már léteznek ugyanazzal a verzióval az alap tesztkörnyezet rendszerképében.

3. Töltse fel a zip fájlt a tóházba.

4. Másolja a OneLake URL-címet (a tömörített fájl tulajdonságaiból)

5. Hívja meg a beépülő modult python .

   • Adja meg a paramétert external_artifacts egy helyi névvel ellátott tulajdonságcsomaggal és a zip-fájl OneLake URL-címével.
   • A beágyazott Python-kódban importálja Zipackagesandbox_utils és meghívja annak metódusát install() a ZIP-fájl nevével.

Példa külső összetevők használatával

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://msit-onelake.dfs.fabric.microsoft.com/MSIT_DEMO_WS/MSIT_DEMO_LH.Lakehouse/Files/Faker.zip;impersonate'))

azonosító	Név
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.