When you want to receive events from an Azure service, you need to subscribe to a topic. The subscription is the connection between a topic and your event handler.
You can create a subscription using the Azure portal, PowerShell cmdlet, or the CLI interface, but behind the scenes, the creation of a subscription is a PUT HTTP REST call to an address with the following form:
PUT /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/{resource-provider}/{resource-type}/{subscription-name}/Microsoft.EventGrid/eventSubscriptions/{event-type-definitions}?api-version=2018-01-01
The subscription name must be a string with a length of 3-64 characters and can only contain a-z, A-Z, 0-9, and -. The payload of the PUT call looks like the following:
{
"properties": {
"destination": {
"endpointType": "webhook",
"properties": {
"endpointUrl": "https://example.azurewebsites.net/api/HttpTriggerCSharp1?code=VXbGWce53l48Mt8wuotr0GPmyJ/nDT4hgdFj9DpBiRt38qqnnm5OFg=="
}
},
"filter": {
"includedEventTypes": [ "Microsoft.Storage.BlobCreated", "Microsoft.Storage.BlobDeleted" ],
"subjectBeginsWith": "blobServices/default/containers/mycontainer/log",
"subjectEndsWith": ".jpg"
}
}
}
Every subscription has destination and filter sections:
- destination: Identifies the object that defines the endpoint that will receive the events.
- endpointtype: The type of the endpoint (for example, webhook, queue, and so on).
- endpointurl: The destination URL for the endpoint.
- filter: Any filters to apply to topic events before sending them to the event handler. This object is optional.
- includedEventTypes: An array of event types that will be sent to the event handler. The events in this array must exactly match the event names registered in the event source. If you use an incorrect name here, you will receive an error.
- subjectBeginsWith: A prefix match for the subject of the events thrown by the source. If you use it, only the events with a subject that starts with the string you use will be sent to the event handler.
- subjectEndsWith: A suffix match for the subject of the events thrown by the source. If you use it, only the events with a subject that ends with the string you use will be sent to the event handler.
- isSubjectCaseSensitive: Chooses whether or not the filter is case sensitive.
You can also implement advanced filtering based on values contained in the data fields of the event payload. The filter section of the JSON payload also accepts a property called "advancedFilters", which allows you to define filtering such as the following:
"filter": {
"advancedFilters": [
{
"operatorType": "NumberGreaterThanOrEquals",
"key": "Data.Key1",
"value": 5
},
{
"operatorType": "StringContains",
"key": "Subject",
"values": ["container1", "container2"]
}
]
}
In the previous snippet, the subscription sends to the event handler only the events that have a property called Key1 in the data section with a value greater or equal to 5 and a subject that contains "container1" or "container2".