Veröffentlichen von Ereignissen in einem benutzerdefinierten Azure Event Grid-Thema mithilfe von Zugriffsschlüsseln

In diesem Artikel wird beschrieben, wie Sie unter Verwendung eines Zugriffsschlüssels ein Ereignis in einem benutzerdefinierten Thema posten. Es wird außerdem das Format von Postings und Ereignisdaten gezeigt. Die Vereinbarung zum Servicelevel (SLA) gilt nur für Postings, die dem erwarteten Format entsprechen.

Hinweis

Microsoft Entra-Authentifizierung bietet eine bessere Authentifizierungsunterstützung als Authentifizierung mit Zugriffsschlüsseln oder SAS-Token (Shared Access Signature). Bei Microsoft Entra-Authentifizierung wird die Identität anhand des Microsoft Entra-Identitätsanbieters überprüft. Als Entwickler müssen Sie keine Schlüssel in Ihrem Code verwalten, wenn Sie Microsoft Entra-Authentifizierung verwenden. Sie profitieren auch von allen Sicherheitsfeatures, die in die Microsoft Identity-Plattform integriert sind, z. B. von bedingtem Zugriff. Diese Features können Ihnen helfen, die Sicherheit Ihrer Anwendung zu verbessern. Weitere Informationen finden Sie unter Authentifizieren von Veröffentlichungsclients mit Microsoft Entra ID.

Endpunkt

Verwenden Sie beim Senden des HTTP-POST-Befehls an ein benutzerdefiniertes Thema das URI-Format: https://<topic-endpoint>?api-version=2018-01-01. https://exampletopic.westus2-1.eventgrid.azure.net/api/events?api-version=2018-01-01 ist beispielsweise ein gültiger URI. Um den Endpunkt für ein benutzerdefiniertes Thema mit der Azure CLI abzurufen, verwenden Sie diesen Befehl:

Azure portal

Sie finden den Endpunkt des Themas auf der Registerkarte Übersicht der Seite Event Grid Topic im Azure-Portal.

Azure-Befehlszeilenschnittstelle

az eventgrid topic show --name <topic-name> -g <topic-resource-group> --query "endpoint"

Azure PowerShell

(Get-AzEventGridTopic -ResourceGroupName <topic-resource-group> -Name <topic-name>).Endpoint

Header

Schließen Sie einen Headerwert namens aeg-sas-key in die Anforderung ein, der einen Schlüssel für die Authentifizierung enthält. Ein gültiger Headerwert ist beispielsweise aeg-sas-key: xxxxxxxxxxxxxxxxxxxxxxx. Um den Schlüssel für ein benutzerdefiniertes Thema mit der Azure CLI abzurufen, verwenden Sie diesen Befehl:

Azure portal

Um die Zugriffstaste für das benutzerdefinierte Thema abzurufen, wählen Sie die Registerkarte Zugriffstasten auf der Seite Ereignisrasterthema im Azure-Portal aus.

Azure-Befehlszeilenschnittstelle

az eventgrid topic key list --name <topic-name> -g <topic-resource-group> --query "key1"

Azure PowerShell

(Get-AzEventGridTopicKey -ResourceGroupName <topic-resource-group> -Name <topic-name>).Key1

Ereignisdaten

Für benutzerdefinierte Themen müssen die Daten der obersten Ebene müssen die gleichen Felder enthalten wie die über Standardressourcen definierten Ereignisse. Eine dieser Eigenschaften ist eine data-Eigenschaft, die eindeutige Eigenschaften für das benutzerdefinierte Thema enthält. Als Ereignisherausgeber legen Sie die Eigenschaften für dieses Datenobjekt fest. Das folgende Schema wird verwendet:

[
  {
    "id": string,    
    "eventType": string,
    "subject": string,
    "eventTime": string-in-date-time-format,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string
  }
]

