Azure Cosmos DB: Esercitazione su un'applicazione console in C++ per l'API DocumentDB

Esercitazione su C++ per l'SDK per C++ approvato per l'API DocumentDB di Azure Cosmos DB Al termine di questa esercitazione, si otterrà un'applicazione console che consente di creare ed eseguire query sulle risorse di Azure Cosmos DB, incluso un database C++.

Tratteremo questo argomento:

  • Creazione e connessione a un account Azure Cosmos DB
  • Configurazione dell'applicazione
  • Creazione di un database Azure Cosmos DB in C++
  • Creare una raccolta
  • Creazione di documenti JSON
  • Esecuzione di query sulla raccolta
  • Sostituzione di un documento
  • Eliminazione di un documento
  • Eliminazione di un database Azure Cosmos DB in C++

Non si ha tempo? Nessun problema. La soluzione completa è disponibile in GitHub. Per istruzioni rapide, vedere ottenere la soluzione completa .

Dopo aver completato l'esercitazione su C++, usare i pulsanti di voto alla fine di questa pagina per fornire commenti e suggerimenti.

Se si desidera contattarci, è possibile includere il proprio indirizzo di posta elettronica nei commenti oppure scriverci qui.

Ecco come procedere.

Prerequisiti per l'esercitazione su C++

Assicurarsi di disporre di quanto segue:

Passaggio 1: Creare un account di Azure Cosmos DB

Creare prima di tutto un account Azure Cosmos DB. Se è già disponibile un account da usare, è possibile passare a Configurare un'applicazione C++.

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

    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 (grafo), MongoDB, SQL (DocumentDB) e Tabella (chiave/valore), ognuno dei quali attualmente richiede un account separato.

    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 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ò offrire 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. I valori effettivi potrebbero essere diversi.

    Pannello Nuovo account per Azure Cosmos DB

    Impostazione Valore consigliato Descrizione
    ID Valore univoco Nome univoco che identifica l'account Azure Cosmos DB. Poiché alI'ID fornito viene aggiunto 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 sull'icona delle notifiche icona delle notifiche per monitorare il processo di distribuzione.

    Riquadro Notifiche del portale di Azure

  6. Quando la finestra Notifiche indica che la distribuzione è stata completata, chiudere la finestra di notifica e aprire il nuovo account dal riquadro Tutte le risorse nel Dashboard.

    Account Azure Cosmos DB nel riquadro Tutte le risorse

Passaggio 2. Configurare un'applicazione C++

  1. Aprire Visual Studio, quindi nel menu File scegliere Nuovo, infine fare clic su Progetto.
  2. Nella finestra Nuovo progetto, nel riquadro Installato, espandere Visual C++, fare clic su Win32 e quindi su Applicazione console Win32. Denominare il progetto hellodocumentdb e quindi fare clic su OK.

    Screenshot della Creazione guidata nuovo progetto

  3. All'avvio della procedura di creazione guidata dell'applicazione Win32, scegliere Fine.
  4. Dopo aver creato il progetto, aprire Gestione pacchetti NuGet facendo clic con il pulsante destro del mouse sul progetto hellodocumentdb in Esplora soluzioni e quindi su Gestisci pacchetti NuGet.

    Screenshot di Gestisci pacchetti NuGet nel menu di progetto

  5. Nella scheda NuGet: hellodocumentdb fare clic su Sfoglia, quindi cercare documentdbcpp. Nei risultati selezionare DocumentDbCPP come illustrato nello screenshot seguente. Questo pacchetto installa i riferimenti all'SDK REST C++, da cui dipende DocumentDbCPP.

    Screenshot con evidenziato il pacchetto DocumentDbCpp

    Dopo aver aggiunto i pacchetti al progetto, è possibile iniziare a scrivere il codice.

Passaggio 3: Copiare dal portale di Azure i dettagli di connessione per il database di Azure Cosmos DB

Visualizzare il portale di Azure e accedere all'account database di Azure Cosmos DB creato. Nel prossimo passaggio sono necessari l'URI e la chiave primaria del Portale di Azure per stabilire una connessione dal frammento di codice C++.

Chiavi e URI di Azure Cosmos DB nel portale di Azure

Passaggio 4: Connettersi a un account Azure Cosmos DB

  1. Aggiungere i seguenti spazi dei nomi e intestazioni al codice sorgente, dopo #include "stdafx.h".

     #include <cpprest/json.h>
     #include <documentdbcpp\DocumentClient.h>
     #include <documentdbcpp\exceptions.h>
     #include <documentdbcpp\TriggerOperation.h>
     #include <documentdbcpp\TriggerType.h>
     using namespace documentdb;
     using namespace std;
     using namespace web::json;
    
  2. Aggiungere quindi il codice seguente alla funzione principale e sostituire la configurazione dell'account e la chiave primaria in modo che corrispondano alle impostazioni di Azure Cosmos DB del passaggio 3.

     DocumentDBConfiguration conf (L"<account_configuration_uri>", L"<primary_key>");
     DocumentClient client (conf);
    

    Ora che è disponibile il codice per inizializzare il client DocumentDB, è possibile esaminare l'uso delle risorse di Azure Cosmos DB.

