From a1989d8f169900ff2fbd94b8eeee226b342c4c37 Mon Sep 17 00:00:00 2001 From: Eduard van Valkenburg Date: Wed, 3 Jun 2020 11:54:32 +0200 Subject: [PATCH] updated docs for AEH (#13646) --- source/_integrations/azure_event_hub.markdown | 40 ++++++++++++++++--- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/source/_integrations/azure_event_hub.markdown b/source/_integrations/azure_event_hub.markdown index 958be7981e9..592bfce2a8d 100644 --- a/source/_integrations/azure_event_hub.markdown +++ b/source/_integrations/azure_event_hub.markdown @@ -21,6 +21,10 @@ You must then create a Shared Access Policy for the Event Hub with 'Send' claims Once you have the name of your namespace, instance, Shared Access Policy and the key for that policy, you can setup the integration itself. +The alternative approach is to use a connection string, this can be retrieved in the same way as the Shared Access Policy and this can also be gotten for a device in an IoT Hub (Event Hub-compatible connection string). + +The final thing to consider is how often you want the integration to send messages in a batch to your hub, this is set with the `send_interval`, with a default of 5 seconds. The other thing to look at is what the maximum delay you want to use, since this component runs in a asynchronous way there is no guarantee that the sending happens exactly on time, so depending on your semantics you might want messages discarded. The actual check of the time happens with `max_delay` plus `send_interval`, so that even with a long `send_interval` the semantics are the same. + ## Configuration Add the following lines to your `configuration.yaml` file: @@ -42,20 +46,34 @@ azure_event_hub: {% configuration %} event_hub_namespace: description: The name of your Event Hub namespace. - required: true + required: exclusive type: string event_hub_instance_name: description: The name of your Event Hub instance. - required: true + required: exclusive type: string event_hub_sas_policy: description: The name of your Shared Access Policy. - required: true + required: exclusive type: string event_hub_sas_key: description: The key for the Shared Access Policy. - required: true + required: exclusive type: string +event_hub_connection_string: + description: The connection string to your event hub. + required: exclusive + type: string +send_interval: + description: The interval in seconds should events be sent to the Event Hub. + required: false + type: integer + default: 5 +max_delay: + description: The time in seconds after which a message is to be discarded. + required: false + type: integer + default: 30 filter: description: Filter domains and entities for Event Hub. required: true @@ -88,7 +106,19 @@ Not filtering domains or entities will send every event to Azure Event Hub, thus Event Hubs have a retention time of at most 7 days, if you do not capture or use the events they are deleted automatically from the Event Hub, the default retention is 1 day. -### Using the data in Azure +### Advanced configuration + +This is what the configuration will look like when using a connection string directly, instead of the four parameters. It also shows how to set the send_interval and max_delay to something other than the default. This means once every minute the integration will connect to your hub and send messages, but the messages have to be less than 65 seconds old at the time of sending for them to be counted (send_interval + max_delay). + +```yaml +# Connection string config with non-defaults for send_interval and max_delay +azure_event_hub: + event_hub_connection_string: CONNECTION_STRING + send_interval: 60 + max_delay: 5 +``` + +## Using the data in Azure There are a number of ways to stream the data that comes into the Event Hub into storages in Azure, the easiest way is to use the built-in Capture function and this allows you to capture the data in Azure Blob Storage or Azure Data Lake store, [details here](https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-capture-overview).