Trigger di accodamento

  • 7 minuti

Una coda di messaggi è un componente software usato per gestire la messaggistica tra processi, thread o applicazioni. Una coda può archiviare un messaggio e i thread di lavoro possono recuperarlo al momento opportuno.

Le code di messaggi nel cloud possono generare eventi con un payload. Un servizio come Funzioni di Azure può restare in ascolto di un messaggio di questo tipo ed eseguire il codice quando viene pubblicato un messaggio.

Gestire le code di messaggi

Per poter utilizzare un messaggio da una coda, una funzione di Azure ha bisogno di un trigger ed eventualmente di un'associazione.

Una funzione di Azure deve restare in ascolto su una coda specifica in modo che il relativo codice sia attivato quando viene pubblicato un nuovo messaggio su tale coda. Per configurare un trigger, è necessario specificare le credenziali corrette per consentire al codice del trigger di connettersi alla coda di messaggi. Per la funzione in ascolto sulla coda si crea una voce nel file function.json. Nell'elemento bindings specificare queste proprietà in una voce:

Proprietà valore
name Un nome a cui è possibile fare riferimento nel codice
type queueTrigger
direction in
queueName Il nome assegnato alla coda
connection Una variabile di configurazione in local.settings.json

È ad esempio possibile definire una voce come la seguente:

{
    "name": "myQueueItem",
    "type": "queueTrigger",
    "direction": "in",
    "queueName": "messages-incoming",
    "connection": "AzureWebJobsStorage"
  }

Se la coda si trova in un account di archiviazione, AzureWebJobsStorage è il valore della stringa di connessione.

Quando si utilizza un messaggio di una coda non deve essere necessariamente definita un'associazione. Se però si vuole scrivere in una coda, è necessaria un'associazione di output, con la quale si ottiene un riferimento alla coda.

Nota

Attualmente, per le code sono supportate solo associazioni di output.

Sviluppare in locale

Durante l'attività di sviluppo, si richiedono brevi cicli di feedback. Si vuole inoltre assicurarsi che l'esperienza di sviluppo sia quanto più vicina possibile a un ambiente di produzione. Per raggiungere entrambi gli obiettivi è possibile usare un emulatore di coda.

Un emulatore di coda consente di simulare i messaggi della coda reali a cui risponderà la funzione di Azure. Per usare l'emulatore:

  1. Installare l'emulatore. Cercare Azurite in Visual Studio Code o scaricare l'estensione Azurite.

  2. Per usare l'emulatore, avviarlo selezionando Azure: Start Queue Service nel riquadro comandi.

    L'esecuzione di questo comando avvia un listener denominato Azure Storage Explorer che può essere richiamato da un'altra applicazione. Storage Explorer è un'applicazione client che consente di esplorare le risorse cloud e usare la funzionalità dell'emulatore.

  3. Scaricare Azure Storage Explorer. Aprire quindi l'applicazione e verrà visualizzata l'indicazione seguente per mostrare che l'emulatore funziona:

    Screenshot che mostra l'emulatore in Azure Storage Explorer.

  4. Creare una coda nell'emulatore. La coda verrà usata come parte della configurazione dell'endpoint della funzione. Facendo clic con il pulsante destro del mouse sull'elemento queue, è possibile creare una nuova coda.

  5. Per assicurarsi che l'app per le funzioni usi l'emulatore, è necessario impostare correttamente la stringa di connessione. Aprire local.settings.json, individuare l'elemento AzureWebJobsStorage e assegnargli il valore "UseDevelopmentStorage=true".

    Nota

    Ricordarsi di impostare questa proprietà in modo diverso durante il passaggio al cloud. In un ambiente di produzione dovrebbe puntare a una risorsa effettiva in Azure.

Compilare la funzione

A questo punto è stato configurato un emulatore locale con una coda. È stato inoltre configurato il progetto in modo che punti all'emulatore locale. È ora necessario creare una funzione per gestire un trigger di accodamento.

Creare un endpoint per la funzione

È tutto pronto per creare una funzione in grado di gestire i messaggi della coda in ingresso. Creare una cartella per la funzione e assegnarle un nome, ad esempio queueTrigger. Creare quindi un file function.json e specificare il contenuto seguente:

{
  "bindings": [{
    "name" "queueItem",
    "type": "queueTrigger",
    "direction": "in",
    "queueName" : "items",
    "connection": "AzureWebJobsStorage"
  }]
}