Eine Beschreibung dieser Eigenschaften finden Sie unter Azure Event Grid-Ereignisschema. Wenn ein Client Ereignisse an ein Ereignisrasterthema sendet, kann das Array eine Gesamtgröße von bis zu 1 MB aufweisen. Die maximal zulässige Größe für ein Ereignis beträgt ebenfalls 1 MB. Ereignisse, die größer als 64 KB sind, werden in Schritten von 64 KB in Rechnung gestellt. Wenn ein Client Ereignisse in einem Batch empfängt, beträgt die maximal zulässige Anzahl von Ereignissen 5.000 pro Batch.

Ein gültiges Ereignisdatenschema lautet beispielsweise wie folgt:

[{
  "id": "1807",
  "eventType": "recordInserted",
  "subject": "myapp/vehicles/motorcycles",
  "eventTime": "2017-08-10T21:03:07+00:00",
  "data": {
    "make": "Ducati",
    "model": "Monster"
  },
  "dataVersion": "1.0"
}]

Senden des Beispielereignisses

In diesem Abschnitt wird gezeigt, wie Sie ein Beispielereignis an das benutzerdefinierte Thema senden.

Azure portal

1. Starten Sie im Azure-Portal Cloud Shell.

2. Führen Sie in der Cloud Shell die Befehle aus der Azure PowerShell- oder Azure CLI in der Bash- oder PowerShell-Sitzung aus.

   

Azure-Befehlszeilenschnittstelle

endpoint=$(az eventgrid topic show --name <topic name> -g <resource group name> --query "endpoint" --output tsv)

key=$(az eventgrid topic key list --name <topic name> -g <resource group name> --query "key1" --output tsv)

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/motorcycles", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "make": "Ducati", "model": "Monster"},"dataVersion": "1.0"} ]'

curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

Azure PowerShell

$resourceGroupName = "<resource group name>"
$topicName = "<topic name>"

$endpoint = (Get-AzEventGridTopic -ResourceGroupName $resourceGroupName -Name $topicName).Endpoint

$keys = Get-AzEventGridTopicKey -ResourceGroupName $resourceGroupName -Name $topicName

$eventID = Get-Random 99999
#Date format should be SortableDateTimePattern (ISO 8601)
$eventDate = Get-Date -Format s

#Construct body using Hashtable
$htbody = @{
    id= $eventID
    eventType="recordInserted"
    subject="myapp/vehicles/motorcycles"
    eventTime= $eventDate   
    data= @{
        make="Ducati"
        model="Monster"
    }
    dataVersion="1.0"
}

#Use ConvertTo-Json to convert event body from Hashtable to JSON Object
#Append square brackets to the converted JSON payload since they are expected in the event's JSON payload syntax
$body = "["+(ConvertTo-Json $htbody)+"]"

Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

Antwort

Nachdem Sie das Posten an den Themenendpunkt durchgeführt haben, erhalten Sie eine Antwort. Die Antwort ist ein HTTP-Standardantwortcode. Einige häufige Antworten lauten:

Ergebnis	Antwort
Erfolg	200 – OK
Fehlerhaftes Format der Ereignisdaten	400 – Ungültige Anforderung
Ungültiger Zugriffsschlüssel	401 – Nicht autorisiert
Falscher Endpunkt	404 – Nicht gefunden
Array oder Ereignis überschreitet Größengrenzwerte	413 Nutzlast zu groß

Für Fehler hat der Nachrichtentext das folgende Format:

{
    "error": {
        "code": "<HTTP status code>",
        "message": "<description>",
        "details": [{
            "code": "<HTTP status code>",
            "message": "<description>"
    }]
  }
}

Zugehöriger Inhalt

• Informationen zur Überwachung von Ereignisübermittlungen finden Sie unter Überwachen der Event Grid-Nachrichtenübermittlung.
• Weitere Informationen zum Authentifizierungsschlüssel finden Sie unter Event Grid – Sicherheit und Authentifizierung.
• Weitere Informationen zum Erstellen eines Azure Event Grid-Abonnements finden Sie unter Event Grid-Abonnementschema.