Esercitazione su NoSQL: Compilare un'applicazione console Java con l'API di DocumentDBNoSQL tutorial: Build a DocumentDB API Java console application

Esercitazione su NoSQL per l'API di DocumentDB per Azure Cosmos DB Java SDK.Welcome to the NoSQL tutorial for the DocumentDB API for Azure Cosmos DB Java SDK! Dopo aver seguito questa esercitazione, si otterrà un'applicazione console che consente di creare e ridefinire le query delle risorse Azure Cosmos DB.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources.

Argomenti trattati:We cover:

  • Creazione e connessione a un account Azure Cosmos DBCreating and connecting to an Azure Cosmos DB account
  • Configurare una soluzione Visual StudioConfiguring your Visual Studio Solution
  • Creazione di un database onlineCreating an online database
  • Creare una raccoltaCreating a collection
  • Creazione di documenti JSONCreating JSON documents
  • Esecuzione di query sulla raccoltaQuerying the collection
  • Creazione di documenti JSONCreating JSON documents
  • Esecuzione di query sulla raccoltaQuerying the collection
  • Sostituzione di un documentoReplacing a document
  • Eliminazione di un documentoDeleting a document
  • Eliminazione del databaseDeleting the database

Ecco come procedere.Now let's get started!

PrerequisitiPrerequisites

Assicurarsi che sia disponibile quanto segue:Make sure you have the following:

Passaggio 1: Creare un account di Azure Cosmos DBStep 1: Create an Azure Cosmos DB account

Creare prima di tutto un account Azure Cosmos DB.Let's create an Azure Cosmos DB account. Se è già disponibile un account da usare, è possibile andare direttamente al passaggio Clonare il progetto GitHub.If you already have an account you want to use, you can skip ahead to Clone the GitHub project. Se si usa l'emulatore Azure Cosmos DB, seguire la procedura illustrata nell'articolo relativo all'emulatore Azure Cosmos DB per configurare l'emulatore e proseguire con il passaggio Clonare il progetto GitHub.If you are using the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to set up the emulator and skip ahead to Clone the GitHub project.

  1. In una nuova finestra del browser accedere al portale di Azure.In a new browser window, sign in to the Azure portal.
  2. Fare clic su Nuovo > Database > Azure Cosmos DB.Click New > Databases > Azure Cosmos DB.

    Riquadro Database nel portale di Azure

  3. Nella pagina Nuovo account immettere le impostazioni per il nuovo account Azure Cosmos DB.In the New account page, enter the settings for the new Azure Cosmos DB account.

    ImpostazioneSetting Valore consigliatoSuggested value DescrizioneDescription
    IDID Immettere un nome univocoEnter a unique name Immettere un nome univoco per identificare l'account Azure Cosmos DB.Enter a unique name to identify this Azure Cosmos DB account. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique but identifiable ID.

    L'ID può contenere solo lettere minuscole, numeri e il segno meno (-) e deve avere una lunghezza compresa tra 3 e 50 caratteri.The ID can contain only lowercase letters, numbers, and the hyphen (-) character, and it must contain 3 to 50 characters.
    APIAPI SQLSQL L'API determina il tipo di account da creare.The API determines the type of account to create. Azure Cosmos DB offre cinque API per soddisfare le esigenze dell'applicazione, ovvero SQL (database di documenti) Gremlin (grafo), MongoDB, SQL (database di documenti), Tabella di Azure e Cassandra, per ognuna delle quali è attualmente necessario un account separato.Azure Cosmos DB provides five APIs to suits the needs of your application: SQL (document database), Gremlin (graph database), MongoDB (document database), Azure Table, and Cassandra, each which currently require a separate account.

    Selezionare SQL perché in questo avvio rapido si sta creando un database di documenti su cui è possibile eseguire query tramite la sintassi SQL e a cui è possibile accedere tramite l'API DocumentDB.Select SQL because in this quickstart you are creating a document database that is queryable using SQL syntax and accessible with the DocumentDB API.

    Altre informazioni sull'API di DocumentDBLearn more about the DocumentDB API
    SottoscrizioneSubscription Sottoscrizione in usoYour subscription Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos DB.Select Azure subscription that you want to use for this Azure Cosmos DB account.
    Gruppo di risorseResource Group Creare un nuovo gruppo di risorseCreate new

    Immettere quindi lo stesso nome univoco specificato sopra in IDThen enter the same unique name as provided above in ID
    Selezionare Crea nuovo, quindi immettere il nome di un nuovo gruppo di risorse per l'account.Select Create New, then enter a new resource-group name for your account. Per semplicità si può usare lo stesso nome usato come ID.For simplicity, you can use the same name as your ID.
    PercorsoLocation Selezionare l'area più vicina agli utentiSelect the region closest to your users Selezionare la posizione geografica in cui ospitare l'account Azure Cosmos DB.Select geographic location in which 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's closest to your users to give them the fastest access to the data.
    Abilita ridondanza geograficaEnable geo-redundancy Lasciare vuotoLeave blank Consente di creare una versione replicata del database in una seconda area abbinata.This creates a replicated version of your database in a second (paired) region. Lasciare vuoto.Leave this blank.
    Aggiungi al dashboardPin to dashboard SelezionareSelect Selezionare questa casella per aggiungere il nuovo account di database al dashboard del portale e accedervi più facilmente.Select this box so that your new database account is added to your portal dashboard for easy access.

    Fare quindi clic su Crea.Then click Create.

    Pannello Nuovo account per Azure Cosmos DB

  4. La creazione dell'account richiede alcuni minuti,The account creation takes a few minutes. Durante la creazione dell'account il portale visualizza il riquadro Deploying Azure Cosmos DB (Distribuzione di Azure Cosmos DB) a destra, quindi potrebbe essere necessario scorrere a destra del dashboard per visualizzare il riquadro.During account creation the portal displays the Deploying Azure Cosmos DB tile on the right side, you may need to scroll right on your dashboard to see the tile. È presente anche un indicatore di stato nella parte superiore della schermata.There is also a progress bar displayed near the top of the screen. È possibile esaminare lo stato di avanzamento nelle due aree.You can watch either area for progress.

    Riquadro Notifiche del portale di Azure

    Al termine della creazione dell'account verrà visualizzata la pagina L'account Azure Cosmos DB è stato creato.Once the account is created, the Congratulations! Your Azure Cosmos DB account was created page is displayed.

