Plug-in PythonPython plugin

Le plug-in Python exécute une fonction définie par l’utilisateur (UDF) à l’aide d’un script Python.The Python plugin runs a user-defined-function (UDF) using a Python script. Le script Python obtient les données tabulaires en tant qu’entrée et est censé produire une sortie tabulaire.The Python script gets tabular data as its input, and is expected to produce a tabular output. Le runtime du plug-in est hébergé dans les bacs à sable (sandbox), en cours d’exécution sur les nœuds du cluster.The plugin's runtime is hosted in sandboxes, running on the cluster's nodes.

SyntaxeSyntax

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])

ArgumentsArguments

  • output_schema: type littéral qui définit le schéma de sortie des données tabulaires, retourné par le code Python.output_schema: A type literal that defines the output schema of the tabular data, returned by the Python code.
    • Le format est : typeof( ColumnName : ColumnType[,...] ) . Par exemple, typeof(col1:string, col2:long) .The format is: typeof(ColumnName: ColumnType[, ...]). For example, typeof(col1:string, col2:long).
    • Pour étendre le schéma d’entrée, utilisez la syntaxe suivante : typeof(*, col1:string, col2:long)To extend the input schema, use the following syntax: typeof(*, col1:string, col2:long)
  • script: string littéral qui est le script Python valide à exécuter.script: A string literal that is the valid Python script to execute.
  • script_parameters: littéral facultatif dynamic .script_parameters: An optional dynamic literal. Il s’agit d’un jeu de propriétés de paires nom/valeur à passer au script Python en tant que kargs dictionnaire réservé.It's a property bag of name/value pairs to be passed to the Python script as the reserved kargs dictionary. Pour plus d’informations, consultez variables python réservées.For more information, see Reserved Python variables.
  • hint. distribution: indication facultative pour que l’exécution du plug-in soit distribuée sur plusieurs nœuds de cluster.hint.distribution: An optional hint for the plugin's execution to be distributed across multiple cluster nodes.
    • La valeur par défaut est single.The default value is single.
    • single: Une seule instance du script est exécutée sur l’ensemble des données de la requête.single: A single instance of the script will run over the entire query data.
    • per_node: Si la requête avant le bloc Python est distribuée, une instance du script s’exécutera sur chaque nœud, sur les données qu’elle contient.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: un dynamic littéral facultatif qui est un jeu de propriétés de paires nom/URL, pour les artefacts accessibles à partir du stockage 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. Elles peuvent être rendues disponibles pour le script à utiliser au moment de l’exécution.They can be made available for the script to use at runtime.
    • Les URL référencées dans ce conteneur de propriétés doivent être :URLs referenced in this property bag are required to be:
    • Les artefacts sont rendus disponibles pour le script à utiliser à partir d’un répertoire temporaire local, .\Temp .The artifacts are made available for the script to consume from a local temporary directory, .\Temp. Les noms fournis dans le jeu de propriétés sont utilisés comme noms de fichiers locaux.The names provided in the property bag are used as the local file names. Consultez les exemples.See Examples.
    • Pour plus d’informations, consultez installer des packages pour le plug-in Python.For more information, see Install packages for the Python plugin.

Variables python réservéesReserved Python variables

Les variables suivantes sont réservées pour l’interaction entre le langage de requête Kusto et le code Python.The following variables are reserved for interaction between Kusto query language and the Python code.

  • df: Données tabulaires d’entrée (les valeurs T ci-dessus), en tant que pandas tableau.df: The input tabular data (the values of T above), as a pandas DataFrame.
  • kargs: La valeur de l’argument script_parameters , sous la forme d’un dictionnaire Python.kargs: The value of the script_parameters argument, as a Python dictionary.
  • result: pandas Tableau créé par le script Python, dont la valeur devient les données tabulaires qui sont envoyées à l’opérateur de requête Kusto qui suit le 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.

Activer le plug-inEnable the plugin

  • Le plug-in est désactivé par défaut.The plugin is disabled by default.
  • Pour activer le plug-in, consultez la liste des composants requis.To enable the plugin, see the list of prerequisites.
  • Activez ou désactivez le plug-in dans le Portail Azure, dans l' onglet Configurationde votre cluster.Enable or disable the plugin in the Azure portal, in your cluster's Configuration tab.

