Skip to content

Commit b584946

Browse files
HarshCasperpaolosalvatori
HarshCasper
and
paolosalvatori
authored
add Azure Service Bus(Data Operations/Messaging) service doc (#500)
Co-authored-by: Paolo Salvatori <leprino@hotmail.com>
1 parent a6d67eb commit b584946

File tree

1 file changed

+222
-1
lines changed

1 file changed

+222
-1
lines changed

‎src/content/docs/azure/services/service-bus-data-plane.mdx‎

Lines changed: 222 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,232 @@
11
---
22
title: "Service Bus Data Plane"
3-
description: API coverage for Microsoft.ServiceBus.DataPlane in LocalStack for Azure.
3+
description: Get started with Azure Service Bus Data Plane on LocalStack
44
template: doc
55
---
66

77
import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage";
88

9+
## Introduction
10+
11+
Azure Service Bus Data Plane APIs let you operate messaging entities through the namespace endpoint directly.
12+
This data plane REST API allows for direct interaction with queues, topics, and subscriptions. It supports core messaging operations including sending, peeking, and receiving messages, as well as batch processing. For more information, see [Azure Service Bus REST API](https://learn.microsoft.com/rest/api/servicebus/service-bus-runtime-rest).
13+
In LocalStack, they are useful for validating data-plane behavior without calling Azure cloud endpoints.
14+
15+
LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Service Bus Data Plane APIs.
16+
The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Service Bus Data Plane integration with LocalStack.
17+
18+
## Getting started
19+
20+
This guide is designed for users new to Service Bus Data Plane APIs and assumes basic knowledge of the Azure CLI and our `azlocal` wrapper script.
21+
22+
Launch LocalStack using your preferred method. For more information, see [Introduction to LocalStack for Azure](/azure/getting-started/). Once the container is running, enable Azure CLI interception by running:
23+
24+
```bash
25+
azlocal start-interception
26+
```
27+
28+
This command points the `az` CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API.
29+
To revert this configuration, run:
30+
31+
```bash
32+
azlocal stop-interception
33+
```
34+
35+
This reconfigures the `az` CLI to send commands to the official Azure management REST API.
36+
37+
### Create a resource group
38+
39+
Create a resource group for your Service Bus resources:
40+
41+
```bash
42+
az group create \
43+
--name rg-servicebus-dp-demo \
44+
--location westeurope
45+
```
46+
47+
```bash title="Output"
48+
{
49+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-servicebus-dp-demo",
50+
"location": "westeurope",
51+
"name": "rg-servicebus-dp-demo",
52+
"properties": {
53+
"provisioningState": "Succeeded"
54+
},
55+
...
56+
}
57+
```
58+
59+
### Create a Service Bus namespace
60+
61+
Create a namespace and capture its data-plane endpoint:
62+
63+
```bash
64+
az servicebus namespace create \
65+
--resource-group rg-servicebus-dp-demo \
66+
--name sbnsdoc84 \
67+
--location westeurope \
68+
--sku Standard
69+
```
70+
71+
```bash title="Output"
72+
{
73+
"name": "sbnsdoc84",
74+
"serviceBusEndpoint": "https://sbnsdoc84.localhost.localstack.cloud:4511",
75+
"provisioningState": "Succeeded",
76+
...
77+
}
78+
```
79+
80+
Store the HTTP endpoint for data-plane REST calls:
81+
82+
```bash
83+
SB_ENDPOINT="http://sbnsdoc84.localhost.localstack.cloud:4511"
84+
```
85+
86+
### Create and inspect a queue entity
87+
88+
Create a queue via the data-plane Entity `Put` API:
89+
90+
```bash
91+
curl -s -X PUT "$SB_ENDPOINT/dpqueue?api-version=2017-04" \
92+
-H "Content-Type: application/atom+xml;type=entry;charset=utf-8" \
93+
-d '<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom"><title type="text">dpqueue</title><content type="application/xml"><QueueDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect" /></content></entry>'
94+
```
95+
96+
```xml title="Output"
97+
<?xml version="1.0" encoding="utf-8"?>
98+
<entry xmlns="http://www.w3.org/2005/Atom">
99+
<title type="text">dpqueue</title>
100+
<content type="application/xml">
101+
<QueueDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
102+
<Status>Active</Status>
103+
...
104+
</QueueDescription>
105+
</content>
106+
</entry>
107+
```
108+
109+
Get the queue entity via Entity `Get`:
110+
111+
```bash
112+
curl -s -X GET "$SB_ENDPOINT/dpqueue?api-version=2017-04"
113+
```
114+
115+
```xml title="Output"
116+
<?xml version="1.0" encoding="utf-8"?>
117+
<entry xmlns="http://www.w3.org/2005/Atom">
118+
<title type="text">dpqueue</title>
119+
<content type="application/xml">
120+
<QueueDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
121+
<MessageCount>0</MessageCount>
122+
<Status>Active</Status>
123+
...
124+
</QueueDescription>
125+
</content>
126+
</entry>
127+
```
128+
129+
### Create and inspect a topic subscription
130+
131+
Create a topic entity:
132+
133+
```bash
134+
curl -s -X PUT "$SB_ENDPOINT/dptopic?api-version=2017-04" \
135+
-H "Content-Type: application/atom+xml;type=entry;charset=utf-8" \
136+
-d '<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom"><title type="text">dptopic</title><content type="application/xml"><TopicDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect" /></content></entry>'
137+
```
138+
139+
Create a subscription via Subscription `Put`:
140+
141+
```bash
142+
curl -s -X PUT "$SB_ENDPOINT/dptopic/subscriptions/dpsub?api-version=2017-04" \
143+
-H "Content-Type: application/atom+xml;type=entry;charset=utf-8" \
144+
-d '<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom"><title type="text">dpsub</title><content type="application/xml"><SubscriptionDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect" /></content></entry>'
145+
```
146+
147+
```xml title="Output"
148+
<?xml version="1.0" encoding="utf-8"?>
149+
<entry xmlns="http://www.w3.org/2005/Atom">
150+
<title type="text">dpsub</title>
151+
<content type="application/xml">
152+
<SubscriptionDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
153+
<Status>Active</Status>
154+
<MaxDeliveryCount>10</MaxDeliveryCount>
155+
...
156+
</SubscriptionDescription>
157+
</content>
158+
</entry>
159+
```
160+
161+
Get the subscription via Subscription `Get`:
162+
163+
```bash
164+
curl -s -X GET "$SB_ENDPOINT/dptopic/subscriptions/dpsub?api-version=2017-04"
165+
```
166+
167+
```xml title="Output"
168+
<?xml version="1.0" encoding="utf-8"?>
169+
<entry xmlns="http://www.w3.org/2005/Atom">
170+
<title type="text">dpsub</title>
171+
<content type="application/xml">
172+
<SubscriptionDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
173+
<MessageCount>0</MessageCount>
174+
<Status>Active</Status>
175+
...
176+
</SubscriptionDescription>
177+
</content>
178+
</entry>
179+
```
180+
181+
### Delete subscription and entities
182+
183+
Delete the subscription via Subscription `Delete`:
184+
185+
```bash
186+
curl -s -X DELETE "$SB_ENDPOINT/dptopic/subscriptions/dpsub?api-version=2017-04"
187+
```
188+
189+
Delete entities via Entity `Delete`:
190+
191+
```bash
192+
curl -s -X DELETE "$SB_ENDPOINT/dptopic?api-version=2017-04"
193+
194+
curl -s -X DELETE "$SB_ENDPOINT/dpqueue?api-version=2017-04"
195+
```
196+
197+
## Features
198+
199+
The emulator includes the following core capabilities:
200+
201+
- **Data Plane REST API**: Supports message-level operations, including Send, Receive, and Peek.
202+
- **Control Plane REST API**: Enables CRUD operations for namespaces and messaging entities (queues, topics, and subscriptions) via Azure Resource Manager (ARM).
203+
- **Multiple Authentication Modes**: Supports both Connection String and Managed Identity authentication.
204+
- **Containerized Deployment**: Runs as a lightweight, Linux-based Docker container.
205+
- **Cross-Platform Compatibility**: Fully compatible with Windows, macOS, and Linux environments.
206+
- **Flexible Configuration**: Manage Service Bus entities via the Service Bus Administration Client or through JSON-based configuration files.
207+
- **Advanced Streaming**: Supports message streaming via the Advanced Message Queuing Protocol (AMQP).
208+
209+
## Limitations
210+
211+
The current version of the emulator does **not** support the following:
212+
213+
- **Protocols**: JMS protocol streaming and AMQP Web Sockets (AMQP over TCP is the only supported transport).
214+
- **Messaging Patterns**: Transactions, auto-forwarding (queue chaining), and message lock renewal.
215+
- **Validation**: Enforcements such as maximum entity counts or maximum message sizes.
216+
- **Metrics**: Property-based message counts for queues, topics, and subscriptions may be inaccurate.
217+
218+
The following Azure-native features are currently unavailable in the emulator:
219+
220+
- **Scaling & Resiliency**: Autoscale, Geo-disaster recovery, and Large Message support.
221+
- **Monitoring**: Visual metrics, alerts, and telemetry dashboards.
222+
223+
## Samples
224+
225+
Explore the following samples to get started with Service Bus on LocalStack:
226+
227+
- [Azure Functions App with Service Bus Messaging](https://github.com/localstack/localstack-azure-samples/blob/main/samples/function-app-service-bus/dotnet/)
228+
- [Azure Service Bus with Spring Boot](https://github.com/localstack/localstack-azure-samples/tree/main/samples/servicebus/java)
229+
9230
## API Coverage
10231

11232
<AzureFeatureCoverage service="Microsoft.ServiceBus.DataPlane" client:load />

0 commit comments

Comments
 (0)