Sdílet prostřednictvím

Modul plug-in Pythonu

  • Článek

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 = (singleper_node | )] [hint.remote = (autolocal | )] 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 (hodnoty T výše) jako pandas datový rámec.
  • kargs: Hodnota argumentu script_parameters jako slovník Pythonu.
  • resultpandas: 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

Snímek obrazovky s ukázkou sinus 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"})
)
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:

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

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

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

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

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

Snímek obrazovky s ukázkou sinus zobrazující výsledek dotazu

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