Mulai menggunakan Azure Cosmos DB untuk NoSQL menggunakan JavaScript

  • Artikel

BERLAKU UNTUK: NoSQL

Artikel ini memperlihatkan kepada Anda cara menyambungkan ke Azure Cosmos DB for NoSQL menggunakan JavaScript SDK. Setelah tersambung, Anda dapat melakukan operasi pada database, kontainer, dan item.

Paket (npm) | Contoh | referensi API | Kode sumber pustaka | Berikan Umpan Balik

Prasyarat

Menyiapkan proyek lokal Anda

  1. Buat direktori baru untuk proyek JavaScript Anda di shell bash.

    mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples

  2. Buat aplikasi JavaScript baru dengan menggunakan npm init perintah dengan templat konsol .

    npm init -y

  3. Instal dependensi yang diperlukan untuk Azure Cosmos DB untuk NoSQL JavaScript SDK.

    npm install @azure/cosmos

Koneksi ke Azure Cosmos DB for NoSQL

Untuk menyambungkan ke API untuk NoSQL Azure Cosmos DB, buat instans CosmosClient kelas . Kelas ini adalah titik awal untuk melakukan semua operasi terhadap database. Ada tiga cara inti untuk terhubung ke API untuk akun NoSQL menggunakan kelas CosmosClient :

Sambungkan dengan titik akhir dan kunci

Konstruktor yang paling umum untuk CosmosClient memiliki dua parameter:

Parameter Contoh nilai Deskripsi
accountEndpoint COSMOS_ENDPOINT Variabel lingkungan API untuk titik akhir NoSQL yang akan digunakan untuk semua permintaan
authKeyOrResourceToken COSMOS_KEY Variabel lingkungan Kunci akun atau token sumber daya yang akan digunakan saat mengautentikasi

Mengambil titik akhir dan kunci akun Anda

  1. Buat variabel shell untuk resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-javascript-howto-rg"

  2. Gunakan perintah az cosmosdb list untuk mengambil nama akun Azure Cosmos DB pertama di grup sumber daya Anda dan simpan di variabel shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Dapatkan API untuk URI titik akhir NoSQL untuk akun menggunakan az cosmosdb show perintah .

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Temukan KUNCI PRIMER dari daftar kunci untuk akun dengan perintah az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Catat nilai URI dan KUNCI PRIMER. Anda akan menggunakan info masuk ini nanti.

Untuk menggunakan nilai URI dan KUNCI PRIMER dalam kode Anda, pertahankan nilai tersebut ke variabel lingkungan baru pada komputer lokal yang menjalankan aplikasi.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Membuat CosmosClient dengan titik akhir dan kunci akun

Buat instans baru kelas CosmosClient dengan variabel lingkungan COSMOS_ENDPOINT dan COSMOS_KEY sebagai parameter.

const client = new CosmosClient({ endpoint, key });

Menghubungkan dengan string koneksi

Konstruktor lain untuk CosmosClient hanya berisi satu parameter:

Parameter Contoh nilai Deskripsi
accountEndpoint COSMOS_ENDPOINT Variabel lingkungan API untuk titik akhir NoSQL yang akan digunakan untuk semua permintaan
connectionString COSMOS_CONNECTION_STRING Variabel lingkungan string Koneksi ion ke API untuk akun NoSQL

Mengambil string koneksi akun Anda

  1. Gunakan perintah az cosmosdb list untuk mengambil nama akun Azure Cosmos DB pertama di grup sumber daya Anda dan simpan di variabel shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Temukan STRING KONEKSI UTAMA dari daftar string koneksi untuk akun dengan perintah az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Untuk menggunakan nilai STRING KONEKSI UTAMA dalam kode Anda, pertahankan ke variabel lingkungan baru pada komputer lokal yang menjalankan aplikasi.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Membuat CosmosClient dengan string koneksi

Buat instans baru kelas CosmosClient dengan variabel lingkungan COSMOS_CONNECTION_STRING sebagai satu-satunya parameter.

// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);

Koneksi menggunakan platform identitas Microsoft

Untuk menyambungkan ke API Anda untuk akun NoSQL menggunakan platform identitas Microsoft dan ID Microsoft Entra, gunakan prinsip keamanan. Jenis utama yang tepat tergantung pada tempat Anda menghosting kode aplikasi Anda. Tabel di bawah ini berfungsi sebagai panduan referensi singkat.

