Uredi

Topic Spaces in Azure Event Grid’s MQTT broker feature

  • Članak

A topic space represents multiple topics through a set of topic templates. Topic templates are an extension of MQTT filters that support variables, along with the MQTT wildcards. Each topic space represents the MQTT topics that the same set of clients need to use to communicate.

Topic spaces are used to simplify access control management by enabling you to grant publish or subscribe access to a group of topics at once instead of managing access for each individual topic. To publish or subscribe to any MQTT topic, you need to:

  1. Create a client resource for each client that needs to communicate over MQTT.
  2. Create a client group that includes the clients that need access to publish or subscribe on the same MQTT topic.
  3. Create a topic space that includes a topic template that represents the intended topic/topic filter.
  4. Create a permission binding to grant the client group access to publish or subscribe to the topic space.

MQTT Topic filter:

An MQTT topic filter is an MQTT topic that can include wildcards for one or more of its segments, allowing it to match multiple MQTT topics. It's used to simplify subscription requests as one topic filter can match multiple topics.

MQTT broker supports all the MQTT wildcards defined by the MQTT specification as follows:

  • +: which matches a single segment.
    • For example, topic filter: "machines/+/alert" matches the following topics:
      • machines/temp/alert
      • machines/humidity/alert
  • #: which matches zero or more segments at the end of the topic.
    • For example, topic filter: "machines/#" matches the following topics:
      • machines
      • machines/temp
      • machines/humidity
      • machines/temp/alert etc.

For more information about wildcards, see Topic Wildcards in the MQTT spec.

Topic templates

Topic templates are an extension of MQTT filters that support variables, along with the MQTT wildcards. Topic spaces configuration also provides granular access control by allowing you to control the authorization of each client within a client group to publish or subscribe to its own topic. Learn more about how topic templates provide granular access control.

Topic Space Configuration:

Topic Spaces can group up to 10 topic templates. Topic templates support MQTT wildcards (+ and #) and the following variables:

  • ${client.authenticationName}: this variable represents the authentication name of the client. Learn more about client authentication names.
  • ${client.attributes.x}: this variable represents an assigned attribute to a client during client creation/update, such as "x" would be equal to the exact string of the attribute key. E.g., if a client has the attribute, a topic template “area/${client.attributes.area}/telemetry” enables only the clients with the client attribute> “area:section1” to publish on the MQTT topic “area/section1/telemetry”. Learn more about client attributes.

Note:

  • Topics that start with $ are reserved for internal use.

  • A variable can represent a portion of a segment or an entire segment but can't cover more than one segment. For example, a topic template could include "machines/${client.authenticationName|.factory1}/temp" matches topics "machines/machine1.factory1/temp", "machines/machine2.factory1/temp", etc.

  • Topic templates use special characters $ and | and these need to be escaped differently based on the shell being used. In PowerShell, $ can be escaped with vehicles/${dollar}telemetry/#. If you’re using PowerShell, you can escape these special characters as shown in the following examples:

    • "vehicles/${client.authenticationName|dollar}/#"

    • vehicles/${client.authenticationName"|"dollar}/#

Azure portal configuration:

Use the following steps to create a topic space:

  • Go to your namespace in the Azure portal.
  • Under Topic Spaces, select +Topic Space.
  • Assign a Name to your topic space.

Note

  • Topic space name can be 3-50 characters long.
  • Topic space name can include alphanumeric, hyphen(-) and, no spaces.
  • Add at least one topic template by selecting +Add topic template.
  • Select Create.

Screenshot of topic space configuration.

Azure CLI configuration:

Use the following commands to create a topic space:

az eventgrid namespace topic-space create -g myRG --namespace-name myNS -n myTopicSpace --topic-templates ['segment1/+/segment3/${client.authenticationName}', "segment1/${client.attributes.attribute1}/segment3/#"]

Note

Topic space configuration updates may take a couple of minutes to propagate.

Next steps:

Learn more authorization and authentication:

Quickstart:

Concepts: