Esercizio - Leggere dati con associazioni di input

20 minuti

Si supponga di voler creare un servizio di ricerca di segnalibri. Il servizio inizialmente è di sola lettura. Se un utente vuole trovare una voce, invia una richiesta con l'ID della voce e la funzione restituisce l'URL. Il diagramma di flusso seguente illustra il flusso logico.

Quando un utente invia una richiesta con testo, la funzione di ricerca del segnalibro tenta di trovare una voce nel database che contiene un segnalibro con il testo come chiave o ID. Il sistema restituisce un risultato che indica se la voce è stata trovata o meno.

Quando la funzione di Azure riceve una richiesta con l'ID del segnalibro, verifica innanzitutto se la richiesta è valida. Se non lo è, viene generata una risposta di errore. Se la richiesta è valida, la funzione controlla se l'ID del segnalibro esiste nel database di Azure Cosmos DB. Se non esiste, viene generata una risposta di errore. Se l'ID del segnalibro è presente, viene generata una risposta di esito positivo.

È necessario archiviare i dati altrove. Nel diagramma di flusso precedente l'archivio dati è un'istanza di Azure Cosmos DB. Ma come connettersi a un database da una funzione e leggere i dati? Nell'ambito delle funzioni si configura un'associazione di input per tale processo. Configurare un'associazione di input tramite il portale di Azure è davvero semplice. Come si vedrà a breve, non è necessario scrivere il codice per attività come l'apertura di una connessione di archiviazione. Queste attività vengono eseguite automaticamente dal runtime di Funzioni di Azure e dalle associazioni.

Creare un account Azure Cosmos DB

Nota

Questo esercizio non deve essere considerato un'esercitazione su Azure Cosmos DB. Se si è interessati a ottenere altre informazioni, vedere il percorso di apprendimento completo su Azure Cosmos DB alla fine di questo modulo.

Creare un account di database

Un account di database è un contenitore per la gestione di uno o più database. Prima di poter creare un database è necessario creare un account di database.

Nel menu delle risorse del portale di Azure o nella pagina Home selezionare Crea una risorsa. Viene visualizzato il riquadro Crea una risorsa.
Nel menu Crea una risorsa selezionare Database quindi cercare e selezionare Azure Cosmos DB. Viene visualizzato il riquadro Quali API si adatta meglio al carico di lavoro?
Nell'opzione Azure Cosmos DB for NoSQL selezionare Crea per creare un trigger di Cosmos DB e associazioni di input/output. Viene visualizzato il riquadro Crea account Azure Cosmos DB - Azure Cosmos DB per NoSQL.

Nella scheda Informazioni di base immettere i valori indicati di seguito per ogni impostazione.

Impostazione	valore	Descrizione
Dettagli del progetto
Subscription	Concierge Subscription	Sottoscrizione di Azure che usa le risorse nella sandbox.
Gruppo di risorse	Nell'elenco a discesa selezionare [nome gruppo di risorse sandbox]	Gruppo di risorse per la sandbox.
Dettagli dell'istanza
Account Name:	`globally unique name`	Immettere un nome univoco ma identificabile per l'account Azure Cosmos DB. `documents.azure.com` viene aggiunto al nome specificato. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Titolo	`region`	Selezionare l'area più vicina.

Accettare i valori predefiniti per le impostazioni rimanenti e selezionare Rivedi e crea per convalidare l'input. Viene visualizzata la notifica Convalida completata.
Selezionare Crea per effettuare il provisioning dell'account del database e distribuirlo.
La distribuzione può richiedere tempo. Prima di procedere, attendere di visualizzare il messaggio Distribuzione riuscita nell'hub delle notifiche.
Per passare all'account del database nel portale, selezionare Vai alla risorsa. Viene visualizzato il riquadro Avvio rapido per l'account di Azure Cosmos DB.

Si aggiungerà quindi un contenitore e poi un database all'account Azure Cosmos DB.