Passaggio 2: Clonare il progetto GitHubStep 2: Clone the GitHub project

Per iniziare, è possibile clonare il repository GitHub per l'introduzione ad Azure Cosmos DB e Java.You can get started by cloning the GitHub repository for Get Started with Azure Cosmos DB and Java. Eseguire questo comando da una directory locale per recuperare il progetto di esempio in locale.For example, from a local directory run the following to retrieve the sample project locally.

git clone git@github.com:Azure-Samples/azure-cosmos-db-documentdb-java-getting-started.git

cd azure-cosmos-db-documentdb-java-getting-started

La directory contiene un oggetto pom.xml per il progetto e una cartella src che contiene il codice sorgente Java incluso Program.java, che mostra come eseguire semplici operazioni con Azure Cosmos DB, come la creazione di documenti e l'esecuzione di query sui dati all'interno di una raccolta.The directory contains a pom.xml for the project and a src folder containing Java source code including Program.java which shows how perform simple operations with Azure Cosmos DB like creating documents and querying data within a collection. L'oggetto pom.xml include una dipendenza per DocumentDB Java SDK su Maven.The pom.xml includes a dependency on the DocumentDB Java SDK on Maven.

<dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-documentdb</artifactId>
    <version>LATEST</version>
</dependency>

Passaggio 3: Connettersi a un account Azure Cosmos DBStep 3: Connect to an Azure Cosmos DB account

Tornare al portale di Azure per recuperare l'endpoint e la chiave master primaria.Next, head back to the Azure Portal to retrieve your endpoint and primary master key. L'endpoint e la chiave primaria di Azure Cosmos DB sono necessari all'applicazione per conoscere la destinazione della connessione e ad Azure Cosmos DB per considerare attendibile la connessione dell'applicazione.The Azure Cosmos DB endpoint and primary key are necessary for your application to understand where to connect to, and for Azure Cosmos DB to trust your application's connection.

Nel portale di Azure passare all'account Azure Cosmos DB e quindi fare clic su Chiavi.In the Azure Portal, navigate to your Azure Cosmos DB account, and then click Keys. Copiare l'URI dal portale e incollarlo in https://FILLME.documents.azure.com nel file Program.java.Copy the URI from the portal and paste it into https://FILLME.documents.azure.com in the Program.java file. Copiare quindi la CHIAVE PRIMARIA dal portale e incollarla in FILLME.Then copy the PRIMARY KEY from the portal and paste it into FILLME.

this.client = new DocumentClient(
    "https://FILLME.documents.azure.com",
    "FILLME"
    , new ConnectionPolicy(),
    ConsistencyLevel.Session);

Screenshot del portale di Azure usato nell'esercitazione su NoSQL per creare un'applicazione console Java.

Passaggio 4: Creare un databaseStep 4: Create a database

È possibile creare un database di Azure Cosmos DB usando il metodo createDatabase della classe DocumentClient.Your Azure Cosmos DB database can be created by using the createDatabase method of the DocumentClient class. Un database è il contenitore logico per l'archiviazione di documenti JSON partizionato nelle raccolte.A database is the logical container of JSON document storage partitioned across collections.

Database database = new Database();
database.setId("familydb");
this.client.createDatabase(database, null);

Passaggio 5: Creare una raccoltaStep 5: Create a collection

Avviso

createCollection crea una nuova raccolta con velocità effettiva riservata, che presenta implicazioni in termini di prezzi.createCollection creates a new collection with reserved throughput, which has pricing implications. Per altre informazioni, visitare la pagina relativa ai prezzi.For more details, visit our pricing page.