Image Python sandboxPython sandbox image

  • L’image Python sandbox est basée sur la distribution Anaconda 5.2.0 avec le moteur python 3,6 .The Python sandbox image is based on Anaconda 5.2.0 distribution with the Python 3.6 engine. Consultez la liste des packages Anaconda.See the list of Anaconda packages.

    Notes

    Un petit pourcentage de packages peut être incompatible avec les limitations imposées par le bac à sable (sandbox) dans lequel le plug-in est exécuté.A small percentage of packages might be incompatible with the limitations enforced by the sandbox where the plugin is run.

  • L’image Python contient également des packages ml communs : tensorflow ,,,, keras et d' torch hdbscan xgboost autres packages utiles.The Python image also contains common ML packages: tensorflow, keras, torch, hdbscan, xgboost, and other useful packages.

  • Le plug-in importe numpy (comme np ) & pandas (AS pd ) par défaut.The plugin imports numpy (as np) & pandas (as pd) by default. Vous pouvez importer d’autres modules en fonction des besoins.You can import other modules as needed.

Utiliser l’ingestion à partir d’une requête et d’une stratégie de mise à jourUse Ingestion from query and update policy

  • Utilisez le plug-in dans les requêtes suivantes :Use the plugin in queries that are:
    • Défini dans le cadre d’une stratégie de mise à jour, dont la table source est ingérée pour l’utilisation de la non-diffusion en continu .Defined as part of an update policy, whose source table is ingested to using non-streaming ingestion.
    • Exécutez dans le cadre d’une commande qui est ingérée à partir d’une requête, telle que .set-or-append .Run as part of a command that ingests from a query, such as .set-or-append. Dans ces deux cas, vérifiez que le volume et la fréquence de l’ingestion, ainsi que la complexité et les ressources utilisées par la logique Python, s’alignent sur les limitations du bac à sable (sandbox) et sur les ressources disponibles du 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. Dans le cas contraire, vous risquez d’obtenir des Erreurs de limitation.Failure to do so may result in throttling errors.
  • Vous ne pouvez pas utiliser le plug-in dans une requête qui est définie dans le cadre d’une stratégie de mise à jour, dont la table source est ingérée à l’aide de l’ingestion de diffusion en continu.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.

ExemplesExamples

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 

démonstration sinus

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"})
)
FichierFile TailleSize
this_is_a_scriptthis_is_a_script 120120
this_is_my_first_filethis_is_my_first_file 105105

Conseils sur les performancesPerformance tips

  • Réduisez le jeu de données d’entrée du plug-in sur la quantité minimale requise (colonnes/lignes).Reduce the plugin's input data set to the minimum amount required (columns/rows).

    • Utilisez des filtres sur le jeu de données source, si possible, avec le langage de requête de Kusto.Use filters on the source data set, when possible, with Kusto's query language.
    • Pour effectuer un calcul sur un sous-ensemble des colonnes sources, projetez uniquement ces colonnes avant d’appeler le plug-in.To do a calculation on a subset of the source columns, project only those columns before invoking the plugin.
  • Utilisez hint.distribution = per_node chaque fois que la logique de votre script est distribuable.Use hint.distribution = per_node whenever the logic in your script is distributable.

  • Utilisez le langage de requête de Kusto dans la mesure du possible pour implémenter la logique de votre script Python.Use Kusto's query language whenever possible, to implement the logic of your Python script.

    ExempleExample

    .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)
    

Conseils d’utilisationUsage tips

  • Pour générer des chaînes multilignes contenant le script Python dans Kusto.Explorer , copiez votre script Python à partir de votre éditeur Python favori (Jupyter, Visual Studio code, PyCharm, etc.).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). À présent, effectuez l’une des opérations suivantes :Now do one of:

    • Appuyez sur F2 pour ouvrir la fenêtre modifier dans python .Press F2 to open the Edit in Python window. Collez le script dans cette fenêtre.Paste the script into this window. Sélectionnez OK.Select OK. Le script sera décoré avec des guillemets et de nouvelles lignes, il est donc valide dans Kusto et collé automatiquement dans l’onglet requête.The script will be decorated with quotes and new lines, so it's valid in Kusto, and automatically pasted into the query tab.
    • Collez le code python directement dans l’onglet requête. Sélectionnez ces lignes, puis appuyez sur CTRL + K, CTRL + S touches d’accès rapide pour les décorer comme indiqué ci-dessus.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. Pour inverser, appuyez sur CTRL + K, Ctrl + M touches d’accès rapide.To reverse, press Ctrl+K, Ctrl+M hot keys. Consultez la liste complète des raccourcisde l’éditeur de requête.See the full list of Query Editor shortcuts.
  • Pour éviter les conflits entre les délimiteurs de chaîne Kusto et les littéraux de chaîne Python, utilisez :To avoid conflicts between Kusto string delimiters and Python string literals, use:

    • Guillemets simples ( ' ) pour les littéraux de chaîne Kusto dans les requêtes KustoSingle quote characters (') for Kusto string literals in Kusto queries
    • Guillemets doubles ( " ) pour les littéraux de chaîne python dans les scripts PythonDouble quote characters (") for Python string literals in Python scripts
  • Utilisez l' externaldata opérateur pour obtenir le contenu d’un script que vous avez stocké dans un emplacement externe, tel que le stockage d’objets BLOB 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.

    ExempleExample

    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 
    

