MQTT 라우팅된 메시지에 대한 보강

  • 아티클

보강 지원을 사용하면 최대 20개의 사용자 지정 키-값 속성이 Event Grid 사용자 지정 토픽으로 전송되기 전에 메시지에 추가할 수 있습니다. 이러한 보강을 통해 다음을 수행할 수 있습니다.

  • 메시지에 컨텍스트 데이터를 추가합니다. 예를 들어 클라이언트 이름 또는 네임스페이스 이름으로 메시지를 보강하면 메시지 원본에 대한 정보를 엔드포인트에 제공할 수 있습니다.
  • 엔드포인트에서 컴퓨팅 부하를 줄입니다. 예를 들어 MQTT 게시 요청의 페이로드 형식 표시기 또는 콘텐츠 형식을 사용하여 메시지를 보강하면 먼저 여러 파서를 시도하지 않고 메시지의 페이로드를 처리하는 방법을 엔드포인트에 알릴 수 있습니다.
  • 추가된 데이터를 기반으로 Event Grid 이벤트 구독을 통해 라우팅된 메시지를 필터링합니다. 예를 들어 클라이언트 특성을 보강하면 다른 특성의 값에 따라 엔드포인트로 라우팅할 메시지를 필터링할 수 있습니다.

구성

보강 키:

보강 키는 다음 요구 사항을 준수해야 하는 문자열입니다.

  • 소문자 영숫자만 포함: (a-z) 및 (0-9)
  • specversion, id, time, type, source, subject, datacontenttype, dataschema, data 또는 data_base64가 아니어야 합니다.
  • azsp로 시작하면 안 됩니다.
  • 복제해서는 안 됩니다.
  • 20자 이상이어야 합니다.

보강 값:

보강 값은 정적 보강을 위한 정적 문자열 또는 동적 보강을 위한 클라이언트 특성 또는 MQTT 메시지 속성을 나타내는 지원되는 값 중 하나일 수 있습니다. 보강 값은 128자를 초과하면 안 됩니다. 다음 목록에는 지원되는 값이 포함되어 있습니다.

클라이언트 특성

  • ${client.authenticationName}: 게시 클라이언트의 이름입니다.
  • ${client.attributes.x}: 게시 클라이언트의 특성입니다. 여기서 x는 특성 키 이름입니다.

MQTT 속성

  • ${mqtt.message.userProperties.x}: MQTTv5 PUBLISH 패킷의 사용자 속성입니다. 여기서 x는 사용자 속성 키 이름입니다.
    • 형식: string
    • 사용자 속성에 특수 문자 ${mqtt.message.userProperties['x']}가 포함된 경우 대신 다음 변수 형식을 사용합니다. 다음과 같이 아포스트로피와 백슬래시를 이스케이프해야 합니다. "PN\t"는 "PN\t"가 됩니다.
  • ${mqtt.message.topicName}: MQTT PUBLISH 패킷의 항목입니다.
    • 형식: string
  • ${mqtt.message.responseTopic}: MQTTv5 PUBLISH 패킷의 응답 항목입니다.
    • 형식: string
  • ${mqtt.message.correlationData}: MQTTv5 PUBLISH 패킷의 상관 관계 데이터입니다.
    • 유형: 이진
  • ${mqtt.message.pfi}: MQTTv5 PUBLISH 패킷의 페이로드 형식 표시기입니다.
    • 형식: Integer

Azure Portal 구성

다음 단계를 사용하여 라우팅 보강을 구성합니다.

  1. Azure Portal에서 네임스페이스로 이동합니다.
  2. 라우팅에서 라우팅을 사용하도록 설정을 확인합니다.
  3. 라우팅 항목에서 모든 MQTT 메시지가 라우팅될 위치에서 만든 Event Grid 토픽을 선택합니다.
  4. 메시지 보강에서 +보강 추가를 선택합니다.
  5. 최대 20개의 키-값 쌍을 추가하고 해당 형식을 적절하게 선택합니다.
  6. 적용을 선택합니다.

Screenshot showing the routing enrichment configuration through the portal.

라우팅 구성에 대한 자세한 내용은 라우팅 Azure Portal 구성으로 이동합니다.

Azure CLI 구성

