Plug-in Python
Si applica a: ✅Microsoft Fabric✅Azure 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.
T evaluate
|
[ (single
| per_node
)] [hint.remote
=
=
hint.distribution
(auto
local
| )] python(
script output_schema,
[ ,
script_parameters] [,
external_artifacts][,
spill_to_disk])
Altre informazioni sulle convenzioni di sintassi.
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 . |
Le variabili seguenti sono riservate per l'interazione tra Linguaggio di query Kusto e il codice Python.
df
: dati tabulari di input (i valori diT
sopra), comepandas
dataframe.kargs
: valore dell'argomento script_parameters , come dizionario Python.result
pandas
: dataframe creato dallo script Python, il cui valore diventa i dati tabulari inviati all'operatore di query Kusto che segue 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.
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 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.
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
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 |
- 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. - Usare il linguaggio di query di Kusto, quando possibile, per implementare la logica dello script Python.
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.
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
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.
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.
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:
Creare un contenitore BLOB per ospitare i pacchetti, preferibilmente nella stessa posizione del cluster. Ad esempio,
https://artifactswestus.blob.core.windows.net/python
supponendo che il cluster si trova negli Stati Uniti occidentali.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 } ]'
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.
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.
Caricare il file compresso in un BLOB nel percorso degli artefatti (dal passaggio 1).
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 ilinstall()
relativo metodo con il nome del file ZIP.
- Specificare il
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.
T evaluate
|
[ (single
per_node
| )] [hint.remote
=
hint.distribution
=
(auto
local
| )] python(
script output_schema ,
[ script_parameters] [,
,
spill_to_disk])
Altre informazioni sulle convenzioni di sintassi.
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 . |
Le variabili seguenti sono riservate per l'interazione tra Linguaggio di query Kusto e il codice Python.
df
: dati tabulari di input (i valori diT
sopra), comepandas
dataframe.kargs
: valore dell'argomento script_parameters , come dizionario Python.result
pandas
: dataframe creato dallo script Python, il cui valore diventa i dati tabulari inviati all'operatore di query Kusto che segue il plug-in.
Il plug-in è disabilitato di default. Prima di iniziare, abilitare il plug-in Python nel database KQL.
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 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.
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
- 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. - Usare il linguaggio di query di Kusto, quando possibile, per implementare la logica dello script Python.
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.
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
Per altri esempi di funzioni definite dall'utente che usano il plug-in Python, vedere la libreria funzioni.