Fonctions JavaScript définies par l’utilisateur dans Azure Stream AnalyticsJavaScript user-defined functions in Azure Stream Analytics

Azure Stream Analytics prend en charge les fonctions définies par l’utilisateur écrites en JavaScript.Azure Stream Analytics supports user-defined functions written in 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.With the rich set of String, RegExp, Math, Array, and Date methods that JavaScript provides, complex data transformations with Stream Analytics jobs become easier to create.

Vue d’ensembleOverview

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.JavaScript user-defined functions support stateless, compute-only scalar functions that don't require external connectivity. La valeur renvoyée par une fonction ne peut être qu’une valeur (unique) scalaire.The return value of a function can only be a scalar (single) value. 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.After you add a JavaScript user-defined function to a job, you can use the function anywhere in the query, like a built-in scalar function.

Voici quelques scénarios dans lesquels les fonctions JavaScript définies par l’utilisateur vous seront utiles :Here are some scenarios where you might find JavaScript user-defined functions useful:

  • Analyse et manipulation de chaînes avec des fonctions d’expressions régulières, par exemple Regexp_Replace() et Regexp_Extract()Parsing and manipulating strings that have regular expression functions, for example, Regexp_Replace() and Regexp_Extract()
  • Décodage de données encodées, par exemple la conversion de binaire en hexadécimalDecoding and encoding data, for example, binary-to-hex conversion
  • Calculs mathématiques avec les fonctions Math de JavaScriptDoing mathematic computations with JavaScript Math functions
  • Opérations de tableaux comme le tri, la jointure, la recherche et le remplissageDoing array operations like sort, join, find, and fill

Voici quelques actions que vous ne pouvez pas effectuer avec une fonction JavaScript définie par l’utilisateur dans Stream Analytics :Here are some things that you can't do with a JavaScript user-defined function in 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 externeCall out external REST endpoints, for example, doing reverse IP lookup or pulling reference data from an external source
  • Sérialisation ou désérialisation à un format d’événement personnalisé sur les entrées/sortiesPerform custom event format serialization or deserialization on inputs/outputs
  • Création d’agrégats personnalisésCreate custom aggregates

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() .Although functions like Date.GetDate() or Math.random() aren't blocked in the functions definition, you should avoid using them. 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.These functions don't return the same result every time you call them, and the Azure Stream Analytics service doesn't keep a journal of function invocations and returned results. 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.If a function returns different result on the same events, repeatability isn't guaranteed when a job is restarted by you or by the Stream Analytics service.

Ajouter une fonction JavaScript définie par l’utilisateur à votre travailAdd a JavaScript user-defined function to your job

Notes

Ces étapes fonctionnent sur les travaux Stream Analytics configurés pour s’exécuter dans le cloud.These steps work on the Stream Analytics jobs configured to run in the cloud. Si votre travail Stream Analytics est configuré pour s’exécuter sur Azure IoT Edge, utilisez plutôt Visual Studio et écrivez la fonction définie par l’utilisateur en C#.If your Stream Analytics job is configured to run on Azure IoT Edge, instead use Visual Studio and write the user-defined function using C#.

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.To create a JavaScript user-defined function in your Stream Analytics job, select Functions under Job Topology. Ensuite, sélectionnez UDF Javascript dans le menu déroulant +Ajouter.Then, select JavaScript UDF from the +Add dropdown menu.

Ajouter une fonction JavaScript définie par l’utilisateur

Vous devez ensuite fournir les propriétés suivantes et sélectionner Enregistrer.You must then provide the following properties and select Save.

PropriétéProperty DescriptionDescription
Alias de fonctionFunction alias Entrez un nom pour appeler la fonction dans votre requête.Enter a name to invoke the function in your query.
Type de sortieOutput type Type qui est retourné par la fonction JavaScript définie par l’utilisateur à votre requête Stream Analytics.Type that will be returned by your JavaScript user-defined function to your Stream Analytics query.
Définition de fonctionFunction definition Implémentation de votre fonction JavaScript qui est exécutée chaque fois que votre fonction définie par l’utilisateur est appelée à partir de votre requête.Implementation of your JavaScript function that will be executed each time your UDF gets invoked from your query.

Tester les fonctions JavaScript définies par l’utilisateur et résoudre les problèmes les concernantTest and troubleshoot JavaScript UDFs

Vous pouvez tester et déboguer votre logique de fonctions UDF JavaScript dans n’importe quel navigateur.You can test and debug your JavaScript UDF logic in any browser. 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.Debugging and testing the logic of these user-defined functions is currently not supported in the Stream Analytics portal. 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.Once the function works as expected, you can add it to the Stream Analytics job as mentioned above and then invoke it directly from your query. 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.You can test your query logic with JavaScript UDF using Stream Analytics tools for 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é.JavaScript runtime errors are considered fatal, and are surfaced through the Activity log. Pour récupérer le journal, dans le portail Azure, accédez à votre travail et sélectionnez Journal d’activité.To retrieve the log, in the Azure portal, go to your job and select Activity log.

Appeler une fonction JavaScript définie par l’utilisateur dans une requêteCall a JavaScript user-defined function in a query

Vous pouvez facilement appeler votre fonction JavaScript dans votre requête à l’aide de l’alias de fonction préfixé avec udf.You can easily invoke your JavaScript function in your query using the function alias prefixed with 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.Here is an example of a JavaScript UDF that converts hexadecimal values to integer being invoked in a Stream Analytics query.

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

