Python-Plug-In
Das Python-Plug-In führt eine benutzerdefinierte Funktion (User-Defined Function, UDF) mithilfe eines Python-Skripts aus. Das Python-Skript ruft tabellarische Daten als Eingabe ab und erzeugt eine tabellarische Ausgabe. Die Runtime des Plug-Ins wird in Sandboxes gehostet, die auf den Knoten des Clusters ausgeführt werden.
Syntax
T|evaluate [hint.distribution= (single | per_node)] [hint.remote= (auto | local)] python(output_schema,Skript [,script_parameters] [,external_artifacts][,spill_to_disk])
Erfahren Sie mehr über Syntaxkonventionen.
Parameter
| Name | Typ | Erforderlich | BESCHREIBUNG |
|---|---|---|---|
| output_schema | string |
✔️ | Ein type Literal, das das Ausgabeschema der tabellarischen Daten definiert, das vom Python-Code zurückgegeben wird. Das Format lautet: typeof(ColumnName:ColumnType[, ...]). Beispiel: typeof(col1:string, col2:long). Verwenden Sie die folgende Syntax, um das Eingabeschema zu erweitern: typeof(*, col1:string, col2:long). |
| script | string |
✔️ | Das gültige python-Skript, das ausgeführt werden soll. Informationen zum Generieren von mehrzeiligen Zeichenfolgen finden Sie unter Verwendungstipps. |
| script_parameters | dynamic |
Ein Eigenschaftenbehälter mit Namenswertpaaren, die als reserviertes kargs Wörterbuch an das Python-Skript übergeben werden sollen. Weitere Informationen finden Sie unter Reservierte Python-Variablen. |
|
| hint.distribution | string |
Ein Hinweis für die Ausführung des Plug-Ins, die auf mehrere Clusterknoten verteilt werden soll. Standardwert: single. singlebedeutet, dass eine einzelne instance des Skripts über die gesamten Abfragedaten ausgeführt wird. per_nodebedeutet, dass, wenn die Abfrage vor der Verteilung des Python-Blocks auf jedem Knoten für die darin enthaltenen Daten eine instance des Skripts ausgeführt wird. |
|
| hint.remote | string |
Dieser Hinweis ist nur für clusterübergreifende Abfragen relevant. Standardwert: auto. auto bedeutet, dass der Server automatisch entscheidet, in welchem Cluster der Python-Code ausgeführt wird. Das Festlegen des Werts auf local erzwingt die Ausführung des Python-Codes im lokalen Cluster. Verwenden Sie es, falls das Python-Plug-In im Remotecluster deaktiviert ist. |
|
| external_artifacts | dynamic |
Ein Eigenschaftenbehälter mit Namens- und URL-Paaren für Artefakte, auf die aus dem Cloudspeicher zugegriffen werden kann. Weitere Informationen finden Sie unter Verwenden externer Artefakte. | |
| spill_to_disk | bool |
Gibt eine alternative Methode zum Serialisieren der Eingabetabelle in die Python-Sandbox an. Legen Sie für die Serialisierung großer Tabellen auf fest true , um die Serialisierung zu beschleunigen und den Sandkastenspeicherverbrauch erheblich zu reduzieren. Der Standardwert ist true. |
Reservierte Python-Variablen
Die folgenden Variablen sind für die Interaktion zwischen Kusto-Abfragesprache und dem Python-Code reserviert.
df: Die tabellarischen Eingabedaten (die Werte vonToben) alspandasDataFrame.kargs: Der Wert des arguments script_parameters als Python-Wörterbuch.result: Einpandasvom Python-Skript erstellter DataFrame, dessen Wert zu den tabellarischen Daten wird, die an den Kusto-Abfrageoperator gesendet werden, der auf das Plug-In folgt.
Aktivieren des Plug-Ins
Das Plug-In ist standardmäßig deaktiviert. Bevor Sie beginnen, überprüfen Sie die Liste der Voraussetzungen. Informationen zum Aktivieren des Plug-Ins und Auswählen der Version des Python-Images finden Sie unter Aktivieren von Spracherweiterungen in Ihrem Cluster.
Python-Sandboximage
Informationen zum Ändern der Version des Python-Images finden Sie unter Ändern des Images der Python-Spracherweiterungen in Ihrem Cluster.
Die Liste der Pakete für die verschiedenen Python-Images finden Sie unter Python-Paketreferenz.
Hinweis
- Standardmäßig importiert das Plug-In numpy als np und pandas als pd. Optional können Sie bei Bedarf andere Module importieren.
- Einige Pakete sind möglicherweise nicht mit den Einschränkungen kompatibel, die von der Sandbox erzwungen werden, in der das Plug-In ausgeführt wird.
Verwenden der Erfassung aus Abfrage- und Updaterichtlinie
- Verwenden Sie das Plug-In in Abfragen wie folgt:
- Definiert als Teil einer Updaterichtlinie, deren Quelltabelle für die Nicht-Streamingerfassung erfasst wird.
- Führen Sie als Teil eines Befehls aus, der aus einer Abfrage erfasst wird, z
.set-or-append. B. .
- Sie können das Plug-In nicht in einer Abfrage verwenden, die als Teil einer Updaterichtlinie definiert ist, deren Quelltabelle mithilfe der Streamingerfassung erfasst wird.
Beispiele
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"})
)
| Datei | Size |
|---|---|
| this_is_a_script | 120 |
| this_is_my_first_file | 105 |
Leistungstipps
- Reduzieren Sie das Eingabedataset des Plug-Ins auf den minimal erforderlichen Betrag (Spalten/Zeilen).
- Verwenden Sie nach Möglichkeit Filter für das Quelldataset mit der Abfragesprache von Kusto.
- Um eine Berechnung für eine Teilmenge der Quellspalten durchzuführen, projizieren Sie nur diese Spalten, bevor Sie das Plug-In aufrufen.
- Verwenden Sie
hint.distribution = per_node, wenn die Logik in Ihrem Skript verteilbar ist.- Sie können auch den Partitionsoperator zum Partitionieren des Eingabedatasets verwenden.
- Verwenden Sie nach Möglichkeit die Abfragesprache von Kusto, um die Logik Ihres Python-Skripts zu implementieren.
Verwendungstipps
Um mehrzeilige Zeichenfolgen zu generieren, die das Python-Skript in Ihrem Abfrage-Editor enthalten, kopieren Sie Ihr Python-Skript aus Ihrem bevorzugten Python-Editor (Jupyter, Visual Studio Code, PyCharm usw.), fügen Sie es in Ihren Abfrage-Editor ein, und schließen Sie dann das vollständige Skript zwischen Zeilen mit drei aufeinanderfolgenden Backticks ein. Beispiel:
```
python code
```Verwenden Sie den
externaldataOperator , um den Inhalt eines Skripts abzurufen, das Sie an einem externen Speicherort gespeichert haben, z. B. Azure Blob Storage.
Beispiel
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
Verwenden externer Artefakte
Externe Artefakte aus dem Cloudspeicher können für das Skript zur Verfügung gestellt und zur Laufzeit verwendet werden.
Die URLs, auf die von der eigenschaft external artifacts verwiesen wird, müssen wie folgt sein:
- Enthalten in der Beschriftungsrichtlinie des Clusters.
- An einem öffentlich verfügbaren Speicherort, oder geben Sie die erforderlichen Anmeldeinformationen an, wie unter Speicherverbindungszeichenfolgen erläutert.
Hinweis
Bei der Authentifizierung externer Artefakte mit verwalteten Identitäten muss die SandboxArtifacts Verwendung in der Verwalteten Identitätsrichtlinie auf Clusterebene definiert werden.
Die Artefakte werden für das Skript zur Nutzung aus einem lokalen temporären Verzeichnis .\Temp( ) zur Verfügung gestellt. Die im Eigenschaftenbehälter angegebenen Namen werden als lokale Dateinamen verwendet. Vgl. Beispiele.
Informationen zum Verweisen auf externe Pakete finden Sie unter Installieren von Paketen für das Python-Plug-In.
Aktualisieren des externen Artefaktcaches
Externe Artefaktdateien, die in Abfragen verwendet werden, werden in Ihrem Cluster zwischengespeichert. Wenn Sie Ihre Dateien im Cloudspeicher aktualisieren und eine sofortige Synchronisierung mit Ihrem Cluster benötigen, können Sie den Befehl .clear cluster cache external-artifacts verwenden. Dieser Befehl löscht die zwischengespeicherten Dateien und stellt sicher, dass nachfolgende Abfragen mit der neuesten Version der Artefakte ausgeführt werden.
Installieren von Paketen für das Python-Plug-In
Möglicherweise müssen Sie Pakete aus den folgenden Gründen selbst installieren:
- Das Paket ist privat und ihr eigenes Paket.
- Das Paket ist öffentlich, aber nicht im Basisimage des Plug-Ins enthalten.
Installieren Sie Pakete wie folgt:
Voraussetzungen
Erstellen Sie einen Blobcontainer, um die Pakete zu hosten, vorzugsweise am gleichen Ort wie Ihr Cluster. Angenommen, Ihr Cluster befindet sich in "USA,
https://artifactswestus.blob.core.windows.net/pythonWesten".Ändern Sie die Beschriftungsrichtlinie des Clusters, um den Zugriff auf diesen Speicherort zuzulassen.
Für diese Änderung sind AllDatabasesAdmin-Berechtigungen erforderlich.
Führen Sie beispielsweise den folgenden Befehl aus, um den Zugriff auf ein Blob in
https://artifactswestus.blob.core.windows.net/pythonzu aktivieren:
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
Installieren von Paketen
Für öffentliche Pakete in PyPi oder anderen Kanälen laden Sie das Paket und die zugehörigen Abhängigkeiten herunter.
- Führen Sie in einem cmd-Fenster in Ihrer lokalen Windows Python-Umgebung Folgendes aus:
pip wheel [-w download-dir] package-name.Erstellen Sie eine ZIP-Datei, die das erforderliche Paket und die zugehörigen Abhängigkeiten enthält.
- Bei privaten Paketen zippen Sie den Ordner des Pakets und die Ordner seiner Abhängigkeiten.
- Zippen Sie für öffentliche Pakete die Dateien, die im vorherigen Schritt heruntergeladen wurden.
Hinweis
- Stellen Sie sicher, dass Sie das Paket herunterladen, das mit der Python-Engine und der Plattform der Sandbox-Runtime (derzeit 3.6.5 unter Windows) kompatibel ist.
- Stellen Sie sicher, dass Sie die
.whlDateien selbst und nicht den übergeordneten Ordner zippen. - Sie können Dateien für Pakete überspringen
.whl, die bereits mit derselben Version im Basissandkastenimage vorhanden sind.
Laden Sie die gezippte Datei in ein Blob am Speicherort der Artefakte hoch (aus Schritt 1).
Rufen Sie das Plug-In auf
python.- Geben Sie den
external_artifactsParameter mit einem Eigenschaftenbehälter mit Namen und Verweis auf die ZIP-Datei (die URL des Blobs, einschließlich eines SAS-Tokens) an. - Importieren Sie
Zipackagein Ihrem Inline-Python-Code diesandbox_utilszugehörigeinstall()Methode, und rufen Sie sie mit dem Namen der ZIP-Datei auf.
- Geben Sie den
Beispiel
Installieren Sie das Faker-Paket , das gefälschte Daten generiert.
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 |
|---|---|
| 1 | Gary Tapia |
| 2 | Emma Evans |
| 3 | Ashley Bowen |
Verwandte Inhalte
Weitere Beispiele für UDF-Funktionen, die das Python-Plug-In verwenden, finden Sie in der Functions-Bibliothek.
Das Python-Plug-In führt eine benutzerdefinierte Funktion (User-Defined Function, UDF) mithilfe eines Python-Skripts aus. Das Python-Skript ruft tabellarische Daten als Eingabe ab und erzeugt eine tabellarische Ausgabe.
Syntax
T|evaluate [hint.distribution= (single | per_node)] [hint.remote= (auto | local)] python(output_schema,Skript [,script_parameters] [,spill_to_disk])
Erfahren Sie mehr über Syntaxkonventionen.
Parameter
| Name | Typ | Erforderlich | BESCHREIBUNG |
|---|---|---|---|
| output_schema | string |
✔️ | Ein type Literal, das das Ausgabeschema der tabellarischen Daten definiert, das vom Python-Code zurückgegeben wird. Das Format lautet: typeof(ColumnName:ColumnType[, ...]). Beispiel: typeof(col1:string, col2:long). Verwenden Sie die folgende Syntax, um das Eingabeschema zu erweitern: typeof(*, col1:string, col2:long). |
| script | string |
✔️ | Das gültige python-Skript, das ausgeführt werden soll. Informationen zum Generieren von mehrzeiligen Zeichenfolgen finden Sie unter Verwendungstipps. |
| script_parameters | dynamic |
Ein Eigenschaftenbehälter mit Namenswertpaaren, die als reserviertes kargs Wörterbuch an das Python-Skript übergeben werden sollen. Weitere Informationen finden Sie unter Reservierte Python-Variablen. |
|
| hint.distribution | string |
Ein Hinweis für die Ausführung des Plug-Ins, die auf mehrere Clusterknoten verteilt werden soll. Standardwert: single. singlebedeutet, dass eine einzelne instance des Skripts über die gesamten Abfragedaten ausgeführt wird. per_nodebedeutet, dass, wenn die Abfrage vor der Verteilung des Python-Blocks auf jedem Knoten für die darin enthaltenen Daten eine instance des Skripts ausgeführt wird. |
|
| hint.remote | string |
Dieser Hinweis ist nur für clusterübergreifende Abfragen relevant. Standardwert: auto. auto bedeutet, dass der Server automatisch entscheidet, in welchem Cluster der Python-Code ausgeführt wird. Das Festlegen des Werts auf local erzwingt die Ausführung des Python-Codes im lokalen Cluster. Verwenden Sie es, falls das Python-Plug-In im Remotecluster deaktiviert ist. |
|
| spill_to_disk | bool |
Gibt eine alternative Methode zum Serialisieren der Eingabetabelle in die Python-Sandbox an. Legen Sie für die Serialisierung großer Tabellen auf fest true , um die Serialisierung zu beschleunigen und den Sandkastenspeicherverbrauch erheblich zu reduzieren. Der Standardwert ist true. |
Reservierte Python-Variablen
Die folgenden Variablen sind für die Interaktion zwischen Kusto-Abfragesprache und dem Python-Code reserviert.
df: Die tabellarischen Eingabedaten (die Werte vonToben) alspandasDataFrame.kargs: Der Wert des arguments script_parameters als Python-Wörterbuch.result: Einpandasvom Python-Skript erstellter DataFrame, dessen Wert zu den tabellarischen Daten wird, die an den Kusto-Abfrageoperator gesendet werden, der auf das Plug-In folgt.
Aktivieren des Plug-Ins
Das Plug-In ist standardmäßig deaktiviert. Bevor Sie beginnen, aktivieren Sie das Python-Plug-In in Ihrer KQL-Datenbank.
Python-Sandboximage
Die Liste der Pakete für die verschiedenen Python-Images finden Sie unter Python-Paketreferenz.
Hinweis
- Standardmäßig importiert das Plug-In numpy als np und pandas als pd. Optional können Sie bei Bedarf andere Module importieren.
- Einige Pakete sind möglicherweise nicht mit den Einschränkungen kompatibel, die von der Sandbox erzwungen werden, in der das Plug-In ausgeführt wird.
Verwenden der Erfassung aus Abfrage- und Updaterichtlinie
- Verwenden Sie das Plug-In in Abfragen wie folgt:
- Definiert als Teil einer Updaterichtlinie, deren Quelltabelle für die Nicht-Streamingerfassung erfasst wird.
- Führen Sie als Teil eines Befehls aus, der aus einer Abfrage erfasst wird, z
.set-or-append. B. .
- Sie können das Plug-In nicht in einer Abfrage verwenden, die als Teil einer Updaterichtlinie definiert ist, deren Quelltabelle mithilfe der Streamingerfassung erfasst wird.
Beispiele
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
Leistungstipps
- Reduzieren Sie das Eingabedataset des Plug-Ins auf den minimal erforderlichen Betrag (Spalten/Zeilen).
- Verwenden Sie nach Möglichkeit Filter für das Quelldataset mit der Abfragesprache von Kusto.
- Um eine Berechnung für eine Teilmenge der Quellspalten durchzuführen, projizieren Sie nur diese Spalten, bevor Sie das Plug-In aufrufen.
- Verwenden Sie
hint.distribution = per_node, wenn die Logik in Ihrem Skript verteilbar ist.- Sie können auch den Partitionsoperator zum Partitionieren des Eingabedatasets verwenden.
- Verwenden Sie nach Möglichkeit die Abfragesprache von Kusto, um die Logik Ihres Python-Skripts zu implementieren.
Verwendungstipps
Um mehrzeilige Zeichenfolgen zu generieren, die das Python-Skript in Ihrem Abfrage-Editor enthalten, kopieren Sie Ihr Python-Skript aus Ihrem bevorzugten Python-Editor (Jupyter, Visual Studio Code, PyCharm usw.), fügen Sie es in Ihren Abfrage-Editor ein, und schließen Sie dann das vollständige Skript zwischen Zeilen mit drei aufeinanderfolgenden Backticks ein. Beispiel:
```
python code
```Verwenden Sie den
externaldataOperator , um den Inhalt eines Skripts abzurufen, das Sie an einem externen Speicherort gespeichert haben, z. B. Azure Blob Storage.
Beispiel
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
Verwandte Inhalte
Weitere Beispiele für UDF-Funktionen, die das Python-Plug-In verwenden, finden Sie in der Functions-Bibliothek.
Diese Funktion wird nicht unterstützt.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für