Plug-in PythonPython plugin

Il plug-in Python esegue una funzione definita dall'utente (UDF) usando uno script Python.The Python plugin runs a user-defined-function (UDF) using a Python script. Lo script Python ottiene i dati tabulari come input ed è previsto che produca un output tabulare.The Python script gets tabular data as its input, and is expected to produce a tabular output. Il runtime del plug-in è ospitato in sandboxin esecuzione nei nodi del cluster.The plugin's runtime is hosted in sandboxes, running on the cluster's nodes.

SintassiSyntax

T | evaluate [ hint.distribution = ( single | per_node )] python( output_schema , script [ , script_parameters] [ , external_artifacts])T | evaluate [hint.distribution = (single | per_node)] python(output_schema, script [, script_parameters][, external_artifacts])

ArgomentiArguments

  • output_schema: type valore letterale che definisce lo schema di output dei dati tabulari, restituito dal codice Python.output_schema: A type literal that defines the output schema of the tabular data, returned by the Python code.
    • Il formato è: typeof( ColumnName : ColumnType[,...] ) . Ad esempio, typeof(col1:string, col2:long) .The format is: typeof(ColumnName: ColumnType[, ...]). For example, typeof(col1:string, col2:long).
    • Per estendere lo schema di input, usare la sintassi seguente:typeof(*, col1:string, col2:long)To extend the input schema, use the following syntax: typeof(*, col1:string, col2:long)
  • script: string valore letterale che rappresenta lo script Python valido da eseguire.script: A string literal that is the valid Python script to execute.
  • script_parameters: dynamic valore letterale facoltativo.script_parameters: An optional dynamic literal. Si tratta di un contenitore di proprietà di coppie nome/valore da passare allo script Python come dizionario riservato kargs .It's a property bag of name/value pairs to be passed to the Python script as the reserved kargs dictionary. Per altre informazioni, vedere variabili di Python riservate.For more information, see Reserved Python variables.
  • hint. Distribution: suggerimento facoltativo che consente di distribuire l'esecuzione del plug-in tra più nodi del cluster.hint.distribution: An optional hint for the plugin's execution to be distributed across multiple cluster nodes.
    • Il valore predefinito è single.The default value is single.
    • single: Una singola istanza dello script viene eseguita su tutti i dati della query.single: A single instance of the script will run over the entire query data.
    • per_node: Se la query prima del blocco Python viene distribuita, viene eseguita un'istanza dello script in ogni nodo sui dati in esso contenuti.per_node: If the query before the Python block is distributed, an instance of the script will run on each node, on the data that it contains.
  • external_artifacts: dynamic valore letterale facoltativo che è un contenitore di proprietà delle coppie nome e URL, per gli artefatti accessibili dalla memoria cloud.external_artifacts: An optional dynamic literal that is a property bag of name and URL pairs, for artifacts that are accessible from cloud storage. Possono essere rese disponibili per lo script da usare in fase di esecuzione.They can be made available for the script to use at runtime.
    • Gli URL a cui viene fatto riferimento in questo contenitore delle proprietà devono essere:URLs referenced in this property bag are required to be:
    • Gli elementi vengono resi disponibili per l'utilizzo da parte dello script da una directory temporanea locale, .\Temp .The artifacts are made available for the script to consume from a local temporary directory, .\Temp. I nomi specificati nel contenitore delle proprietà vengono usati come nomi di file locali.The names provided in the property bag are used as the local file names. Vedere gli esempi.See Examples.
    • Per altre informazioni, vedere Install Packages for the Python plugin.For more information, see Install packages for the Python plugin.

Variabili di Python riservateReserved Python variables

