Esercizio - Scrivere dati con associazioni di output

15 minuti

Nell'esercizio precedente è stato implementato uno scenario per cercare i segnalibri in un database Azure Cosmos DB. È stata inoltre configurata un'associazione di input per leggere i dati dalla raccolta di segnalibri. Ma si può fare di più. Ad esempio, è possibile espandere lo scenario per includere anche la scrittura. Prendere in considerazione il diagramma di flusso seguente:

Diagramma del flusso decisionale che illustra il processo di aggiunta di un segnalibro nel back-end di Azure Cosmos DB e di restituzione di una risposta.

In questo scenario si riceveranno richieste per aggiungere segnalibri alla raccolta. Le richieste passano la chiave desiderata, o ID, insieme all'URL del segnalibro. Come si può notare nel diagramma di flusso, si riceverà un errore se la chiave esiste già nel back-end.

Se la chiave che è stata passata non viene trovata, il nuovo segnalibro verrà aggiunto al database. È possibile andare anche oltre.

Si può infatti notare un altro passaggio nel diagramma di flusso. Finora non è stato fatto granché con i dati ricevuti in termini di elaborazione. Sono stati semplicemente spostati in un database. Tuttavia, in una soluzione reale è possibile che i dati vengano in qualche modo elaborati. Si può eseguire tutta l'elaborazione nella stessa funzione, ma in questo esercizio verrà mostrato un modello che trasferisce l'ulteriore elaborazione a un altro componente o a un'altra parte della logica di business.

Quale potrebbe essere un valido esempio di offload del lavoro nello scenario basato sui segnalibri? potrebbe essere l'invio di un nuovo segnalibro a un servizio di generazione di codice a matrice. Questo servizio, a sua volta, genera un codice a matrice per l'URL, archivia l'immagine in Archiviazione BLOB e aggiunge l'indirizzo dell'immagine del codice a matrice nella voce della raccolta di segnalibri. Chiamare un servizio per generare un'immagine del codice a matrice può richiedere molto tempo, quindi invece di attendere il risultato è consigliabile trasferire l'attività a una funzione che la completerà in modalità asincrona.

Proprio come Funzioni di Azure supporta associazioni di input per varie origini di integrazione, include anche un set di modelli di associazioni di output per semplificare la scrittura dei dati nelle origini dati. Le associazioni di output vengono configurate anche nel file function.json. Come si vedrà in questo esercizio, è possibile configurare la funzione per usare più origini dati e servizi.

Importante

Questo esercizio si basa sulle risorse e sulle risorse della sandbox create nelle unità precedenti; in particolare, il database di database Azure Cosmos DB, i segnalibri e le associazioni di input. Se non sono stati completati gli esercizi nelle unità precedenti, non sarà possibile completare questo esercizio.

Creare una funzione attivata da HTTP

Nel portale di Azure passare all'app per le funzioni creata selezionando il nome dell'app per le funzioni nel percorso di navigazione nella parte superiore della pagina della funzione HttpTrigger2.
Nella scheda Funzioni della pagina Panoramica dovrebbero essere presenti le funzioni di trigger HTTP create.
Selezionare Crea nella scheda Funzioni. Viene visualizzato il riquadro Crea funzione.
Nella sezione Selezionare un modello selezionare Trigger HTTP e quindi Avanti. Accettare le impostazioni predefinite nella scheda Dettagli modello e selezionare Crea. Viene visualizzato il riquadro Panoramica per la funzione HttpTrigger3.

Aggiungere un'associazione di input di Azure Cosmos DB

Aggiungere ora un'altra associazione di input di Azure Cosmos DB.

Nel menu della funzione HttpTrigger3 selezionare Integrazione. Viene visualizzato il riquadro Integrazione.
Nella casella Trigger e input, selezionare Aggiungi input. Viene visualizzato il riquadro Crea input.
Nell'elenco a discesa Tipo di associazione selezionare Azure Cosmos DB.
L'impostazione Connessione all'account Cosmos DB dovrebbe essere già popolata con la connessione creata nell'esercizio precedente.

