Plug-in Python

Le plug-in Python exécute une fonction définie par l’utilisateur (UDF) à l’aide d’un script Python. Le script Python obtient des données tabulaires comme entrée et produit une sortie tabulaire. Le runtime du plug-in est hébergé dans des bacs à sable, s’exécutant sur les nœuds du cluster.

Syntaxe

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

En savoir plus sur les conventions de syntaxe.

Paramètres

Variables Python réservées

Les variables suivantes sont réservées pour l’interaction entre Langage de requête Kusto et le code Python.

• df: données tabulaires d’entrée (valeurs ci-dessus), sous forme de T pandas DataFrame.
• kargs: valeur de l’argument script_parameters , en tant que dictionnaire Python.
• result: DataFrame pandas créé par le script Python, dont la valeur devient les données tabulaires envoyées à l’opérateur de requête Kusto qui suit le plug-in.

Activer le plug-in

Cette option est désactivée par défaut. Avant de commencer, passez en revue la liste des prérequis. Pour activer le plug-in et sélectionner la version de l’image Python, consultez Activer les extensions de langage sur votre cluster.

Image de bac à sable Python

Pour modifier la version de l’image Python en une autre image managée ou une image personnalisée, consultez Modifier l’image des extensions de langage Python sur votre cluster.

Pour afficher la liste des packages pour les différentes images Python, consultez la référence du package Python.

Utiliser l’ingestion à partir de la stratégie de requête et de mise à jour

• Utilisez le plug-in dans les requêtes suivantes :
  • Défini dans le cadre d’une stratégie de mise à jour, dont la table source est ingérée à l’aide d’une ingestion sans diffusion en continu .
  • Exécutez dans le cadre d’une commande qui ingère à partir d’une requête, par .set-or-appendexemple .
• Vous ne pouvez pas utiliser le plug-in dans une requête 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 streaming.

Exemples

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"})
)

Astuces pour les performances

• Réduisez le jeu de données d’entrée du plug-in à la quantité minimale requise (colonnes/lignes).
  • Utilisez des filtres sur le jeu de données source, le cas échéant, avec le langage de requête de Kusto.
  • Pour effectuer un calcul sur un sous-ensemble des colonnes sources, projetez uniquement ces colonnes avant d’appeler le plug-in.
• Utilisez hint.distribution = per_node chaque fois que la logique de votre script est distribuable.
  • Vous pouvez également utiliser l’opérateur de partition pour partitionner le jeu de données d’entrée.
• Utilisez le langage de requête de Kusto chaque fois que possible, pour implémenter la logique de votre script Python.

Conseils d’utilisation

• Pour générer des chaînes à plusieurs lignes contenant le script Python dans votre éditeur de requête, copiez votre script Python à partir de votre éditeur Python favori (Jupyter, Visual Studio Code, PyCharm, et ainsi de suite), collez-le dans votre éditeur de requête, puis placez le script complet entre les lignes contenant trois backticks consécutifs. Par exemple :

  ```
python code
```

• Utilisez l’opérateur externaldata pour obtenir le contenu d’un script que vous avez stocké dans un emplacement externe, tel que stockage Blob Azure.

Exemple

    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 

Utilisation d’artefacts externes

Les artefacts externes du stockage cloud peuvent être mis à la disposition du script et utilisés lors de l’exécution.

Les URL référencées par la propriété artefacts externes doivent être les suivantes :

• Inclus dans la stratégie de légende du cluster.
• Dans un emplacement disponible publiquement ou fournissez les informations d’identification nécessaires, comme expliqué dans les chaîne de connexion de stockage.

Les artefacts sont mis à la disposition du script pour qu’il consomme à partir d’un répertoire temporaire local. .\Temp Les noms fournis dans le conteneur de propriétés sont utilisés comme noms de fichiers locaux. Voir Exemples.

Pour plus d’informations sur le référencement de packages externes, consultez Installer des packages pour le plug-in Python.

Actualisation du cache d’artefacts externes

Les fichiers d’artefacts externes utilisés dans les requêtes sont mis en cache sur votre cluster. Si vous effectuez des mises à jour de vos fichiers dans le stockage cloud et que vous avez besoin d’une synchronisation immédiate avec votre cluster, vous pouvez utiliser la commande .clear cluster cache external-artifacts. Cette commande efface les fichiers mis en cache et garantit que les requêtes suivantes s’exécutent avec la dernière version des artefacts.

Installer des packages pour le plug-in Python

Dans la plupart des cas d’usage, vous préférerez peut-être créer une image personnalisée.

Vous souhaiterez peut-être installer vous-même des packages pour les raisons suivantes :

• Vous n’avez pas les autorisations nécessaires pour créer une image personnalisée.
• Le package est privé.
• Vous préférez créer une installation de package ad hoc pour le test et ne souhaitez pas que la surcharge de création d’une image personnalisée soit nécessaire.

Installez les packages comme suit :

Prérequis

1. Créez un conteneur d’objets blob pour héberger les packages, de préférence au même endroit que votre cluster. Par exemple, https://artifactswestus.blob.core.windows.net/pythonen supposant que votre cluster se trouve dans la région USA Ouest.

2. Modifiez la stratégie de légende du cluster pour autoriser l’accès à cet emplacement.

   • Cette modification nécessite des autorisations AllDatabasesAdmin .

   • Par exemple, pour activer l’accès à un objet blob situé dans https://artifactswestus.blob.core.windows.net/python, exécutez la commande suivante :

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

Installer des packages

1. Pour les packages publics dans PyPi ou d’autres canaux, téléchargez le package et ses dépendances.

   • À partir d’une fenêtre cmd dans votre environnement Windows Python local, exécutez :

   pip wheel [-w download-dir] package-name.
   

2. Créez un fichier ZIP qui contient le package requis et ses dépendances.

   • Pour les packages privés, compressez le dossier du package et les dossiers de ses dépendances.
   • Pour les packages publics, compressez les fichiers téléchargés à l’étape précédente.

   Remarque

   • Veillez à télécharger le package compatible avec le moteur Python et la plateforme du runtime de bac à sable (actuellement 3.6.5 sur Windows)
   • Veillez à compresser les .whl fichiers eux-mêmes, et non à leur dossier parent.
   • Vous pouvez ignorer .whl les fichiers des packages qui existent déjà avec la même version dans l’image de bac à sable de base.

3. Chargez le fichier compressé dans un objet blob à l’emplacement des artefacts (à l’étape 1).

4. Appelez le python plug-in.

   • Spécifiez le external_artifacts paramètre avec un conteneur de propriétés de nom et référence au fichier ZIP (URL de l’objet blob, y compris un jeton SAP).
   • Dans votre code python inline, importez et sandbox_utils appelez Zipackage sa install() méthode avec le nom du fichier ZIP.

Exemple

Installez le package Faker qui génère des données fausses.

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 ***'))

Contenu connexe

Pour plus d’exemples de fonctions UDF qui utilisent le plug-in Python, consultez la bibliothèque Functions.

Le plug-in Python exécute une fonction définie par l’utilisateur (UDF) à l’aide d’un script Python. Le script Python obtient des données tabulaires comme entrée et produit une sortie tabulaire.

Syntaxe

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

En savoir plus sur les conventions de syntaxe.

Paramètres

Variables Python réservées

Les variables suivantes sont réservées pour l’interaction entre Langage de requête Kusto et le code Python.

• df: données tabulaires d’entrée (valeurs ci-dessus), sous forme de T pandas DataFrame.
• kargs: valeur de l’argument script_parameters , en tant que dictionnaire Python.
• result: DataFrame pandas créé par le script Python, dont la valeur devient les données tabulaires envoyées à l’opérateur de requête Kusto qui suit le plug-in.

Activer le plug-in

Cette option est désactivée par défaut. Avant de commencer, activez le plug-in Python dans votre base de données KQL.

Image de bac à sable Python

Pour afficher la liste des packages pour les différentes images Python, consultez la référence du package Python.

Utiliser l’ingestion à partir de la stratégie de requête et de mise à jour

• Utilisez le plug-in dans les requêtes suivantes :
  • Défini dans le cadre d’une stratégie de mise à jour, dont la table source est ingérée à l’aide d’une ingestion sans diffusion en continu .
  • Exécutez dans le cadre d’une commande qui ingère à partir d’une requête, par .set-or-appendexemple .
• Vous ne pouvez pas utiliser le plug-in dans une requête 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 streaming.

Exemples

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 

Astuces pour les performances

• Réduisez le jeu de données d’entrée du plug-in à la quantité minimale requise (colonnes/lignes).
  • Utilisez des filtres sur le jeu de données source, le cas échéant, avec le langage de requête de Kusto.
  • Pour effectuer un calcul sur un sous-ensemble des colonnes sources, projetez uniquement ces colonnes avant d’appeler le plug-in.
• Utilisez hint.distribution = per_node chaque fois que la logique de votre script est distribuable.
  • Vous pouvez également utiliser l’opérateur de partition pour partitionner le jeu de données d’entrée.
• Utilisez le langage de requête de Kusto chaque fois que possible, pour implémenter la logique de votre script Python.

Conseils d’utilisation

• Pour générer des chaînes à plusieurs lignes contenant le script Python dans votre éditeur de requête, copiez votre script Python à partir de votre éditeur Python favori (Jupyter, Visual Studio Code, PyCharm, et ainsi de suite), collez-le dans votre éditeur de requête, puis placez le script complet entre les lignes contenant trois backticks consécutifs. Par exemple :

  ```
python code
```

• Utilisez l’opérateur externaldata pour obtenir le contenu d’un script que vous avez stocké dans un emplacement externe, tel que stockage Blob Azure.

Exemple

    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 

Contenu connexe

Pour plus d’exemples de fonctions UDF qui utilisent le plug-in Python, consultez la bibliothèque Functions.