Archiviare dati non strutturati usando Funzioni di Azure e Azure Cosmos DBStore unstructured data using Azure Functions and Azure Cosmos DB

Azure Cosmos DB offre un approccio ottimale per archiviare dati non strutturati e JSON.Azure Cosmos DB is a great way to store unstructured and JSON data. Insieme a Funzioni di Azure, Cosmos DB semplifica e velocizza l'archiviazione dei dati con una quantità minore di codice rispetto a quella necessaria per l'archiviazione dei dati in un database relazionale.Combined with Azure Functions, Cosmos DB makes storing data quick and easy with much less code than required for storing data in a relational database.

Nota

Al momento, il trigger e le associazioni di input e output di Azure Cosmos DB funzionano solo con gli account API SQL e API Graph.At this time, the Azure Cosmos DB trigger, input bindings, and output bindings work with SQL API and Graph API accounts only.

In Funzioni di Azure, i binding di input e di output forniscono una modalità dichiarativa per connettersi a dati di servizio esterni dalla funzione.In Azure Functions, input and output bindings provide a declarative way to connect to external service data from your function. Questo articolo illustra come aggiornare una funzione esistente per l'aggiunta di un binding di output che archivia dati non strutturati in un documento di Azure Cosmos DB.In this article, learn how to update an existing function to add an output binding that stores unstructured data in an Azure Cosmos DB document.

PrerequisitiPrerequisites

Per completare questa esercitazione:To complete this tutorial:

Questo argomento usa per iniziare le risorse create in Creare la prima funzione nel portale di Azure.This topic uses as its starting point the resources created in Create your first function from the Azure portal. Se queste procedure non sono state ancora completate, completarle ora per creare l'app per le funzioni.If you haven't already done so, please complete these steps now to create your function app.

Creare un account Azure Cosmos DBCreate an Azure Cosmos DB account

Prima di creare il binding di output è necessario un account Azure Cosmos DB che usa l'API SQL.You must have an Azure Cosmos DB account that uses the SQL API before you create the output binding.

  1. Nel menu del portale di Azure o dalla pagina Home selezionare Crea una risorsa.From the Azure portal menu or the Home page, select Create a resource.

  2. Nella pagina Nuovo cercare e selezionare Azure Cosmos DB.On the New page, search for and select Azure Cosmos DB.

  3. Nella pagina Azure Cosmos DB selezionare Crea.On the Azure Cosmos DB page, select Create.

  4. Nella pagina Crea account Cosmos DB immettere le impostazioni base per il nuovo account Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ImpostazioneSetting ValoreValue DescrizioneDescription
    SubscriptionSubscription Nome sottoscrizioneSubscription name Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Gruppo di risorseResource Group Nome del gruppo di risorseResource group name Selezionare un gruppo di risorse oppure fare clic su Crea nuovo, quindi immettere un nome univoco per il nuovo gruppo di risorse.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome accountAccount Name Un nome univocoA unique name Immettere un nome per identificare l'account Azure Cosmos.Enter a name to identify your Azure Cosmos account. Dato che al nome specificato viene aggiunto documents.azure.com per creare l'URI, usare un nome univoco.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    Il nome può contenere solo lettere minuscole, numeri e il segno meno (-).The name can only contain lowercase letters, numbers, and the hyphen (-) character. Deve avere una lunghezza compresa tra 3 e 44 caratteri.It must be between 3-44 characters in length.
    APIAPI Il tipo di account da creareThe type of account to create Selezionare Core (SQL) per creare un database di documenti e una query con la sintassi SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    L'API determina il tipo di account da creare.The API determines the type of account to create. Azure Cosmos DB offre cinque API: Core (SQL) e MongoDB per dati dei documenti, Gremlin per i dati dei grafici, Tabelle di Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Attualmente, è necessario creare un account separato per ogni API.Currently, you must create a separate account for each API.
    Modalità di capacitàCapacity mode Provisioning velocità effettiva o ServerlessProvisioned throughput or Serverless Selezionare Provisioning velocità effettiva per creare un account in modalità Provisioning velocità effettiva.Select Provisioned throughput to create an account in provisioned throughput mode. Selezionare Serverless per creare un account in modalità Serverless.Select Serverless to create an account in serverless mode.
    Applica sconto per il livello gratuitoApply Free Tier Discount Applica o Non applicareApply or Do not apply Azure Cosmos DB livello gratuito offre i primi 400 UR/s e 5 GB di spazio di archiviazione gratuiti per account.With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Altre informazioni sul livello gratuito.Learn more about free tier.
    LocationLocation Area più vicina ai propri utentiThe region closest to your users Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.Use the location that is closest to your users to give them the fastest access to the data.
    Tipo di accountAccount Type Produzione o Non di produzioneProduction or Non-Production Selezionare Produzione se l'account verrà usato per un carico di lavoro di produzione.Select Production if the account will be used for a production workload. Selezionare Non di produzione se l'account non verrà usato per un carico di lavoro di produzione, ad esempio per lo sviluppo, il test, il controllo di qualità o lo staging.Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. Si tratta di un'impostazione di tag delle risorse di Azure che consente di ottimizzare l'esperienza del portale, ma non influisce sull'account Azure Cosmos DB sottostante.This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. È possibile modificare questo valore in qualsiasi momento.You can change this value anytime.

    Nota

    È possibile avere fino a un account Azure Cosmos DB del livello gratuito per ogni sottoscrizione di Azure ed è necessario acconsentire esplicitamente durante la creazione dell'account.You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. Se l'opzione per l'applicazione dello sconto per il livello gratuito non è visualizzata, un altro account nella sottoscrizione è già stato abilitato per il livello gratuito.If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

    Nota

    Le opzioni seguenti non sono disponibili se si seleziona Serverless come modalità di capacità:The following options are not available if you select Serverless as the Capacity mode:

    • Applica sconto per il livello gratuitoApply Free Tier Discount
    • Ridondanza geograficaGeo-redundancy
    • Scritture in più areeMulti-region Writes

    Pagina del nuovo account per Azure Cosmos DB

  5. Selezionare Rivedi e crea.Select Review + create. È possibile ignorare le sezioni Rete e Tag.You can skip the Network and Tags sections.

  6. Esaminare le impostazioni dell'account e quindi selezionare Crea.Review the account settings, and then select Create. La creazione dell'account richiede alcuni minuti.It takes a few minutes to create the account. Attendere che la pagina del portale visualizzi La distribuzione è stata completata.Wait for the portal page to display Your deployment is complete.

    Riquadro Notifiche del portale di Azure

  7. Selezionare Vai alla risorsa per passare alla pagina dell'account Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    Pagina dell'account Azure Cosmos DB