Se la connessione non è inclusa nell'elenco, seguire questa procedura per creare una nuova connessione.
1. Nella sezione Dettagli Cosmos DB selezionare il collegamento Nuovo nell'impostazione Connessione all'account Cosmos DB.
2. Quando viene visualizzata la finestra di dialogo Nuova connessione Cosmos DB, selezionare OK per creare la connessione. Viene creata una nuova connessione all'account Cosmos DB.

Immettere i valori seguenti per le altre impostazioni in questo riquadro. Per altre informazioni sullo scopo di un'impostazione, in qualsiasi momento è possibile selezionare l'icona delle informazioni a destra.

Impostazione	valore	Descrizione
Nome del parametro del documento	`bookmark`	Nome usato per identificare questa associazione nel codice.
Nome database	`func-io-learn-db`	Il database da usare. Questo valore corrisponde al nome del database impostato in precedenza in questa lezione.
Nome raccolta	`Bookmarks`	Nome della raccolta da cui vengono letti i dati. Questa impostazione è stata definita in precedenza nella lezione.
Document ID	`{id}`	Aggiungere `{id}` per usare l'espressione di associazione corretta e accettare il parametro passato nella stringa di query.
Chiave di partizione	`{id}`	Aggiungere `{id}` di nuovo per usare l'espressione di associazione corretta e accettare il parametro passato nella stringa di query.
Query SQL (facoltativa)	Lasciare vuoto	Si sta recuperando un solo elemento alla volta in base all'ID. L'applicazione di filtri con l'impostazione Documento è quindi una scelta migliore rispetto all'uso di una query SQL in questa istanza. Sarebbe possibile creare una query SQL per restituire una voce (`SELECT * from b where b.ID = /id`). La query restituirebbe in effetti un elemento, ma in una raccolta di elementi. Il codice dovrebbe modificare una raccolta inutilmente. Usare l'approccio basato sulle query SQL quando si vuole ottenere più documenti.

Come per l'associazione di input creata nell'esercizio precedente, si vuole cercare un segnalibro con un ID specifico e quindi l'ID documento ricevuto dalla funzione è stato collegato nella stringa di query all'associazione, nota come espressione di associazione. La funzione viene attivata da una richiesta HTTP che usa una stringa di query per specificare l'ID da cercare. L'associazione restituisce 0 documenti (non trovato) o 1 documento (trovato).

Selezionare Aggiungi per salvare la configurazione dell'associazione di input.

È stata creata un'associazione di input di Azure Cosmos DB. È il momento di aggiungere un'associazione di output per poter scrivere nuove voci nella raccolta.

Aggiungere un'associazione di output di Azure Cosmos DB

Nel riquadro Integrazione di HttpTrigger3 selezionare Aggiungi output nella casella Output. Viene visualizzato il riquadro Crea output.
Dall'elenco a discesa in Tipo di associazione selezionare Azure Cosmos DB.
L'impostazione Connessione all'account Cosmos DB dovrebbe essere già popolata con la connessione creata in precedenza. Se non lo è, espandere l'elenco a discesa e selezionare la connessione definita per l'associazione di input HttpTrigger3.

Immettere i valori seguenti per le impostazioni rimanenti per l'associazione di output.

Impostazione	valore	Descrizione
Nome del parametro del documento	`newbookmark`	Nome usato per identificare questa associazione nel codice. Questo parametro viene usato per scrivere una nuova voce segnalibro.
Nome database	`func-io-learn-db`	Il database da usare. Questo valore corrisponde al nome del database impostato in precedenza in questa lezione.
Nome raccolta	`Bookmarks`	Nome della raccolta da cui vengono letti i dati. Questo valore è il nome del contenitore definito in precedenza nella lezione.
Chiave di partizione	`/id`	Aggiungere la chiave di partizione definita al momento della creazione del contenitore Bookmarks di Azure Cosmos DB in precedenza. La chiave immessa qui, specificata nella configurazione di associazione di input `<key>`, deve corrispondere a quella nel contenitore.

