AI 原生开放教材

外观

Microsoft Agent Skills技能与配置库·英文原文 ↗原件 ↓仓库 ↗

Azure Event Hubs SDK Acceptance Criteria ​

SDK: azure-eventhubRepository: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhubCommit: mainPurpose: Skill testing acceptance criteria for validating generated code correctness

1. Correct Import Patterns ​

1.1 Client Imports ​

✅ CORRECT: Sync Producer/Consumer ​

python
from azure.eventhub import EventHubProducerClient, EventHubConsumerClient, EventData
from azure.identity import DefaultAzureCredential

✅ CORRECT: Blob Checkpoint Store (Sync) ​

python
from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore

✅ CORRECT: Async Clients ​

python
from azure.eventhub.aio import EventHubProducerClient, EventHubConsumerClient
from azure.identity.aio import DefaultAzureCredential

✅ CORRECT: Async Blob Checkpoint Store ​

python
from azure.eventhub.extensions.checkpointstoreblob.aio import BlobCheckpointStore

1.2 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Wrong modules ​

python
# WRONG - package name is azure.eventhub
from azure.eventhubs import EventHubProducerClient

# WRONG - DefaultAzureCredential is from azure.identity(.aio)
from azure.eventhub.aio import DefaultAzureCredential

2. Authentication Patterns ​

2.1 ✅ CORRECT: DefaultAzureCredential with Fully Qualified Namespace ​

python
import os
from azure.eventhub import EventHubProducerClient, EventHubConsumerClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
namespace = os.environ["EVENT_HUB_FULLY_QUALIFIED_NAMESPACE"]
eventhub_name = os.environ["EVENT_HUB_NAME"]

producer = EventHubProducerClient(
    fully_qualified_namespace=namespace,
    eventhub_name=eventhub_name,
    credential=credential,
)

consumer = EventHubConsumerClient(
    fully_qualified_namespace=namespace,
    eventhub_name=eventhub_name,
    consumer_group="$Default",
    credential=credential,
)

2.2 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Hardcoded connection strings ​

python
# WRONG - avoid hardcoded connection strings
producer = EventHubProducerClient.from_connection_string(
    "Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=...",
    eventhub_name="my-eventhub",
)

3. EventHubProducerClient Patterns ​

3.1 ✅ CORRECT: Batch Send with Size Handling ​

python
from azure.eventhub import EventHubProducerClient, EventData
from azure.identity import DefaultAzureCredential

producer = EventHubProducerClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    eventhub_name="my-eventhub",
    credential=DefaultAzureCredential(),
)

with producer:
    batch = producer.create_batch()
    for i in range(10):
        try:
            batch.add(EventData(f"event-{i}"))
        except ValueError:
            producer.send_batch(batch)
            batch = producer.create_batch()
            batch.add(EventData(f"event-{i}"))
    producer.send_batch(batch)

3.2 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing context manager or close ​

python
# WRONG - producer should be used with context manager or explicitly closed
producer = EventHubProducerClient(
    fully_qualified_namespace=namespace,
    eventhub_name=eventhub_name,
    credential=credential,
)
producer.send_batch([EventData("event")])

4. EventHubConsumerClient Patterns ​

4.1 ✅ CORRECT: Receive with Checkpoint Update ​

python
from azure.eventhub import EventHubConsumerClient
from azure.identity import DefaultAzureCredential

def on_event(partition_context, event):
    print(event.body_as_str())
    partition_context.update_checkpoint(event)

consumer = EventHubConsumerClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    eventhub_name="my-eventhub",
    consumer_group="$Default",
    credential=DefaultAzureCredential(),
)

with consumer:
    consumer.receive(on_event=on_event, starting_position="-1")

4.2 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing on_event handler ​

python
# WRONG - receive requires an on_event callback
consumer.receive(starting_position="-1")

5. Partitions ​

5.1 ✅ CORRECT: Send to Specific Partition ​

