Training
Certification
Microsoft Certified: Azure Cosmos DB Developer Specialty - Certifications
Write efficient queries, create indexing policies, manage, and provision resources in the SQL API and SDK with Microsoft Azure Cosmos DB.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This article describes how to post an event to a custom topic using an access key. It shows the format of the post and event data. The Service Level Agreement (SLA) only applies to posts that match the expected format.
Note
Microsoft Entra authentication provides a superior authentication support than that's offered by access key or Shared Access Signature (SAS) token authentication. With Microsoft Entra authentication, the identity is validated against Microsoft Entra identity provider. As a developer, you won't have to handle keys in your code if you use Microsoft Entra authentication. you'll also benefit from all security features built into the Microsoft identity platform, such as Conditional Access, that can help you improve your application's security stance. For more information, see Authenticate publishing clients using Microsoft Entra ID.
When sending the HTTP POST to a custom topic, use the URI format: https://<topic-endpoint>?api-version=2018-01-01
. For example, a valid URI is: https://exampletopic.westus2-1.eventgrid.azure.net/api/events?api-version=2018-01-01
. To get the endpoint for a custom topic using Azure CLI, use:
You can find the topic's endpoint on the Overview tab of the Event Grid Topic page in the Azure portal.
In the request, include a header value named aeg-sas-key
that contains a key for authentication. For example, a valid header value is aeg-sas-key: xxxxxxxxxxxxxxxxxxxxxxx
. To get the key for a custom topic using Azure CLI, use:
To get the access key for the custom topic, select Access keys tab on the Event Grid Topic page in the Azure portal.
For custom topics, the top-level data contains the same fields as standard resource-defined events. One of those properties is a data
property that contains properties unique to the custom topic. As an event publisher, you determine properties for that data object. Here's the schema:
[
{
"id": string,
"eventType": string,
"subject": string,
"eventTime": string-in-date-time-format,
"data":{
object-unique-to-each-publisher
},
"dataVersion": string
}
]
For a description of these properties, see Azure Event Grid event schema. When a client sends events to an Event Grid topic, the array can have a total size of up to 1 MB. The maximum allowed size for an event is also 1 MB. Events over 64 KB are charged in 64-KB increments. When a client receives events in a batch, the maximum allowed number of events is 5,000 per batch.
For example, a valid event data schema is:
[{
"id": "1807",
"eventType": "recordInserted",
"subject": "myapp/vehicles/motorcycles",
"eventTime": "2017-08-10T21:03:07+00:00",
"data": {
"make": "Ducati",
"model": "Monster"
},
"dataVersion": "1.0"
}]
This section shows how to send a sample event to the custom topic.
In the Azure portal, launch Cloud Shell.
In the Cloud Shell, run the commands from the Azure PowerShell or Azure CLI in the Bash or PowerShell session.
After posting to the topic endpoint, you receive a response. The response is a standard HTTP response code. Some common responses are:
Result | Response |
---|---|
Success | 200 OK |
Event data has incorrect format | 400 Bad Request |
Invalid access key | 401 Unauthorized |
Incorrect endpoint | 404 Not Found |
Array or event exceeds size limits | 413 Payload Too Large |
For errors, the message body has the following format:
{
"error": {
"code": "<HTTP status code>",
"message": "<description>",
"details": [{
"code": "<HTTP status code>",
"message": "<description>"
}]
}
}
Training
Certification
Microsoft Certified: Azure Cosmos DB Developer Specialty - Certifications
Write efficient queries, create indexing policies, manage, and provision resources in the SQL API and SDK with Microsoft Azure Cosmos DB.