Il valore dell'elemento name è importante, perché vi si farà riferimento più avanti nel codice per analizzare i dati in ingresso dalla coda. Deve essere di tipo queueTrigger in modo da essere attivabile automaticamente dalla coda quando arriva un nuovo messaggio.

L'elemento queueName identifica in modo univoco la coda con cui si interagisce. Qualsiasi valore immesso per questo elemento deve corrispondere al nome assegnato alla coda nell'emulatore o a quello che si assegnerà alla coda effettiva in Azure.

L'elemento connection punta al valore di AzureWebJobsStorage in local.settings.json.

Gestire un messaggio della coda

Per gestire un messaggio della coda in ingresso, è necessario scrivere codice in grado di analizzare il messaggio richiesto. A questo punto, è possibile decidere cosa fare in seguito. È ad esempio possibile avviare una richiesta Web, inserire il messaggio in un'altra coda o inviare il messaggio a un database.

Configurare una route

Per gestire le richieste in ingresso è necessario configurare una route. Funzioni di Azure gestirà le richieste inviate a una coda nella radice. Quando si configura una route come indicato di seguito, la richiesta viene richiamata come http://localhost:<port>/queueTrigger:

http.HandleFunc("/queueTrigger", handleQueueTrigger)

Decodificare una richiesta

Quando il messaggio della coda viene inviato all'utente, ha l'aspetto seguente:

{
  "Data": {
    "queueItem": "your message"
  },
  "Metadata": {
    "DequeueCount": 1,
    "ExpirationTime": "2019-10-16T17:58:31+00:00",
    "Id": "800ae4b3-bdd2-4c08-badd-f08e5a34b865",
    "InsertionTime": "2019-10-09T17:58:31+00:00",
    "NextVisibleTime": "2019-10-09T18:08:32+00:00",
    "PopReceipt": "AgAAAAMAAAAAAAAAAgtnj8x+1QE=",
    "sys": {
      "MethodName": "QueueTrigger",
      "UtcNow": "2019-10-09T17:58:32.2205399Z",
      "RandGuid": "24ad4c06-24ad-4e5b-8294-3da9714877e9"
    }
  }
}

Per la decodifica della richiesta in ingresso, è necessaria una struttura helper in grado di modellare il messaggio precedente. La cartella dovrebbe avere un aspetto simile a questo:

type InvokeRequest {
   Data map[string]json.RawMessage
   Metadata map[string]interface{}
}

Iniziare a scrivere codice per decodificare la richiesta in ingresso:

func handleQueueTrigger(w http.ResponseWrite, r *http.Request) {
   var invokeRequest InvokeRequest
   d := json.NewDecoder(r.Body)
   d.Decode(&invokeRequest)
}

A questo punto la richiesta è stata decodificata, ma è necessario analizzare il messaggio della coda.

Analizzare un messaggio della coda

Dopo la decodifica della richiesta, il messaggio della coda può essere recuperato dalla richiesta nella proprietà Data. È anche necessario fare riferimento al messaggio in base al valore della proprietà name configurato nel file function.json. Il codice per il recupero del messaggio consiste in un'unica riga simile alla seguente:

invokeRequest.Data["queueItem"]

Poiché è necessario essere in grado di leggere questo messaggio in testo non crittografato, si userà una libreria JSON e si analizzerà il messaggio. La libreria JSON userà un metodo Unmarshal() che accetta due parametri: il messaggio da analizzare e la variabile in cui inserire il messaggio analizzato. Il codice dovrà assumere un aspetto simile al seguente:

var parsedMessage string
json.Unmarshal(invokeRequest.Data["queueItem"], &parsedMessage)

A questo punto, parsedMessage contiene il messaggio. Se si vuole che venga visualizzato nella console, usare il codice seguente:

fmt.Println(parsedMessage) // your message

Nota

Se il messaggio è più complesso di una semplice stringa, parsedMessage deve avere una struttura che corrisponda alla forma di ciò a cui fa riferimento queueMessage.

Attivare un messaggio

Per testare l'applicazione, è possibile usare Azure Storage Explorer. Nel riquadro destro dello strumento selezionare il pulsante Aggiungi messaggio per creare un messaggio nella coda.

Screenshot che mostra il pulsante per l'aggiunta di un messaggio nella coda.

Se a questo punto l'app per le funzioni è in esecuzione, l'associazione verrà attivata e il codice verrà richiamato.