In this quickstart, you do pull delivery using thecurl bash shell command to publish, receive, and acknowledge events. Use Azure CLI commands to create Azure Event Grid resources. This article is suitable for a quick test of the pull delivery functionality.

For sample code that uses the data plane SDKs, see these resources:

• .NET:Send and receive messages from an Azure Event Grid namespace topic (.NET)
• Java:Publish events to namespace topics using Java
• Java:Receive events using pull delivery with Java

For more information about the pull delivery model, seeAzure Event Grid namespace concepts andPull delivery with HTTP articles.

If you don't have an Azure account, create afree account before you begin.

Prerequisites

• Use the Bash environment inAzure Cloud Shell. For more information, seeGet started with Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally,install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, seeHow to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using theaz login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, seeAuthenticate to Azure using Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, seeUse and manage extensions with the Azure CLI.

  • Runaz version to find the version and dependent libraries that are installed. To upgrade to the latest version, runaz upgrade.

• This article requires version 2.0.70 or later of the Azure CLI. If you use Azure Cloud Shell, the latest version is already installed.

Create a resource group

Create an Azure resource group with theaz group create command. Use this resource group to contain all resources you create in this article.

The general steps to use Cloud Shell to run commands are:

• SelectOpen Cloud Shell to see an Azure Cloud Shell window on the right pane.
• Copy the command and paste into the Azure Cloud Shell window.
• Press ENTER to run the command.

1. Declare a variable to hold the name of an Azure resource group. Specify a name for the resource group by replacing<your-resource-group-name> with your value.

   resource_group="<your-resource-group-name>"

2. Create a resource group. You can change the location to any Azure location.

   az group create --name $resource_group --location eastus

Enable the Event Grid resource provider

1. If this is the first time you're using Event Grid in your Azure subscription, you might need to register the Event Grid resource provider. Run the following command to register the provider:

   az provider register --namespace Microsoft.EventGrid

2. It might take a moment for the registration to finish. To check the status, run the following command:

   az provider show --namespace Microsoft.EventGrid --query "registrationState"

   WhenregistrationState isRegistered, you're ready to continue.

Create a namespace

An Event Grid namespace provides a user-defined endpoint to which you post your events. The following example creates a namespace in your resource group using Bash in Azure Cloud Shell. The namespace name must be unique because it's part of a Domain Name System (DNS) entry. A namespace name should meet the following rules:

• It should be between 3-50 characters.
• It should be regionally unique.
• Only allowed characters are: a-z, A-Z, 0-9, and -
• It shouldn't start with reserved key word prefixes likeMicrosoft,System, orEventGrid.

1. Declare a variable to hold the name for your Event Grid namespace. Specify a name for the namespace by replacing<your-namespace-name> with your value.

   namespace="<your-namespace-name>"

2. Create a namespace. You might want to change the location where you deploy it.

   az eventgrid namespace create --resource-group $resource_group --name $namespace --location eastus

Create a namespace topic

Create a topic that holds all events published to the namespace endpoint.

1. Declare a variable to hold the name for your namespace topic. Specify a name for the namespace topic by replacing<your-topic-name> with your value.

   topic="<your-topic-name>"

2. Create your namespace topic:

   az eventgrid namespace topic create --resource-group $resource_group --name $topic --namespace-name $namespace

Create an event subscription

Create an event subscription setting its delivery mode toqueue, which supportspull delivery. For more information on all configuration options, seeAzure Event Grid REST API.

1. Declare a variable to hold the name for an event subscription to your namespace topic. Specify a name for the event subscription by replacing<your-event-subscription-name> with your value.

   event_subscription="<your-event-subscription-name>"

2. Create an event subscription to the namespace topic:

   az eventgrid namespace topic event-subscription create --resource-group $resource_group --topic-name $topic --name $event_subscription --namespace-name $namespace --delivery-configuration "{deliveryMode:Queue,queue:{receiveLockDurationInSeconds:300,maxDeliveryCount:4,eventTimeToLive:P1D}}"

Send events to your topic

Send a sample event to the namespace topic by following steps in this section.

List namespace access keys

1. Get the access keys associated with the namespace you created. You need one of them to authenticate when publishing events. To list your keys, get the full namespace resource ID. Run the following command:

   namespace_resource_id=$(az eventgrid namespace show --resource-group $resource_group --name $namespace --query "id" --output tsv)

2. Get the first key from the namespace:

   key=$(az eventgrid namespace list-key --resource-group $resource_group --namespace-name $namespace --query "key1" --output tsv)

Publish an event

1. Retrieve the namespace hostname. You use it to compose the namespace HTTP endpoint to which events are sent. The following operations were first available with API version2023-06-01-preview.

   publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview

2. Create a sampleCloudEvents compliant event:

   event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '

   Thedata element is the payload of your event. Any well-formed JSON can go in this field. Properties that can go into an event are also known ascontext attributes. For more information, seeCloudEvents.

3. Use CURL to send the event to the topic. CURL is a utility that sends HTTP requests.

   curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri

Receive the event

You receive events from Event Grid using an endpoint that refers to an event subscription.

1. Compose the endpoint by running the following command:

   receive_operation_uri="https://"$(az eventgrid namespace show --resource-group $resource_group --name $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:receive?api-version=2023-06-01-preview

2. Submit a request to consume the event:

   curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" $receive_operation_uri

Acknowledge an event

After you receive an event, you pass that event to your application for processing. After you successfully process your event, you no longer need that event to be in your event subscription. To instruct Event Grid to delete the event, youacknowledge it using its lock token that you got on the receive operation's response.

1. In the previous section, you received a response that includes abrokerProperties object with alockToken property. Copy the lock token value and set it on an environment variable:

   lockToken="<paste-the-lock-token-here>"

2. Build the acknowledge operation payload, which specifies the lock token for the event you want to be acknowledged.

   acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '

3. Proceed with building the string with the acknowledge operation URI:

   acknowledge_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:acknowledge?api-version=2023-06-01-preview

4. Finally, submit a request to acknowledge the event received:

   curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" -d "$acknowledge_request_payload" $acknowledge_operation_uri

   If the acknowledge operation is executed before the lock token expires (300 seconds as set when we created the event subscription), you should see a response like the following example:

   {"succeededLockTokens":["CiYKJDQ4NjY5MDEyLTk1OTAtNDdENS1BODdCLUYyMDczNTYxNjcyMxISChDZae43pMpE8J8ovYMSQBZS"],"failedLockTokens":[]}

Next step

To learn more about pull delivery model, seePull delivery with HTTP.