Привязки центра Интернета вещей Azure для функций AzureAzure IoT Hub bindings for Azure Functions

В этой статье объясняется, как работать с привязками функций Azure для центра Интернета вещей.This article explains how to work with Azure Functions bindings for IoT Hub. Поддержка центра Интернета вещей основана на привязке концентраторов событий Azure.The IoT Hub support is based on the Azure Event Hubs Binding.

Это справочные сведения для разработчиков функций Azure.This is reference information for Azure Functions developers. Если вы новичок в функциях Azure, начните со следующих ресурсов:If you're new to Azure Functions, start with the following resources:

Пакеты – Функции 1.xPackages - Functions 1.x

Для функций Azure версии 1. x привязки центра Интернета вещей предоставляются в пакете NuGet Microsoft. Azure. веб-заданий. servicebus , версия 2. x.For Azure Functions version 1.x, the IoT Hub bindings are provided in the Microsoft.Azure.WebJobs.ServiceBus NuGet package, version 2.x. Исходный код для пакета находится в репозитории GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Для добавления поддержки вTo add support in
Функции 1.xFunctions 1.x
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка – Скрипт C#, JavaScript, F#Local development - C# script, JavaScript, F# АвтоматическийAutomatic
Разработка на порталеPortal development АвтоматическийAutomatic

Packages — функции 2. x и более поздних версийPackages - Functions 2.x and higher

Для функций 2. x и более поздних версий используйте пакет Microsoft. Azure. веб-задания. Extensions. EventHubs версии 3. x.For Functions 2.x and higher, use the Microsoft.Azure.WebJobs.Extensions.EventHubs package, version 3.x. Исходный код для пакета находится в репозитории GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Добавление поддержкиTo add support
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка — скрипт C#, JavaScript, F#, Java и PythonLocal development - C# script, JavaScript, F#, Java and Python Регистрация расширенияRegister the extension
Разработка на порталеPortal development Установка при добавлении выходной привязкиInstall when adding output binding

Дополнительные сведения об обновлении существующих расширений привязки на портале, не переиздавая проект приложения-функции, см. раздел Обновление расширений.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

Важно!

Хотя в следующих примерах кода используется API концентратора событий, заданный синтаксис применим к функциям центра Интернета вещей.While the following code samples use the Event Hub API, the given syntax is applicable for IoT Hub functions.

ТриггерTrigger

Используйте триггер функции для реагирования на событие, отправленное в поток событий концентратора событий.Use the function trigger to respond to an event sent to an event hub event stream. Для настройки триггера необходимо иметь доступ на чтение к базовому концентратору событий.You must have read access to the underlying event hub to set up the trigger. При запуске функции сообщение, передаваемое в функцию, вводится в виде строки.When the function is triggered, the message passed to the function is typed as a string.

Триггер: масштабированиеTrigger - scaling

Каждый экземпляр функции, активируемой событием, поддерживается одним экземпляром EventProcessorHost .Each instance of an event triggered function is backed by a single EventProcessorHost instance. Триггер (на основе концентраторов событий) гарантирует, что только один экземпляр EventProcessorHost может получить аренду для данного раздела.The trigger (powered by Event Hubs) ensures that only one EventProcessorHost instance can get a lease on a given partition.

Например, рассмотрим концентратор событий:For example, consider an Event Hub as follows:

  • 10 секций10 partitions
  • 1 000 события равномерно распределены по всем секциям с 100 сообщениями в каждой секции1,000 events distributed evenly across all partitions, with 100 messages in each partition

