教程:Azure 流分析 JavaScript 用户定义的函数Tutorial: Azure Stream Analytics JavaScript user-defined functions

Azure 流分析支持以 JavaScript 编写的用户定义的函数。Azure Stream Analytics supports user-defined functions written in JavaScript. 利用 JavaScript 提供的丰富 StringRegExpMathArrayDate 方法,可以更轻松地创建包含流分析作业的复杂数据转换。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.

本教程介绍如何执行下列操作:In this tutorial, you learn how to:

  • 定义 JavaScript 用户定义的函数Define a JavaScript user-defined function
  • 将函数添加到门户Add the function to the portal
  • 定义运行函数的查询Define a query that runs the function

如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

JavaScript 用户定义的函数JavaScript user-defined functions

JavaScript 用户定义的函数支持仅用于计算的且不需要外部连接的无状态标量函数。JavaScript user-defined functions support stateless, compute-only scalar functions that do not require external connectivity. 函数的返回值只能是标量(单个)值。The return value of a function can only be a scalar (single) value. 将某个 JavaScript 用户定义的函数添加到作业后,可在查询中的任意位置使用该函数,如同内置标量函数一样。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.

下面是 JavaScript 用户定义的函数可派上用场的一些情景:Here are some scenarios where you might find JavaScript user-defined functions useful:

  • 使用 Regexp_Replace()Regexp_Extract() 等正则表达式函数分析和处理字符串Parsing and manipulating strings that have regular expression functions, for example, Regexp_Replace() and Regexp_Extract()
  • 解码和编码数据,例如,二进制到十六进制的转换Decoding and encoding data, for example, binary-to-hex conversion
  • 使用 JavaScript Math 函数执行数学计算Performing mathematic computations with JavaScript Math functions
  • 执行排序、联接、查找和填充等数组操作Performing array operations like sort, join, find, and fill

使用流分析中的 JavaScript 用户定义的函数无法实现以下目的:Here are some things that you cannot do with a JavaScript user-defined function in Stream Analytics:

  • 调用外部 REST 终结点,例如,执行反向 IP 查找,或者从外部源提取引用数据Call out external REST endpoints, for example, performing reverse IP lookup or pulling reference data from an external source
  • 针对输入/输出执行自定义事件格式序列化或反序列化Perform custom event format serialization or deserialization on inputs/outputs
  • 创建自定义聚合Create custom aggregates

尽管函数定义中并不禁止 Date.GetDate()Math.random() 等函数,但应该避免使用这些函数。Although functions like Date.GetDate() or Math.random() are not blocked in the functions definition, you should avoid using them. 这些函数在每次被调用时不会返回相同的结果,并且 Azure 流分析服务不会保留函数调用和返回结果的日记。These functions do not return the same result every time you call them, and the Azure Stream Analytics service does not keep a journal of function invocations and returned results. 当你或流分析服务重新启动某个作业时,如果某个函数针对相同的事件返回不同的结果,则无法保证可重复性。If a function returns different result on the same events, repeatability is not guaranteed when a job is restarted by you or by the Stream Analytics service.

在 Azure 门户中添加 JavaScript 用户定义的函数Add a JavaScript user-defined function in the Azure portal

若要在现有的流分析作业中创建一个简单的 JavaScript 用户定义函数,请执行以下步骤:To create a simple JavaScript user-defined function under an existing Stream Analytics job, follow these steps:

Note

这些步骤适用于配置为在云中运行的流分析作业。These steps work on the Stream Analytics jobs configured to run in the cloud. 如果流分析作业配置为在 Azure IoT Edge 上运行,请改用 Visual Studio 并使用 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#.

  1. 在 Azure 门户中找到流分析作业。In the Azure portal, find your Stream Analytics job.

  2. 在“作业拓扑”标题下,选择“函数”。Under the Job topology heading, select Functions. 此时显示一个空白的函数列表。An empty list of functions appears.

  3. 若要新建用户定义函数,请选择“+添加”。To create a new user-defined function, select + Add.

  4. 在“新建函数”边栏选项卡中,为“函数类型”选择“JavaScript”。On the New Function blade, for Function Type, select JavaScript. 编辑器中会显示默认函数模板。A default function template appears in the editor.

  5. 为“UDF 别名”输入 hex2Int,并按如下所示更改函数实现:For the UDF alias, enter hex2Int, and change the function implementation as follows:

    // Convert Hex value to integer.
    function hex2Int(hexValue) {
        return parseInt(hexValue, 16);
    }
    
  6. 选择“其他安全性验证” 。Select Save. 该函数随即显示在函数列表中。Your function appears in the list of functions.

  7. 选择新的 hex2Int 函数并检查函数定义。Select the new hex2Int function, and check the function definition. 所有函数的函数别名带有 UDF 前缀。All functions have a UDF prefix added to the function alias. 在流分析查询中调用该函数时,需要 包含该前缀You need to include the prefix when you call the function in your Stream Analytics query. 在本例中,调用的是 UDF.hex2IntIn this case, you call UDF.hex2Int.