Selezionare Aggiungi per salvare questa configurazione dell'associazione di ouput.

Ora è presente un'associazione per la lettura della raccolta e una per la scrittura.

Aggiungere un'associazione di output di archiviazione code di Azure

Archiviazione code di Azure è un servizio che consente di archiviare messaggi a cui è possibile accedere da qualsiasi parte del mondo. Le dimensioni di un singolo messaggio possono essere al massimo 64 KB e una coda può contenere milioni di messaggi, fino alla capacità complessiva dell'account di archiviazione in cui viene definita la coda. Il diagramma seguente mostra, a livello generale, come viene usata una coda in questo scenario.

Illustrazione che mostra una coda di archiviazione con una funzione che esegue il push e un'altra funzione che preleva i messaggi.

In questo esempio si vede che una funzione denominata add-bookmark aggiunge messaggi a una coda e che un'altra denominata gen-qr-code preleva messaggi dalla stessa coda ed elabora la richiesta. Poiché vengono scritti messaggi (o se ne esegue il push) nella coda da add-bookmark, si aggiungerà una nuova associazione di output alla soluzione.

L'associazione verrà creata tramite il portale.

Nel riquadro Integrazione relativo alla funzione selezionare Aggiungi output nella casella Output. Viene visualizzato il riquadro Crea output.
Nell'elenco a discesa Tipo di associazione selezionare Archiviazione code di Azure.

Se viene visualizzato un messaggio che richiede di installare l'estensione Microsoft.Azure.WebJobs.Extensions.Storage, selezionare Installa e attendere il completamento dell'operazione.

Verrà quindi configurata una connessione all'account di archiviazione, in cui verrà ospitata la coda.

In Connessione dell'account di archiviazione selezionare Nuova. Viene visualizzata la finestra di dialogo Nuova connessione dell'account di archiviazione.
All'inizio di questo modulo, quando è stata creata l'app per le funzioni, è stato creato anche un account di archiviazione. Selezionarlo nell'elenco a discesa e quindi selezionare OK.

L'impostazione Connessione dell'account di archiviazione viene popolata con il nome di una connessione.

Anche se è possibile mantenere i valori predefiniti, alcune impostazioni verranno modificate per dare più significato alle proprietà rimanenti.

Completare le impostazioni nel riquadro Crea output sostituendo questi valori precedenti con i nuovi valori:

Impostazione	Valore precedente	Nuovo valore	Descrizione
Nome del parametro del messaggio	outputQueueItem	newmessage	Proprietà di associazione che verrà usata nel codice.
Nome coda	outqueue	bookmarks-post-process	Nome della coda usata per l'inserimento dei segnalibri, affinché possano essere ulteriormente elaborati da un'altra funzione.

Selezionare Aggiungi per salvare la configurazione di output per l'archiviazione code di Azure.

Aggiornare l'implementazione della funzione

Tutte le associazioni sono ora impostate. È il momento di usarle nell'ambito della funzione.

Per aprire il file index.js nell'editor di codice, selezionare la funzione HttpTrigger3.
Nel menu, selezionare Codice e test. Viene visualizzato il riquadro Codice e test per la funzione.