네임스페이스를 만드는/업데이트하는 동안 명령 및 페이로드를 사용하여 라우팅 보강을 구성합니다.

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --api-version 2023-06-01-preview --properties @./resources/NS.json

NS.json

{
  "properties": {
    "topicSpacesConfiguration": {
        "state": "Enabled",
        "routeTopicResourceId": "/subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/topics/<Event Grid Topic name>",
        "routingEnrichments": {
            "static": [
                {
                    "key": "namespaceid",
                    "value": "123",
                    "valueType": "string"
                }
            ],
            "dynamic": [
                {
                    "key": "clientname",
                    "value": "${client.authenticationName}"
                },
                {
                    "key": "clienttype",
                    "value": "${client.attributes.type}"
                },
                {
                    "key": "address",
                    "value": "${mqtt.message.userProperties['client.address']}"
                },
                {
                    "key": "region",
                    "value": "${mqtt.message.userProperties.location}"
                },
                {
                    "key": "mqtttopic",
                    "value": "${mqtt.message.topicName}"
                },
                {
                    "key": "mqttresponsetopic",
                    "value": "${mqtt.message.responseTopic}"
                },
                {
                    "key": "mqttcorrelationdata",
                    "value": "${mqtt.message.correlationData}"
                },
                {
                    "key": "mqttpfi",
                    "value": "${mqtt.message.pfi}"
                }
            ]
        }
    }
},
"location": "eastus2euap",
"tags": {},
}

라우팅 구성에 대한 자세한 내용은 라우팅 Azure CLI 구성으로 이동하세요.

샘플 출력

다음 CloudEvent는 이전 보강 구성을 적용한 후 PFI=0이 있는 MQTTv5 메시지의 샘플 출력입니다.

{
    "specversion": "1.0",
	"id": "9aeb0fdf-c01e-0131-0922-9eb54906e20", // unique id stamped by the service
	"time": "2019-11-18T15:13:39.4589254Z", // timestamp when messages was received by the service
	"type": "MQTT.EventPublished", // set type for all MQTT messages enveloped by the service
	"source": "testnamespace", // namespace name
	"subject": "campus/buildings/building17", // topic of the MQTT publish request
	"namespaceid": "123", // static enrichment
	"clientname": "client1", // dynamic enrichment of the name of the publishing client
	"clienttype": "operator", // dynamic enrichment of an attribute of the publishing client
	"address": "1 Microsoft Way, Redmond, WA 98052", // dynamic enrichment of a user property in the MQTT publish request
	"region": "North America", // dynamic enrichment of another user property in the MQTT publish request
	"mqtttopic": "campus/buildings/building17", // dynamic enrichment of the topic of the MQTT publish request
	"mqttresponsetopic": "campus/buildings/building17/response", // dynamic enrichment of the response topic of the MQTT publish request
	"mqttcorrelationdata": "cmVxdWVzdDE=", // dynamic enrichment of the correlation data of the MQTT publish request encoded in base64
	"mqttpfi": 0, // dynamic enrichment of the payload format indicator of the MQTT publish request
	"datacontenttype": "application/octet-stream", //content type of the MQTT publish request
	"data_base64": 
    {
	    IlRlbXAiOiAiNzAiLAoiaHVtaWRpdHkiOiAiNDAiCg==
	}
}

특별한 경우 처리:

  • 지정되지 않은 클라이언트 특성/사용자 속성: 동적 보강이 존재하지 않는 클라이언트 특성/사용자 속성을 가리키는 경우 보강에는 값에 대한 빈 문자열이 있는 지정된 키가 포함됩니다. 예를 들어, emptyproperty: "".
  • 배열: 클라이언트 특성의 배열과 중복된 사용자 속성은 쉼표로 구분된 문자열로 변환됩니다. 예를 들어 보강된 클라이언트 특성이 "array": "value1", "value2", "value3"로 설정된 경우 결과 보강된 속성은 array: value1,value2,value3입니다. 또 다른 예: 동일한 MQTT 게시 요청에 사용자 속성 > "userproperty1": "value1", "userproperty1": "value2"가 있는 경우 보강된 속성은 userproperty1: value1,value2입니다.

다음 단계:

다음 문서에서 라우팅에 대해 자세히 알아봅니다.

빠른 시작:

개념: