Szybki start: sterownik usługi Azure Cosmos DB dla bazy danych MongoDB dla Node.js

DOTYCZY: MongoDB

• Node.js
• Python
• Java
• .NET
• Golang

Rozpocznij pracę z pakietem npm bazy danych MongoDB, aby utworzyć bazy danych, kolekcje i dokumenty w ramach zasobu usługi Azure Cosmos DB. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Dokumentacja referencyjna interfejsu API dla bazy danych | MongoDB — pakiety Pakietu MongoDB (NuGet) /Microsoft.Azure.Cosmos) | Interfejs wiersza polecenia dla deweloperów platformy Azure

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Konto usługi GitHub

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Interfejs wiersza polecenia dla deweloperów platformy Azure
• Docker Desktop

Konfigurowanie

Wdróż kontener projektowy w swoim środowisku. Następnie użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd), aby utworzyć konto usługi Azure Cosmos DB dla bazy danych MongoDB i wdrożyć konteneryzowaną przykładową aplikację. Przykładowa aplikacja używa biblioteki klienta do zarządzania, tworzenia, odczytywania i wykonywania zapytań dotyczących przykładowych danych.

Ważne

Konta usługi GitHub obejmują uprawnienia do magazynowania i godzin podstawowych bez ponoszenia kosztów. Aby uzyskać więcej informacji, zobacz uwzględnione godziny magazynowania i rdzeni dla kont usługi GitHub.

1. Otwórz terminal w katalogu głównym projektu.

2. Uwierzytelnianie w interfejsie wiersza polecenia dla deweloperów platformy Azure przy użyciu polecenia azd auth login. Wykonaj kroki określone przez narzędzie, aby uwierzytelnić się w interfejsie wiersza polecenia przy użyciu preferowanych poświadczeń platformy Azure.

   azd auth login
   

3. Użyj azd init polecenia , aby zainicjować projekt.

   azd init --template cosmos-db-mongodb-nodejs-quickstart
   

   Uwaga

   W tym przewodniku Szybki start użyto repozytorium GitHub szablonu azure-samples/cosmos-db-mongodb-nodejs-quickstart . Interfejs wiersza polecenia dla deweloperów platformy Azure automatycznie sklonuje ten projekt na maszynę, jeśli jeszcze nie istnieje.

4. Podczas inicjowania skonfiguruj unikatową nazwę środowiska.

   Napiwek

   Nazwa środowiska będzie również używana jako nazwa docelowej grupy zasobów. W tym przewodniku Szybki start rozważ użycie polecenia msdocs-cosmos-db.

5. Wdróż konto usługi Azure Cosmos DB przy użyciu polecenia azd up. Szablony Bicep wdrażają również przykładową aplikację internetową.

   azd up
   

6. Podczas procesu aprowizacji wybierz subskrypcję i żądaną lokalizację. Poczekaj na zakończenie procesu aprowizacji. Proces może potrwać około pięciu minut.

7. Po zakończeniu aprowizacji zasobów platformy Azure adres URL uruchomionej aplikacji internetowej zostanie uwzględniony w danych wyjściowych.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Użyj adresu URL w konsoli, aby przejść do aplikacji internetowej w przeglądarce. Obserwuj dane wyjściowe uruchomionej aplikacji.

   

---

Instalowanie pakietu

Dodaj pakiet npm bazy danych MongoDB do projektu JavaScript. npm install package Użyj polecenia określającego nazwę pakietu npm. Pakiet dotenv służy do odczytywania zmiennych środowiskowych z pliku podczas programowania lokalnego .env .

npm install mongodb dotenv

Model obiektów

Przed rozpoczęciem tworzenia aplikacji przyjrzyjmy się hierarchii zasobów w usłudze Azure Cosmos DB. Usługa Azure Cosmos DB ma określony model obiektów używany do tworzenia zasobów i uzyskiwania do ich dostępu. Usługa Azure Cosmos DB tworzy zasoby w hierarchii składającej się z kont, baz danych, kolekcji i dokumentów.

Diagram hierarchiczny przedstawiający konto usługi Azure Cosmos DB u góry. Konto ma dwa podrzędne fragmenty bazy danych. Jeden z fragmentów bazy danych zawiera dwa podrzędne fragmenty kolekcji. Drugi fragment bazy danych zawiera jeden węzeł kolekcji podrzędnej. Ten fragment pojedynczej kolekcji ma trzy podrzędne fragmenty dokumentów.

Do interakcji z tymi zasobami służą następujące klasy bazy danych MongoDB:

• MongoClient — Ta klasa zapewnia logiczną reprezentację po stronie klienta dla warstwy interfejsu API dla bazy danych MongoDB w usłudze Azure Cosmos DB. Obiekt klienta służy do konfigurowania i wykonywania żądań względem usługi.
• Db — Ta klasa jest odwołaniem do bazy danych, która może lub nie istnieje jeszcze w usłudze. Baza danych jest weryfikowana po stronie serwera podczas próby uzyskania do niej dostępu lub wykonania operacji względem niej.
• Collection — Ta klasa jest odwołaniem do kolekcji, która również może nie istnieć w usłudze. Kolekcja jest weryfikowana po stronie serwera podczas próby jej pracy.

Przykłady kodu

• Uwierzytelnianie użytkownika
• Pobieranie wystąpienia bazy danych
• Pobieranie wystąpienia kolekcji
• Używanie metod łańcuchowych
• Tworzenie indeksu
• Tworzenie dokumentu
• Uzyskiwanie dokumentu
• Uruchamianie zapytań

Przykładowy kod opisany w tym artykule tworzy bazę danych o nazwie z kolekcją o nazwie adventureworks products. Kolekcja została zaprojektowana products tak, aby zawierała szczegóły produktu, takie jak nazwa, kategoria, ilość i wskaźnik sprzedaży. Każdy produkt zawiera również unikatowy identyfikator.

W tej procedurze baza danych nie używa fragmentowania.

Uwierzytelnianie użytkownika

1. W katalogu projektu utwórz plik index.js . W edytorze dodaj instrukcje wymagają odwołania do pakietów npm MongoDB i DotEnv.

   // Read .env file and set environment variables
   require('dotenv').config();
   const random = Math.floor(Math.random() * 100);
   
   // Use official mongodb driver to connect to the server
   const { MongoClient, ObjectId } = require('mongodb');
   

2. Zdefiniuj nowe wystąpienie MongoClient, klasy przy użyciu konstruktora i process.env. odczytaj utworzoną wcześniej zmienną środowiskową.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   

Aby uzyskać więcej informacji na temat różnych sposobów tworzenia MongoClient wystąpienia, zobacz Przewodnik Szybki start sterownika NodeJS bazy danych MongoDB.

Konfigurowanie operacji asynchronicznych

index.js W pliku dodaj następujący kod, aby obsługiwać operacje asynchroniczne:

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

Następujące fragmenty kodu powinny zostać dodane do funkcji main w celu obsługi składni async/await.

Łączenie z bazą danych

Użyj metody , aby nawiązać połączenie z zasobem MongoClient.connect usługi Azure Cosmos DB dla bazy danych MongoDB. Metoda connect zwraca odwołanie do bazy danych.

// Use connect method to connect to the server
await client.connect();

Pobieranie wystąpienia bazy danych

MongoClient.db Użyj metody pobiera odwołanie do bazy danych.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Pobieranie wystąpienia kolekcji

Obiekt MongoClient.Db.collection pobiera odwołanie do kolekcji.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Wystąpienia łańcuchowe

Możesz połączyć klienta, bazę danych i kolekcję. Łączenie łańcuchów jest wygodniejsze, jeśli musisz uzyskać dostęp do wielu baz danych lub kolekcji.

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Tworzenie indeksu

Użyj elementu , Collection.createIndex aby utworzyć indeks we właściwościach dokumentu, których zamierzasz użyć do sortowania FindCursor.sort za pomocą metody bazy danych MongoDB.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Tworzenie dokumentu

Utwórz dokument z właściwościami produktu dla adventureworks bazy danych:

• Właściwość _id unikatowego identyfikatora produktu.
• Właściwość category. Tej właściwości można użyć jako klucza partycji logicznej.
• Właściwość name .
• Właściwość ilości zapasów.
• Nieruchomość sprzedaży wskazująca, czy produkt jest w sprzedaży.

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Utwórz dokument w kolekcji, wywołując polecenie Collection.UpdateOne. W tym przykładzie wybraliśmy opcję upsert zamiast utworzyć nowy dokument na wypadek, gdy uruchomisz ten przykładowy kod więcej niż raz.

Uzyskiwanie dokumentu

W usłudze Azure Cosmos DB można wykonać mniej kosztowną operację odczytu punktu przy użyciu zarówno unikatowego identyfikatora (_id) jak i klucza partycji (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Dokumentacja zapytań

Po wstawieniu dokumentu można uruchomić zapytanie, aby pobrać wszystkie dokumenty pasujące do określonego filtru. W tym przykładzie znajdują się wszystkie dokumenty pasujące do określonej kategorii: gear-surf-surfboards. Po zdefiniowaniu zapytania wywołaj metodę Collection.find FindCursor , aby uzyskać wynik. Przekonwertuj kursor na tablicę, aby użyć metod tablicy JavaScript.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Rozwiązywanie problemów:

• Jeśli wystąpi błąd, taki jak The index path corresponding to the specified order-by item is excluded., upewnij się, że utworzono indeks.

Uruchamianie kodu

Ta aplikacja tworzy interfejs API dla bazy danych MongoDB i kolekcji oraz tworzy dokument, a następnie odczytuje dokładnie ten sam dokument. Na koniec przykład wystawia zapytanie, które powinno zwrócić tylko ten pojedynczy dokument. W każdym kroku przykładowe dane wyjściowe są wyświetlane w konsoli programu na temat wykonanych kroków.

Aby uruchomić aplikację, użyj terminalu, aby przejść do katalogu aplikacji i uruchomić aplikację.

node index.js

Dane wyjściowe aplikacji powinny być podobne do tego przykładu:

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

Czyszczenie zasobów

Jeśli nie potrzebujesz już konta usługi Azure Cosmos DB dla bazy danych MongoDB, możesz usunąć odpowiednią grupę zasobów.

Interfejs wiersza polecenia platformy Azure

Użyj polecenia , az group delete aby usunąć grupę zasobów.

az group delete --name $resourceGroupName

Program PowerShell

Remove-AzResourceGroup Użyj polecenia cmdlet , aby usunąć grupę zasobów.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portal

1. Przejdź do grupy zasobów utworzonej wcześniej w witrynie Azure Portal.

   Napiwek

   W tym przewodniku Szybki start zalecamy nazwę msdocs-cosmos-javascript-quickstart-rg.

2. Wybierz pozycję Usuń grupę zasobów.

   

3. W oknie dialogowym Czy na pewno chcesz usunąć, wprowadź nazwę grupy zasobów, a następnie wybierz pozycję Usuń.

   

Następne kroki

W tym przewodniku Szybki start przedstawiono sposób tworzenia konta usługi Azure Cosmos DB dla bazy danych MongoDB, tworzenia bazy danych i tworzenia kolekcji przy użyciu sterownika Bazy danych MongoDB. Teraz możesz dokładniej zapoznać się z usługą Azure Cosmos DB dla bazy danych MongoDB, aby zaimportować więcej danych, wykonywać złożone zapytania i zarządzać zasobami bazy danych MongoDB w usłudze Azure Cosmos DB.

Migrowanie bazy danych MongoDB do usługi Azure Cosmos DB dla bazy danych MongoDB w trybie offline