Aggiungere un contenitore

In Azure Cosmos DB viene usato un contenitore per archiviare varie entità generate dall'utente, dette anche elementi. Verrà creato un contenitore denominato Bookmarks.

Verrà ora usato lo strumento Esplora dati per creare un database e un contenitore.

Nel menu dell'account Azure Cosmos DB selezionare Esplora dati. Viene visualizzato il riquadro Esplora dati per l'account Cosmos DB.
Selezionare la casella Nuovo contenitore. Viene visualizzato il riquadro Nuovo contenitore. Potrebbe essere necessario scorrere la finestra verso il basso per visualizzare l'opzione.

Immettere i seguenti valori per ogni impostazione.

Impostazione	valore	Descrizione
ID database	Selezionare Crea nuovo e immettere func-io-learn-db nell'ID del database	I nomi di database possono contenere da 1 a 255 caratteri e non possono contenere `/, \\, #, ?`, o uno spazio finale. È possibile immettere qualsiasi elemento desiderato, ma in questo modulo si usa func-io-learn-db.
Numero massimo di UR/s	4000	Accettare la velocità effettiva predefinita di 4000 unità richiesta al secondo (RU/s). Per ridurre la latenza, è possibile aumentare le prestazioni in un secondo momento.
ID contenitore	Bookmarks	Gli ID contenitore prevedono gli stessi requisiti relativi ai caratteri dei nomi di database. In questo modulo si usa Bookmarks.
Chiave di partizione	/id	La chiave di partizione specifica la modalità di distribuzione dei documenti tra le partizioni di dati logiche nelle raccolte di Azure Cosmos DB. Per praticità si userà l'impostazione Chiave di partizione, in quanto in questo modulo le prestazioni del database non sono un aspetto critico. Per altre informazioni sulle strategie relative alla chiave di partizione di Azure Cosmos DB, vedere i moduli di Microsoft Learn relativi ad Azure Cosmos DB.

Accettare le impostazioni predefinite per tutte le altre impostazioni.

Scorrere fino alla parte inferiore del riquadro e selezionare OK. Attendere alcuni minuti per la compilazione del database e del contenitore.

Al termine, Esplora dati mostra func-io-learn-db in DATI in API NOSQL.
Selezionare func-io-learn-db per espanderlo. Si noti che il database func-io-learn-db contiene diversi membri figlio, tra cui Scala e Segnalibri.
Espandere il contenitore Segnalibri. Si noti che diversi membri figlio lo prepopolano già.

Nell'attività successiva si aggiungeranno alcuni dati, noti anche come elementi, al contenitore Bookmarks.

Aggiungere i dati del test

Si vogliono aggiungere dati al contenitore Segnalibri. Si userà Esplora dati per archiviare un URL e un ID per ogni elemento.

