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

DOTYCZY: Mongodb

• .NET
• Python
• Java
• Node.js
• Przejdź

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ń.

Uwaga

Przykładowe fragmenty kodu są dostępne w witrynie GitHub jako projekt JavaScript.

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
   

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 użyjesz następujących klas 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
• Wystąpienia łańcuchowe
• Tworzenie indeksu
• Tworzenie dokumentu
• Uzyskiwanie dokumentu
• Dokumentacja zapytań

Przykładowy kod opisany w tym artykule tworzy bazę danych o nazwie z kolekcją o nazwie adventureworksproducts. 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 będzie 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.findFindCursor , 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ład generuje informacje do konsoli o wykonanych krokach.

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