Objets JavaScript pris en chargeSupported JavaScript objects

Les fonctions JavaScript définies par l’utilisateur Azure Stream Analytics prennent en charge les objets prédéfinis standard du langage JavaScript.Azure Stream Analytics JavaScript user-defined functions support standard, built-in JavaScript objects. Pour obtenir la liste de ces objets, consultez Objets globaux.For a list of these objects, see Global Objects.

Conversion de type Stream Analytics et JavaScriptStream Analytics and JavaScript type conversion

Il existe des différences entre les types pris en charge dans le langage de requête Stream Analytics et JavaScript.There are differences in the types that the Stream Analytics query language and JavaScript support. Le tableau suivant répertorie les mappages de conversion entre les deux :This table lists the conversion mappings between the two:

Stream AnalyticsStream Analytics JavaScriptJavaScript
bigintbigint Number (JavaScript ne peut représenter les entiers que jusqu’à 2^53 précisément)Number (JavaScript can only represent integers up to precisely 2^53)
DateTimeDateTime Date (JavaScript ne prend en charge que les millisecondes)Date (JavaScript only supports milliseconds)
doubledouble NumberNumber
nvarchar(MAX)nvarchar(MAX) StringString
EnregistrementRecord ObjectObject
ArrayArray ArrayArray
NULLNULL NullNull

Voici les conversions de JavaScript à Stream Analytics :Here are JavaScript-to-Stream Analytics conversions:

JavaScriptJavaScript Stream AnalyticsStream Analytics
NumberNumber Bigint (si le nombre est rond et entre long.MinValue et long.MaxValue, sinon, double)Bigint (if the number is round and between long.MinValue and long.MaxValue; otherwise, it's double)
DateDate DateTimeDateTime
StringString nvarchar(MAX)nvarchar(MAX)
ObjectObject EnregistrementRecord
ArrayArray ArrayArray
Null, UndefinedNull, Undefined NULLNULL
Un autre type (par exemple une fonction ou une erreur)Any other type (for example, a function or error) Non pris en charge (entraîne une erreur d’exécution)Not supported (results in runtime error)

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.JavaScript language is case-sensitive and casing of the object fields in JavaScript code must match the casing of the fields in the incoming data. Les tâches avec le niveau de compatibilité 1.0 convertissent les champs de l’instruction SQL SELECT en minuscules.Jobs with compatibility level 1.0 will convert fields from SQL SELECT statement to be lowercase. À 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.Under compatibility level 1.1 and higher, fields from SELECT statement will have the same casing as specified in the SQL query.

Autres modèles de fonctions JavaScript définies par l’utilisateurOther JavaScript user-defined function patterns

Écrire du code JSON imbriqué en sortieWrite nested JSON to output

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.If you have a follow-up processing step that uses a Stream Analytics job output as input, and it requires a JSON format, you can write a JSON string to output. 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.The next example calls the JSON.stringify() function to pack all name/value pairs of the input, and then write them as a single string value in output.

Définition de la fonction JavaScript définie par l’utilisateur :JavaScript user-defined function definition:

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

Exemple de requête :Sample query:

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

Convertir une chaîne en objet JSON à traiterCast string to JSON object to process

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.If you have a string field that is JSON and want to convert it to a JSON object for processing in a JavaScript UDF, you can use the JSON.parse() function to create a JSON object that can then be used.

Définition de la fonction JavaScript définie par l’utilisateur :JavaScript user-defined function definition:

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

Exemple de requête :Sample query:

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

Utiliser try/catch pour la gestion des erreursUse try/catch for error handling

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.Try/catch blocks can help you identify problems with malformed input data that are passed into a JavaScript UDF.

Définition de la fonction JavaScript définie par l’utilisateur :JavaScript user-defined function definition:

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.Sample query: Pass entire record as first parameter so that it can be returned if there is an error.

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

toLocaleString()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.The toLocaleString method in JavaScript can be used to return a language sensitive string that represents the date time data from where this method is called. Bien qu’Azure Stream Analtyics accepte uniquement l’heure UTC comme horodatage système, cette méthode peut être utilisée pour convertir l’horodatage système en un autre paramètre régional et fuseau horaire.Even though Azure Stream Analtyics only accepts UTC date time as system timestamp, this method can be used to covert the system timestamp to another locale and timezone. Cette méthode suit le même comportement d’implémentation que celui disponible dans Internet Explorer.This method follows the same implementation behavior as the one available in Internet Explorer .

Définition de la fonction JavaScript définie par l’utilisateur :JavaScript user-defined function definition:

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

Exemple de requête : Passer une valeur DateTime comme valeur d’entréeSample query: Pass a datetime as input value

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.The output of this query will be the input datetime in de-DE with the options provided.

Samstag, 28. Dezember 2019

Journalisation utilisateurUser Logging

Le mécanisme de journalisation vous permet de capturer des informations personnalisées pendant l’exécution d’un travail.The logging mechanism allows you to capture custom information while a job is running. Vous pouvez utiliser les données de journal pour déboguer ou évaluer l’exactitude du code personnalisé en temps réel.You can use log data to debug or assess the correctness of the custom code in real time. Ce mécanisme est disponible via la méthode Console.Log().This mechanism is available through the Console.Log() method.

console.log('my error message');

Vous pouvez accéder aux messages du journal par le biais des journaux de diagnostic.You can access log messages through the diagnostic logs.

Étapes suivantesNext steps