Installer des packages pour le plug-in PythonInstall packages for the Python plugin

Vous devrez peut-être installer le ou les packages vous-même pour les raisons suivantes :You may need to install package(s) yourself, for the following reasons:

  • Le package est privé et est votre propre.The package is private and is your own.
  • Le package est public, mais n’est pas inclus dans l’image de base du plug-in.The package is public but isn't included in the plugin's base image.

Installez les packages comme suit :Install packages as follows:

PrérequisPrerequisites

  1. Créez un conteneur d’objets BLOB pour héberger les packages, de préférence au même emplacement que votre cluster.Create a blob container to host the packages, preferably in the same place as your cluster. Par exemple, https://artifcatswestus.blob.core.windows.net/python en supposant que votre cluster se trouve dans l’ouest des États-Unis.For example, https://artifcatswestus.blob.core.windows.net/python, assuming your cluster is in West US.

  2. Modifiez la stratégie de légende du cluster pour autoriser l’accès à cet emplacement.Alter the cluster's callout policy to allow access to that location.

    • Cette modification nécessite des autorisations AllDatabasesAdmin .This change requires AllDatabasesAdmin permissions.

    • Par exemple, pour activer l’accès à un objet BLOB situé dans https://artifcatswestus.blob.core.windows.net/python , exécutez la commande suivante :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 } ]'
    

Installer des packagesInstall packages

  1. Pour les packages publics dans PyPi ou d’autres canaux, téléchargez le package et ses dépendances.For public packages in PyPi or other channels, download the package and its dependencies.

    • Compilez les fichiers Wheel ( *.whl ), si nécessaire.Compile wheel (*.whl) files, if required.
    • À partir d’une fenêtre cmd dans votre environnement python local, exécutez :From a cmd window in your local Python environment, run:
    pip wheel [-w download-dir] package-name.
    
  2. Créez un fichier zip contenant le package requis et ses dépendances.Create a zip file, that contains the required package and its dependencies.

    • Pour les packages privés : compressez le dossier du package et les dossiers de ses dépendances.For private packages: zip the folder of the package and the folders of its dependencies.
    • Pour les packages publics, compressez les fichiers qui ont été téléchargés à l’étape précédente.For public packages, zip the files that were downloaded in the previous step.

    Notes

    • Veillez à compresser les .whl fichiers eux-mêmes, et non leur dossier parent.Make sure to zip the .whl files themselves, and not their parent folder.
    • Vous pouvez ignorer les .whl fichiers pour les packages qui existent déjà avec la même version dans l’image de bac à sable (sandbox) de base.You can skip .whl files for packages that already exist with the same version in the base sandbox image.
  3. Chargez le fichier zippé dans un objet blob à l’emplacement des artefacts (à partir de l’étape 1).Upload the zipped file to a blob in the artifacts location (from step 1).

  4. Appelez le python plug-in.Call the python plugin.

    • Spécifiez le external_artifacts paramètre avec un conteneur de propriétés de nom et une référence au fichier zip (l’URL de l’objet BLOB).Specify the external_artifacts parameter with a property bag of name and reference to the zip file (the blob's URL).
    • Dans votre code python Inline, importez Zipackage à partir de sandbox_utils et appelez sa install() méthode avec le nom du fichier. zip.In your inline python code, import Zipackage from sandbox_utils and call its install() method with the name of the zip file.

ExempleExample

Installez le package factice qui génère des données factices.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 NomName
11 Gary TapiaGary Tapia
22 Emma EvansEmma Evans
33 Ashley BowenAshley Bowen

Cette fonctionnalité n’est pas prise en charge dans Azure MonitorThis capability isn't supported in Azure Monitor