Espandere il database func-io-learn-db e il contenitore Segnalibri e infine selezionare Elementi. Viene visualizzata la scheda Elementi.
Nella barra dei comandi selezionare Nuovo elemento.
Sostituire il codice predefinito del nuovo elemento con il codice JSON seguente.
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```

Sulla barra dei comandi selezionare Salva.

Si noti che vengono visualizzate altre proprietà oltre alle due righe aggiunte. Iniziano tutte con una sottolineatura (_rid, _self, _etag, _attachments, _ts). Queste proprietà, descritte nella tabella seguente, vengono generate dal sistema per gestire gli elementi aggiunti al contenitore.

Proprietà	Descrizione
`_rid`	L'ID della risorsa è un identificatore univoco e anche gerarchico per ogni stack di risorse nel modello di risorsa. L’ID viene usato internamente per il posizionamento e l'esplorazione della risorsa elemento.
`_self`	URI indirizzabile univoco della risorsa.
`_etag`	Necessaria per il controllo della concorrenza ottimistica.
`_attachments`	Percorso indirizzabile della risorsa allegati.
`_ts`	Timestamp dell'ultimo aggiornamento della risorsa.

Si aggiungeranno altri elementi nel contenitore Segnalibri. Nella barra dei comandi selezionare Nuovo elemento. Creare quattro elementi aggiuntivi con il contenuto seguente. Per aggiungere gli elementi, selezionare Nuovo elemento e quindi Salva dopo aver copiato e incollato ogni nuovo elemento. Si noti come ogni elemento viene aggiunto all'elenco di elementi.
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
Al termine dell’immissione dei dati dei segnalibri, il contenitore sarà simile a quello mostrato nell'immagine seguente.

Il contenitore Segnalibri include cinque elementi. In questo scenario se arriva una richiesta con "id=docs", verrà cercato tale ID nel contenitore Bookmarks e verrà restituito l'URL https://learn.microsoft.com/azure. Verrà ora creata una funzione di Azure che esegue la ricerca di valori nel contenitore Segnalibri.

Creare una funzione

Passare all'app per le funzioni creata nell'unità precedente. Nel menu della risorsa selezionare Home e nella sezione Risorse recenti verrà visualizzata l'app per le funzioni (Tipo indica App per le funzioni). Selezionare l'app per le funzioni. Viene visualizzato il riquadro App per le funzioni.
Nella scheda Funzioni della pagina Panoramica dovrebbe essere presente una funzione, HttpTrigger1.
Verrà creata un'altra funzione. Selezionare Crea nella scheda Funzioni. Viene visualizzato il riquadro Crea funzione, elencando i modelli per i trigger supportati.
Nella sezione Selezionare un modello selezionare Trigger HTTP e quindi Avanti.
Accettare tutte le impostazioni predefinite e selezionare Crea per creare la funzione.

Viene visualizzato il riquadro Panoramica per la funzione HttpTrigger2.

Verificare la funzione

È possibile verificare lo stato di avanzamento fino a questo momento testando la nuova funzione.

Nella barra dei comandi selezionare Recupera URL della funzione. Viene visualizzata la finestra di dialogo Recupera URL della funzione.
Selezionare predefinito (tasto funzione) nell'elenco a discesa, quindi selezionare l'icona Copia negli appunti e OK.
Incollare l'URL della funzione copiato nella barra degli indirizzi di una nuova scheda del browser. Aggiungere il valore &name=<your name> della stringa di query alla fine dell'URL, sostituendo <your name> con il nome e quindi premere INVIO. La funzione di Azure deve restituire una risposta personalizzata nel browser.

Ora che la funzione di base funziona, è possibile concentrarsi sulla lettura dei dati da Azure Cosmos DB, ovvero, in questo scenario, dal contenitore Segnalibri.

Aggiungere un'associazione di input di Azure Cosmos DB

Per leggere i dati dal database è necessario definire un'associazione di input. Come si vedrà, con pochi passaggi è possibile configurare un'associazione che può comunicare con il database.

Nel portale di Azure, nel menu delle funzioni HttpTrigger2 in alto, selezionare Integrazione. Viene visualizzato il riquadro Integrazione relativo alla funzione.

È stato usato un modello che ha creato una richiesta di trigger HTTP con un'associazione di output HTTP. Viene ora aggiunta un'associazione di input di Azure Cosmos DB.
Nella casella Trigger e input, selezionare Aggiungi input. Viene visualizzato il riquadro Crea input.
Dall'elenco a discesa Tipo di associazione selezionare Azure Cosmos DB.
Nella sezione Dettagli Cosmos DB selezionare il collegamento Nuovo nell'impostazione Connessione all'account Cosmos DB. Viene visualizzata la finestra di dialogo Nuova connessione Cosmos DB.

Se viene visualizzato un messaggio che chiede di installare l'estensione Microsoft.Azure.WebJobs.Extensions.CosmosDB, selezionare Installa e attendere il completamento.
Per impostazione predefinita, Azure riconosce l'account Azure Cosmos DB creato in precedenza. Selezionare OK per configurare una connessione al database. Una nuova connessione all'account del database viene configurata e visualizzata nel campo Connessione all'account Cosmos DB.

Poiché si vuole cercare un segnalibro con un ID specifico, si collegherà l'ID ricevuto nella stringa di query all'associazione.

Vengono completate le impostazioni nel riquadro Crea input. Immettere i seguenti valori per ogni impostazione. Per altre informazioni sullo scopo di ogni impostazione, selezionare l'icona delle informazioni in quel campo.

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 è il nome del database impostato.
Nome raccolta	`Bookmarks`	Raccolta da cui vengono letti i dati. Questa impostazione è stata definita.
Document ID	`id`	Aggiungere l'ID del documento definito al momento della creazione del contenitore Segnalibri di Azure Cosmos DB.
Chiave di partizione	`/id`	Aggiungere la chiave di partizione definita quando è stata creata la raccolta Segnalibri di Azure Cosmos DB. La chiave immessa qui (specificata nel formato di associazione di input `<key>`) deve corrispondere a quella della raccolta.
Query SQL (facoltativa)	Lasciare vuoto	Si sta recuperando un solo documento alla volta in base all'ID. L'applicazione di filtri con l'impostazione ID documento è quindi preferibile all'uso di una query SQL in questa istanza. Si potrebbe creare una query SQL per restituire una singola voce (`SELECT * from b where b.ID = id`). Tale query restituirebbe in effetti un documento, ma lo restituirebbe in una raccolta di documenti. Il codice dovrebbe modificare una raccolta senza necessità. Usare l'approccio basato sulle query SQL quando si vuole ottenere più documenti.

Per spiegare il motivo per cui vengono usate queste impostazioni, si vuole cercare un segnalibro con un ID specifico, quindi l'ID documento ricevuto dalla funzione nella stringa di query è stato collegato all'associazione. Questa sintassi è 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. Poiché gli ID sono univoci nella raccolta, l'associazione restituirà 0 documenti (non trovato) o 1 documento (trovato).

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

Aggiornare l'implementazione della funzione

Ora che l'associazione è stata definita, è possibile usarla nella funzione. Per implementare l'associazione appena creata, è necessario apportare due modifiche:

Modificare il codice di implementazione specifico del linguaggio della funzione per determinare se nel database è stato trovato un documento corrispondente all'ID passato alla funzione.
Modificare il codice di implementazione JSON della funzione in modo che accetti un parametro passato nella stringa di query.

Modificare il codice di implementazione JavaScript della funzione

Nel menu Funzione per la funzione HttpTrigger2 selezionare Codice e test. Viene visualizzato il riquadro Codice e test per la funzione HttpTrigger2.

Sostituire tutto il codice nel file index.js con il codice seguente.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

Sulla barra dei comandi selezionare Salva. Selezionare Log del file system nell'elenco a discesa nella parte superiore centrale del riquadro dei log, che visualizza i log di App Insights per impostazione predefinita. Viene visualizzato il riquadro Log che mostra il messaggio Connected!

Si esaminerà ora il risultato di questo codice.

Una richiesta HTTP in ingresso attiva la funzione e un parametro di query id viene passato all'associazione di input di Azure Cosmos DB.
Se nel database viene trovato un documento corrispondente a questo ID, il parametro bookmark viene impostato sul documento trovato.

In questo esempio il codice costruisce una risposta che contiene il valore dell'URL presente nel documento corrispondente del database.
Se non vengono trovati documenti corrispondenti a questa chiave, la richiesta risponde con un payload e un codice di stato che comunica all'utente la cattiva notizia.

Modificare il codice di implementazione JSON della funzione

Selezionare function.json dall'elenco a discesa nel <functionapp> \ HttpTrigger2 \ percorso.

Sostituire tutto il codice nel file function.json con il codice seguente. Assicurarsi e sostituire your-database con il nome dell'account Azure Cosmos DB.

{
  "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}",
    }
  ]
}

Sulla barra dei comandi selezionare Salva.

Modificare il codice di implementazione PowerShell della funzione

Nel menu Funzione per la funzione HttpTrigger2 selezionare Codice e test. Viene visualizzato il riquadro Codice e test per la funzione HttpTrigger2 che mostra il file run.ps1.

Sostituire tutto il codice nel file run.ps1 con il codice seguente.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

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

Sulla barra dei comandi selezionare Salva. Selezionare Log del file system nell'elenco a discesa nella parte superiore centrale del riquadro dei log, che visualizza i log di App Insights per impostazione predefinita. Viene visualizzato il riquadro Log che mostra il messaggio Connected!

Si esaminerà ora il risultato di questo codice.

Una richiesta HTTP in ingresso attiva la funzione e un parametro di query id viene passato all'associazione di input di Azure Cosmos DB.
Se nel database viene trovato un documento corrispondente a questo ID, il parametro bookmark viene impostato sul documento trovato.

In questo esempio il codice costruisce una risposta che contiene il valore dell'URL presente nel documento corrispondente del database.
Se non vengono trovati documenti corrispondenti a questa chiave, la richiesta risponde con un payload e un codice di stato che comunica all'utente la cattiva notizia.

Modificare il codice di implementazione JSON della funzione

Selezionare function.json dall'elenco a discesa nel <functionapp> \ HttpTrigger2 \ percorso.

Modificare i valori per id e partitionKey in modo che accettino un parametro {id}. Il codice function.json dovrebbe essere simile all'esempio seguente, dove your-database viene sostituito con il nome del database di Cosmos DB.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

Sulla barra dei comandi selezionare Salva.

Provala

Si dovrebbe già essere nel riquadro Codice e test per la funzione HttpTrigger2.
Nella barra dei comandi selezionare Recupera URL della funzione. Verrà visualizzata la finestra di dialogo Recupera URL della funzione.
Nell'elenco a discesa Chiave selezionare predefinito in Tasto funzione e quindi selezionare l'icona Copia negli Appunti alla fine dell'URL.
Incollare la chiave della funzione copiata nella barra degli indirizzi di una nuova scheda del browser e quindi aggiungere il valore &id=docs della stringa di query alla fine dell'URL. L'URL risultante sarà simile a quello nell'esempio seguente:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Per eseguire la richiesta, premere INVIO. La risposta restituita dalla funzione dovrebbe essere simile a quella nell'esempio seguente.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Sostituire &id=docs con &id=missing, premere INVIO e osservare la risposta. Sono stati definiti cinque segnalibri ed è stata creata una risposta di errore significativa se il segnalibro richiesto non esiste.

In questa unità è stata creata manualmente la prima associazione di input per leggere da un database di Azure Cosmos DB. Grazie alle associazioni, la quantità di codice che è stato necessario scrivere per eseguire una ricerca nel database e leggere i dati è stata minima. La maggior parte del lavoro è stata finalizzata alla configurazione dichiarativa dell'associazione, mentre la piattaforma ha eseguito le altre operazioni.

Nell'unità successiva si aggiungeranno altri dati alla raccolta di segnalibri tramite un'associazione di output di Azure Cosmos DB.

Esercizio - Leggere dati con associazioni di input

Creare un account Azure Cosmos DB

Creare un account di database

Aggiungere un contenitore

Aggiungere i dati del test

Creare una funzione

Verificare la funzione

Aggiungere un'associazione di input di Azure Cosmos DB

Aggiornare l'implementazione della funzione

Modificare il codice di implementazione JavaScript della funzione

Modificare il codice di implementazione JSON della funzione

Modificare il codice di implementazione PowerShell della funzione

Modificare il codice di implementazione JSON della funzione

Provala

Commenti e suggerimenti