Plug-in Python

Si applica a: ✅Microsoft FabricAzure Esplora dati

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

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Digita Obbligatorio Descrizione
output_schema string ✔️ Valore type letterale che definisce lo schema di output dei dati tabulari, restituito dal codice Python. Il formato è ColumnName typeof(:ColumnType[, ...].) Ad esempio, typeof(col1:string, col2:long). Per estendere lo schema di input, usare la sintassi seguente: typeof(*, col1:string, col2:long).
script string ✔️ Script Python valido da eseguire. Per generare stringhe su più righe, vedere Suggerimenti sull'utilizzo.
script_parameters dynamic Contenitore di proprietà di coppie nome valore da passare allo script Python come dizionario riservato kargs . Per altre informazioni, vedere Variabili Python riservate.
hint.distribution string Suggerimento per l'esecuzione del plug-in da distribuire tra più nodi del cluster. Il valore predefinito è single. single significa che una singola istanza dello script verrà eseguita sull'intero dati della query. per_node significa che se la query prima della distribuzione del blocco Python, un'istanza dello script verrà eseguita in ogni nodo nei dati contenuti.
hint.remote string Questo hint è rilevante solo per le query tra cluster. Il valore predefinito è auto. auto indica che il server decide automaticamente in quale cluster viene eseguito il codice Python. L'impostazione del valore su local forza l'esecuzione del codice Python nel cluster locale. Usarlo nel caso in cui il plug-in Python sia disabilitato nel cluster remoto.
external_artifacts dynamic Contenitore di proprietà di coppie nome e URL per gli artefatti accessibili dall'archiviazione cloud. Per altre informazioni, vedere Uso di artefatti esterni.
spill_to_disk bool Specifica un metodo alternativo per serializzare la tabella di input nella sandbox Python. Per serializzare tabelle di grandi dimensioni impostarla per true velocizzare la serializzazione e ridurre significativamente il consumo di memoria sandbox. Il valore predefinito è true.

Variabili Python riservate

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

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

Abilitare il plug-in

Il plug-in è disabilitato di default. Prima di iniziare, esaminare l'elenco dei prerequisiti. Per abilitare il plug-in e selezionare la versione dell'immagine Python, vedere Abilitare le estensioni del linguaggio nel cluster.

Immagine sandbox Python

Per modificare la versione dell'immagine Python in un'immagine gestita diversa o in un'immagine personalizzata, vedere Modificare l'immagine delle estensioni del linguaggio Python nel cluster.

Per visualizzare l'elenco dei pacchetti per le diverse immagini Python, vedere Informazioni di riferimento sui pacchetti Python.

Nota

  • Per impostazione predefinita, il plug-in importa numpy come np e pandas come pd. Facoltativamente, è possibile importare altri moduli in base alle esigenze.
  • Alcuni pacchetti potrebbero non essere compatibili con le limitazioni applicate dalla sandbox in cui viene eseguito il plug-in.

Usare l'inserimento da criteri di query e aggiornamento

  • Usare il plug-in nelle query che sono:
    • Definito come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita per l'uso dell'inserimento non in streaming .
    • Eseguire come parte di un comando che inserisce da una query, ad esempio .set-or-append.
  • 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 in streaming.

Esempi

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 

Screenshot della demo seno che mostra il risultato della query.

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 le colonne prima di richiamare il plug-in.
  • Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.
    • È anche possibile usare l'operatore partition per partizionare il set di dati di input.
  • 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 nell'editor di query, copiare lo script Python dall'editor Python preferito (Jupyter, Visual Studio Code, PyCharm e così via), incollarlo nell'editor di query e quindi racchiudere lo script completo tra le righe contenenti tre backtick consecutivi. Ad esempio:

    ```
    python code
    ```

  • Usare l'operatore externaldata 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), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart 

Uso di artefatti esterni

Gli artefatti esterni dall'archiviazione cloud possono essere resi disponibili per lo script e usati in fase di esecuzione.

Gli URL a cui fa riferimento la proprietà degli artefatti esterni devono essere:

  • Incluso nei criteri di callout del cluster.
  • In un percorso disponibile pubblicamente o specificare le credenziali necessarie, come illustrato nelle stringa di connessione di archiviazione.

Nota

Quando si autenticano artefatti esterni usando identità gestite, l'utilizzo SandboxArtifacts deve essere definito nei criteri di identità gestita a livello di cluster.

Gli artefatti vengono resi disponibili per l'utilizzo dello script da una directory temporanea locale, .\Temp. I nomi specificati nel contenitore delle proprietà vengono usati come nomi di file locali. Vedere Esempi.

Per informazioni sul riferimento ai pacchetti esterni, vedere Installare i pacchetti per il plug-in Python.

Aggiornamento della cache degli artefatti esterni

I file di artefatti esterni utilizzati nelle query vengono memorizzati nella cache nel cluster. Se si apportano aggiornamenti ai file nell'archiviazione cloud e si richiede una sincronizzazione immediata con il cluster, è possibile usare il comando .clear cluster cache external-artifacts. Questo comando cancella i file memorizzati nella cache e garantisce che le query successive vengano eseguite con la versione più recente degli artefatti.

Installare pacchetti per il plug-in Python

Nella maggior parte dei casi d'uso potrebbe essere preferibile creare un'immagine personalizzata.

