Service Bus: queues, topics en toegang¶

Het Integratieplatform biedt Azure Service Bus aan als gedeelde messagingservice. Je maakt geen eigen namespace aan. Je beschrijft de queues, topics en subscriptions die je workload nodig heeft in JSON-bestanden, opent een pull request, en het platform maakt ze aan, samen met de Entra ID-groepen die bepalen wie kan verzenden en ontvangen. Deze pagina is voor workload teams. Operators: zie Service Bus-automatisering (platformzijde).

Optioneel aanbod, per platform ingesteld

Of de gedeelde service Service Bus beschikbaar is, in welke omgevingen en met welke opties, hangt af van je platform. Namen, standaardwaarden en groepspatronen op deze pagina zijn de gebruikelijke waarden van het referentieontwerp. Vraag het aan je platformteam.

Hoe het werkt¶

Drie lagen werken samen (ADR-012):

Laag	Wat het doet	Wie het beheert
Gedeelde service	De Service Bus-namespace (Premium) en zijn netwerk. Geen entiteiten.	Platformteam
Spoke extension	Geeft je spoke de rechten die hij nodig heeft op de namespace wanneer de spoke wordt gedeployd (Spoke extensions)	Platformteam, samen met de spoke-deployment
Service Bus-automatisering	Maakt je queues, topics en subscriptions aan vanuit JSON-bestanden, en de toegangsgroepen per entiteit	Integration platform engineers, vanuit jouw pull requests

flowchart LR
    json["queues.json, topics.json,<br/>workload.json<br/>(your pull request)"] --> auto["Service Bus automation"]
    auto -->|"creates"| ent["Queues, topics,<br/>subscriptions"]
    auto -->|"creates"| grp["Entra ID groups<br/>per entity and role"]
    grp -->|"role assignment"| ent
    you["Your team"] -->|"adds managed identities<br/>to the groups"| grp
    app["Logic App, Function App,<br/>Container App"] -->|"Entra ID, private endpoint"| ent

De namespace is alleen bereikbaar via een private endpoint. Maak verbinding met Entra ID, niet met connection strings of keys.

Queues definiëren¶

Maak een bestand met precies de naam queues.json ergens onder je configuratiemap. Een bestand bevat één queue-object of een lijst met queue-objecten. Houd de bestandsnaam aan: de automatisering verzamelt elke queues.json (en topics.json) in de map en alle submappen, dus je kunt mappen indelen per workload, domein of omgeving. Dubbele definities van dezelfde queue in verschillende mappen moeten worden vermeden.

{
  "workload": "orders",
  "name": "intake",
  "max_delivery_count": 10
}

Veld	Verplicht	Standaard	Betekenis
`workload`	ja		De workload die eigenaar is van de queue. Moet overeenkomen met een workloaddefinitie (zie hieronder).
`name`	ja		Naam van de queue. De queue in Azure heet `sbq-<workload>-<name>`.
`max_delivery_count`	nee	10	Aantal leveringen voordat een bericht naar de dead-letter queue gaat
`lock_duration`	nee	`PT1M`	Duur van de lock terwijl een receiver een bericht verwerkt (ISO 8601-duur)
`max_size_in_megabytes`	nee	1024	Grootte van de queue
`requires_session`	nee	false	Session-aware queue
`requires_duplicate_detection`	nee	false	Duplicate detection, met `duplicate_detection_history_time_window` (standaard `PT10M`)
`dead_lettering_on_message_expiration`	nee	false	Verlopen berichten naar de dead-letter queue verplaatsen
`forward_dead_lettered_messages_to`	nee	geen	Dead-lettered berichten doorsturen naar een andere entiteit
`default_message_ttl`, `auto_delete_on_idle`, `max_message_size_in_kilobytes`, `partitioning_enabled`, `express_enabled`, `batched_operations_enabled`, `status`	nee	zie de module	Meer Service Bus-eigenschappen, doorgegeven

Topics, subscriptions en rules definiëren¶

Een topic is eigendom van de workload die publiceert. Elke subscription noemt de workload die consumeert.

{
  "workload": "orders",
  "name": "order-created",
  "subscriptions": [
    {
      "workload": "billing",
      "name": "billing",
      "rules": [
        {
          "name": "only-eu",
          "filter_type": "SqlFilter",
          "sql_filter": "region = 'EU'"
        }
      ]
    }
  ]
}

Veld	Opmerkingen
Topicvelden	`workload`, `name`, `support_ordering` (standaard false), `requires_duplicate_detection`, `max_size_in_megabytes` (standaard 1024), en dezelfde doorgegeven eigenschappen als bij queues
Subscriptionvelden	`workload`, `name`, `max_delivery_count` (standaard 10), `dead_lettering_on_filter_evaluation_error` (standaard true), `lock_duration` (standaard `PT1M`), `requires_session`, en meer
Rules	`name` en `filter_type`. `SqlFilter` neemt `sql_filter`. `CorrelationFilter` neemt een `correlation_filter`-object (`correlation_id`, `label`, `message_id`, `to`, `reply_to`, `session_id`, `content_type`, `properties`). Een optionele `action`.

Namen in Azure: topic sbt-<workload>-<name>, subscription sbts-<subscription workload>-<subscription name>.