Le variabili seguenti sono riservate per l'interazione tra il linguaggio di query kusto e il codice Python.The following variables are reserved for interaction between Kusto query language and the Python code.

  • df: Dati tabulari di input, ovvero i valori T sopra riportati, come pandas frame di dati.df: The input tabular data (the values of T above), as a pandas DataFrame.
  • kargs: Il valore dell'argomento script_parameters come dizionario Python.kargs: The value of the script_parameters argument, as a Python dictionary.
  • result: Un pandas frame di dati creato dallo script Python, il cui valore diventa i dati tabulari che vengono inviati all'operatore di query kusto che segue il plug-in.result: A pandas DataFrame created by the Python script, whose value becomes the tabular data that gets sent to the Kusto query operator that follows the plugin.

Abilitare il plug-inEnable the plugin

  • Il plug-in è disabilitato per impostazione predefinita.The plugin is disabled by default.
  • Per abilitare il plug-in, vedere l'elenco dei prerequisiti.To enable the plugin, see the list of prerequisites.
  • Abilitare o disabilitare il plug-in nella portale di Azure nella scheda configurazionedel cluster.Enable or disable the plugin in the Azure portal, in your cluster's Configuration tab.

Immagine sandbox PythonPython sandbox image

  • L'immagine di Python sandbox è basata sulla distribuzione 5.2.0 Anaconda con il motore Python 3,6 .The Python sandbox image is based on Anaconda 5.2.0 distribution with the Python 3.6 engine. Vedere l'elenco dei pacchetti Anaconda.See the list of Anaconda packages.

    Nota

    Una piccola percentuale di pacchetti potrebbe non essere compatibile con le limitazioni applicate dalla sandbox in cui viene eseguito il plug-in.A small percentage of packages might be incompatible with the limitations enforced by the sandbox where the plugin is run.

  • L'immagine Python contiene anche pacchetti ml comuni: tensorflow , keras , torch , hdbscan , xgboost e altri pacchetti utili.The Python image also contains common ML packages: tensorflow, keras, torch, hdbscan, xgboost, and other useful packages.

  • Il plug-in Importa numpy (as np ) & Pandas (As pd ) per impostazione predefinita.The plugin imports numpy (as np) & pandas (as pd) by default. È possibile importare altri moduli in base alle esigenze.You can import other modules as needed.

Usare l'inserimento dai criteri di query e di aggiornamentoUse Ingestion from query and update policy

  • Usare il plug-in nelle query:Use the plugin in queries that are:
    • Definito come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita nell'uso dell'inserimento di non streaming .Defined as part of an update policy, whose source table is ingested to using non-streaming ingestion.
    • Eseguire come parte di un comando che inserisce da una query, ad esempio .set-or-append .Run as part of a command that ingests from a query, such as .set-or-append. In entrambi i casi, verificare che il volume e la frequenza dell'inserimento e la complessità e le risorse usate dalla logica di Python siano allineate con le limitazioni della sandbox e le risorse disponibili del cluster.In both these cases, verify that the volume and frequency of the ingestion, and the complexity and resources used by the Python logic, align with sandbox limitations and the cluster's available resources. In caso contrario, potrebbero verificarsi errori di limitazione.Failure to do so may result in throttling errors.
  • Non è possibile usare il plug-in in una query definita come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita con l'inserimento di flussi.You can't use the plugin in a query that is defined as part of an update policy, whose source table is ingested using streaming ingestion.

EsempiExamples

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'                     //  The Python decorated script
'n = df.shape[0]\n'
'g = kargs["gain"]\n'
'f = kargs["cycles"]\n'
'result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)\n'
//
, pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart 

Demo seno

print "This is an example for using 'external_artifacts'"
| evaluate python(
    typeof(File:string, Size:string),
    "import os\n"
    "result = pd.DataFrame(columns=['File','Size'])\n"
    "sizes = []\n"
    "path = '.\\\\Temp'\n"
    "files = os.listdir(path)\n"
    "result['File']=files\n"
    "for file in files:\n"
    "    sizes.append(os.path.getsize(path + '\\\\' + file))\n"
    "result['Size'] = sizes\n"
    "\n",
    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"})
)
FileFile DimensioneSize
this_is_a_scriptthis_is_a_script 120120
this_is_my_first_filethis_is_my_first_file 105105