Sostituire tutto il codice nel file index.js con il codice del frammento seguente e nella barra dei menu selezionare Salva.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark;
    if(bookmark){
            context.res = {
            status: 422,
            body : "Bookmark already exists.",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    else {
        
        // Create a JSON string of our bookmark.
        var bookmarkString = JSON.stringify({ 
            id: req.body.id,
            url: req.body.url
        });

        // Write this bookmark to our database.
        context.bindings.newbookmark = bookmarkString;

        // Push this bookmark onto our queue for further processing.
        context.bindings.newmessage = bookmarkString;

        // Tell the user all is well.
        context.res = {
            status: 200,
            body : "bookmark added!",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    context.done();
};

Verrà ora esaminato in dettaglio il funzionamento di questo codice:

Dato che questa funzione modifica i dati, si prevede che la richiesta HTTP sia di tipo POST e che i dati del segnalibro facciano parte del corpo della richiesta.
L'associazione di input di Azure Cosmos DB tenta di recuperare un documento o un segnalibro usando l'oggetto id ricevuto. Se viene trovata una voce, l'oggetto bookmark viene impostato. La condizione if(bookmark) verifica se è stata trovata una voce.
L'aggiunta al database è un'operazione semplice quanto l'impostazione del parametro di associazione context.bindings.newbookmark sulla nuova voce del segnalibro, creata sotto forma di stringa JSON.
Anche pubblicare un messaggio nella coda è un'operazione semplice che prevede l'impostazione del parametro context.bindings.newmessage.

Nota

L'unica attività eseguita è stata quella di creare un'associazione di coda. In modo esplicito non è stata creata alcuna coda, il tutto è avvenuto automaticamente grazie alle associazioni. Come dichiarato nella notifica seguente, la coda viene creata automaticamente se non esiste già.

Screenshot che mostra il messaggio che indica che la coda verrà creata automaticamente. .

Selezionare function.json dall'elenco a discesa nel percorso <functionapp> \ HttpTrigger3 \ e apportare le seguenti modifiche:
1. Modificare tutte le istanze di "collectionName" in "containerName".
2. Modificare tutte le istanze di "connectionStringSetting" in "connection".
3. Eliminare i riferimenti a "methods": [].

Il file function.json finale dovrebbe essere simile a questo codice.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{id}"
    },
    {
      "name": "newbookmark",
      "direction": "out",
      "type": "cosmosDB",
      "partitionKey": "/id",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB"
    },
    {
      "name": "newmessage",
      "direction": "out",
      "type": "queue",
      "queueName": "bookmarks-post-process",
      "connection": "your-storage-account_STORAGE"
    }
  ]
}

Sulla barra dei comandi selezionare Salva.

Questo è tutto. Nella sezione successiva verrà messo in pratica il lavoro svolto.

Per aprire il file run.ps1 nell'editor di codice, selezionare la funzione HttpTrigger3 nel percorso di navigazione nella parte superiore del riquadro.
Nel menu Funzione in Sviluppatore selezionare Codice e test. Viene visualizzato il riquadro Codice e test per la funzione HttpTrigger3, che mostra il contenuto predefinito di run.ps1.

Sostituire il contenuto del file con il codice seguente.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = 422
    $body = "Bookmark already exists."
}
else {
    $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }

    Push-OutputBinding -Name newbookmark -Value $newBookmark

    Push-OutputBinding -Name newmessage -Value $newBookmark

    $status = [HttpStatusCode]::OK
    $body = "bookmark added!"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
    ContentType = "application/json"
})

Seleziona Salva nella barra dei comandi. Viene eseguita una connessione e viene aperta una sessione di file di log.

Verrà ora esaminato in dettaglio il funzionamento di questo codice:

Dato che questa funzione modifica i dati, si prevede che la richiesta HTTP sia di tipo POST e che i dati del segnalibro facciano parte del corpo della richiesta.
L'associazione di input di Azure Cosmos DB tenta di recuperare un documento o un segnalibro usando id nella richiesta. Se viene trovata una voce, l'oggetto bookmark viene impostato. La condizione if ($bookmark) verifica se è stata trovata una voce.
Per aggiungere il database, è sufficiente chiamare Push-OutputBinding con il nome dell'associazione di output di Cosmos DB (newbookmark) e il valore dell'oggetto $newBookmark.
Per pubblicare un messaggio nella coda, è sufficiente chiamare Push-OutputBinding con il nome dell'associazione di output della coda (newmessage) e il valore dell'oggetto $newBookmark.

Nota

Screenshot che mostra la descrizione comando nell'interfaccia utente che indica che la coda verrà creata automaticamente.

Questo è tutto. Nella sezione successiva verrà messo in pratica il lavoro svolto.

Provala

