Mengembangkan secara lokal menggunakan emulator Azure Cosmos DB
Artikel
Kasus penggunaan umum untuk emulator adalah berfungsi sebagai database pengembangan saat Anda membangun aplikasi Anda. Menggunakan emulator untuk pengembangan dapat membantu Anda mempelajari karakteristik pembuatan dan pemodelan data untuk database seperti Azure Cosmos DB tanpa dikenakan biaya layanan apa pun. Selain itu, menggunakan emulator sebagai bagian dari alur kerja otomatisasi dapat memastikan bahwa Anda dapat menjalankan rangkaian pengujian integrasi yang sama. Anda dapat memastikan bahwa pengujian yang sama berjalan baik secara lokal pada komputer pengembangan Anda dan dari jarak jauh dalam pekerjaan integrasi berkelanjutan.
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Tarik gambar kontainer Linux menggunakan mongodb tag dari registri kontainer ke host Docker lokal.
Varian kontainer Docker emulator tidak mendukung API untuk Apache Cassandra.
Mulai executable emulator (Microsoft.Azure.Cosmos.Emulator.exe) di %ProgramFiles%\Azure Cosmos DB Emulator jalur . Gunakan parameter ini untuk mengonfigurasi emulator:
Deskripsi
EnableCassandraEndpoint
Mengaktifkan API untuk titik akhir Apache Cassandra.
Varian kontainer Docker emulator tidak mendukung API untuk Apache Gremlin.
Mulai executable emulator (Microsoft.Azure.Cosmos.Emulator.exe) di %ProgramFiles%\Azure Cosmos DB Emulator jalur . Gunakan parameter ini untuk mengonfigurasi emulator:
Deskripsi
EnableGremlinEndpoint
Mengaktifkan API untuk titik akhir Apache Gremlin.
Varian kontainer Docker emulator tidak mendukung API untuk Table.
Mulai executable emulator (Microsoft.Azure.Cosmos.Emulator.exe) di %ProgramFiles%\Azure Cosmos DB Emulator jalur . Gunakan parameter ini untuk mengonfigurasi emulator:
Navigasi ke https://localhost:8081/_explorer/index.html untuk mengakses penjelajah data.
Gambar kontainer Docker (Windows) tidak mendukung API untuk MongoDB.
Mulai executable emulator (Microsoft.Azure.Cosmos.Emulator.exe) di %ProgramFiles%\Azure Cosmos DB Emulator jalur . Gunakan parameter ini untuk mengonfigurasi emulator:
Deskripsi
EnableMongoDbEndpoint
Mengaktifkan API untuk titik akhir MongoDB pada versi MongoDB tertentu.
Sertifikat untuk emulator tersedia di jalur _explorer/emulator.pem pada kontainer yang sedang berjalan. Gunakan curl untuk mengunduh sertifikat dari kontainer yang sedang berjalan ke komputer lokal Anda.
Dapatkan sertifikat dari kontainer yang sedang berjalan.
Anda mungkin perlu mengubah host (atau alamat IP) dan nomor port jika sebelumnya Anda telah memodifikasi nilai-nilai tersebut.
Instal sertifikat sesuai dengan proses yang biasanya digunakan untuk sistem operasi Anda. Misalnya, di Linux Anda akan menyalin sertifikat ke /usr/local/share/ca-certificates/ jalur.
Untuk sistem linux, regenerasi bundel sertifikat dengan menggunakan perintah yang sesuai untuk distribusi Linux Anda.
Untuk sistem Linux berbasis Debian (misalnya, Ubuntu), gunakan:
sudo update-ca-certificates
Untuk sistem Linux berbasis Red Hat (misalnya, CentOS, Fedora), gunakan:
sudo update-ca-trust
Untuk petunjuk lebih rinci, lihat dokumentasi khusus untuk sistem operasi Anda.
Sertifikat untuk emulator tersedia di folder C:\CosmosDB.Emulator\bind-mount pada kontainer yang sedang berjalan. Folder juga berisi skrip untuk menginstal sertifikat secara otomatis.
Gunakan docker cp untuk menyalin seluruh folder ke komputer lokal Anda.
var item = new
{
id = "68719518371",
name = "Kiama classic surfboard"
};
await container.UpsertItemAsync(item);
Jalankan aplikasi .NET.
dotnet run
Peringatan
Jika Anda mendapatkan kesalahan SSL, Anda mungkin perlu menonaktifkan TLS/SSL untuk aplikasi Anda. Ini biasanya terjadi jika Anda mengembangkan di komputer lokal Anda, menggunakan emulator Azure Cosmos DB dalam kontainer, dan belum mengimpor sertifikat SSL kontainer. Untuk mengatasi hal ini, konfigurasikan opsi klien untuk menonaktifkan validasi TLS/SSL sebelum membuat klien:
Jika Anda mendapatkan kesalahan SSL, Anda mungkin perlu menonaktifkan TLS/SSL untuk aplikasi Anda. Ini biasanya terjadi jika Anda mengembangkan di komputer lokal Anda, menggunakan emulator Azure Cosmos DB dalam kontainer, dan belum mengimpor sertifikat SSL kontainer. Untuk mengatasinya, konfigurasikan aplikasi untuk menonaktifkan validasi TLS/SSL sebelum membuat klien:
import urllib3
urllib3.disable_warnings()
Jika Anda masih menghadapi kesalahan SSL, ada kemungkinan Python mengambil sertifikat dari penyimpanan sertifikat yang berbeda. Untuk menentukan jalur tempat Python mencari sertifikat, ikuti langkah-langkah berikut:
Penting
Jika Anda menggunakan lingkungan virtual Python (venv) pastikan itu diaktifkan sebelum menjalankan perintah!
Buka terminal
Mulai penerjemah Python dengan mengetik python atau python3, tergantung pada versi Python Anda.
Di penerjemah Python, jalankan perintah berikut:
from requests.utils import DEFAULT_CA_BUNDLE_PATH
print(DEFAULT_CA_BUNDLE_PATH)
Di dalam lingkungan virtual, jalurnya mungkin (setidaknya di Ubuntu):
Di luar lingkungan virtual, jalurnya mungkin (setidaknya di Ubuntu):
/etc/ssl/certs/ca-certificates.crt
Setelah Anda mengidentifikasi DEFAULT_CA_BUNDLE_PATH, buka terminal baru dan jalankan perintah berikut untuk menambahkan sertifikat emulator ke bundel sertifikat:
Penting
Jika variabel DEFAULT_CA_BUNDLE_PATH menunjuk ke direktori sistem, Anda mungkin mengalami kesalahan "Izin ditolak" . Dalam hal ini, Anda harus menjalankan perintah dengan hak istimewa yang ditingkatkan (sebagai root). Selain itu, Anda perlu memperbarui dan meregenerasi bundel sertifikat setelah menjalankan perintah yang disediakan.
# Add a new line to the certificate bundle
echo >> /path/to/ca_bundle
# Append the emulator certificate to the certificate bundle
cat /path/to/emulatorcert.crt >> /path/to/ca_bundle
Jika Anda mendapatkan kesalahan SSL, Anda mungkin perlu menonaktifkan TLS/SSL untuk aplikasi Anda. Ini biasanya terjadi jika Anda mengembangkan di komputer lokal Anda, menggunakan emulator Azure Cosmos DB dalam kontainer, dan belum mengimpor sertifikat SSL kontainer. Untuk mengatasinya, konfigurasikan aplikasi untuk menonaktifkan validasi TLS/SSL sebelum membuat klien:
Tambahkan blok penggunaan untuk MongoDB.Driver namespace layanan.
using MongoDB.Driver;
Buat instans baru menggunakan MongoClient kredensial emulator.
var client = new MongoClient(
"mongodb://localhost:C2y6yDjf5%2FR%2Bob0N8A7Cgv30VRDJIWEHLM%2B4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw%2FJw%3D%3D@localhost:10255/admin?ssl=true&retrywrites=false"
);
db = client["cosmicworks"]
if "cosmicworks" not in client.list_database_names():
db.command(
{
"customAction": "CreateDatabase",
"offerThroughput": 400,
}
)
collection = db["products"]
if "products" not in db.list_collection_names():
db.command({"customAction": "CreateCollection", "collection": "products"})
Gunakan update_one untuk membuat item baru dalam kontainer.
Jika Anda mendapatkan kesalahan SSL, Anda mungkin perlu menonaktifkan TLS/SSL untuk aplikasi Anda. Ini biasanya terjadi jika Anda mengembangkan di komputer lokal Anda, menggunakan emulator Azure Cosmos DB dalam kontainer, dan belum mengimpor sertifikat SSL kontainer. Untuk mengatasinya, konfigurasikan aplikasi untuk menonaktifkan validasi TLS/SSL sebelum membuat klien:
var createKeyspace = await session.PrepareAsync("CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'basicclass', 'replication_factor': 1};");
await session.ExecuteAsync(createKeyspace.Bind());
var createTable = await session.PrepareAsync("CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)");
await session.ExecuteAsync(createTable.Bind());
Buat item baru dalam tabel menggunakan ExecuteAsync. Gunakan Bind untuk menetapkan properti ke item.
var item = new
{
id = "68719518371",
name = "Kiama classic surfboard"
};
var createItem = await session.PrepareAsync("INSERT INTO cosmicworks.products (id, name) VALUES (?, ?)");
var createItemStatement = createItem.Bind(item.id, item.name);
await session.ExecuteAsync(createItemStatement);
Jalankan aplikasi .NET.
dotnet run
Gunakan driver Apache Cassandra Python untuk terhubung ke emulator dari aplikasi Python.
Impor PROTOCOL_TLS_CLIENT, SSLContext, dan CERT_NONE dari ssl modul . Kemudian, impor Cluster dari cassandra.cluster modul. Terakhir, impor PlainTextAuthProvider dari cassandra.auth modul.
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
Buat variabel konteks TLS/SSL baru menggunakan SSLContext. Konfigurasikan konteks untuk tidak memverifikasi sertifikat emulator yang ditandatangani sendiri.
Buat keyspace dan tabel baru menggunakan session.execute.
session.execute(
"CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'ba"
"sicclass', 'replication_factor': 1};"
)
session.execute(
"CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, nam"
"e text)"
)
Gunakan session.execute untuk membuat item baru dalam tabel.
Client Impor jenis dan auth namespace layanan dari cassandra-driver modul.
import { Client, auth } from 'cassandra-driver'
Gunakan PlainTextAuthProvider untuk membuat objek baru untuk kredensial emulator. Gunakan Client untuk menyambungkan ke emulator menggunakan kredensial.
const credentials = new auth.PlainTextAuthProvider(
'localhost',
'C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=='
)
const client = new Client({
contactPoints: [
'localhost:10350'
],
authProvider: credentials,
localDataCenter: 'South Central US'
})
Gunakan execute untuk menjalankan sisi server perintah untuk membuat keyspace dan tabel.
await client.execute(
'CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {\'class\':\'basicclass\', \'replication_factor\': 1};'
)
await client.execute(
'CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)'
)
Gunakan execute lagi untuk membuat item baru dengan parameter.
Jika Anda mendapatkan kesalahan SSL, Anda mungkin perlu menonaktifkan TLS/SSL untuk aplikasi Anda. Ini biasanya terjadi jika Anda mengembangkan di komputer lokal Anda, menggunakan emulator Azure Cosmos DB dalam kontainer, dan belum mengimpor sertifikat SSL kontainer. Untuk mengatasinya, konfigurasikan klien untuk menonaktifkan validasi TLS/SSL:
Sebelum memulai, API untuk Apache Gremlin mengharuskan Anda membuat sumber daya di emulator. Buat database bernama db1 dan kontainer bernama coll1. Pengaturan throughput tidak relevan untuk panduan ini dan dapat diatur serendah yang Anda inginkan.
var server = new GremlinServer(
hostname: "localhost",
port: 65400,
username: "/dbs/db1/colls/coll1",
password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);
using var client = new GremlinClient(
gremlinServer: server,
messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);
Gunakan PlainTextSaslAuthenticator untuk membuat objek baru untuk kredensial emulator. Gunakan Client untuk menyambungkan ke emulator menggunakan kredensial.
var serviceClient = new TableServiceClient(
connectionString: "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;"
);
Jika Anda mendapatkan kesalahan SSL, Anda mungkin perlu menonaktifkan TLS/SSL untuk aplikasi Anda. Ini biasanya terjadi jika Anda mengembangkan di komputer lokal Anda, menggunakan emulator Azure Cosmos DB dalam kontainer, dan belum mengimpor sertifikat SSL kontainer. Untuk mengatasinya, konfigurasikan klien untuk menonaktifkan validasi TLS/SSL:
Menggunakan emulator dalam alur kerja GitHub Actions CI
Untuk menjalankan beban kerja integrasi berkelanjutan yang secara otomatis memvalidasi aplikasi Anda, gunakan emulator Azure Cosmos DB dengan rangkaian pengujian dari kerangka kerja pilihan Anda. Emulator Azure Cosmos DB telah diinstal sebelumnya dalam varian runner yang dihosting windows-latest GitHub Action.
Jalankan rangkaian pengujian menggunakan driver pengujian bawaan untuk .NET dan kerangka kerja pengujian seperti MSTest, NUnit, atau XUnit.
Validasi bahwa rangkaian pengujian unit untuk aplikasi Anda berfungsi seperti yang diharapkan.
dotnet test
Buat alur kerja baru di repositori GitHub Anda dalam file bernama .github/workflows/ci.yml.
Tambahkan pekerjaan ke alur kerja Anda untuk memulai emulator Azure Cosmos DB menggunakan PowerShell dan jalankan rangkaian pengujian unit Anda.
name: Continuous Integration
on:
push:
branches:
- main
jobs:
unit_tests:
name: Run .NET unit tests
runs-on: windows-latest
steps:
- name: Checkout (GitHub)
uses: actions/checkout@v3
- name: Start Azure Cosmos DB emulator
run: |
Write-Host "Launching Cosmos DB Emulator"
Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
Start-CosmosDbEmulator
- name: Run .NET tests
run: dotnet test
Catatan
Mulai emulator dari baris perintah menggunakan berbagai argumen atau perintah PowerShell. Untuk informasi selengkapnya, lihat argumen baris perintah emulator.
Uji operasi aplikasi dan database Python Anda menggunakan pytest.
Validasi bahwa rangkaian pengujian unit untuk aplikasi Anda berfungsi seperti yang diharapkan.
pip install -U pytest
pytest
Buat alur kerja baru di repositori GitHub Anda dalam file bernama .github/workflows/ci.yml.
Tambahkan pekerjaan ke alur kerja Anda untuk memulai emulator Azure Cosmos DB menggunakan PowerShell dan jalankan rangkaian pengujian unit Anda.
name: Continuous Integration
on:
push:
branches:
- main
jobs:
unit_tests:
name: Run Python unit tests
runs-on: windows-latest
steps:
- name: Checkout (GitHub)
uses: actions/checkout@v3
- name: Start Azure Cosmos DB emulator
run: |
Write-Host "Launching Cosmos DB Emulator"
Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
Start-CosmosDbEmulator
- name: Install test runner
run: pip install pytest
- name: Run Python tests
run: pytest
Catatan
Mulai emulator dari baris perintah menggunakan berbagai argumen atau perintah PowerShell. Untuk informasi selengkapnya, lihat argumen baris perintah emulator.
Gunakan mocha untuk menguji aplikasi Node.js Anda dan modifikasi databasenya.
Validasi bahwa rangkaian pengujian unit untuk aplikasi Anda berfungsi seperti yang diharapkan.
npm install --global mocha
mocha
Buat alur kerja baru di repositori GitHub Anda dalam file bernama .github/workflows/ci.yml.
Tambahkan pekerjaan ke alur kerja Anda untuk memulai emulator Azure Cosmos DB menggunakan PowerShell dan jalankan rangkaian pengujian unit Anda.
name: Continuous Integration
on:
push:
branches:
- main
jobs:
unit_tests:
name: Run Node.js unit tests
runs-on: windows-latest
steps:
- name: Checkout (GitHub)
uses: actions/checkout@v3
- name: Start Azure Cosmos DB emulator
run: |
Write-Host "Launching Cosmos DB Emulator"
Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
Start-CosmosDbEmulator
- name: Install test runner
run: npm install --global mocha
- name: Run Node.js tests
run: mocha
Catatan
Mulai emulator dari baris perintah menggunakan berbagai argumen atau perintah PowerShell. Untuk informasi selengkapnya, lihat argumen baris perintah emulator.