Aggiungere un binding di outputAdd an output binding

  1. Nel portale di Azure passare all'app per le funzioni creata in precedenza e selezionarla.In the Azure portal, navigate to and select the function app you created previously.

  2. Selezionare Funzioni e quindi selezionare la funzione HttpTrigger.Select Functions, and then select the HttpTrigger function.

    Selezionare la funzione HTTP nel portale di Azure.

  3. Selezionare Integrazione e + Aggiungi output.Select Integration and + Add output.

    Aggiungere un binding di output di Azure Cosmos DB.

  4. Usare le impostazioni di Crea output come specificato nella tabella:Use the Create Output settings as specified in the table:

    Configurare il binding di output di Azure Cosmos DB.

    ImpostazioneSetting Valore consigliatoSuggested value DescrizioneDescription
    Tipo di bindingBinding Type Azure Cosmos DBAzure Cosmos DB Nome del tipo di binding da selezionare per creare il binding di output per Azure Cosmos DB.Name of the binding type to select to create the output binding to Azure Cosmos DB.
    Nome del parametro del documentoDocument parameter name taskDocumenttaskDocument Nome che fa riferimento all'oggetto Cosmos DB nel codice.Name that refers to the Cosmos DB object in code.
    Nome databaseDatabase name taskDatabasetaskDatabase Nome del database per il salvataggio dei documenti.Name of database to save documents.
    Nome raccoltaCollection name taskCollectiontaskCollection Nome della raccolta di database.Name of the database collection.
    Se true, crea il database e la raccolta di Cosmos DBIf true, creates the Cosmos DB database and collection Yes La raccolta non esiste ancora, quindi crearla.The collection doesn't already exist, so create it.
    Connessione all'account Cosmos DBCosmos DB account connection Nuova impostazioneNew setting Selezionare Nuovo, scegliere Account Azure Cosmos DB e l'account di database creato in precedenza, quindi selezionare OK.Select New, then choose Azure Cosmos DB Account and the Database account you created earlier, and then select OK. Viene creata un'impostazione applicazione per la connessione all'account.Creates an application setting for your account connection. Questa impostazione viene usata dal binding per la connessione al database.This setting is used by the binding to connection to the database.
  5. Selezionare OK per creare il binding.Select OK to create the binding.

