Emulator berbasis Linux - vNext (pratinjau)

2025-06-25

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

Docker

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	string	`<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	✅ Didukung
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
UDF	❌ 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.