mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-09 18:36:51 +00:00
Add azure servicebus documentation (#10756)
* Add azure servicebus documentation
* attemt to fixed links in note blocks
* rename integration
* bit too much auto formating
* ✏️ Tweaks
* :tweak: Remove optional name, keeping example minimal
This commit is contained in:
parent
28ada04e44
commit
2f40dddf94
107
source/_integrations/azure_service_bus.markdown
Normal file
107
source/_integrations/azure_service_bus.markdown
Normal file
@ -0,0 +1,107 @@
|
||||
---
|
||||
title: "Azure Service Bus"
|
||||
description: "Setup for Azure Service Bus integration"
|
||||
logo: azure_service_bus.svg
|
||||
ha_category:
|
||||
- Notification
|
||||
ha_release: 0.102
|
||||
---
|
||||
|
||||
The `Azure Service Bus` integration allows you to send messages to [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus/) from within Home Assistant.
|
||||
|
||||
## First-time setup
|
||||
|
||||
This assumes you already have an Azure account. Otherwise, create a free account [here](https://azure.microsoft.com/en-us/free/).
|
||||
|
||||
You need to create a Service Bus namespace; you can follow [this guide](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-create-namespace-portal).
|
||||
|
||||
You must then create a Shared Access Policy for the Service Bus with `Send` claims or use the RootManageAccessKey from your namespace (this key has additional claims, including managing the event hub and listening, which are not needed for this purpose), for more details on the security of Service Bus [go here](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-authentication-and-authorization#shared-access-signature). Alternatively you can create a dedicated key for only one queue or topic, to restrict access to only that queue or topic.
|
||||
|
||||
Once you have the connection string with `Send` policy, you can set up the integration itself.
|
||||
|
||||
<div class='note warning'>
|
||||
|
||||
The queue or topic that you are sending to needs to exists with the service bus namespace before you use it within Home Assistant. See [here](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quickstart-portal) for how to set up a queue and [here](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quickstart-topics-subscriptions-portal) for setting up a topic and subscriptions.
|
||||
|
||||
</div>
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the following lines to your `configuration.yaml` file:
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
notify:
|
||||
- platform: azure_service_bus
|
||||
connection_string: !secret servicebus_connection_string
|
||||
topic: t-test
|
||||
- platform: azure_service_bus
|
||||
connection_string: !secret servicebus_connection_string
|
||||
queue: q-test
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
name:
|
||||
description: Setting the optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`.
|
||||
required: false
|
||||
type: string
|
||||
default: notify
|
||||
connection_string:
|
||||
description: Connection string found in the Azure portal, with `send` claim in the key.
|
||||
required: true
|
||||
type: string
|
||||
queue:
|
||||
description: Which queue to send notifications on.
|
||||
required: exclusive
|
||||
type: string
|
||||
topic:
|
||||
description: Which topic to send notifications on.
|
||||
required: exclusive
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
|
||||
<div class="note">
|
||||
|
||||
If you plan to send all state changes from one or more entities within Home Assistant, you should consider using the [Azure Event Hub](/integrations/azure_event_hub/) integration instead.
|
||||
|
||||
</div>
|
||||
|
||||
## Usage
|
||||
|
||||
The notification service will translate the data given to a JSON object on the service bus. The `message` field will always be set, but the fields `target` and `title` are optional and are only included in the service bus message if set. Any input given in the `data` section, will be flattened to the root of the JSON object and follow the structure given. All input given in the data section will be included in the message.
|
||||
|
||||
See the example below for how an automation trigger translates to a message on the service bus.
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: Sunset Service Bus message
|
||||
trigger:
|
||||
platform: sun
|
||||
event: sunset
|
||||
action:
|
||||
service: notify.test_queue
|
||||
data:
|
||||
message: "Sun is going down"
|
||||
title: "Good evening"
|
||||
data:
|
||||
sun_direction: "Down"
|
||||
custom_field: 123
|
||||
custom_object:
|
||||
trigger_more: true
|
||||
explain: "Its starting to get dark"
|
||||
```
|
||||
|
||||
The message that can be retrieved from a queue or topic subscription:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Sun is going down",
|
||||
"title": "Good evening",
|
||||
"sun_direction": "Down",
|
||||
"custom_field": 123,
|
||||
"custom_object": {
|
||||
"trigger_more": true,
|
||||
"explain": "Its starting to get dark"
|
||||
}
|
||||
}
|
||||
```
|
14
source/images/supported_brands/azure_service_bus.svg
Normal file
14
source/images/supported_brands/azure_service_bus.svg
Normal file
@ -0,0 +1,14 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- Generator: Adobe Illustrator 19.2.1, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
|
||||
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
|
||||
viewBox="0 0 50 50" enable-background="new 0 0 50 50" xml:space="preserve">
|
||||
<path fill="#0072C6" d="M0.833,0C0.333,0,0,0.333,0,0.833v10c0,0.5,0.333,0.833,0.833,0.833h5c0.5,0,0.833-0.333,0.833-0.833V6.667
|
||||
h36.667v4.167c0,0.5,0.333,0.833,1,0.833h4.833c0.5,0,0.833-0.333,0.833-0.833v-5v-5C50,0.333,49.667,0,49.167,0l0,0H0.833z"/>
|
||||
<path fill="#0072C6" d="M49.167,50c0.5,0,0.833-0.333,0.833-0.833v-9.833c0-0.5-0.333-0.833-0.833-0.833h-4.833
|
||||
c-0.5,0-0.833,0.333-0.833,0.833v4H6.667v-4.167c0-0.5-0.333-0.833-1-0.833H0.833c-0.5,0-0.833,0.333-0.833,1v9.833
|
||||
C0,49.667,0.333,50,0.833,50H49.167z"/>
|
||||
<path fill="#59B4D9" d="M29.857,26.098C28.56,27.395,26.835,28.11,25,28.11s-3.56-0.714-4.858-2.012l-9.309-9.309v18.923h28.333
|
||||
V16.788L29.857,26.098z"/>
|
||||
<path fill="#59B4D9" d="M25,26.728c1.466,0,2.844-0.571,3.88-1.607l10.286-10.286V14.29H10.833v0.546L21.119,25.12
|
||||
C22.156,26.157,23.534,26.728,25,26.728z"/>
|
||||
</svg>
|
After Width: | Height: | Size: 1.1 KiB |
Loading…
x
Reference in New Issue
Block a user