Passaggio 5. Creare un database e una raccolta C++

Per coloro che hanno appena iniziato a usare Azure Cosmos DB, prima di eseguire questo passaggio verrà esaminata l'interazione tra database, raccolta e documenti. Un database è un contenitore logico di archiviazione documenti partizionato nelle raccolte. Una raccolta è un contenitore di documenti JSON e di logica dell'applicazione JavaScript associata. Per altre informazioni sui concetti e sul modello di risorse gerarchico di Azure Cosmos DB, vedere Modello di risorse gerarchico e concetti relativi ad Azure Cosmos DB.

Per creare un database con relativa raccolta, aggiungere il codice seguente alla fine della funzione principale. Verranno creati un database denominato 'FamilyRegistry' e una raccolta denominata 'FamilyCollection' tramite la configurazione del client dichiarata nel passaggio precedente.

try {
  shared_ptr<Database> db = client.CreateDatabase(L"FamilyRegistry");
  shared_ptr<Collection> coll = db->CreateCollection(L"FamilyCollection");
} catch (DocumentDBRuntimeException ex) {
  wcout << ex.message();
}

Passaggio 6. Creare un documento

I documenti corrispondono al contenuto JSON liberamente definito dall'utente. È ora possibile inserire un documento in Azure Cosmos DB. È possibile creare un documento copiando il codice seguente alla fine della funzione principale.

try {
  value document_family;
  document_family[L"id"] = value::string(L"AndersenFamily");
  document_family[L"FirstName"] = value::string(L"Thomas");
  document_family[L"LastName"] = value::string(L"Andersen");
  shared_ptr<Document> doc = coll->CreateDocumentAsync(document_family).get();

  document_family[L"id"] = value::string(L"WakefieldFamily");
  document_family[L"FirstName"] = value::string(L"Lucy");
  document_family[L"LastName"] = value::string(L"Wakefield");
  doc = coll->CreateDocumentAsync(document_family).get();
} catch (ResourceAlreadyExistsException ex) {
  wcout << ex.message();
}

Per riassumere, questo codice crea un database, una raccolta e i documenti di Azure Cosmos DB per l'esecuzione di query in Esplora documenti nel portale di Azure.

Esercitazione C++: diagramma che illustra la relazione gerarchica tra l'account, il database, la raccolta e i documenti

Passaggio 7: Eseguire query sulle risorse di Azure Cosmos DB

Azure Cosmos DB supporta query complesse sui documenti JSON archiviati in ogni raccolta. Il codice di esempio seguente mostra una query che usa la sintassi SQL e che può essere eseguita sui documenti creati nel passaggio precedente.

La funzione accetta come argomenti l'ID di risorsa o l'identificatore univoco per il database e la raccolta, oltre al client di documenti. Aggiungere questo codice prima della funzione principale.

void executesimplequery(const DocumentClient &client,
                        const wstring dbresourceid,
                        const wstring collresourceid) {
  try {
    client.GetDatabase(dbresourceid).get();
    shared_ptr<Database> db = client.GetDatabase(dbresourceid);
    shared_ptr<Collection> coll = db->GetCollection(collresourceid);
    wstring coll_name = coll->id();
    shared_ptr<DocumentIterator> iter =
        coll->QueryDocumentsAsync(wstring(L"SELECT * FROM " + coll_name)).get();
    wcout << "\n\nQuerying collection:";
    while (iter->HasMore()) {
      shared_ptr<Document> doc = iter->Next();
      wstring doc_name = doc->id();
      wcout << "\n\t" << doc_name << "\n";
      wcout << "\t"
            << "[{\"FirstName\":"
            << doc->payload().at(U("FirstName")).as_string()
            << ",\"LastName\":" << doc->payload().at(U("LastName")).as_string()
            << "}]";
    }
  } catch (DocumentDBRuntimeException ex) {
    wcout << ex.message();
  }
}

Passaggio 8. Sostituire un documento

Azure Cosmos DB supporta la sostituzione dei documenti JSON, come illustrato nel codice seguente. Aggiungere questo codice dopo la funzione executesimplequery.

void replacedocument(const DocumentClient &client, const wstring dbresourceid,
                     const wstring collresourceid,
                     const wstring docresourceid) {
  try {
    client.GetDatabase(dbresourceid).get();
    shared_ptr<Database> db = client.GetDatabase(dbresourceid);
    shared_ptr<Collection> coll = db->GetCollection(collresourceid);
    value newdoc;
    newdoc[L"id"] = value::string(L"WakefieldFamily");
    newdoc[L"FirstName"] = value::string(L"Lucy");
    newdoc[L"LastName"] = value::string(L"Smith Wakefield");
    coll->ReplaceDocument(docresourceid, newdoc);
  } catch (DocumentDBRuntimeException ex) {
    throw;
  }
}