Een queue per subscription (standaard)¶

Voor elke subscription maakt de automatisering ook een queue aan met de naam sbq-<subscription workload>-<topic name>-<subscription name> en stuurt de subscription ernaar door. Je luistert naar die queue, niet naar de subscription. Dit is ADR-008. Het geeft je:

dead-lettering op een queue die alleen jouw workload beheert;
een retry van een mislukt bericht zonder het opnieuw naar de topic te sturen, zodat andere subscribers het niet twee keer ontvangen;
een eenvoudiger model: je hoeft alleen te weten hoe je uit een queue leest.

De queue erft zijn grootte- en duplicate-detection-instellingen van de topic. Het gedrag is een schakelaar van de automatisering (auto_generate_queue_for_topic_subscription, standaard true). Als het platformteam dit heeft uitgezet, lezen receivers in plaats daarvan uit de subscription.

De workload definiëren¶

Elke workload die in een bestand voorkomt heeft een workloaddefinitie (workload.json) nodig met de naam en de identities van zijn spoke, zodat de automatisering weet welke service principal en groepen ze moet gebruiken. Vraag je platformteam wie dit bestand onderhoudt en waar het staat. De velden die de automatisering leest zijn name, service_principal_object_id, owner_group_id, contributor_group_id en reader_group_id. Als een workload in een queue of topic wordt gebruikt maar geen definitie heeft, faalt het plan.

Wie wat mag: groepen¶

Voor elke entiteit maakt de automatisering Entra ID-groepen aan in de administrative unit van het platform. Jouw team is owner van de groepen (via de service principal van je spoke) en beheert het lidmaatschap.

Groep	Aangemaakt voor	Rol die ze krijgt	Leden bij aanmaken
Sender-groep	Elke queue en elke topic	`Azure Service Bus Data Sender` op die entiteit	Leeg. Jij voegt managed identities en service principals toe.
Receiver-groep	Elke queue, en elke subscription die niet naar een queue wordt doorgestuurd	`Azure Service Bus Data Receiver` op die entiteit	Leeg. Jij voegt identities toe.
Operators-groep	Eén keer per workload	Sender- en receiver-rechten op elke entiteit van de workload, voor supportacties zoals een mislukt bericht met de hand opnieuw aanbieden	De Owners- en Contributors-groepen van je workload-spoke

De namen volgen een patroon dat het platformteam instelt, met {workload} en {entity} als placeholders. Het referentie- patroon is integration-workload-{workload}-{entity}-sender en ...-receiver, waarbij de entiteit de Azure-naam van de queue of topic is, bijvoorbeeld sbq-orders-intake. Vraag je platformteam naar het patroon op jouw platform.

De Readers-groep van je spoke wordt ook toegevoegd aan de read-only groep van het platform voor de namespace, zodat readers de namespace in het portal kunnen zien.

Een applicatie toegang geven¶

Zoek de groep voor de entiteit en rol (bijvoorbeeld de sender-groep van sbq-orders-intake). Je platformteam kan je de object-ID's geven (de automatisering geeft ze per workload als output).
Voeg de managed identity van je Logic App, Function App of Container App toe aan de groep in Microsoft Entra ID.
Wacht een paar minuten. Een groepswijziging heeft even tijd nodig om op de namespace van kracht te worden.
Maak verbinding met de hostnaam van de namespace (<namespace>.servicebus.windows.net) en Entra ID-authenticatie.

Hiervoor heb je geen pull request nodig. Dat is het punt van het groepsmodel (ADR-005). Je hebt wel een firewallregel nodig als de verzender buiten je spoke staat of het verkeer nog niet is toegestaan (Firewallregels en IP-groepen).

Voeg geen identities toe aan de entiteitsrollen in het portal

Geef toegang via de groepen. Een roltoewijzing die iemand direct op een queue toevoegt, maakt geen deel uit van de code, en de volgende deployment kan die verwijderen of een toestand achterlaten die niemand kan reviewen.

Entiteiten wijzigen of verwijderen¶

Wijzig de JSON en open een pull request. Lees het plan van de pull request om te zien wat er gebeurt.

De meeste eigenschappen worden ter plekke gewijzigd.
Een queue, topic of subscription verwijderen verwijdert ook zijn groepen, en verwijdert de berichten erin.
Een naam wijzigen maakt een nieuwe entiteit aan en verwijdert de oude.
Partitioning van een draaiende namespace is een wijziging met data-impact. Vraag eerst het platformteam.

Hoe de pull request een wijziging wordt: Aanvragen en wijzigen.

Operationele opmerkingen voor workload teams¶

Onderwerp	Wat je moet weten
Beschikbaarheid	De Premium-namespace is standaard zone-redundant. Geo-disaster recovery is een optionele maatregel van het platform (Beschikbaarheid).
Doorvoer	Messaging units worden handmatig door het platformteam geschaald. Schalen kan verbindingen even resetten, dus doe een retry in je client.
Dead letters	Houd de groei van dead letters op je queues in de gaten. Alerting op de namespace is van het platform. Alerts op je applicatie zijn van jou.
Delen	Meerdere workloads delen één namespace. Groepen op entiteitsniveau houden ze gescheiden: jouw groep geeft geen toegang tot de queue van een andere workload.