Fonctions JavaScript définies par l’utilisateur dans Azure Stream Analytics

Azure Stream Analytics prend en charge les fonctions définies par l’utilisateur écrites en JavaScript. Avec le large éventail de méthodes String, RegExp, Math, Array et Date que fournit JavaScript, les transformations complexes de données des travaux Stream Analytics sont plus faciles à créer.

Vue d’ensemble

Les fonctions JavaScript définies par l’utilisateur prennent en charge les fonctions scalaires de calcul pur sans état qui ne nécessitent pas de connectivité externe. La valeur renvoyée par une fonction ne peut être qu’une valeur (unique) scalaire. Une fois que vous avez ajouté une fonction JavaScript définie par l’utilisateur à un travail, vous pouvez utiliser la fonction n’importe où dans la requête, comme une fonction scalaire intégrée.

Voici quelques scénarios dans lesquels les fonctions JavaScript définies par l’utilisateur vous seront utiles :

• Analyse et manipulation de chaînes avec des fonctions d’expressions régulières, par exemple Regexp_Replace() et Regexp_Extract()
• Décodage de données encodées, par exemple la conversion de binaire en hexadécimal
• Calculs mathématiques avec les fonctions Math de JavaScript
• Opérations de tableaux comme le tri, la jointure, la recherche et le remplissage

Voici quelques actions que vous ne pouvez pas effectuer avec une fonction JavaScript définie par l’utilisateur dans Stream Analytics :

• Appel de points de terminaison REST externes, par exemple la recherche inversée d’une adresse IP ou l’extraction de données de référence à partir d’une source externe
• Sérialisation ou désérialisation à un format d’événement personnalisé sur les entrées/sorties
• Création d’agrégats personnalisés

Bien qu’elles ne soient pas bloquées dans la définition des fonctions, évitez d’utiliser des fonctions telles que Date.GetDate() ou Math.random() . Ces fonctions ne retournent pas le même résultat à chaque fois que vous les appelez et le service Azure Stream Analytics ne conserve pas de journal des appels de fonction et des résultats retournés. Si une fonction retourne un résultat différent sur les mêmes événements, la reproductibilité n’est pas garantie quand un travail est relancé par vos soins ou par le service Stream Analytics.

Ajouter une fonction JavaScript définie par l’utilisateur à votre travail

Pour créer une fonction JavaScript définie par l’utilisateur dans votre travail Stream Analytics, sélectionnez Fonctions sous Topologie de la tâche. Ensuite, sélectionnez UDF Javascript dans le menu déroulant +Ajouter.

Vous devez ensuite fournir les propriétés suivantes et sélectionner Enregistrer.

Tester les fonctions JavaScript définies par l’utilisateur et résoudre les problèmes les concernant

Vous pouvez tester et déboguer votre logique de fonctions UDF JavaScript dans n’importe quel navigateur. Le débogage et le test de la logique de ces fonctions définies par l’utilisateur ne sont actuellement pas pris en charge dans le portail Stream Analytics. Une fois que la fonction fonctionne comme prévu, vous pouvez l’ajouter au travail Stream Analytics comme indiqué ci-dessus, puis l’appeler directement à partir de votre requête. Vous pouvez tester la logique de votre requête avec la fonction JavaScript définie par l’utilisateur à l’aide des outils Stream Analytics pour Visual Studio.

Les erreurs d’exécution JavaScript sont considérées comme irrécupérables et remontées par le biais du journal d’activité. Pour récupérer le journal, dans le portail Azure, accédez à votre travail et sélectionnez Journal d’activité.

Appeler une fonction JavaScript définie par l’utilisateur dans une requête

Vous pouvez facilement appeler votre fonction JavaScript dans votre requête à l’aide de l’alias de fonction préfixé avec udf. Voici l’exemple d’une fonction JavaScript définie par l’utilisateur, qui convertit des valeurs hexadécimales en entier, appelée dans une requête Stream Analytics.

    SELECT
        time,
        UDF.hex2Int(offset) AS IntOffset
    INTO
        output
    FROM
        InputStream

Objets JavaScript pris en charge

Les fonctions JavaScript définies par l’utilisateur Azure Stream Analytics prennent en charge les objets prédéfinis standard du langage JavaScript. Pour obtenir la liste de ces objets, consultez Objets globaux.

Conversion de type Stream Analytics et JavaScript

Il existe des différences entre les types pris en charge dans le langage de requête Stream Analytics et JavaScript. Le tableau suivant répertorie les mappages de conversion entre les deux :

Voici les conversions de JavaScript à Stream Analytics :

Le langage JavaScript respecte la casse, et la casse des champs d’objet dans le code JavaScript doit correspondre à la casse des champs dans les données entrantes. Les tâches avec le niveau de compatibilité 1.0 convertissent les champs de l’instruction SQL SELECT en minuscules. À partir de la compatibilité 1.1 et dans les versions ultérieures, les champs de l’instruction SELECT auront la même casse que celle spécifiée dans la requête SQL.

Autres modèles de fonctions JavaScript définies par l’utilisateur

Écrire du code JSON imbriqué en sortie

Si vous avez une étape de traitement de suivi qui prend la sortie du travail Stream Analytics en entrée et qu’un format JSON est requis, vous pouvez écrire une chaîne JSON comme sortie. L’exemple suivant appelle la fonction JSON.stringify() pour compresser toutes les paires nom/valeur de l’entrée, puis les écrire sous la forme d’une valeur de chaîne unique en sortie.

Définition de la fonction JavaScript définie par l’utilisateur :

function main(x) {
return JSON.stringify(x);
}

Exemple de requête :

SELECT
    DataString,
    DataValue,
    HexValue,
    UDF.jsonstringify(input) As InputEvent
INTO
    output
FROM
    input PARTITION BY PARTITIONID

Convertir une chaîne en objet JSON à traiter

Si vous disposez d’un champ de chaîne JSON que vous souhaitez convertir en objet JSON à des fins de traitement dans une fonction JavaScript définie par l’utilisateur, vous pouvez utiliser la fonction JSON.parse() pour créer un objet JSON à utiliser ensuite.

Définition de la fonction JavaScript définie par l’utilisateur :

function main(x) {
var person = JSON.parse(x);  
return person.name;
}

Exemple de requête :

SELECT
    UDF.getName(input) AS Name
INTO
    output
FROM
    input

Utiliser try/catch pour la gestion des erreurs

Les blocs try/catch vous aident à identifier les problèmes liés aux données d’entrée incorrectes transmises dans une fonction JavaScript définie par l’utilisateur.

Définition de la fonction JavaScript définie par l’utilisateur :

function main(input, x) {
    var obj = null;

    try{
        obj = JSON.parse(x);
    }catch(error){
        throw input;
    }
    
    return obj.Value;
}

Exemple de requête : Transmettez l’intégralité de l’enregistrement en tant que premier paramètre de manière à ce qu’il soit renvoyé en cas d’erreur.

SELECT
    A.context.company AS Company,
    udf.getValue(A, A.context.value) as Value
INTO
    output
FROM
    input A

toLocaleString()

La méthode toLocaleString en JavaScript peut être utilisée pour retourner une chaîne sensible au langage qui représente les données de date et d’heure d’où cette méthode est appelée. Bien qu’Azure Stream Analytics accepte uniquement la date et l’heure UTC comme timestamp système, vous pouvez utiliser cette méthode pour convertir le timestamp système en choisissant d’autres paramètres régionaux et un autre fuseau horaire. Cette méthode suit le même comportement d’implémentation que celui disponible dans Internet Explorer.

Définition de la fonction JavaScript définie par l’utilisateur :

function main(datetime){
    const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
    return datetime.toLocaleDateString('de-DE', options);
}

Exemple de requête : Passer une valeur DateTime comme valeur d’entrée

SELECT
    udf.toLocaleString(input.datetime) as localeString
INTO
    output
FROM
    input

La sortie de cette requête sera la valeur DateTime d’entrée dans de-DE avec les options fournies.

Samstag, 28. Dezember 2019

Journalisation utilisateur

Le mécanisme de journalisation permet aux utilisateurs de capturer des informations personnalisées pendant l’exécution d’un travail. Vous pouvez utiliser les données de journal pour déboguer ou évaluer l’exactitude du code personnalisé en temps réel. Ce mécanisme est disponible via trois méthodes différentes.

Console.Info()

La méthode Console.Info permet d’enregistrer des informations générales pendant l’exécution du code. Cette méthode journalise les données sans interrompre le calcul. Le message journalisé est marqué comme Informations sur le niveau de l’événement.

console.info('my info message');

Console.Warn()

La méthode Console.Warn permet de journaliser des données qui peuvent ne pas être correctes ou attendues, mais qui sont toujours acceptées pour le calcul. Cette méthode n’interrompt pas le calcul et reprendra son exécution une fois la méthode retournée. Le message journalisé est marqué comme Avertissement au niveau de l’événement.

console.warn('my warning message');

Console.Error() et Console.Log()

La méthode Console.Error permet uniquement de journaliser les cas d’erreur où le code ne peut pas continuer à s’exécuter. Cette méthode lève une exception avec les informations d’erreur fournies en tant que paramètre d’entrée et le travail cesse de s’exécuter. Le message d’erreur journalisé est marqué comme Erreur au niveau de l’événement.

console.error('my error message');

Vous pouvez accéder aux messages du journal par le biais des journaux de diagnostic.

atob() et btoa()

La méthode btoa() permet de coder une chaîne ASCII en Base64. Cette opération est généralement effectuée pour transférer des données dans un format binaire. La méthode atob() peut être utilisée pour décoder une chaîne de données codée en Base64 au format de chaîne ASCII.

var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);

Étapes suivantes

• Fonction définie par l’utilisateur pour le machine learning
• C# UDF