Azure Cosmos DB: Creare un'app Web con .NET, Xamarin e l'autenticazione di Facebook

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft. È possibile creare ed eseguire rapidamente query su database di documenti, coppie chiave/valore e grafi, sfruttando in ognuno dei casi i vantaggi offerti dalle funzionalità di scalabilità orizzontale e distribuzione globale alla base di Azure Cosmos DB.

Questa guida di avvio rapido mostra come creare un account, un database di documenti e una raccolta di Azure Cosmos DB tramite il portale di Azure. Si creerà e distribuirà quindi l'app Web elenco attività basata sull'API .NET DocumentDB, su Xamarin, e sul motore di autorizzazione di Azure Cosmos DB. L'app Web elenco attività implementa un modello di dati per utente che permette agli utenti di accedere tramite l'autenticazione di Facebook e gestire le proprie attività.

Prerequisiti

Se Visual Studio 2017 non è ancora installato, è possibile scaricare e usare la versione gratuita Visual Studio 2017 Community Edition. Durante l'installazione di Visual Studio abilitare Sviluppo di Azure.

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

Creare un account di database

  1. In una nuova finestra accedere al portale di Azure.
  2. Nel riquadro a sinistra fare clic su Nuovo, quindi su Database e infine su Azure Cosmos DB.

    Riquadro Database nel portale di Azure

  3. Nel pannello Nuovo account specificare la configurazione desiderata per l'account Azure Cosmos DB.

    Con Azure Cosmos DB è possibile scegliere uno dei quattro modelli di programmazione: Gremlin (graph), MongoDB, SQL (DocumentDB) e Table (key-value).

    In questa guida introduttiva viene eseguita la programmazione in base all'API di DocumentDB, quindi scegliere SQL (DocumentDB) quando si compila il modulo. Se si hanno tuttavia dati di grafi di un'app di social media, dati chiave/valore (tabella) o dati di cui è stata eseguita la migrazione da un'app MongoDB, tenere presente che Azure Cosmos DB può fornire una piattaforma di servizi di database con distribuzione a livello globale e a disponibilità elevata per tutte le applicazioni cruciali.

    Completare i campi nel pannello Nuovo account usando le informazioni riportate nello screenshot seguente come guida. Quando si configura l'account scegliere valori univoci, non corrispondenti a quelli dello screenshot.

    Nuovo pannello di Azure Cosmos DB

    Impostazione Valore consigliato Descrizione
    ID Valore univoco Nome univoco che identifica l'account Azure Cosmos DB. Poiché alI'ID fornito viene aggiunta la stringa documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile. L'ID può contenere solo lettere minuscole, numeri e il segno meno (-) e deve avere una lunghezza compresa tra 3 e 50 caratteri.
    API SQL (DocumentDB) La programmazione in base all'API di DocumentDB verrà eseguita più avanti in questo articolo.
    Sottoscrizione Sottoscrizione in uso Sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
    Gruppo di risorse Stesso valore di ID Nome del nuovo gruppo di risorse per l'account. Per semplicità si può usare lo stesso nome usato come ID.
    Località Area più vicina ai propri utenti Posizione geografica in cui ospitare l'account Azure Cosmos DB. Scegliere la posizione più vicina agli utenti, per offrire loro l'accesso più rapido possibile ai dati.
  4. Fare clic su Crea per creare l'account.
  5. Nella barra degli strumenti superiore fare clic su Notifiche per monitorare il processo di distribuzione.

    Riquadro Notifiche del portale di Azure

  6. Al termine della distribuzione, aprire il nuovo account dal riquadro Tutte le risorse.

    Account DocumentDB nel riquadro Tutte le risorse

Aggiungere una raccolta

È ora possibile usare Esplora dati per creare una raccolta e aggiungere dati al database.

  1. Nel menu di navigazione a sinistra del portale di Azure fare clic su Esplora dati (anteprima).

  2. Nel pannello Esplora dati (anteprima) fare clic su Nuova raccolta e quindi specificare le informazioni seguenti:

    Pannello Esplora dati nel portale di Azure

    Impostazione Valore consigliato Descrizione
    ID database Attività ID del nuovo database. I nomi dei database devono avere una lunghezza compresa tra 1 e 255 caratteri e non possono contenere /, \, #, ? o spazi finali.
    ID raccolta Items ID della nuova raccolta. I nomi delle raccolte prevedono requisiti per i caratteri uguali a quelli degli ID dei database.
    Capacità di archiviazione Fissa (10 GB) Usare il valore predefinito. Indica la capacità di archiviazione del database.
    Velocità effettiva 400 UR Usare il valore predefinito. Se si vuole ridurre la latenza, è possibile aumentare la velocità effettiva in un secondo momento.
    UR/min Off Lasciare il valore predefinito. Se in seguito sarà necessario gestire carichi di lavoro di picco, sarà possibile attivare la funzionalità UR/min al momento.
    Chiave di partizione /category Chiave di partizione che distribuisce i dati in modo uniforme a ogni partizione. Quando si crea una raccolta ad alte prestazioni è importante selezionare la chiave di partizione corretta. Per altre informazioni, vedere Progettazione per il partizionamento.
  3. Dopo aver completato il modulo, fare clic su OK.

Clonare l'applicazione di esempio

Clonare ora un'app per le API DocumentDB da GitHub, impostare la stringa di connessione ed eseguirla. Come si noterà, è facile usare i dati a livello di codice.

  1. Aprire una finestra del terminale Git, ad esempio Git Bash, ed eseguire il comando cd per passare a una directory di lavoro.

  2. Eseguire il comando seguente per clonare l'archivio di esempio.

    git clone https://github.com/Azure/azure-documentdb-dotnet.git
    
  3. Aprire quindi il file DocumentDBTodo.sln dalla cartella samples/xamarin/UserItems/xamarin.forms in Visual Studio.

