Plug-in Python

Il plug-in Python esegue una funzione definita dall'utente usando uno script Python. Lo script Python ottiene i dati tabulari come input e produce output tabulare. Il runtime del plug-in è ospitato in sandbox,in esecuzione nei nodi del cluster.

Sintassi

Tevaluate [ ( hint.distribution=single | per_node )] python(evaluate,hint.distribution [ ,=][ ,single])

Argomenti

  • output_schema:valore letterale che definisce lo schema di output dei dati tabulari, restituito dal codice Python.
    • Il formato è: typeof(typeof(::[, ...] ) . Ad esempio, typeof(col1:string, col2:long) .
    • Per estendere lo schema di input, usare la sintassi seguente: typeof(*, col1:string, col2:long)
  • script:valore letterale che è uno script Python valido da eseguire. Per generare stringhe su più righe, vedere Suggerimenti per l'utilizzo.
  • script_arguments:valore letterale facoltativo. È un contenitore di proprietà di coppie nome/valore da passare allo script Python come kargs dizionario riservato. Per altre informazioni, vedere Variabili Python riservate.
  • hint.distribution:suggerimento facoltativo per l'esecuzione del plug-in da distribuire tra più nodi del cluster.
    • Il valore predefinito è single.
    • single: una singola istanza dello script verrà eseguita su tutti i dati della query.
    • per_node: se la query prima del blocco Python viene distribuita, verrà eseguita un'istanza dello script in ogni nodo, sui dati in esso contenuti.
  • external_artifacts:valore letterale facoltativo che è un contenitore di proprietà di coppie di nome e URL per gli artefatti accessibili dall'archiviazione cloud. Possono essere resi disponibili per l'uso da parte dello script in fase di esecuzione.
    • Gli URL a cui si fa riferimento in questo contenitore delle proprietà devono essere:
    • Gli artefatti vengono resi disponibili per l'utilizzo da parte dello script da una directory temporanea locale, .\Temp . I nomi specificati nel contenitore delle proprietà vengono usati come nomi di file locali. Vedere gli esempi.
    • Per altre informazioni, vedere Installare i pacchetti per il plug-in Python.

Variabili Python riservate

Le variabili seguenti sono riservate per l'interazione tra il linguaggio di query Kusto e il codice Python.

  • df: dati tabulari di input (i valori T di precedenti), come pandas dataframe.
  • kargs: valore kargs come dizionario Python.
  • result: dataframe creato dallo script Python, il cui valore diventa i dati tabulari che vengono pandas inviati all'operatore di query Kusto che segue il plug-in.

Abilitare il plug-in

Immagine sandbox Python

  • L'immagine sandbox Python si basa sulla distribuzione di Anaconda 5.2.0 con il motore Python 3.6. Vedere l'elenco dei pacchetti Anaconda.

    Nota

    Una piccola percentuale di pacchetti potrebbe non essere compatibile con le limitazioni applicate dalla sandbox in cui viene eseguito il plug-in.

  • L'immagine Python contiene anche ML pacchetti comuni: tensorflow , , , , e altri pacchetti kerastorchhdbscanxgboost utili.

  • Il plug-in importa numpy (come ) && (come pd ) per impostazione predefinita. È possibile importare altri moduli in base alle esigenze.

Usare l'inserimento da criteri di query e aggiornamento

  • Usare il plug-in nelle query seguenti:
    • Definito come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita in usando l'inserimento non di streaming.
    • Eseguire come parte di un comando che esegue l'inserimento da una query, ad esempio . In entrambi questi casi, verificare che il volume e la frequenza dell'inserimento e la complessità e le risorse usate dalla logica python siano allineati alle limitazioni della sandbox e alle risorse disponibili del cluster. In caso negativo, potrebbero verificarsi errori di limitazione.
  • Non è possibile usare il plug-in in una query definita come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita usando l'inserimento del flusso.

Esempio

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)
```
, pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart 

sine demo.

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 Dimensione
this_is_a_script 120
this_is_my_first_file 105

Suggerimenti per incrementare le prestazioni

  • Ridurre il set di dati di input del plug-in alla quantità minima richiesta (colonne/righe).
    • Usare i filtri nel set di dati di origine, quando possibile, con il linguaggio di query di Kusto.
    • Per eseguire un calcolo su un subset delle colonne di origine, proiettare solo tali colonne prima di richiamare il plug-in.
  • Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.
  • Usare il linguaggio di query di Kusto, quando possibile, per implementare la logica dello script Python.

Suggerimenti per l'uso

  • Per generare stringhe su più righe contenenti lo script Python in , copiare lo script Python dall'editor Python preferito Kusto.Explorer (Kusto.Explorer, Visual Studio Code, PyCharme così via). A questo punto eseguire una delle seguenti:

    • Racchiudere lo script completo tra le righe contenenti tre backtick consecutivi, ad esempio:
      ```
      python code
      ```
    • Premere F2 per aprire la finestra Modifica in Python. Incollare lo script in questa finestra. Selezionare OK. Lo script verrà decorato con virgolette e nuove righe, quindi è valido in Kusto e incollato automaticamente nella scheda della query.
    • Incollare il codice Python direttamente nella scheda query. Selezionare le righe e premere CTRL+K, CTRL+S per decorare le righe come sopra. Per invertire le prestazioni, premere CTRL+K,CTRL+M. Vedere l'elenco completo dei Editor di query seguenti.
  • Per evitare conflitti tra delimitatori di stringa Kusto e valori letterali stringa Python, usare:

    • Virgolette singole ( ' ) per valori letterali stringa Kusto nelle query Kusto
    • Virgolette doppie ( " ) per i valori letterali stringa Python negli script Python
  • Usare l'operatore per ottenere il contenuto di uno script archiviato in una posizione esterna, ad esempio Archiviazione BLOB di Azure.

    Esempio

    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 Python

Potrebbe essere necessario installare manualmente uno o più pacchetti per i motivi seguenti:

  • Il pacchetto è privato ed è proprio.
  • Il pacchetto è pubblico, ma non è incluso nell'immagine di base del plug-in.

Installare i pacchetti come indicato di seguito:

Prerequisiti

  1. Creare un contenitore BLOB per ospitare i pacchetti, preferibilmente nella stessa posizione del cluster. Ad esempio, https://artifcatswestus.blob.core.windows.net/python , presupponendo che il cluster si trova negli Stati Uniti occidentali.

  2. Modificare i criteri di callout del cluster per consentire l'accesso a tale posizione.

    • Questa modifica richiede le autorizzazioni AllDatabasesAdmin.

    • Ad esempio, per abilitare l'accesso a un BLOB che si trova in https://artifcatswestus.blob.core.windows.net/python , eseguire il comando seguente:

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

Installare i pacchetti

  1. Per i pacchetti pubblici in PyPi o altri canali, scaricare il pacchetto e le relative dipendenze.

    • Compilare i file wheel ( *.whl ), se necessario.
    • Da una finestra di comando nell'ambiente Python locale eseguire:
    pip wheel [-w download-dir] package-name.
    
  2. Creare un file ZIP contenente il pacchetto richiesto e le relative dipendenze.

    • Per i pacchetti privati, comprimere la cartella del pacchetto e le cartelle delle relative dipendenze.
    • Per i pacchetti pubblici, comprimere i file scaricati nel passaggio precedente.

    Nota

    • Assicurarsi di scaricare il pacchetto compatibile con il motore Python del runtime sandbox (attualmente 3.6.5)
    • Assicurarsi di comprimere i .whl file stessi e non la cartella padre.
    • È possibile ignorare .whl i file per i pacchetti già esistenti con la stessa versione nell'immagine sandbox di base.
  3. Upload il file compresso in un BLOB nel percorso degli artefatti (dal passaggio 1).

  4. Chiamare il python plug-in.

    • Specificare il parametro con un contenitore delle proprietà di nome e riferimento al external_artifacts file ZIP (URL del BLOB, incluso un token di firma di accesso condiviso).
    • Nel codice Python inline importare Zipackage da e chiamare il relativo metodo con il nome del file sandbox_utilsinstall() ZIP.

Esempio

Installare il pacchetto Faker che genera dati falsi.

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=pack('faker.zip', 'https://artifacts.blob.core.windows.net/kusto/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
ID Nome
1 Tapia Persa
2 Emma Evans
3 Alex Bowen

Questa funzionalità non è supportata in Monitoraggio di Azure