Suggerimenti per incrementare le prestazioniPerformance tips

  • Ridurre il set di dati di input del plug-in alla quantità minima richiesta (colonne/righe).Reduce the plugin's input data set to the minimum amount required (columns/rows).

    • Usare i filtri sul set di dati di origine, quando possibile, con il linguaggio di query di Kusto.Use filters on the source data set, when possible, with Kusto's query language.
    • Per eseguire un calcolo su un subset di colonne di origine, proiettare solo le colonne prima di richiamare il plug-in.To do a calculation on a subset of the source columns, project only those columns before invoking the plugin.
  • Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.Use hint.distribution = per_node whenever the logic in your script is distributable.

  • Usare il linguaggio di query di Kusto, laddove possibile, per implementare la logica dello script Python.Use Kusto's query language whenever possible, to implement the logic of your Python script.

    EsempioExample

    .show operations
    | where StartedOn > ago(7d) // Filtering out irrelevant records before invoking the plugin
    | project d_seconds = Duration / 1s // Projecting only a subset of the necessary columns
    | evaluate hint.distribution = per_node python( // Using per_node distribution, as the script's logic allows it
        typeof(*, _2d:double),
        'result = df\n'
        'result["_2d"] = 2 * df["d_seconds"]\n' // Negative example: this logic should have been written using Kusto's query language
      )
    | summarize avg = avg(_2d)
    

Suggerimenti per l'usoUsage tips

  • Per generare stringhe a più righe contenenti lo script Python in Kusto.Explorer , copiare lo script Python dall'editor Python preferito (Jupyter, Visual Studio Code, PyCharme così via).To generate multi-line strings containing the Python script in Kusto.Explorer, copy your Python script from your favorite Python editor (Jupyter, Visual Studio Code, PyCharm, and so on). A questo punto, eseguire una delle operazioni seguenti:Now do one of:

    • Premere F2 per aprire la finestra modifica in Python .Press F2 to open the Edit in Python window. Incollare lo script in questa finestra.Paste the script into this window. Selezionare OK.Select OK. Lo script verrà decorato con le virgolette e le nuove righe, quindi è valido in kusto e incollato automaticamente nella scheda della query.The script will be decorated with quotes and new lines, so it's valid in Kusto, and automatically pasted into the query tab.
    • Incollare il codice Python direttamente nella scheda query. Selezionare le righe e premere CTRL + K, CTRL + S tasti di scelta rapida per decorarle come sopra.Paste the Python code directly into the query tab. Select those lines, and press Ctrl+K, Ctrl+S hot keys, to decorate them as above. Per invertire, premere i tasti di scelta rapida CTRL + K, CTRL + M .To reverse, press Ctrl+K, Ctrl+M hot keys. Vedere l'elenco completo dei tasti di scelta rapida dell'editor di query.See the full list of Query Editor shortcuts.
  • Per evitare conflitti tra i delimitatori di stringa kusto e i valori letterali stringa Python, usare:To avoid conflicts between Kusto string delimiters and Python string literals, use:

    • Virgolette singole ( ' ) per valori letterali stringa kusto nelle query kustoSingle quote characters (') for Kusto string literals in Kusto queries
    • Virgolette doppie ( " ) per i valori letterali stringa Python negli script PythonDouble quote characters (") for Python string literals in Python scripts
  • Usare l' externaldata operatore per ottenere il contenuto di uno script archiviato in una posizione esterna, ad esempio archiviazione BLOB di Azure.Use the externaldata operator to obtain the content of a script that you've stored in an external location, such as Azure Blob storage.

    EsempioExample

    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), 
        pack('gain', 100, 'cycles', 4))
    | render linechart 
    

Installare i pacchetti per il plug-in PythonInstall packages for the Python plugin

Potrebbe essere necessario installare i pacchetti manualmente per i motivi seguenti:You may need to install package(s) yourself, for the following reasons:

  • Il pacchetto è privato ed è personalizzato.The package is private and is your own.
  • Il pacchetto è pubblico ma non è incluso nell'immagine di base del plug-in.The package is public but isn't included in the plugin's base image.