È possibile creare una raccolta usando il metodo createCollection della classe DocumentClient.A collection can be created by using the createCollection method of the DocumentClient class. Una raccolta è un contenitore di documenti JSON e di logica dell'applicazione JavaScript associata.A collection is a container of JSON documents and associated JavaScript application logic.

DocumentCollection collectionInfo = new DocumentCollection();
collectionInfo.setId("familycoll");

// Azure Cosmos DB collections can be reserved with throughput specified in request units/second. 
// Here we create a collection with 400 RU/s.
RequestOptions requestOptions = new RequestOptions();
requestOptions.setOfferThroughput(400);

this.client.createCollection("/dbs/familydb", collectionInfo, requestOptions);

Passaggio 6: Creare documenti JSONStep 6: Create JSON documents

È possibile creare un documento usando il metodo createDocument della classe DocumentClient.A document can be created by using the createDocument method of the DocumentClient class. I documenti sono contenuto JSON definito dall'utente (arbitrario).Documents are user-defined (arbitrary) JSON content. Ora è possibile inserire uno o più documenti.We can now insert one or more documents. Se sono già disponibili dati da archiviare nel database, è possibile usare lo strumento di migrazione dei dati di Azure Cosmos DB per importare i dati in un database.If you already have data you'd like to store in your database, you can use Azure Cosmos DB's Data Migration tool to import the data into a database.

// Insert your Java objects as documents 
Family andersenFamily = new Family();
andersenFamily.setId("Andersen.1");
andersenFamily.setLastName("Andersen")

// More initialization skipped for brevity. You can have nested references
andersenFamily.setParents(new Parent[] { parent1, parent2 });
andersenFamily.setDistrict("WA5");
Address address = new Address();
address.setCity("Seattle");
address.setCounty("King");
address.setState("WA");

andersenFamily.setAddress(address);
andersenFamily.setRegistered(true);

this.client.createDocument("/dbs/familydb/colls/familycoll", family, new RequestOptions(), true);

Diagramma che illustra la relazione gerarchica tra l'account, il database online, la raccolta e i documenti usati nell'esercitazione su NoSQL per creare un'applicazione console Java

Passaggio 7: Eseguire query sulle risorse di Azure Cosmos DBStep 7: Query Azure Cosmos DB resources

Azure Cosmos DB supporta query complesse sui documenti JSON archiviati in ogni raccolta.Azure Cosmos DB supports rich queries against JSON documents stored in each collection. Il codice di esempio seguente mostra come eseguire query su documenti in Azure Cosmos DB usando la sintassi SQL con il metodo queryDocuments.The following sample code shows how to query documents in Azure Cosmos DB using SQL syntax with the queryDocuments method.

FeedResponse<Document> queryResults = this.client.queryDocuments(
    "/dbs/familydb/colls/familycoll",
    "SELECT * FROM Family WHERE Family.lastName = 'Andersen'", 
    null);

System.out.println("Running SQL query...");
for (Document family : queryResults.getQueryIterable()) {
    System.out.println(String.format("\tRead %s", family));
}

Passaggio 8: Sostituire un documento JSONStep 8: Replace JSON document

Azure Cosmos DB supporta l'aggiornamento di documenti JSON con il metodo replaceDocument.Azure Cosmos DB supports updating JSON documents using the replaceDocument method.

// Update a property
andersenFamily.Children[0].Grade = 6;

this.client.replaceDocument(
    "/dbs/familydb/colls/familycoll/docs/Andersen.1", 
    andersenFamily,
    null);

Passaggio 9: Eliminare un documento JSONStep 9: Delete JSON document

Analogamente, Azure Cosmos DB supporta l'eliminazione di documenti JSON con il metodo deleteDocument.Similarly, Azure Cosmos DB supports deleting JSON documents using the deleteDocument method.

this.client.delete("/dbs/familydb/colls/familycoll/docs/Andersen.1", null);

Passaggio 10: Eliminare il databaseStep 10: Delete the database

Se si elimina il database creato, insieme al database vengono rimosse tutte le risorse figlio, come raccolte, documenti e così via.Deleting the created database removes the database and all children resources (collections, documents, etc.).

this.client.deleteDatabase("/dbs/familydb", null);

Passaggio 11: Eseguire l'intera applicazione console JavaStep 11: Run your Java console application all together!

Per eseguire l'applicazione dalla console, passare alla cartella del progetto e compilare usando Maven:To run the application from the console, navigate to the project folder and compile using Maven:

mvn package

L'esecuzione di mvn package scarica la libreria di Azure Cosmos DB più recente da Maven e produce GetStarted-0.0.1-SNAPSHOT.jar.Running mvn package downloads the latest Azure Cosmos DB library from Maven and produces GetStarted-0.0.1-SNAPSHOT.jar. Eseguire l'app usando quanto segue:Then run the app by running:

mvn exec:java -D exec.mainClass=GetStarted.Program

Congratulazioni.Congratulations! L'esercitazione su NoSQL è stata completata ed è stata creata un'applicazione console Java funzionante.You've completed this NoSQL tutorial and have a working Java console application!

Passaggi successiviNext steps