При первом включении у функции будет только 1 экземпляр.When your function is first enabled, there is only one instance of the function. Давайте назовем первый экземпляр функции Function_0.Let's call the first function instance Function_0. Функция Function_0 имеет один экземпляр EventProcessorHost , который содержит аренду для всех десяти секций.The Function_0 function has a single instance of EventProcessorHost that holds a lease on all ten partitions. Этот экземпляр начнет считывать события из разделов 0–9.This instance is reading events from partitions 0-9. При этом возможно следующее:From this point forward, one of the following happens:

  • Новые экземпляры функций не требуются: Function_0 может обрабатывать все события 1 000 до вступления в силу логики масштабирования функций.New function instances are not needed: Function_0 is able to process all 1,000 events before the Functions scaling logic take effect. В этом случае все сообщения 1 000 обрабатываются Function_0.In this case, all 1,000 messages are processed by Function_0.

  • Добавлен дополнительный экземпляр функции: Если логика масштабирования функций определяет, что Function_0 содержит больше сообщений, чем может обработать, создается новый экземпляр приложения-функции (Function_1).An additional function instance is added: If the Functions scaling logic determines that Function_0 has more messages than it can process, a new function app instance (Function_1) is created. Эта новая функция также имеет связанный экземпляр EventProcessorHost.This new function also has an associated instance of EventProcessorHost. Так как базовые концентраторы событий обнаруживают, что новый экземпляр узла пытается читать сообщения, он распределяет секции между экземплярами узла.As the underlying Event Hubs detect that a new host instance is trying read messages, it load balances the partitions across the host instances. Например, разделы 0–4 могут быть назначены Function_0, а разделы 5–9 — Function_1.For example, partitions 0-4 may be assigned to Function_0 and partitions 5-9 to Function_1.

  • Добавлено больше экземпляров функций: Если логика масштабирования функций определяет, что Function_0 и Function_1 имеют больше сообщений, чем они могут обработать, создаются новые экземпляры приложения Functions_N функции.N more function instances are added: If the Functions scaling logic determines that both Function_0 and Function_1 have more messages than they can process, new Functions_N function app instances are created. Приложения создаются в точке, где N больше числа разделов концентратора событий.Apps are created to the point where N is greater than the number of event hub partitions. В нашем примере Центры событий снова распределяют нагрузку разделов, в этом случае — по экземплярам Function_0...Functions_9.In our example, Event Hubs again load balances the partitions, in this case across the instances Function_0...Functions_9.

Как только происходит масштабирование, N экземпляры — это число, превышающее число разделов в концентраторе событий.As scaling occurs, N instances is a number greater than the number of event hub partitions. Этот шаблон используется, чтобы обеспечить доступность экземпляров EventProcessorHost для получения блокировок на секциях по мере их появления в других экземплярах.This pattern is used to ensure EventProcessorHost instances are available to obtain locks on partitions as they become available from other instances. Вы платите только за ресурсы, используемые при выполнении экземпляра функции.You are only charged for the resources used when the function instance executes. Иными словами, у вас нет оплаты за эту избыточную подготовку.In other words, you are not charged for this over-provisioning.

Когда функция выполнена (с ошибками или без), в связанную учетную запись хранения добавляются контрольные точки.When all function execution completes (with or without errors), checkpoints are added to the associated storage account. После завершения проверки все сообщения 1 000 никогда не извлекаются снова.When check-pointing succeeds, all 1,000 messages are never retrieved again.

В следующем примере показана функция C#, которая записывает в журнал текст сообщений триггера концентратора событий.The following example shows a C# function that logs the message body of the event hub trigger.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

Чтобы получить доступ к метаданным события в коде функции, создайте привязку к объекту EventData (требуется инструкция using для Microsoft.Azure.EventHubs).To get access to event metadata in function code, bind to an EventData object (requires a using statement for Microsoft.Azure.EventHubs). Вы также можете получить доступ к тем же свойствам, используя выражения привязки в сигнатуре метода.You can also access the same properties by using binding expressions in the method signature. В следующем примере показаны оба способа получения одних и тех же данных:The following example shows both ways to get the same data:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Для пакетного получения событий сделайте string или EventData массивом.To receive events in a batch, make string or EventData an array.

Примечание

При пакетном получении нельзя привязываться к параметрам метода (как в примере выше) с помощью DateTime enqueuedTimeUtc. Параметры необходимо получать из каждого объекта EventData.When receiving in a batch you cannot bind to method parameters like in the above example with DateTime enqueuedTimeUtc and must receive these from each EventData object

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Атрибуты и заметки триггераTrigger - attributes and annotations

В библиотеках классов C# используйте атрибут EventHubTriggerAttribute.In C# class libraries, use the EventHubTriggerAttribute attribute.

Конструктор атрибута принимает имя концентратора событий, имя группы потребителей и имя параметра приложения, содержащего строку подключения.The attribute's constructor takes the name of the event hub, the name of the consumer group, and the name of an app setting that contains the connection string. Дополнительные сведения об этих параметрах см. в разделе Привязки концентраторов событий функций Azure.For more information about these settings, see the trigger configuration section. Ниже приведен пример атрибута EventHubTriggerAttribute.Here's an EventHubTriggerAttribute attribute example:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

Полный пример см. в разделе Пример C# в триггере.For a complete example, see Trigger - C# example.

Конфигурация триггераTrigger - configuration

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json и атрибуте EventHubTrigger.The following table explains the binding configuration properties that you set in the function.json file and the EventHubTrigger attribute.

свойство function.jsonfunction.json property Свойство атрибутаAttribute property DescriptionDescription
typetype Н/Дn/a Нужно задать значение eventHubTrigger.Must be set to eventHubTrigger. Это свойство задается автоматически при создании триггера на портале Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection Н/Дn/a Нужно задать значение in.Must be set to in. Это свойство задается автоматически при создании триггера на портале Azure.This property is set automatically when you create the trigger in the Azure portal.
namename Н/Дn/a Имя переменной, представляющей элемент события в коде функции.The name of the variable that represents the event item in function code.
путьpath EventHubNameEventHubName Только служба "Функции" версии 1.x.Functions 1.x only. Имя концентратора событий.The name of the event hub. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.When the event hub name is also present in the connection string, that value overrides this property at runtime.
eventHubNameeventHubName EventHubNameEventHubName Функции 2. x и более поздних версий.Functions 2.x and higher. Имя концентратора событий.The name of the event hub. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.When the event hub name is also present in the connection string, that value overrides this property at runtime. Можно ссылаться через параметры приложения% eventHubName%Can be referenced via app settings %eventHubName%
consumerGroupconsumerGroup ConsumerGroupConsumerGroup Необязательное свойство, которое используется для задания группы потребителей, используемой для подписки на события в концентраторе.An optional property that sets the consumer group used to subscribe to events in the hub. Если аргумент опущен, используется группа потребителей $Default.If omitted, the $Default consumer group is used.
кратностьcardinality Н/Дn/a Для JavaScript.For Javascript. Задайте значение many, чтобы включить пакетную обработку.Set to many in order to enable batching. Если параметр опущен или задано значение one, в функцию передается одно сообщение.If omitted or set to one, a single message is passed to the function.
connectionconnection СоединениеConnection Имя параметра приложения, содержащего строку подключения к пространству имен концентратора событий.The name of an app setting that contains the connection string to the event hub's namespace. Скопируйте эту строку подключения, нажав кнопку Сведения о подключении для пространства имен, а не сам концентратор событий.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Для активации триггера эта строка подключения должна обладать, по крайней мере, правами на чтение.This connection string must have at least read permissions to activate the trigger.

При локальной разработке параметры приложения перейдут в файл local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Триггер — метаданные событияTrigger - event metadata

Триггер Центров событий предоставляет несколько свойств метаданных.The Event Hubs trigger provides several metadata properties. Свойства метаданных можно использовать как часть выражений привязки в других привязках или в качестве параметров в коде.Metadata properties can be used as part of binding expressions in other bindings or as parameters in your code. Свойства берутся из класса EVENTDATA .The properties come from the EventData class.