Esaminare il codice

Il codice nella cartella di Xamarin contiene:

  • App Xamarin. L'app archivia le attività dell'utente in una raccolta partizionata chiamata UserItems.
  • API del gestore di token di risorsa. Semplice API Web ASP.NET per la gestione dei token di risorsa di Azure Cosmos DB per gli utenti connessi dell'app. I token di risorsa sono token di accesso di breve durata che forniscono all'app l'accesso ai dati dell'utente connesso.

L'autenticazione e il flusso di dati vengono mostrati nel diagramma seguente.

  • La raccolta UserItems viene creata con la chiave di partizione '/userid'. Specificando una chiave di partizione per una raccolta, Azure Cosmos DB può ridimensionarsi in modo illimitato in base all'aumentare del numero di utenti ed elementi.
  • L'app Xamarin permette agli utenti di accedere con le credenziali di Facebook.
  • L'app Xamarin usa il token di accesso di Facebook per l'autenticazione con l'API ResourceTokenBroker
  • L'API del gestore di token di risorsa autentica la richiesta tramite la funzionalità Autenticazione servizio app e richiede un token di risorsa di Azure Cosmos DB con accesso in lettura/scrittura a tutti i documenti che condividono la chiave di partizione dell'utente autenticato.
  • Il gestore di token di risorsa restituisce il token di risorsa all'app client.
  • L'app accede alle attività dell'utente usando il token di risorsa.

App elenco attività con dati di esempio

Aggiornare la stringa di connessione

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app.

  1. Nell'account Azure Cosmos DB nel portale di Azure fare clic su Chiavi nel riquadro di spostamento a sinistra e quindi su Chiavi di lettura/scrittura. Usare i pulsanti di copia sul lato destro dello schermo per copiare l'URI e la chiave primaria nel file Web.config nel passaggio seguente.

    Visualizzazione e copia di una chiave di accesso nel portale di Azure, pannello Chiavi

  2. In Visual Studio 2017 aprire il file Web.config nella cartella azure-documentdb-dotnet/samples/xamarin/UserItems/ResourceTokenBroker/ResourceTokenBroker.

  3. Copiare il valore di URI dal portale (usando il pulsante di copia) e impostarlo come valore di accountUrl in Web.config.

    <add key="accountUrl" value="{Azure Cosmos DB account URL}"/>

  4. Copiare quindi il valore di CHIAVE PRIMARIA dal portale e impostarlo come valore di accountKey in Web.config.

    <add key="accountKey" value="{Azure Cosmos DB secret}"/>

L'app è stata aggiornata con tutte le informazioni necessarie per comunicare con Azure Cosmos DB.

Creare e distribuire l'app Web

  1. Nel portale di Azure creare il sito Web di un servizio app per ospitare l'API del gestore di token di risorsa.
  2. Nel portale di Azure aprire il pannello Impostazioni app del sito Web dell'API del gestore di token di risorsa. Immettere le impostazioni dell'app seguenti:

    • accountUrl: URL dell'account Azure Cosmos DB impostato nella scheda Chiavi dell'account Azure Cosmos DB.
    • accountKey: chiave master dell'account Azure Cosmos DB impostato nella scheda Chiavi dell'account Azure Cosmos DB.
    • Valori di databaseId e collectionId del database e della raccolta creati
  3. Pubblicare la soluzione ResourceTokenBroker nel sito Web creato.

  4. Aprire il progetto Xamarin e passare a TodoItemManager.cs. Immettere i valori per accountURL, collectionId, databaseId, nonché per resourceTokenBrokerURL come URL HTTPS di base per il sito Web del gestore di token di risorsa.

  5. Completare l'esercitazione Come configurare un'applicazione del servizio App per usare l'account di accesso di Facebook per configurare l'autenticazione di Facebook e il sito Web ResourceTokenBroker.

    Eseguire l'app Xamarin.

Esaminare i contratti di servizio nel portale di Azure

Ora che l'app è operativa, è opportuno garantire la continuità aziendale e controllare l'accesso degli utenti per garantire disponibilità elevata. Per esaminare la disponibilità, la latenza, la velocità effettiva e la coerenza della raccolta, si può usare il portale di Azure.

Ogni grafo associato ai contratti di servizio per Azure Cosmos DB fornisce una linea che mostra la quota necessaria per soddisfare il contratto di servizio e l'utilizzo effettivo, per garantire informazioni chiare sulle prestazioni del database. Nel portale sono anche incluse altre metriche, ad esempio per quanto riguarda l'uso dello spazio di archiviazione e il numero di richieste al minuto.

  • Nel riquadro a sinistra del portale di Azure, in Monitoraggio, fare clic su Metriche.

    App Todo con dati di esempio

Pulire le risorse

Se non si intende continuare a usare l'app, eliminare tutte le risorse create tramite questa guida di avvio rapido nel portale di Azure eseguendo questi passaggi:

  1. Scegliere Gruppi di risorse dal menu a sinistra del portale di Azure e quindi fare clic sul nome della risorsa appena creata.
  2. Nella pagina del gruppo di risorse fare clic su Elimina, digitare il nome della risorsa da eliminare nella casella di testo e quindi fare clic su Elimina.

Passaggi successivi

In questa guida di avvio rapido si è appreso come creare un account Azure Cosmos DB, come creare una raccolta con Esplora dati e come creare e distribuire un'app Xamarin. È ora possibile importare dati aggiuntivi nell'account Cosmos DB.