Installare i pacchetti come indicato di seguito:Install packages as follows:

PrerequisitiPrerequisites

  1. Creare un contenitore BLOB per ospitare i pacchetti, preferibilmente nella stessa posizione del cluster.Create a blob container to host the packages, preferably in the same place as your cluster. Si supponga, ad esempio, che https://artifcatswestus.blob.core.windows.net/python il cluster si trovi negli Stati Uniti occidentali.For example, https://artifcatswestus.blob.core.windows.net/python, assuming your cluster is in West US.

  2. Modificare i criteri di callout del cluster per consentire l'accesso a tale percorso.Alter the cluster's callout policy to allow access to that location.

    • Questa modifica richiede autorizzazioni AllDatabasesAdmin .This change requires AllDatabasesAdmin permissions.

    • Ad esempio, per abilitare l'accesso a un BLOB che si trova in https://artifcatswestus.blob.core.windows.net/python , eseguire il comando seguente:For example, to enable access to a blob located in https://artifcatswestus.blob.core.windows.net/python, run the following command:

    .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifcatswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
    

Installare i pacchettiInstall packages

  1. Per i pacchetti pubblici in pypi o in altri canali, scaricare il pacchetto e le relative dipendenze.For public packages in PyPi or other channels, download the package and its dependencies.

    • Compila i file della rotellina ( *.whl ), se necessario.Compile wheel (*.whl) files, if required.
    • Da una finestra cmd nell'ambiente Python locale eseguire:From a cmd window in your local Python environment, run:
    pip wheel [-w download-dir] package-name.
    
  2. Creare un file zip contenente il pacchetto necessario e le relative dipendenze.Create a zip file, that contains the required package and its dependencies.

    • Per i pacchetti privati: zip la cartella del pacchetto e le cartelle delle relative dipendenze.For private packages: zip the folder of the package and the folders of its dependencies.
    • Per i pacchetti pubblici, eseguire il zip dei file scaricati nel passaggio precedente.For public packages, zip the files that were downloaded in the previous step.

    Nota

    • Assicurarsi di eseguire il zip dei .whl file stessi e non della relativa cartella padre.Make sure to zip the .whl files themselves, and not their parent folder.
    • È possibile ignorare i .whl file per i pacchetti già esistenti con la stessa versione nell'immagine sandbox di base.You can skip .whl files for packages that already exist with the same version in the base sandbox image.
  3. Caricare il file compresso in un BLOB nella posizione degli artefatti (dal passaggio 1).Upload the zipped file to a blob in the artifacts location (from step 1).

  4. Chiamare il python plug-in.Call the python plugin.

    • Specificare il external_artifacts parametro con un contenitore di proprietà denominato e un riferimento al file zip (URL del BLOB).Specify the external_artifacts parameter with a property bag of name and reference to the zip file (the blob's URL).
    • Nel codice Python inline importare Zipackage da sandbox_utils e chiamare il relativo install() metodo con il nome del file zip.In your inline python code, import Zipackage from sandbox_utils and call its install() method with the name of the zip file.

EsempioExample

Installare il pacchetto Faker che genera dati fittizi.Install the Faker package that generates fake data.

range ID from 1 to 3 step 1 
| extend Name=''
| evaluate python(typeof(*),
    'from sandbox_utils import Zipackage\n'
    'Zipackage.install("Faker.zip")\n'
    'from faker import Faker\n'
    'fake = Faker()\n'
    'result = df\n'
    'for i in range(df.shape[0]):\n'
    '    result.loc[i, "Name"] = fake.name()\n',
    external_artifacts=pack('faker.zip', 'https://artifacts.blob.core.windows.net/kusto/Faker.zip?...'))
IDID NomeName
11 Gary TapiaGary Tapia
22 Emma EvansEmma Evans
33 Ashley BowenAshley Bowen

Questa funzionalità non è supportata in monitoraggio di AzureThis capability isn't supported in Azure Monitor