Modul plug-in Pythonu
Modul plug-in Pythonu spustí 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, které běží na uzlech clusteru.
Syntax
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 | Typ | Vyžadováno | Popis |
---|---|---|---|
output_schema | string |
✔️ | Literál type , který definuje výstupní schéma tabulkových dat vrácené kódem Pythonu. Formát je: typeof( ColumnName: ColumnType[, ...]) . Například typeof(col1:string, col2:long) . K rozšíření vstupního schématu 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 téma Tipy k používání. |
script_parameters | dynamic |
Pytel vlastností párů hodnot názvů, které se mají předat skriptu Pythonu jako rezervovaný kargs slovník. Další informace najdete v tématu Rezervované proměnné Pythonu. |
|
hint.distribution | string |
Nápověda k distribuci spuštění modulu plug-in 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, spustí se instance skriptu na každém uzlu na datech, která obsahuje. |
|
hint.remote | string |
Tato nápověda je relevantní pouze pro dotazy mezi clustery. Výchozí hodnota je auto . auto znamená, že server automaticky rozhodne, ve kterém clusteru se kód Pythonu spustí. Nastavení hodnoty na 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 |
Pytel vlastností s názvy a adresami URL pro artefakty, které jsou přístupné z cloudového úložiště. Další informace najdete v tématu Používání externích artefaktů. | |
spill_to_disk | bool |
Určuje alternativní metodu serializace vstupní tabulky do sandboxu Pythonu. Pro serializaci velkých tabulek ji nastavte na true , aby se urychlila serializace a výrazně se snížila spotřeba paměti sandboxu. Výchozí 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 (výše uvedenéT
hodnoty) jakopandas
datový rámec.kargs
: Hodnota argumentu script_parameters jako slovník Pythonu.result
pandas
: Datový rámec vytvořený skriptem Pythonu, jehož hodnotou se stanou tabulková data odesílaná 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 v 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 se modul plug-in spouští.
Použití příjmu dat ze zásad dotazů a aktualizací
- Modul plug-in použijte v dotazech, které jsou:
- Definováno jako součást zásady aktualizace, jejíž zdrojová tabulka je ingestovaná tak, aby používala 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, který je definovaný jako součást zásady aktualizace, jejíž zdrojová tabulka se ingestuje pomocí streamování.
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"})
)
File | Velikost |
---|---|
this_is_a_script | 120 |
this_is_my_first_file | 105 |
Tipy pro zvýšení výkonu
- Snižte vstupní datovou sadu modulu plug-in na minimální požadované množství (sloupce/řádky).
- Pokud je to možné, používejte filtry pro zdrojovou datovou sadu s dotazovacím jazykem Kusto.
- Pokud chcete provést výpočet na podmnožině zdrojových sloupců, před vyvoláním modulu plug-in promítejte pouze tyto sloupce.
- Použijte
hint.distribution = per_node
vždy, když je logika ve vašem skriptu distribuovatelná.- K dělení vstupní datové sady můžete použít také operátor oddílu .
- Kdykoli 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í backticks. Příklad:
```
python code
```
Pomocí operátoru
externaldata
získáte obsah skriptu, který jste uložili v externím 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ů
Pro skript je možné zpřístupnit externí artefakty z cloudového úložiště a používat je za běhu.
Adresy URL, na které odkazuje vlastnost externích artefaktů, musí být:
- Součástí zásad popisku clusteru.
- Ve veřejně dostupném umístění nebo zadejte potřebné přihlašovací údaje, jak je vysvětleno v připojovacích řetězcích úložiště.
Poznámka
Při ověřování externích artefaktů pomocí spravovaných identit musí být použití definováno v zásadách spravovanýchSandboxArtifacts
identit na úrovni clusteru.
Artefakty jsou dostupné 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ů. Podívejte se na příklady.
Informace o odkazování na externí balíčky najdete v tématu Instalace balíčků pro modul plug-in Pythonu.
Aktualizace mezipaměti externích artefaktů
Soubory externích artefaktů využívané v dotazech se ve vašem clusteru ukládají do mezipaměti. Pokud aktualizujete soubory v cloudovém úložišti a potřebujete 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í, aby následné dotazy běžely 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 váš vlastní.
- Balíček je veřejný, ale není součástí základní image modulu plug-in.
Nainstalujte balíčky následujícím způsobem:
Požadavky
Vytvořte kontejner objektů blob, který bude hostovat balíčky, nejlépe na stejném místě jako váš cluster. Například , za předpokladu,
https://artifactswestus.blob.core.windows.net/python
že se váš cluster nachází 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ů
V případě veřejných balíčků v PyPi nebo jiných kanálech si stáhněte balíček a jeho závislosti.
- Z příkazového okna v místním prostředí Windows Python 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 jeho závislostí.
- U veřejných balíčků zazipujte soubory, které byly staženy v předchozím kroku.
Poznámka
- Nezapomeňte si stáhnout balíček, který je kompatibilní s modulem Pythonu a platformou modulu runtime sandboxu (aktuálně 3.6.5 ve Windows).
- Nezapomeňte zkomprimovat
.whl
samotné soubory, a ne jejich nadřazenou složku. - Soubory pro balíčky, které už existují se stejnou verzí, můžete přeskočit
.whl
v imagi základního sandboxu.
Nahrajte komprimovaný soubor do objektu blob v umístění artefaktů (z kroku 1).
Zavolejte modul plug-in
python
.external_artifacts
Zadejte parametr s sadou vlastností 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
zsandbox_utils
a zavolejte 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 |
---|---|
1 | Gary Tapia |
2 | Emma Evans |
3 | Ashley Bowen |
Související obsah
Další příklady funkcí UDF, které používají modul plug-in Pythonu, najdete v knihovně Functions.
Modul plug-in Pythonu spustí uživatelem definovanou funkci (UDF) pomocí skriptu Pythonu. Skript Pythonu získá jako vstup tabulková data a vytvoří tabulkový výstup.
Syntax
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 | Typ | Vyžadováno | Popis |
---|---|---|---|
output_schema | string |
✔️ | Literál type , který definuje výstupní schéma tabulkových dat vrácené kódem Pythonu. Formát je: typeof( ColumnName: ColumnType[, ...]) . Například typeof(col1:string, col2:long) . K rozšíření vstupního schématu 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 téma Tipy k používání. |
script_parameters | dynamic |
Pytel vlastností párů hodnot názvů, které se mají předat skriptu Pythonu jako rezervovaný kargs slovník. Další informace najdete v tématu Rezervované proměnné Pythonu. |
|
hint.distribution | string |
Nápověda k distribuci spuštění modulu plug-in 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, spustí se instance skriptu na každém uzlu na datech, která obsahuje. |
|
hint.remote | string |
Tato nápověda je relevantní pouze pro dotazy mezi clustery. Výchozí hodnota je auto . auto znamená, že server automaticky rozhodne, ve kterém clusteru se kód Pythonu spustí. Nastavení hodnoty na 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 ji nastavte na true , aby se urychlila serializace a výrazně se snížila spotřeba paměti sandboxu. Výchozí 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 (výše uvedenéT
hodnoty) jakopandas
datový rámec.kargs
: Hodnota argumentu script_parameters jako slovník Pythonu.result
pandas
: Datový rámec vytvořený skriptem Pythonu, jehož hodnotou se stanou tabulková data odesílaná 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 v databázi KQL modul plug-in Pythonu .
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 se modul plug-in spouští.
Použití příjmu dat ze zásad dotazů a aktualizací
- Modul plug-in použijte v dotazech, které jsou:
- Definováno jako součást zásady aktualizace, jejíž zdrojová tabulka je ingestovaná tak, aby používala 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, který je definovaný jako součást zásady aktualizace, jejíž zdrojová tabulka se ingestuje pomocí streamování.
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 pro zvýšení výkonu
- Snižte vstupní datovou sadu modulu plug-in na minimální požadované množství (sloupce/řádky).
- Pokud je to možné, používejte filtry pro zdrojovou datovou sadu s dotazovacím jazykem Kusto.
- Pokud chcete provést výpočet na podmnožině zdrojových sloupců, před vyvoláním modulu plug-in promítejte pouze tyto sloupce.
- Použijte
hint.distribution = per_node
vždy, když je logika ve vašem skriptu distribuovatelná.- K dělení vstupní datové sady můžete použít také operátor oddílu .
- Kdykoli 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í backticks. Příklad:
```
python code
```
Pomocí operátoru
externaldata
získáte obsah skriptu, který jste uložili v externím 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í UDF, 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