È possibile installare personalmente i pacchetti, per i motivi seguenti:

  • Non si dispone delle autorizzazioni per creare un'immagine personalizzata.
  • Il pacchetto è privato.
  • Si preferisce creare un'installazione di pacchetto ad hoc per il test e non si vuole che il sovraccarico della creazione di un'immagine personalizzata.

Installare i pacchetti come segue:

Prerequisiti

  1. Creare un contenitore BLOB per ospitare i pacchetti, preferibilmente nella stessa posizione del cluster. Ad esempio, https://artifactswestus.blob.core.windows.net/pythonsupponendo 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 autorizzazioni AllDatabasesAdmin .

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

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

Installare i pacchetti

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

    • Da una finestra cmd nell'ambiente Windows Python locale eseguire:
    pip wheel [-w download-dir] package-name.
    
  2. Creare un file ZIP contenente il pacchetto necessario 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 e la piattaforma del runtime sandbox (attualmente 3.6.5 in Windows)
    • Assicurarsi di comprimere i file stessi e non la .whl cartella padre.
    • È possibile ignorare .whl i file per i pacchetti già esistenti con la stessa versione nell'immagine sandbox di base.
  3. Caricare il file compresso in un BLOB nel percorso degli artefatti (dal passaggio 1).

  4. Chiamare il plug-in python .

    • Specificare il external_artifacts parametro con un contenitore di proprietà di nome e riferimento al file ZIP (URL del BLOB, incluso un token di firma di accesso condiviso).
    • Nel codice Python inline importare Zipackage sandbox_utils e chiamare il install() relativo metodo con il nome del file 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=bag_pack('faker.zip', 'https://artifacts.blob.core.windows.net/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
ID Nome
1 Gary Tapia
2 Emma Evans
3 Ashley Bowen

Per altri esempi di funzioni definite dall'utente che usano il plug-in Python, vedere la libreria funzioni.

Il plug-in Python esegue una funzione definita dall'utente (UDF) usando uno script Python. Lo script Python ottiene i dati tabulari come input e produce un output tabulare.

Sintassi

T evaluate | [ (singleper_node | )] [hint.remote =hint.distribution = (autolocal | )] python(script output_schema ,[ script_parameters] [,, spill_to_disk])

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Digita Obbligatorio Descrizione
output_schema string ✔️ Valore type letterale che definisce lo schema di output dei dati tabulari, restituito dal codice Python. Il formato è ColumnName typeof(:ColumnType[, ...].) Ad esempio, typeof(col1:string, col2:long). Per estendere lo schema di input, usare la sintassi seguente: typeof(*, col1:string, col2:long).
script string ✔️ Script Python valido da eseguire. Per generare stringhe su più righe, vedere Suggerimenti sull'utilizzo.
script_parameters dynamic Contenitore di proprietà di coppie nome valore da passare allo script Python come dizionario riservato kargs . Per altre informazioni, vedere Variabili Python riservate.
hint.distribution string Suggerimento per l'esecuzione del plug-in da distribuire tra più nodi del cluster. Il valore predefinito è single. single significa che una singola istanza dello script verrà eseguita sull'intero dati della query. per_node significa che se la query prima della distribuzione del blocco Python, un'istanza dello script verrà eseguita in ogni nodo nei dati contenuti.
hint.remote string Questo hint è rilevante solo per le query tra cluster. Il valore predefinito è auto. auto indica che il server decide automaticamente in quale cluster viene eseguito il codice Python. L'impostazione del valore su local forza l'esecuzione del codice Python nel cluster locale. Usarlo nel caso in cui il plug-in Python sia disabilitato nel cluster remoto.
spill_to_disk bool Specifica un metodo alternativo per serializzare la tabella di input nella sandbox Python. Per serializzare tabelle di grandi dimensioni impostarla per true velocizzare la serializzazione e ridurre significativamente il consumo di memoria sandbox. Il valore predefinito è true.

Variabili Python riservate

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

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

Abilitare il plug-in

Il plug-in è disabilitato di default. Prima di iniziare, abilitare il plug-in Python nel database KQL.

Immagine sandbox Python

Per visualizzare l'elenco dei pacchetti per le diverse immagini Python, vedere Informazioni di riferimento sui pacchetti Python.

Nota

  • Per impostazione predefinita, il plug-in importa numpy come np e pandas come pd. Facoltativamente, è possibile importare altri moduli in base alle esigenze.
  • Alcuni pacchetti potrebbero non essere compatibili con le limitazioni applicate dalla sandbox in cui viene eseguito il plug-in.

Usare l'inserimento da criteri di query e aggiornamento

  • Usare il plug-in nelle query che sono:
    • Definito come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita per l'uso dell'inserimento non in streaming .
    • Eseguire come parte di un comando che inserisce da una query, ad esempio .set-or-append.
  • 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 in streaming.

Esempi

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 

Screenshot della demo seno che mostra il risultato della query.

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 le colonne prima di richiamare il plug-in.
  • Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.
    • È anche possibile usare l'operatore partition per partizionare il set di dati di input.
  • 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 nell'editor di query, copiare lo script Python dall'editor Python preferito (Jupyter, Visual Studio Code, PyCharm e così via), incollarlo nell'editor di query e quindi racchiudere lo script completo tra le righe contenenti tre backtick consecutivi. Ad esempio:

    ```
    python code
    ```

  • Usare l'operatore externaldata 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), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart 

Contenuto correlato

Per altri esempi di funzioni definite dall'utente che usano il plug-in Python, vedere la libreria funzioni.