СвойствоProperty ТипType DescriptionDescription
PartitionContext PartitionContextPartitionContext Экземпляр PartitionContext.The PartitionContext instance.
EnqueuedTimeUtc DateTime Время попадания в очередь в формате UTC.The enqueued time in UTC.
Offset string Смещение данных относительно потока разделов концентратора событий.The offset of the data relative to the Event Hub partition stream. Смещение — это маркер или идентификатор события в потоке Центров событий.The offset is a marker or identifier for an event within the Event Hubs stream. Этот идентификатор уникален внутри раздела потока Центров событий.The identifier is unique within a partition of the Event Hubs stream.
PartitionKey string Раздел, в который следует отправлять данные события.The partition to which event data should be sent.
Properties IDictionary<String,Object> Свойства пользователя данных события.The user properties of the event data.
SequenceNumber Int64 Регистрационный номер транзакции события в журнале.The logical sequence number of the event.
SystemProperties IDictionary<String,Object> Свойства системы, включая данные события.The system properties, including the event data.

См. примеры кода, в которых используются эти свойства, в предыдущих разделах этой статьи.See code examples that use these properties earlier in this article.

Свойства host.json в триггереTrigger - host.json properties

В файле host.json содержатся параметры, управляющие реакцией триггера Центров событий на событие.The host.json file contains settings that control Event Hubs trigger behavior.

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}
СвойствоProperty значение по умолчаниюDefault ОписаниеDescription
maxBatchSizemaxBatchSize 6464 Максимальное число событий, получаемых в цикле получения.The maximum event count received per receive loop.
prefetchCountprefetchCount Недоступноn/a Значение PrefetchCount по умолчанию, которое будет использоваться базовым узлом EventProcessorHost.The default PrefetchCount that will be used by the underlying EventProcessorHost.
batchCheckpointFrequencybatchCheckpointFrequency 11 Количество пакетов событий, которые необходимо обработать перед созданием контрольной точки курсора EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.

Выходные данныеOutput

Используйте выходную привязку Центров событий для записи событий в поток событий.Use the Event Hubs output binding to write events to an event stream. Чтобы записывать события в концентратор событий, необходимо иметь разрешение на оправку в него событий.You must have send permission to an event hub to write events to it.

Прежде чем пытаться реализовать выходную привязку, убедитесь в наличии необходимых ссылок на пакеты.Make sure the required package references are in place before you try to implement an output binding.

В следующем примере показана функция C#, которая записывает сообщение в концентратор событий, используя возвращаемое значение метода в качестве выходных данных.The following example shows a C# function that writes a message to an event hub, using the method return value as the output:

[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
    return $"{DateTime.Now}";
}

В следующем примере показано, как использовать интерфейс IAsyncCollector для отправки пакета сообщений.The following example shows how to use the IAsyncCollector interface to send a batch of messages. Этот сценарий часто используется при обработке сообщений, поступающих из одного концентратора событий, и при отправке результата в другой концентратор событий.This scenario is common when you are processing messages coming from one Event Hub and sending the result to another Event Hub.

[FunctionName("EH2EH")]
public static async Task Run(
    [EventHubTrigger("source", Connection = "EventHubConnectionAppSetting")] EventData[] events,
    [EventHub("dest", Connection = "EventHubConnectionAppSetting")]IAsyncCollector<string> outputEvents,
    ILogger log)
{
    foreach (EventData eventData in events)
    {
        // do some processing:
        var myProcessedEvent = DoSomething(eventData);

        // then send the message
        await outputEvents.AddAsync(JsonConvert.SerializeObject(myProcessedEvent));
    }
}

Выходные атрибуты и заметкиOutput - attributes and annotations

В библиотеках классов C# используйте атрибут EventHubAttribute.For C# class libraries, use the EventHubAttribute attribute.

Конструктор атрибута принимает имя концентратора событий и имя параметра приложения, содержащего строку подключения.The attribute's constructor takes the name of the event hub and the name of an app setting that contains the connection string. Дополнительные сведения об этих параметрах см. в разделе Привязки концентраторов событий функций Azure.For more information about these settings, see Output - configuration. Ниже приведен пример атрибута EventHub.Here's an EventHub attribute example:

[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    ...
}

Полный пример см. в разделе Пример выходных данных C#.For a complete example, see Output - C# example.

Выходная конфигурацияOutput - configuration

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json и атрибуте EventHub.The following table explains the binding configuration properties that you set in the function.json file and the EventHub attribute.

свойство function.jsonfunction.json property Свойство атрибутаAttribute property DescriptionDescription
typetype Н/Дn/a Для этого свойства необходимо задать значение "eventHub"Must be set to "eventHub".
directiondirection Н/Дn/a Для этого свойства необходимо задать значение out.Must be set to "out". Этот параметр задается автоматически при создании привязки на портале Azure.This parameter is set automatically when you create the binding in the Azure portal.
namename Н/Дn/a Имя переменной, используемое в коде функции, которая представляет событие.The variable name used in function code that represents the event.
путьpath EventHubNameEventHubName Только служба "Функции" версии 1.x.Functions 1.x only. Имя концентратора событий.The name of the event hub. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.When the event hub name is also present in the connection string, that value overrides this property at runtime.
eventHubNameeventHubName EventHubNameEventHubName Функции 2. x и более поздних версий.Functions 2.x and higher. Имя концентратора событий.The name of the event hub. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.When the event hub name is also present in the connection string, that value overrides this property at runtime.
connectionconnection СоединениеConnection Имя параметра приложения, содержащего строку подключения к пространству имен концентратора событий.The name of an app setting that contains the connection string to the event hub's namespace. Скопируйте эту строку подключения, нажав кнопку Сведения о подключении для пространства имен, а не сам концентратор событий.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Чтобы отправлять сообщения в поток событий, эта строка подключения должна иметь разрешения на отправку.This connection string must have send permissions to send the message to the event stream.

При локальной разработке параметры приложения перейдут в файл local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Использование выходной привязкиOutput - usage

Отправка сообщений с помощью параметра метода, например out string paramName.Send messages by using a method parameter such as out string paramName. В скрипте C# paramName — это значение, заданное в свойстве name файла function.json.In C# script, paramName is the value specified in the name property of function.json. Для записи нескольких сообщений можно использовать ICollector<string> или IAsyncCollector<string> вместо out string.To write multiple messages, you can use ICollector<string> or IAsyncCollector<string> in place of out string.

Исключения и коды возвратаExceptions and return codes

ПривязкаBinding Справочные материалыReference
Концентратор событийEvent Hub Руководство по операциямOperations Guide

Параметры файла host.jsonhost.json settings

В этом разделе описаны глобальные параметры конфигурации, доступные для этой привязки в версиях 2. x и более поздних.This section describes the global configuration settings available for this binding in versions 2.x and higher. Пример файла host. JSON ниже содержит только параметры версии 2. x + для этой привязки.The example host.json file below contains only the version 2.x+ settings for this binding. Дополнительные сведения о глобальных параметрах конфигурации в версиях 2. x и более поздних версий см. в справочнике по Host. JSON для функций Azure.For more information about global configuration settings in versions 2.x and beyond, see host.json reference for Azure Functions.

Примечание

Чтобы получить дополнительные сведения о файле host.json в Функции 1.x, см. статью host.json reference for Azure Functions 1.x(Справочник по файлу host.json для службы "Функции Azure" версии 1.x.).For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "batchCheckpointFrequency": 5,
            "eventProcessorOptions": {
                "maxBatchSize": 256,
                "prefetchCount": 512
            }
        }
    }
}  
СвойствоProperty По умолчаниюDefault DescriptionDescription
maxBatchSize 1010 Максимальное число событий, получаемых в цикле получения.The maximum event count received per receive loop.
prefetchCount 300300 Счетчик предварительной выборки по умолчанию, используемый базовым EventProcessorHost.The default pre-fetch count used by the underlying EventProcessorHost.
batchCheckpointFrequency 11 Количество пакетов событий, которые необходимо обработать перед созданием контрольной точки курсора EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.

Дальнейшие действияNext steps