Ora che sono disponibili più associazioni di output, i test diventano un po' più complessi. Nelle unità precedenti i test sono stati eseguiti inviando una richiesta HTTP e una stringa di query, ma questa volta viene inviata una richiesta HTTP POST. È anche necessario verificare se i messaggi vengono inseriti in una coda.

Nella barra dei comandi del riquadro Codice e test per la funzione HttpTrigger3 selezionare Test/Esegui. Viene visualizzato un nuovo riquadro, con la scheda Input aperta, come illustrato in questa immagine:
Assicurarsi che nell'elenco a discesa Metodo HTTP sia selezionato POST.
Sostituire il contenuto del corpo della richiesta con il payload JSON seguente:
```
{
    "id": "docs",
    "url": "https://zcusa.951200.xyz/azure"
}
```
Selezionare Esegui.
Lo stato di avanzamento a livello di codice viene visualizzato nel riquadro Log. Al termine, verificare che nella scheda Output venga visualizzato "Bookmark already exists." nell'impostazione Contenuto della risposta HTTP.

È stato aggiunto l'elemento segnalibro in Esercizio - Leggere dati con associazioni di input. La risposta conferma che JavaScript var bookmark = context.bindings.bookmark funziona correttamente e che il codice di PowerShell sta effettuando la stessa connessione.
Viene ora inserito un secondo segnalibro nel database. Selezionare la scheda Input.
Sostituire il contenuto del corpo della richiesta con il payload JSON seguente:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Selezionare Esegui.
Verificare che la scheda Output mostri il messaggio "Il segnalibro è stato aggiunto." in Contenuto della risposta HTTP, come illustrato nello screenshot seguente.

Congratulazioni. La funzione viene eseguita come da progetto. Ma cosa è successo all'operazione di coda aggiunta al codice? Per prima cosa, occorre verificare se è stato scritto qualcosa in una coda.

Verificare che sia stato scritto un messaggio nella coda

Le code di Archiviazione code di Azure sono ospitate in un account di archiviazione. L'account di archiviazione è stato configurato durante la creazione dell'associazione di output.

Nella barra di ricerca globale del portale di Azure immettere gli account di archiviazione e quindi nell'elenco risultati selezionare Account di archiviazione. Viene visualizzato il riquadro Account di archiviazione.
Selezionare l'account di archiviazione usato per configurare l'associazione di output newmessage.
Nel menu Account di archiviazione, in Archiviazione dati selezionare Code per elencare le code ospitate da questo account di archiviazione. Verificare che la coda bookmarks-post-process sia elencata, come illustrato nello screenshot seguente.
Selezionare bookmarks-post-process per elencare i messaggi presenti nella coda. In assenza di errori, la coda include il messaggio inviato al momento dell'aggiunta di un segnalibro al database. Il messaggio sarà simile al seguente.

In questo esempio è stato assegnato un ID univoco al messaggio e nella colonna Testo del messaggio viene visualizzato il segnalibro in formato JSON. Non è presente alcun messaggio per il segnalibro docs di Azure che si è tentato di aggiungere perché esiste già nel database.
È possibile testare la funzione ulteriormente modificando il corpo della richiesta nel riquadro Test con nuovi set di ID/URL ed eseguendo la funzione. Prestare attenzione alla coda per vedere se arrivano altri messaggi. È anche possibile esaminare il database per verificare che siano state aggiunte nuove voci.

In questo esercizio sono state approfondite le conoscenze sulle associazioni prendendo in esame le associazioni di output e scrivendo dati in Azure Cosmos DB. È stata aggiunta un'associazione di output per inserire i messaggi in una coda di Azure. Questo esempio dimostra tutta l'efficacia delle associazioni, che consentono di modellare e spostare i dati dalle origini in ingresso a diverse destinazioni. Non è stato necessario scrivere il codice del database, né gestire manualmente le stringhe di connessione. Al contrario, le associazioni sono state configurate in modo dichiarativo lasciando che la piattaforma si occupasse automaticamente della protezione delle connessioni, oltre che del ridimensionamento della funzione e delle connessioni.