python
batch_by_id = producer.create_batch(partition_id="0")
batch_by_id.add(EventData("event-for-partition-0"))

batch_by_key = producer.create_batch(partition_key="user-123")
batch_by_key.add(EventData("event-for-user-123"))

5.2 ✅ CORRECT: Read Partition Properties ​

python
with producer:
    info = producer.get_eventhub_properties()
    for partition_id in info["partition_ids"]:
        partition_info = producer.get_partition_properties(partition_id)
        print(partition_info["last_enqueued_sequence_number"])

5.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Passing both partition_id and partition_key ​

python
# WRONG - only one of partition_id or partition_key is allowed
producer.create_batch(partition_id="0", partition_key="user-123")

6. Checkpointing ​

6.1 ✅ CORRECT: BlobCheckpointStore with Consumer ​

python
from azure.eventhub import EventHubConsumerClient
from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore
from azure.identity import DefaultAzureCredential

checkpoint_store = BlobCheckpointStore(
    blob_account_url="https://<account>.blob.core.windows.net",
    container_name="checkpoints",
    credential=DefaultAzureCredential(),
)

consumer = EventHubConsumerClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    eventhub_name="my-eventhub",
    consumer_group="$Default",
    credential=DefaultAzureCredential(),
    checkpoint_store=checkpoint_store,
)

def on_event(partition_context, event):
    partition_context.update_checkpoint(event)

6.2 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Checkpoint store without updating checkpoints ​

python
# WRONG - checkpoint store requires update_checkpoint to persist progress
def on_event(partition_context, event):
    print(event.body_as_str())
    return  # No checkpoint update!

7. Async Variants ​

7.1 ✅ CORRECT: Async Producer Send ​

python
import asyncio
from azure.eventhub import EventData
from azure.eventhub.aio import EventHubProducerClient
from azure.identity.aio import DefaultAzureCredential

async def main():
    async with EventHubProducerClient(
        fully_qualified_namespace="<namespace>.servicebus.windows.net",
        eventhub_name="my-eventhub",
        credential=DefaultAzureCredential(),
    ) as producer:
        batch = await producer.create_batch()
        batch.add(EventData("async-event"))
        await producer.send_batch(batch)

asyncio.run(main())

7.2 ✅ CORRECT: Async Consumer with Checkpointing ​

python
import asyncio
from azure.eventhub.aio import EventHubConsumerClient
from azure.eventhub.extensions.checkpointstoreblob.aio import BlobCheckpointStore
from azure.identity.aio import DefaultAzureCredential

async def on_event(partition_context, event):
    print(event.body_as_str())
    await partition_context.update_checkpoint(event)

async def main():
    checkpoint_store = BlobCheckpointStore(
        blob_account_url="https://<account>.blob.core.windows.net",
        container_name="checkpoints",
        credential=DefaultAzureCredential(),
    )

    async with EventHubConsumerClient(
        fully_qualified_namespace="<namespace>.servicebus.windows.net",
        eventhub_name="my-eventhub",
        consumer_group="$Default",
        credential=DefaultAzureCredential(),
        checkpoint_store=checkpoint_store,
    ) as consumer:
        await consumer.receive(on_event=on_event, starting_position="-1")

asyncio.run(main())

7.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Mixing sync credential with async client ​

python
from azure.eventhub.aio import EventHubProducerClient
from azure.identity import DefaultAzureCredential  # WRONG - use azure.identity.aio

async with EventHubProducerClient(
    fully_qualified_namespace=namespace,
    eventhub_name=eventhub_name,
    credential=DefaultAzureCredential(),
):
    ...

8. Environment Variables ​

Required Variables ​

bash
EVENT_HUB_FULLY_QUALIFIED_NAMESPACE=<namespace>.servicebus.windows.net
EVENT_HUB_NAME=my-eventhub

Optional Variables (Checkpointing) ​

bash
STORAGE_ACCOUNT_URL=https://<account>.blob.core.windows.net
CHECKPOINT_CONTAINER=checkpoints