Modul plug-in Pythonu

  • Článek

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) jako pandas datový rámec.
  • kargs: Hodnota argumentu script_parameters jako slovník Pythonu.
  • resultpandas: 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

Snímek obrazovky s sinus demo zobrazující výsledek dotazu 

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á.
  • 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átoruexternaldata 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:

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

  1. 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.

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

  1. 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.

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

  3. Nahrajte komprimovaný soubor do objektu blob v umístění artefaktů (z kroku 1).

  4. 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 z sandbox_utils a zavolejte jeho install() 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) jako pandas datový rámec.
  • kargs: Hodnota argumentu script_parameters jako slovník Pythonu.
  • resultpandas: 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

Snímek obrazovky s sinus demo zobrazující výsledek dotazu

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á.
  • 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átoruexternaldata 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á.