Guida introduttiva: Pubblicare negli argomenti dello spazio dei nomi e utilizzare gli eventi in Griglia di eventi di Azure

In questa guida introduttiva verrà eseguito il recapito pull utilizzando il comando curldella Shell Bash per pubblicare, ricevere e confermare gli eventi. Usare i comandi dell'interfaccia della riga di comando di Azure per creare risorse di Griglia di eventi di Azure. Questo articolo è adatto per un rapido test della funzionalità di consegna pull.

Per il codice di esempio che usa gli SDK del piano dati, vedere queste risorse:

• .NET: Inviare e ricevere messaggi da un topic del namespace di Azure Event Grid (.NET)
• Java: pubblicare gli eventi negli argomenti dello spazio dei nomi con Java
• Java: ricevere gli eventi utilizzando il recapito pull con Java

Per altre informazioni sul modello di recapito pull, vedere gli articoli Concetti relativi allo spazio dei nomi di Griglia di eventi di Azure e Recapito pull con HTTP.

Se non si ha un account Azure, creare un account gratuito prima di iniziare.

Prerequisiti

• È possibile utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

  

• Se preferisci eseguire localmente i comandi di riferimento della CLI, installa l'Azure CLI. Se si esegue in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

  • Se usi un'installazione locale, accedi all'interfaccia della riga di comando di Azure usando il comando az login. Per completare il processo di autenticazione, seguire i passaggi visualizzati nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

  • Quando ti viene richiesto, installa l'estensione Azure CLI al primo utilizzo. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.

  • Esegui az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, avviare az upgrade.

• Questo articolo richiede la versione 2.0.70 o successiva dell'interfaccia della riga di comando di Azure. Se si usa Azure Cloud Shell, la versione più recente è già installata.

Creare un gruppo di risorse

Creare un gruppo di risorse di Azure con il comando az group create. Usare questo gruppo di risorse per contenere tutte le risorse create in questo articolo.

I passaggi generali per usare Cloud Shell per eseguire i comandi sono:

• Selezionare Apri Cloud Shell per visualizzare una finestra di Azure Cloud Shell nel riquadro destro.
• Copiare il comando e incollarlo nella finestra di Azure Cloud Shell.
• Premere INVIO per eseguire il comando.

1. Dichiarare una variabile per contenere il nome di un gruppo di risorse di Azure. Specificare un nome per il gruppo di risorse sostituendo <your-resource-group-name> con il valore.

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

2. Creare un gruppo di risorse. È possibile modificare la posizione in qualsiasi posizione di Azure.

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

Abilitare il provider di risorse di Griglia di eventi

1. Se è la prima volta che si usa Griglia di eventi nella sottoscrizione di Azure, potrebbe essere necessario registrare il provider di risorse di Griglia di eventi. Eseguire il comando seguente per registrare il provider:

   az provider register --namespace Microsoft.EventGrid
   

2. La registrazione può richiedere qualche secondo. Eseguire il comando seguente per verificare lo stato:

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

   Quando registrationState è Registered, è possibile continuare.

Creare uno spazio dei nomi

Uno spazio dei nomi di Event Grid fornisce un endpoint definito dall'utente a cui si inviano gli eventi. Nell'esempio seguente viene creato uno spazio dei nomi nel gruppo di risorse utilizzando Bash in Azure Cloud Shell. Il nome dello spazio dei nomi deve essere univoco perché fa parte di una voce DNS (Domain Name System). Un nome dello spazio dei nomi deve soddisfare le regole seguenti:

• Deve essere compreso tra 3 e 50 caratteri.
• Deve essere univoco a livello di area.
• Solo i caratteri consentiti sono: a-z, A-Z, 0-9 e -
• Non deve iniziare con prefissi di parole chiave riservate come Microsoft, Systemo EventGrid.

1. Dichiarare una variabile per contenere il nome per lo spazio dei nomi di Griglia di eventi. Specificare un nome per lo spazio dei nomi sostituendo <your-namespace-name> con il valore.

   namespace="<your-namespace-name>"
   

