Modul plug-in Pythonu
Modul plug-in Pythonu spouští uživatelem definovanou funkci (UDF) pomocí skriptu Pythonu. Skript Pythonu získá jako vstup tabulková data a vytvoří tabulkový výstup. Modul runtime modulu plug-in je hostovaný v sandboxech spuštěných na uzlech clusteru.
Syntaxe
T evaluate
|
[hint.distribution
=
(single
per_node
| )] [hint.remote
=
(auto
local
| )] python(
output_schema,
skript [ ,
script_parameters] [,
external_artifacts][,
spill_to_disk])
Přečtěte si další informace o konvencích syntaxe.
Parametry
Název | Type | Požadováno | Popis |
---|---|---|---|
output_schema | string |
✔️ | Literál type , který definuje výstupní schéma tabulkových dat vrácených kódem Pythonu. Formát je: typeof( ColumnName: ColumnType[, ...]) . Například typeof(col1:string, col2:long) . Chcete-li rozšířit vstupní schéma, použijte následující syntaxi: typeof(*, col1:string, col2:long) . |
skript | string |
✔️ | Platný skript Pythonu, který se má spustit. Pokud chcete generovat víceřádkové řetězce, přečtěte si tipy k používání. |
script_parameters | dynamic |
Sada vlastností párů hodnot názvů, které se mají předat skriptu Pythonu jako vyhrazený kargs slovník. Další informace najdete v tématu Rezervované proměnné Pythonu. |
|
hint.distribution | string |
Tip pro spuštění modulu plug-in, který se má distribuovat napříč několika uzly clusteru. Výchozí hodnota je single . single znamená, že jedna instance skriptu se spustí přes celá data dotazu. per_node znamená, že pokud je dotaz před distribuovaným blokem Pythonu, instance skriptu se spustí na každém uzlu na datech, která obsahuje. |
|
hint.remote | string |
Tento tip je relevantní pouze pro dotazy napříč clustery. Výchozí hodnota je auto . auto znamená, že se server rozhodne automaticky v clusteru, ve kterém se kód Pythonu spustí. Nastavení hodnoty pro local vynutí spuštění kódu Pythonu v místním clusteru. Použijte ho v případě, že je modul plug-in Pythonu ve vzdáleném clusteru zakázaný. |
|
external_artifacts | dynamic |
Sada vlastností párů názvů a adres URL pro artefakty, které jsou přístupné z cloudového úložiště. Další informace najdete v tématu Použití externích artefaktů. | |
spill_to_disk | bool |
Určuje alternativní metodu serializace vstupní tabulky do sandboxu Pythonu. Pro serializaci velkých tabulek je nastavena na true zrychlení serializace a výrazně snížit spotřebu paměti sandboxu. Výchozí hodnota je true . |
Rezervované proměnné Pythonu
Následující proměnné jsou vyhrazené pro interakci mezi dotazovací jazyk Kusto a kódem Pythonu.
df
: Vstupní tabulková data (hodnotyT
výše) jakopandas
datový rámec.kargs
: Hodnota argumentu script_parameters jako slovník Pythonu.result
pandas
: Datový rámec vytvořený skriptem Pythonu, jehož hodnota se stane tabulkovými daty, která se odešlou do operátoru dotazu Kusto, který následuje za modulem plug-in.
Povolení modulu plug-in
Modul plug-in je ve výchozím nastavení zakázaný. Než začnete, projděte si seznam požadavků. Pokud chcete modul plug-in povolit a vybrat verzi image Pythonu, přečtěte si téma Povolení jazykových rozšíření v clusteru.
Obrázek sandboxu Pythonu
Pokud chcete změnit verzi image Pythonu, přečtěte si téma Změna image rozšíření jazyka Python ve vašem clusteru.
Seznam balíčků pro různé image Pythonu najdete v referenčních informacích k balíčkům Pythonu.
Poznámka:
- Ve výchozím nastavení modul plug-in importuje numpy jako np a pandas jako pd. Volitelně můžete podle potřeby importovat další moduly.
- Některé balíčky můžou být nekompatibilní s omezeními vynucenými sandboxem, ve kterém je modul plug-in spuštěný.
Použití příjmu dat z dotazů a zásad aktualizací
- Modul plug-in použijte v dotazech, které jsou:
- Definuje se jako součást zásady aktualizace, jejíž zdrojová tabulka se ingestuje na příjem dat bez streamování .
- Spusťte jako součást příkazu, který ingestuje z dotazu, například
.set-or-append
.
- Modul plug-in nemůžete použít v dotazu definovaném jako součást zásad aktualizace, jejichž zdrojová tabulka se ingestuje pomocí příjmu streamu.
Příklady
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"})
)
Soubor | Velikost |
---|---|
this_is_a_script | 120 |
this_is_my_first_file | 105 |
Tipy týkající se výkonu
- Snižte vstupní datovou sadu modulu plug-in na minimální požadované množství (sloupce nebo řádky).
- Pokud je to možné, použijte filtry u zdrojové datové sady s dotazovacím jazykem Kusto.
- Pokud chcete provést výpočet pro podmnožinu zdrojových sloupců, projektujte před vyvoláním modulu plug-in pouze tyto sloupce.
- Použijte
hint.distribution = per_node
pokaždé, když je logika ve vašem skriptu distribuovatelná.- K dělení vstupní datové sady můžete použít také operátor oddílu.
- Pokud je to možné, použijte dotazovací jazyk Kusto k implementaci logiky skriptu Pythonu.
Tipy k používání
Pokud chcete vygenerovat víceřádkové řetězce obsahující skript Pythonu v editoru dotazů, zkopírujte skript Pythonu z oblíbeného editoru Pythonu (Jupyter, Visual Studio Code, PyCharm atd.), vložte ho do editoru dotazů a pak celý skript uzavřete mezi řádky obsahující tři po sobě jdoucí backticky. Příklad:
```
python code
```
externaldata
Operátor slouží k získání obsahu skriptu, který jste uložili do externího umístění, jako je azure Blob Storage.
Příklad
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
Použití externích artefaktů
Externí artefakty z cloudového úložiště je možné zpřístupnit pro skript a použít je za běhu.
Adresy URL odkazované vlastností externích artefaktů musí být:
- Součástí zásad popisku clusteru.
- V veřejně dostupném umístění nebo zadejte nezbytné přihlašovací údaje, jak je vysvětleno v připojovací řetězec úložiště.
Poznámka:
Při ověřování externích artefaktů pomocí spravovaných SandboxArtifacts
identit musí být použití definované v zásadách spravované identity na úrovni clusteru.
Artefakty jsou zpřístupněny pro skript, který může využívat z místního dočasného adresáře . .\Temp
Názvy zadané v kontejneru vlastností se používají jako názvy místních souborů. Viz příklady.
Informace o odkazování na externí balíčky naleznete v tématu Instalace balíčků pro modul plug-in Python.
Aktualizace mezipaměti externích artefaktů
Soubory externích artefaktů využívané v dotazech se ukládají do mezipaměti ve vašem clusteru. Pokud aktualizujete soubory v cloudovém úložišti a vyžadujete okamžitou synchronizaci s clusterem, můžete použít příkaz .clear cluster cache external-artifacts. Tento příkaz vymaže soubory uložené v mezipaměti a zajistí, že následné dotazy poběží s nejnovější verzí artefaktů.
Instalace balíčků pro modul plug-in Pythonu
Možná budete muset nainstalovat balíčky sami, a to z následujících důvodů:
- Balíček je soukromý a je vlastní.
- Balíček je veřejný, ale není součástí základní image modulu plug-in.
Balíčky nainstalujte následujícím způsobem:
Požadavky
Vytvořte kontejner objektů blob pro hostování balíčků, nejlépe na stejném místě jako cluster. Předpokládejme například,
https://artifactswestus.blob.core.windows.net/python
že váš cluster je v oblasti USA – západ.Upravte zásady popisku clusteru tak, aby umožňovaly přístup k danému umístění.
Tato změna vyžaduje oprávnění AllDatabasesAdmin .
Pokud například chcete povolit přístup k objektu blob umístěnému v
https://artifactswestus.blob.core.windows.net/python
, spusťte následující příkaz:
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
Instalace balíčků
U veřejných balíčků v PyPi nebo jiných kanálech stáhněte balíček a jeho závislosti.
- V okně příkazového panelu v místním prostředí Windows Pythonu spusťte:
pip wheel [-w download-dir] package-name.
Vytvořte soubor ZIP, který obsahuje požadovaný balíček a jeho závislosti.
- U privátních balíčků zazipujte složku balíčku a složky jejích závislostí.
- U veřejných balíčků zazipujte soubory, které byly staženy v předchozím kroku.
Poznámka:
- Nezapomeňte stáhnout balíček, který je kompatibilní s modulem Python a platformou modulu sandbox runtime (aktuálně 3.6.5 ve Windows).
- Nezapomeňte soubory zazipovat
.whl
sami, a ne jejich nadřazenou složku. - Soubory pro balíčky, které už existují se stejnou verzí v základní imagi sandboxu, můžete přeskočit
.whl
.
Nahrajte komprimovaný soubor do objektu blob v umístění artefaktů (z kroku 1).
Zavolejte modul plug-in
python
.external_artifacts
Zadejte parametr s názvem a odkazem na soubor ZIP (adresa URL objektu blob včetně tokenu SAS).- Ve vloženého kódu Pythonu naimportujte
Zipackage
sandbox_utils
a volejte jehoinstall()
metodu s názvem souboru ZIP.
Příklad
Nainstalujte balíček Faker, který generuje falešná data.
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 |
---|---|
0 | Gary Tapia |
2 | Emma Evans |
3 | Ashley Bowen |
Související obsah
Další příklady funkcí definované uživatelem, které používají modul plug-in Pythonu, najdete v knihovně Functions.
Modul plug-in Pythonu spouští uživatelem definovanou funkci (UDF) pomocí skriptu Pythonu. Skript Pythonu získá jako vstup tabulková data a vytvoří tabulkový výstup.
Syntaxe
T evaluate
|
[hint.distribution
=
(single
| per_node
)] [hint.remote
=
(auto
| local
)] python(
output_schema ,
skript [,
script_parameters] [,
spill_to_disk])
Přečtěte si další informace o konvencích syntaxe.
Parametry
Název | Type | Požadováno | Popis |
---|---|---|---|
output_schema | string |
✔️ | Literál type , který definuje výstupní schéma tabulkových dat vrácených kódem Pythonu. Formát je: typeof( ColumnName: ColumnType[, ...]) . Například typeof(col1:string, col2:long) . Chcete-li rozšířit vstupní schéma, použijte následující syntaxi: typeof(*, col1:string, col2:long) . |
skript | string |
✔️ | Platný skript Pythonu, který se má spustit. Pokud chcete generovat víceřádkové řetězce, přečtěte si tipy k používání. |
script_parameters | dynamic |
Sada vlastností párů hodnot názvů, které se mají předat skriptu Pythonu jako vyhrazený kargs slovník. Další informace najdete v tématu Rezervované proměnné Pythonu. |
|
hint.distribution | string |
Tip pro spuštění modulu plug-in, který se má distribuovat napříč několika uzly clusteru. Výchozí hodnota je single . single znamená, že jedna instance skriptu se spustí přes celá data dotazu. per_node znamená, že pokud je dotaz před distribuovaným blokem Pythonu, instance skriptu se spustí na každém uzlu na datech, která obsahuje. |
|
hint.remote | string |
Tento tip je relevantní pouze pro dotazy napříč clustery. Výchozí hodnota je auto . auto znamená, že se server rozhodne automaticky v clusteru, ve kterém se kód Pythonu spustí. Nastavení hodnoty pro local vynutí spuštění kódu Pythonu v místním clusteru. Použijte ho v případě, že je modul plug-in Pythonu ve vzdáleném clusteru zakázaný. |
|
spill_to_disk | bool |
Určuje alternativní metodu serializace vstupní tabulky do sandboxu Pythonu. Pro serializaci velkých tabulek je nastavena na true zrychlení serializace a výrazně snížit spotřebu paměti sandboxu. Výchozí hodnota je true . |
Rezervované proměnné Pythonu
Následující proměnné jsou vyhrazené pro interakci mezi dotazovací jazyk Kusto a kódem Pythonu.
df
: Vstupní tabulková data (hodnotyT
výše) jakopandas
datový rámec.kargs
: Hodnota argumentu script_parameters jako slovník Pythonu.result
pandas
: Datový rámec vytvořený skriptem Pythonu, jehož hodnota se stane tabulkovými daty, která se odešlou do operátoru dotazu Kusto, který následuje za modulem plug-in.
Povolení modulu plug-in
Modul plug-in je ve výchozím nastavení zakázaný. Než začnete, povolte modul plug-in Pythonu v databázi KQL.
Obrázek sandboxu Pythonu
Seznam balíčků pro různé image Pythonu najdete v referenčních informacích k balíčkům Pythonu.
Poznámka:
- Ve výchozím nastavení modul plug-in importuje numpy jako np a pandas jako pd. Volitelně můžete podle potřeby importovat další moduly.
- Některé balíčky můžou být nekompatibilní s omezeními vynucenými sandboxem, ve kterém je modul plug-in spuštěný.
Použití příjmu dat z dotazů a zásad aktualizací
- Modul plug-in použijte v dotazech, které jsou:
- Definuje se jako součást zásady aktualizace, jejíž zdrojová tabulka se ingestuje na příjem dat bez streamování .
- Spusťte jako součást příkazu, který ingestuje z dotazu, například
.set-or-append
.
- Modul plug-in nemůžete použít v dotazu definovaném jako součást zásad aktualizace, jejichž zdrojová tabulka se ingestuje pomocí příjmu streamu.
Příklady
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
Tipy týkající se výkonu
- Snižte vstupní datovou sadu modulu plug-in na minimální požadované množství (sloupce nebo řádky).
- Pokud je to možné, použijte filtry u zdrojové datové sady s dotazovacím jazykem Kusto.
- Pokud chcete provést výpočet pro podmnožinu zdrojových sloupců, projektujte před vyvoláním modulu plug-in pouze tyto sloupce.
- Použijte
hint.distribution = per_node
pokaždé, když je logika ve vašem skriptu distribuovatelná.- K dělení vstupní datové sady můžete použít také operátor oddílu.
- Pokud je to možné, použijte dotazovací jazyk Kusto k implementaci logiky skriptu Pythonu.
Tipy k používání
Pokud chcete vygenerovat víceřádkové řetězce obsahující skript Pythonu v editoru dotazů, zkopírujte skript Pythonu z oblíbeného editoru Pythonu (Jupyter, Visual Studio Code, PyCharm atd.), vložte ho do editoru dotazů a pak celý skript uzavřete mezi řádky obsahující tři po sobě jdoucí backticky. Příklad:
```
python code
```
externaldata
Operátor slouží k získání obsahu skriptu, který jste uložili do externího umístění, jako je azure Blob Storage.
Příklad
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
Související obsah
Další příklady funkcí definované uživatelem, které používají modul plug-in Pythonu, najdete v knihovně Functions.
Tato funkce není podporovaná.
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro