Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Emulator Azure Cosmos DB generasi berikutnya sepenuhnya berbasis Linux dan tersedia sebagai kontainer Docker. Ini mendukung berjalan pada berbagai prosesor dan sistem operasi.
Penting
Versi emulator ini hanya mendukung API untuk NoSQL dalam mode gateway, dengan beberapa fitur tertentu. Untuk informasi selengkapnya, lihat dukungan fitur.
Prasyarat
Penginstalan
Dapatkan gambar kontainer Docker menggunakan docker pull
. Gambar kontainer diterbitkan ke Registri Artefak Microsoft sebagai mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
.
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
Berlari
Untuk menjalankan kontainer, gunakan docker run
. Setelah itu, gunakan docker ps
untuk memvalidasi bahwa kontainer sedang berjalan.
docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c1bb8cf53f8a mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview "/bin/bash -c /home/…" 5 seconds ago Up 5 seconds 0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp <container-name>
Catatan
Emulator terdiri dari dua komponen:
-
Data explorer - menjelajahi data secara interaktif di emulator. Secara default ini berjalan pada port
1234
-
Emulator Azure Cosmos DB - versi lokal layanan database Azure Cosmos DB. Secara default, ini berjalan pada port
8081
.
Titik akhir gateway emulator biasanya tersedia di port 8081
di alamat http://localhost:8081. Untuk menavigasi ke penjelajah data, gunakan alamat http://localhost:1234 di browser web Anda. Mungkin perlu beberapa detik agar penjelajah data tersedia. Titik akhir gateway biasanya segera tersedia.
Penting
.NET dan Java SDK tidak mendukung mode HTTP di emulator. Karena versi emulator ini dimulai dengan HTTP secara default, Anda harus secara eksplisit mengaktifkan HTTPS saat memulai kontainer (lihat di bawah). Untuk Java SDK, Anda juga perlu menginstal sertifikat.
docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https
Perintah Docker
Tabel berikut ini meringkas perintah Docker yang tersedia untuk mengonfigurasi emulator. Tabel ini merinci argumen terkait, variabel lingkungan, nilai yang diizinkan, pengaturan default, dan deskripsi setiap perintah.
Persyaratan | Aduh! | Env | Nilai yang diizinkan | Bawaan | Deskripsi |
---|---|---|---|---|---|
Cetak pengaturan ke stdout dari dalam kontainer |
--help , -h |
T/A | T/A | T/A | Menampilkan informasi tentang konfigurasi yang tersedia |
Atur port dari titik akhir Cosmos | --port [INT] |
PELABUHAN | INT | 8081 | Port titik akhir Cosmos pada kontainer. Anda masih perlu menerbitkan port ini (misalnya, -p 8081:8081 ). |
Tentukan protokol yang digunakan oleh titik akhir Cosmos | --protocol |
PROTOKOL |
https , http , https-insecure |
http |
Protokol titik akhir Cosmos pada kontainer. |
Mengaktifkan penjelajah data | --enable-explorer |
AKTIFKAN_PENJELAJAH |
true , false |
true |
Aktifkan menjalankan Cosmos Data Explorer pada kontainer yang sama. |
Mengatur port yang digunakan oleh penjelajah data | --explorer-port |
EXPLORER_PORT | INT | 1234 | Port Cosmos Data Explorer pada kontainer. Anda masih perlu menerbitkan port ini (misalnya, -p 1234:1234 ). |
Pengguna harus dapat menentukan protokol yang digunakan oleh penjelajah, jika tidak, maka gunakan default yang digunakan oleh titik akhir Cosmos. | --explorer-protocol |
PROTOKOL_EKSPLORER |
https , http , https-insecure |
<the value of --protocol> |
Protokol Cosmos Data Explorer pada kontainer. Mengikuti pengaturan bawaan pada titik akhir Cosmos. |
Tentukan kunci melalui file | --key-file [PATH] |
BERKAS_KUNCI | JALAN | <default secret> |
Ambil alih kunci default dengan kunci yang ditentukan dalam file. Anda perlu memasang file ini ke dalam kontainer (misalnya, jika KEY_FILE=/mykey, Anda akan menambahkan opsi seperti berikut ini ke eksekusi docker Anda: --mount type=bind,source=./myKey,target=/myKey ) |
Mengatur jalur data | --data-path [PATH] |
In this case, however, since "DATA_PATH" is a technical identifier, it should remain as is without translation. Therefore, no improvements are necessary. | JALAN | /data |
Tentukan direktori untuk data. Sering digunakan dengan docker run --mount opsi (misalnya, jika DATA_PATH=/usr/cosmos/data, Anda akan menambahkan opsi seperti berikut ini ke eksekusi docker Anda: --mount type=bind,source=./.local/data,target=/usr/cosmos/data ) |
Tentukan jalur sertifikasi yang akan digunakan untuk https | --cert-path [PATH] |
CERT_PATH | JALAN | <default cert> |
Tentukan jalur sertifikat untuk mengamankan lalu lintas data. Anda perlu memasang file ini ke dalam kontainer (misalnya, jika CERT_PATH=/mycert.pfx, Anda akan menambahkan opsi seperti berikut ini ke eksekusi docker Anda: --mount type=bind,source=./mycert.pfx,target=/mycert.pfx ) |
Tentukan rahasia sertifikasi yang akan digunakan untuk https | T/A | SERTIFIKAT_RAHASIA | benang | <default secret> |
Rahasia untuk sertifikat yang ditentukan pada CERT_PATH. |
Mengatur tingkat log | --log-level [LEVEL] |
LOG_LEVEL |
quiet , error , warn , info , debug , trace |
info |
Verbositas log yang dipancarkan oleh emulator dan penjelajah data. |
Mengaktifkan info diagnostik yang dikirim ke Microsoft | --enable-telemetry |
AKTIFKAN_TELEMETRI |
true , false |
true |
Aktifkan pengiriman log ke Microsoft untuk membantu kami meningkatkan emulator. |
Dukungan fitur
Emulator ini sedang dalam pengembangan dan tersedia dalam pratinjau aktif. Akibatnya, tidak semua fitur Azure Cosmos DB didukung. Beberapa fitur juga tidak akan didukung di masa mendatang. Tabel ini mencakup status berbagai fitur dan tingkat dukungannya.
Fitur | Dukungan |
---|---|
Batch API | ✅ Didukung |
API Berbasis Massal | ✅ Didukung |
Pengubahan Umpan | ✅ Didukung |
Membuat dan membaca dokumen dengan data utf | ✅ Didukung |
Membuat koleksi | ✅ Didukung |
Membuat koleksi dua kali konflik | ✅ Didukung |
Membuat koleksi dengan kebijakan indeks kustom | ⚠️ Belum diimplementasikan |
Membuat koleksi dengan kedaluwarsa TTL | ✅ Didukung |
Membuat database | ✅ Didukung |
Membuat database dua kali berkonflik | ✅ Didukung |
Membuat dokumen | ✅ Didukung |
Membuat koleksi yang dipartisi | ✅ Didukung |
Menghapus koleksi | ✅ Didukung |
Menghapus database | ✅ Didukung |
Menghapus dokumen | ✅ Didukung |
Mendapatkan dan mengubah performa pengumpulan | ⚠️ Belum diimplementasikan |
Sisipkan dokumen besar | ✅ Didukung |
Dokumen patch | ⚠️ Belum diimplementasikan |
Melakukan kueri pada koleksi yang dipartisi secara paralel | ⚠️ Belum diimplementasikan |
Kueri dengan agregat | ⚠️ Belum diimplementasikan |
Kueri dengan dan filter | ⚠️ Belum diimplementasikan |
Kueri dengan dan filter dan proyeksi | ⚠️ Belum diimplementasikan |
Pencarian dengan persamaan | ✅ Didukung |
Kueri dengan id yang sama | ✅ Didukung |
Kueri dengan gabungan | ⚠️ Belum diimplementasikan |
Kueri dengan urutan menurut | ✅ Didukung |
Kueri dengan urutan menurut untuk koleksi yang dipartisi | ⚠️ Belum diimplementasikan |
Kueri dengan urutan menurut angka | ✅ Didukung |
Kueri dengan urutan menurut string | ⚠️ Belum diimplementasikan |
Kueri dengan paginasi | ⚠️ Belum diimplementasikan |
Kueri dengan operator rentang tanggal dan waktu | ⚠️ Belum diimplementasikan |
Kueri dengan operator rentang pada angka | ⚠️ Belum diimplementasikan |
Kueri dengan operator rentang pada string | ⚠️ Belum diimplementasikan |
Kueri dengan gabungan tunggal | ⚠️ Belum diimplementasikan |
Kueri dengan matematika string dan operator array | ⚠️ Belum diimplementasikan |
Kueri dengan subdokumen | ⚠️ Belum diimplementasikan |
Kueri dengan dua gabungan | ⚠️ Belum diimplementasikan |
Kueri dengan dua gabungan dan filter | ⚠️ Belum diimplementasikan |
Baca koleksi | ✅ Didukung |
Membaca umpan koleksi | ⚠️ Belum diimplementasikan |
Membaca database | ✅ Didukung |
Membaca umpan database | ⚠️ Belum diimplementasikan |
Membaca dokumen | ✅ Didukung |
Baca umpan dokumen | ✅ Didukung |
Ganti dokumen | ✅ Didukung |
Unit Permintaan | ⚠️ Belum diimplementasikan |
Prosedur tersimpan | ❌ Tidak direncanakan |
Memicu | ❌ Tidak direncanakan |
UDFs | ❌ Tidak direncanakan |
Perbarui koleksi | ⚠️ Belum diimplementasikan |
Memperbarui dokumen | ✅ Didukung |
Batasan
Selain fitur yang belum didukung atau belum direncanakan, daftar berikut mencakup batasan emulator saat ini.
- .NET SDK untuk Azure Cosmos DB tidak mendukung eksekusi massal di emulator.
- .NET dan Java SDK tidak mendukung mode HTTP di emulator.
Menginstal sertifikat untuk Java SDK
Saat menggunakan Java SDK untuk Azure Cosmos DB dengan versi emulator ini dalam mode https, perlu untuk menginstal sertifikatnya ke penyimpanan kepercayaan Java lokal Anda.
Dapatkan sertifikat
bash
Di jendela, jalankan hal berikut:
# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
Menginstal sertifikat
Navigasikan ke direktori penginstalan java Anda di mana cacerts
file berada (ganti di bawah ini dengan direktori yang benar):
cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"
Impor sertifikasi (Anda mungkin dimintai kata sandi, nilai defaultnya adalah "changeit"):
keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH
Jika Anda mendapatkan kesalahan karena alias sudah ada, hapus lalu jalankan di atas lagi:
keytool -cacerts -delete -alias cosmos_emulator
Gunakan dalam alur kerja integrasi berkelanjutan
Ada banyak manfaat untuk menggunakan kontainer Docker dalam alur CI/CD, terutama untuk sistem stateful seperti database. Ini bisa dalam hal efektivitas biaya, performa, keandalan, dan konsistensi suite pengujian Anda.
Emulator dapat dimasukkan sebagai bagian alur CI/CD. Anda dapat merujuk ke repositori GitHub ini yang menyediakan contoh cara menggunakan emulator sebagai bagian dari alur kerja GitHub Actions CI untuk aplikasi .NET, Python, Java, dan Go pada kedua x64
dan ARM64
arsitektur (ditunjukkan untuk pelari Linux menggunakan ubuntu
).
Berikut adalah contoh alur kerja GITHub Actions CI yang menunjukkan cara mengonfigurasi emulator sebagai kontainer layanan GitHub Actions sebagai bagian dari pekerjaan dalam alur kerja. GitHub mengurus memulai kontainer Docker dan menghancurkannya ketika pekerjaan selesai, tanpa perlu intervensi manual (seperti menggunakan docker run
perintah).
name: CI demo app
on:
push:
branches: [main]
paths:
- 'java-app/**'
pull_request:
branches: [main]
paths:
- 'java-app/**'
jobs:
build-and-test:
runs-on: ubuntu-latest
services:
cosmosdb:
image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
ports:
- 8081:8081
env:
PROTOCOL: https
env:
COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}
steps:
- name: Set up Java
uses: actions/setup-java@v3
with:
distribution: 'microsoft'
java-version: '21.0.0'
- name: Export Cosmos DB Emulator Certificate
run: |
sudo apt update && sudo apt install -y openssl
openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert
cat cosmos_emulator.cert
$JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
- name: Checkout repository
uses: actions/checkout@v4
- name: Run tests
run: cd java-app && mvn test
Pekerjaan ini berjalan pada runner Ubuntu dan menggunakan image Docker mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
sebagai wadah layanan. Ini menggunakan variabel lingkungan untuk mengonfigurasi string koneksi, nama database, dan nama kontainer. Karena dalam hal ini pekerjaan berjalan langsung di mesin runner GitHub Actions, langkah Jalankan pengujian dalam pekerjaan dapat mengakses emulator dapat diakses menggunakan localhost:8081
(8081
adalah port yang diekspos oleh emulator).
Langkah Ekspor Sertifikat Emulator Cosmos DB khusus untuk aplikasi Java karena Azure Cosmos DB Java SDK saat ini tidak mendukung HTTP
mode di emulator. Variabel PROTOCOL
lingkungan diatur ke https
di bagian services
dan langkah ini mengekspor sertifikat emulator dan mengimpornya ke keystore Java. Hal yang sama juga berlaku untuk .NET.
Melaporkan masalah
Jika Anda mengalami masalah saat menggunakan versi emulator ini, buka masalah di repositori GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) dan tandai dengan label cosmosEmulatorVnextPreview
.