2. Creare uno spazio dei nomi. Potrebbe essere necessario modificare il percorso in cui viene distribuito.

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

Creare un argomento per lo spazio dei nomi

Creare un argomento che racchiude tutti gli eventi pubblicati nell'endpoint dello spazio dei nomi.

1. Dichiara una variabile destinata a contenere il nome del tuo argomento dello spazio dei nomi. Specifica un nome per l'argomento dello spazio dei nomi sostituendo <your-topic-name> con il tuo valore.

   topic="<your-topic-name>"
   

2. Creare l'argomento per lo spazio dei nomi:

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

Creare una sottoscrizione di eventi

Creare una sottoscrizione a un evento impostando la modalità di recapito su coda, che supporta il recapito pull. Per altre informazioni su tutte le opzioni di configurazione, vedere API REST di Griglia di eventi di Azure.

1. Dichiarare una variabile che contenga il nome di una sottoscrizione per l'evento dell'argomento nello spazio di nomi. Specificare un nome per la sottoscrizione di eventi sostituendo <your-event-subscription-name> con il valore.

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

2. Creare una sottoscrizione eventi per l'argomento dello spazio dei nomi:

   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}}"
   

Invia eventi al tuo tema

Inviare un evento di esempio all'argomento dello spazio dei nomi seguendo la procedura descritta in questa sezione.

Elenca le chiavi di accesso dello spazio dei nomi

1. Ottenere le chiavi di accesso associate allo spazio dei nomi creato. È necessario uno di essi per eseguire l'autenticazione durante la pubblicazione di eventi. Per elencare le chiavi, ottieni l'ID completo della risorsa del namespace. Eseguire il comando seguente:

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

2. Ottenere la prima chiave dallo spazio dei nomi:

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

Pubblicare un evento

1. Recuperare il nome host dello spazio dei nomi. Verrà utilizzato per comporre l'endpoint HTTP dello spazio dei nomi a cui inviare gli eventi. Le operazioni seguenti sono state disponibili per la prima volta con la versione 2023-06-01-previewdell'API .

   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. Creare un esempio di evento conforme a CloudEvents:

   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"}} '
   

   L'elemento data è il payload dell'evento. Questo campo accetta qualsiasi JSON ben formato. Le proprietà che possono accedere a un evento sono note anche come attributi di contesto. Per altre informazioni, vedere CloudEvents.

3. Utilizzare CURL per inviare l'evento all'argomento. CURL è un'utilità che invia richieste HTTP.

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

Ricevere l'evento

Si ricevono eventi da Griglia di eventi usando un endpoint che fa riferimento a una sottoscrizione di eventi.

1. Comporre l'endpoint eseguendo il comando seguente:

   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. Inviare una richiesta per utilizzare l'evento:

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

Confermare un evento

Dopo aver ricevuto un evento, passare tale evento all'applicazione per l'elaborazione. Dopo aver elaborato correttamente l'evento, non è più necessario che l'evento si trovi nella sottoscrizione di eventi. Per indicare a Event Grid di eliminare l'evento, riconoscerlo usando il token di blocco ottenuto nella risposta dell'operazione di ricezione.

1. Nella sezione precedente, hai ricevuto una risposta che include un oggetto brokerProperties con una proprietà lockToken. Copiare il valore del token di blocco e impostarlo in una variabile di ambiente:

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

2. Compilare il payload dell'operazione di conferma, che specifica il token di blocco per l'evento da confermare.

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

3. Procedere con la compilazione della stringa con l'URI dell'operazione di conferma:

   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. Infine, inviare una richiesta per confermare l'evento ricevuto:

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

   Se l'operazione di conferma viene eseguita prima della scadenza del token di blocco (300 secondi come impostato al momento della creazione della sottoscrizione di eventi), verrà visualizzata una risposta simile all'esempio seguente:

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

Passo successivo

Per altre informazioni sul modello di recapito pull, vedere Recapito pull con HTTP.