Aggiornare il codice funzioneUpdate the function code

Sostituire il codice della funzione esistente con quello seguente nel linguaggio scelto:Replace the existing function code with the following code, in your chosen language:

Sostituire la funzione C# esistente con il codice seguente:Replace the existing C# function with the following code:

#r "Newtonsoft.Json"

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

public static IActionResult Run(HttpRequest req, out object taskDocument, ILogger log)
{
    string name = req.Query["name"];
    string task = req.Query["task"];
    string duedate = req.Query["duedate"];

    // We need both name and task parameters.
    if (!string.IsNullOrEmpty(name) && !string.IsNullOrEmpty(task))
    {
        taskDocument = new
        {
            name,
            duedate,
            task
        };

        return (ActionResult)new OkResult();
    }
    else
    {
        taskDocument = null;
        return (ActionResult)new BadRequestResult();
    }
}

Questo esempio di codice legge le stringhe della query di richiesta HTTP e le assegna ai campi dell'oggetto taskDocument.This code sample reads the HTTP Request query strings and assigns them to fields in the taskDocument object. Il binding taskDocument invia i dati dell'oggetto di questo parametro di binding per l'archiviazione nel database di documenti associato.The taskDocument binding sends the object data from this binding parameter to be stored in the bound document database. Il database viene creato alla prima esecuzione della funzione.The database is created the first time the function runs.

Testare la funzione e il databaseTest the function and database

  1. Selezionare Test/Esegui.Select Test/Run. In Query selezionare + Aggiungi parametro e aggiungere i parametri seguenti alla stringa di query:Under Query, select + Add parameter and add the following parameters to the query string:

    • name
    • task
    • duedate

    Testare la funzione.

  2. Selezionare Esegui e verificare che venga restituito uno stato 200.Select Run and verify that a 200 status is returned.

    Screenshot dello stato 200 del codice di risposta HTTP evidenziato dopo la selezione di Esegui.

  3. Nel portale di Azure cercare e selezionare Azure Cosmos DB.In the Azure portal, search for and select Azure Cosmos DB.

    Cercare il servizio Cosmos DB.

  4. Scegliere l'account Azure Cosmos DB, quindi selezionare Esplora dati.Choose your Azure Cosmos DB account, then select Data Explorer.

  5. Espandere i nodi TaskCollection, selezionare il nuovo documento e verificare che contenga i valori della stringa di query, oltre ad alcuni metadati aggiuntivi.Expand the TaskCollection nodes, select the new document, and confirm that the document contains your query string values, along with some additional metadata.

    Verificare i valori di stringa nel documento.

È stato aggiunto un binding al trigger HTTP per archiviare dati non strutturati in un'istanza di Azure Cosmos DB.You've successfully added a binding to your HTTP trigger to store unstructured data in an Azure Cosmos DB.

Pulire le risorseClean up resources

Nei passaggi precedenti sono state create risorse di Azure in un gruppo di risorse.In the preceding steps, you created Azure resources in a resource group. Se non si prevede di aver bisogno di queste risorse in futuro, è possibile eliminarle eliminando il gruppo di risorse.If you don't expect to need these resources in the future, you can delete them by deleting the resource group.

Nel menu del portale di Azure o nella pagina Home selezionare Gruppi di risorse.From the Azure portal menu or Home page, select Resource groups. Quindi, nella pagina Gruppi di risorse selezionare myResourceGroup.Then, on the Resource groups page, select myResourceGroup.

Nella pagina myResourceGroup assicurarsi che le risorse elencate siano quelle da eliminare.On the myResourceGroup page, make sure that the listed resources are the ones you want to delete.

Selezionare Elimina gruppo di risorse, digitare myResourceGroup nella casella di testo per confermare e quindi selezionare Elimina.Select Delete resource group, type myResourceGroup in the text box to confirm, and then select Delete.

Passaggi successiviNext steps

Per altre informazioni sul binding a un database Cosmos DB, vedere Binding di Azure Cosmos DB in Funzioni di Azure.For more information about binding to a Cosmos DB database, see Azure Functions Cosmos DB bindings.