Passaggio 9. Eliminare un documento

In Azure Cosmos DB è possibile eliminare documenti JSON copiando e incollando il codice seguente dopo la funzione replacedocument.

void deletedocument(const DocumentClient &client, const wstring dbresourceid,
                    const wstring collresourceid, const wstring docresourceid) {
  try {
    client.GetDatabase(dbresourceid).get();
    shared_ptr<Database> db = client.GetDatabase(dbresourceid);
    shared_ptr<Collection> coll = db->GetCollection(collresourceid);
    coll->DeleteDocumentAsync(docresourceid).get();
  } catch (DocumentDBRuntimeException ex) {
    wcout << ex.message();
  }
}

Passaggio 10. Eliminare un database

Se si elimina il database creato, insieme al database vengono rimosse tutte le risorse figlio (raccolte, documenti e così via).

Copiare e incollare il frammento di codice seguente della funzione cleanup dopo la funzione deletedocument per rimuovere il database e tutte le risorse figlio.

void deletedb(const DocumentClient &client, const wstring dbresourceid) {
  try {
    client.DeleteDatabase(dbresourceid);
  } catch (DocumentDBRuntimeException ex) {
    wcout << ex.message();
  }
}

Passaggio 11. Eseguire l'intera applicazione C++

A questo punto è stato aggiunto il codice per creare, eseguire query, modificare ed eliminare diverse risorse di Azure Cosmos DB. A questo punto è possibile aggiungere chiamate a queste funzioni dalla funzione principale in hellodocumentdb.cpp, insieme ad alcuni messaggi di diagnostica.

Per farlo, è possibile sostituire la funzione principale dell'applicazione con il codice seguente. Vengono sovrascritti i valori account_configuration_uri e primary_key copiati nel codice al Passaggio 3, quindi salvare la riga o copiare nuovamente i valori dal portale.

int main() {
    try {
        // Start by defining your account's configuration
        DocumentDBConfiguration conf (L"<account_configuration_uri>", L"<primary_key>");
        // Create your client
        DocumentClient client(conf);
        // Create a new database
        try {
            shared_ptr<Database> db = client.CreateDatabase(L"FamilyDB");
            wcout << "\nCreating database:\n" << db->id();
            // Create a collection inside database
            shared_ptr<Collection> coll = db->CreateCollection(L"FamilyColl");
            wcout << "\n\nCreating collection:\n" << coll->id();
            value document_family;
            document_family[L"id"] = value::string(L"AndersenFamily");
            document_family[L"FirstName"] = value::string(L"Thomas");
            document_family[L"LastName"] = value::string(L"Andersen");
            shared_ptr<Document> doc =
                coll->CreateDocumentAsync(document_family).get();
            wcout << "\n\nCreating document:\n" << doc->id();
            document_family[L"id"] = value::string(L"WakefieldFamily");
            document_family[L"FirstName"] = value::string(L"Lucy");
            document_family[L"LastName"] = value::string(L"Wakefield");
            doc = coll->CreateDocumentAsync(document_family).get();
            wcout << "\n\nCreating document:\n" << doc->id();
            executesimplequery(client, db->resource_id(), coll->resource_id());
            replacedocument(client, db->resource_id(), coll->resource_id(),
                doc->resource_id());
            wcout << "\n\nReplaced document:\n" << doc->id();
            executesimplequery(client, db->resource_id(), coll->resource_id());
            deletedocument(client, db->resource_id(), coll->resource_id(),
                doc->resource_id());
            wcout << "\n\nDeleted document:\n" << doc->id();
            deletedb(client, db->resource_id());
            wcout << "\n\nDeleted db:\n" << db->id();
            cin.get();
        }
        catch (ResourceAlreadyExistsException ex) {
            wcout << ex.message();
        }
    }
    catch (DocumentDBRuntimeException ex) {
        wcout << ex.message();
    }
    cin.get();
}

A questo punto dovrebbe essere possibile compilare ed eseguire il codice in Visual Studio premendo F5 oppure nella finestra del terminale individuando l'applicazione e avviando il file eseguibile.

Verrà visualizzato l'output dell'app introduttiva. L'output deve corrispondere a quello illustrato nella schermata seguente.

Output dell'applicazione C++ in Azure Cosmos DB

Congratulazioni. È stata completata l'esercitazione su C++ ed stata creata la prima applicazione console Azure Cosmos DB.

Ottenere la soluzione completa per l'esercitazione su C++

Per creare la soluzione GetStarted completa contenente tutti gli esempi riportati in questo articolo, è necessario avere:

Passaggi successivi