在查询中调用 JavaScript 用户定义的函数Call a JavaScript user-defined function in a query

  1. 在查询编辑器中的“作业拓扑”标题下,选择“查询”。In the query editor, under the Job topology heading, select Query.

  2. 编辑查询,并调用该用户定义的函数,如下所示:Edit your query, and then call the user-defined function, like this:

    SELECT
        time,
        UDF.hex2Int(offset) AS IntOffset
    INTO
        output
    FROM
        InputStream
    
  3. 若要上传示例数据文件,请右键单击作业输入。To upload the sample data file, right-click the job input.

  4. 若要测试查询,请选择“测试”。To test your query, select Test.

支持的 JavaScript 对象Supported JavaScript objects

Azure 流分析 JavaScript 用户定义的函数支持标准的内置 JavaScript 对象。Azure Stream Analytics JavaScript user-defined functions support standard, built-in JavaScript objects. 有关这些对象的列表,请参阅 Global Objects(全局对象)。For a list of these objects, see Global Objects.

流分析和 JavaScript 类型转换Stream Analytics and JavaScript type conversion

流分析查询语言与 JavaScript 支持的类型有差别。There are differences in the types that the Stream Analytics query language and JavaScript support. 下表列出了两者之间的转换映射:This table lists the conversion mappings between the two:

流分析Stream Analytics JavascriptJavaScript
bigintbigint 数字(JavaScript 只能精确呈现最大 2^53 的整数)Number (JavaScript can only represent integers up to precisely 2^53)
DateTimeDateTime 日期(JavaScript 仅支持毫秒)Date (JavaScript only supports milliseconds)
Doubledouble NumberNumber
nvarchar(MAX)nvarchar(MAX) StringString
记录Record 对象Object
ArrayArray ArrayArray
NullNULL NullNull

下面是 JavaScript 到流分析的转换:Here are JavaScript-to-Stream Analytics conversions:

JavascriptJavaScript 流分析Stream Analytics
NumberNumber 如果数字已舍入并介于 long.MinValue 和 long.MaxValue 之间,则为 Bigint;否则为 double日期Bigint (if the number is round and between long.MinValue and long.MaxValue; otherwise, it's double)
日期Date DateTimeDateTime
StringString nvarchar(MAX)nvarchar(MAX)
对象Object 记录Record
ArrayArray ArrayArray
Null、UndefinedNull, Undefined NullNULL
其他任何类型(例如函数或错误)Any other type (for example, a function or error) 不支持(导致运行时错误)Not supported (results in runtime error)

故障排除Troubleshooting

JavaScript 运行时错误被视为严重错误,可通过活动日志查看。JavaScript runtime errors are considered fatal, and are surfaced through the Activity log. 如果要检索日志,请在 Azure 门户中转到用户的作业,并选择“活动日志”。To retrieve the log, in the Azure portal, go to your job and select Activity log.

JavaScript 用户定义的函数的其他模式Other JavaScript user-defined function patterns

编写要输出的嵌套 JSONWrite nested JSON to output

如果后续处理步骤需要使用流分析作业输出作为输入并且要求采用 JSON 格式,可以编写要输出的 JSON 字符串。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. 以下示例调用 JSON.stringify() 函数封装输入的所有名称/值对,并将其写入为输出中的单个字符串值。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.

JavaScript 用户定义的函数定义:JavaScript user-defined function definition:

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

示例查询:Sample query:

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

清理资源Clean up resources

若不再需要资源组、流式处理作业以及所有相关资源,请将其删除。When no longer needed, delete the resource group, the streaming job, and all related resources. 删除作业可避免对作业使用的流单元进行计费。Deleting the job avoids billing the streaming units consumed by the job. 如果计划在将来使用该作业,可以先停止该作业,以后在需要时再重启该作业。If you're planning to use the job in future, you can stop it and re-start it later when you need. 如果不打算继续使用该作业,请按照以下步骤删除本快速入门创建的所有资源:If you are not going to continue to use this job, delete all resources created by this quickstart by using the following steps:

  1. 在 Azure 门户的左侧菜单中,单击“资源组”,然后单击已创建资源的名称。From the left-hand menu in the Azure portal, click Resource groups and then click the name of the resource you created.
  2. 在资源组页上单击“删除”,在文本框中键入要删除的资源的名称,并单击“删除”。On your resource group page, click Delete, type the name of the resource to delete in the text box, and then click Delete.

获取帮助Get help

如需更多帮助,请访问我们的 Azure 流分析论坛For additional help, try our Azure Stream Analytics forum.