Tempat aplikasi berjalan Prinsip keamanan
Komputer lokal (pengembangan dan pengujian) Identitas pengguna atau perwakilan layanan
Azure Identitas Terkelola
Server atau klien di luar Azure Perwakilan layanan

Impor @azure/identity

Paket npm @azure/identitas berisi fungsionalitas autentikasi inti yang dibagikan di antara semua pustaka Azure SDK.

  1. Impor paket npm @azure/identitas menggunakan npm install perintah .

    npm install @azure/identity

  2. Di editor kode Anda, tambahkan dependensi.

    const { DefaultAzureCredential } = require("@azure/identity");

Membuat CosmosClient dengan implementasi kredensial default

Jika Anda melakukan pengujian pada mesin lokal, atau aplikasi Anda akan berjalan di layanan Azure dengan dukungan langsung untuk identitas terkelola, dapatkan token OAuth dengan membuat instans DefaultAzureCredential. Kemudian buat instans baru kelas CosmosClient dengan COSMOS_ENDPOINT variabel lingkungan dan objek TokenCredential sebagai parameter.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Membuat CosmosClient dengan implementasi kredensial kustom

Jika Anda berencana untuk menyebarkan aplikasi ke luar Azure, Anda dapat memperoleh token OAuth dengan menggunakan kelas lain di pustaka klien @azure/identitas untuk JavaScript. Kelas-kelas lain ini juga berasal dari kelas TokenCredential.

Untuk contoh ini, kami membuat instans ClientSecretCredential dengan menggunakan pengidentifikasi klien dan penyewa, bersama dengan rahasia klien.

Anda dapat memperoleh ID klien, ID penyewa, dan rahasia klien saat mendaftarkan aplikasi di ID Microsoft Entra. Untuk informasi selengkapnya tentang mendaftarkan aplikasi Microsoft Entra, lihat Mendaftarkan aplikasi dengan platform identitas Microsoft.

Buat instans baru kelas CosmosClient dengan variabel lingkungan COSMOS_ENDPOINT dan objek TokenCredential sebagai parameter.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new ClientSecretCredential(
    tenantId: process.env.AAD_TENANT_ID,
    clientId: process.env.AAD_CLIENT_ID,
    clientSecret: process.env.AAD_CLIENT_SECRET
);

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Bangun aplikasi Anda

Saat Anda membangun aplikasi, kode Anda utamanya akan berinteraksi dengan empat jenis sumber daya:

  • API untuk akun NoSQL, yang merupakan namespace layanan tingkat atas unik untuk data Azure Cosmos DB Anda.

  • Database, yang mengatur kontainer di akun Anda.

  • Kontainer, yang berisi sekumpulan item individual dalam database Anda.

  • Item, yang mewakili dokumen JSON dalam kontainer Anda.

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Setiap jenis sumber daya diwakili oleh satu atau beberapa kelas terkait. Berikut adalah daftar kelas yang paling umum:

Kelas Deskripsi
CosmosClient Kelas ini menyediakan representasi logis sisi klien untuk layanan Azure Cosmos DB. Klien ini digunakan untuk mengonfigurasi dan menjalankan permintaan terhadap layanan.
Database Kelas ini adalah referensi ke database yang mungkin sudah ada, atau mungkin belum ada dalam layanan. Database divalidasi di sisi server saat Anda mencoba mengaksesnya atau melakukan operasi terhadapnya.
Container Kelas ini adalah referensi ke kontainer yang juga mungkin belum ada dalam layanan. Kontainer divalidasi di sisi server ketika Anda mencoba untuk menggunakannya.

Panduan berikut menunjukkan cara menggunakan masing-masing kelas ini untuk membangun aplikasi Anda.

Panduan Deskripsi
Membuat database Membuat database
Membuat kontainer Membuat kontainer
Membuat dan membaca item Membaca poin item tertentu
Item kueri Mengkueri beberapa item

Baca juga

Langkah berikutnya

Sekarang setelah Anda tersambung ke API untuk akun NoSQL, gunakan panduan berikutnya untuk membuat dan mengelola database.

Membuat database di Azure Cosmos DB untuk NoSQL menggunakan JavaScript