Linux tabanlı emülatör - vNext (önizleme)

  • Şunlara uygulanır: ✅ NoSQL

Azure Cosmos DB öykünücüsünün yeni nesli tamamen Linux tabanlıdır ve Docker kapsayıcısı olarak kullanılabilir. Çok çeşitli işlemcilerde ve işletim sistemlerinde çalıştırmayı destekler.

Important

Öykünücünün bu sürümü yalnızca belirli bir özellik alt kümesiyle gateway modunda NoSQL api'sini destekler. Daha fazla bilgi için bkz . özellik desteği.

Prerequisites

Installation

Docker kapsayıcı görüntüsünü docker pull kullanarak alın. Kapsayıcı görüntüsü üzerinde mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview olarak yayımlanır.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

Koşmak

Kapsayıcıyı çalıştırmak için kullanın docker run. Daha sonra, kapsayıcının çalıştığını doğrulamak için kullanın docker ps .

docker run --detach --publish 8081:8081 --publish 8080:8080 --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>

Öykünücü iki bileşen içerir:

  • Veri Gezgini - Öykünücüdeki verileri etkileşimli olarak keşfedin. Varsayılan olarak, bu bileşen bağlantı noktasında 1234çalışır.
  • Azure Cosmos DB öykünücüsü - Azure Cosmos DB veritabanı hizmetinin yerel sürümü. Varsayılan olarak, bu bileşen bağlantı noktasında 8081çalışır.

Öykünücü ağ geçidi uç noktası, 8081 adresinde http://localhost:8081 bağlantı noktasını kullanır. Veri Gezgini gitmek için web tarayıcınızda http://localhost:1234 adresini kullanın. Ağ geçidi uç noktası genellikle hemen kullanılabilir, ancak Veri Gezgini başlatılması birkaç saniye sürebilir.

Sağlık soruşturması

Öykünücü, bağlantı noktasında bir durum yoklama uç noktasını kullanıma sunar. Öykünücünün tam olarak başlatılıp istekleri kabul etmeye hazır olduğu zamanı belirlemek için bu uç noktayı kullanın.

Aşağıdaki uç noktalar kullanılabilir:

Note

Eski günlük iletisi System is now fully ready to accept requests geriye dönük uyumluluk için yine de gönderilir, ancak gelecekteki bir sürümde kaldırılabilir. Bunun yerine hazır olma denetimleri için sağlık probunu kullanın.

HTTPS modu

.NET ve Java SDK'ları öykünücüde HTTP modunu desteklemez. Öykünücünün bu sürümü varsayılan olarak HTTP ile başladığından, kapsayıcıyı başlatırken HTTPS'yi açıkça etkinleştirmeniz gerekir (aşağıya bakın). Java SDK'sı için ayrıca sertifikalarını yüklemeniz gerekir.

docker run --detach --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

Kalıcı veri birimleriyle HTTPS kullandığınızda öykünücü başlangıçta SSL sertifikalarını otomatik olarak yeniden oluşturur, bu nedenle sertifika yenilemeyi yönetmeniz gerekmez.

Docker komutları

Aşağıdaki tabloda öykünücüyü yapılandırmak için kullanılabilen Docker komutları özetlemektedir. Bu tabloda ilgili bağımsız değişkenler, ortam değişkenleri, izin verilen değerler, varsayılan ayarlar ve her komutun açıklamaları açıklanır.

Gereksinim Arg Env İzin verilen değerler Varsayılan Description
Ayarları kapsayıcıdan stdout'a yazdırma --help, -h N/A N/A N/A Kullanılabilir yapılandırmayla ilgili bilgileri görüntüleme
Cosmos uç noktasının bağlantı noktasını ayarla --port [INT] Port INT 8081 Kapsayıcıdaki Cosmos uç noktasının portu. Yine de bu bağlantı noktasını yayımlamanız gerekir (örneğin, -p 8081:8081).
Cosmos uç noktası tarafından kullanılan protokolü belirtme --protocol PROTOKOL https, http, https-insecure http Kapsayıcıdaki Cosmos uç noktasının protokolü.
Veri gezginini etkinleştirme --enable-explorer ENABLE_EXPLORER true, false true Cosmos Veri Gezgini aynı kapsayıcıda çalıştırmayı etkinleştirin.
Veri gezgini tarafından kullanılan bağlantı noktasını ayarlama --explorer-port KEŞİFÇİ_PORTU INT 1234 Kapsayıcıda Cosmos Veri Gezgini bağlantı noktası. Yine de bu bağlantı noktasını yayımlamanız gerekir (örneğin, -p 1234:1234).
Veri gezgini tarafından kullanılan protokolü belirtme --explorer-protocol KAŞİF_PROTOKOLÜ https, http, https-insecure <the value of --protocol> Kapsayıcıda Cosmos Veri Gezgini protokolü. Cosmos uç noktasındaki protokol ayarını varsayılan olarak kullanır.
Ağ geçidi genel uç noktasını özelleştirme --gateway-endpoint AĞ GEÇİDİ HALKA AÇIK UÇ NOKTASI N/A localhost Genel ağ geçidi uç noktası. Varsayılan olarak localhost değerini alır.
Dosya aracılığıyla anahtarı belirtin --key-file [PATH] ANAHTAR_DOSYA DİZİN <default secret> Varsayılan anahtarı dosyada belirtilen anahtarla geçersiz kılın. Bu dosyayı kapsayıcıya bağlamanız gerekir (örneğin, KEY_FILE=/mykey ise, docker çalıştırmanıza aşağıdaki gibi bir seçenek eklersiniz: --mount type=bind,source=./myKey,target=/myKey)
Veri yolunu ayarlama --data-path [PATH] DATA_PATH DİZİN /data Veriler için bir dizin belirtin. Sık kullanılan docker run --mount seçeneği ile (örneğin, DATA_PATH=/usr/cosmos/data ise, docker çalıştırma komutunuza aşağıdakine benzer bir seçenek ekleyin: --mount type=bind,source=./.local/data,target=/usr/cosmos/data)
https için kullanılacak sertifika yolunu belirtin --cert-path [PATH] CERT_PATH DİZİN <default cert> Trafiğin güvenliğini sağlamak için sertifikanın yolunu belirtin. Bu dosyayı kapsayıcıya bağlamanız gerekir (örneğin, CERT_PATH=/mycert.pfx ise, docker çalıştırmanıza aşağıdaki gibi bir seçenek eklersiniz: --mount type=bind,source=./mycert.pfx,target=/mycert.pfx)
https için kullanılacak sertifika gizli dizisini belirtin N/A CERT_SECRET string <default secret> CERT_PATH'da belirtilen sertifikanın gizli dizisi.
Günlük düzeyini ayarlama --log-level [LEVEL] KAYIT_SEVİYESİ quiet, error, warn, , info, debug, trace info Emülatör ve veri gezgini tarafından yayılan günlüklerin detay seviyesi.
OpenTelemetry OTLP dışa aktarma özelliğini etkinleştir. --enable-otlp ENABLE_OTLP_EXPORTER true, false false OpenTelemetry tümleştirmesini etkinleştirin.
Konsol aktarıcısını etkinleştir --enable-console ENABLE_CONSOLE_EXPORTER true, false false Telemetri verilerinin konsol çıkışını etkinleştirin (hata ayıklama için kullanışlıdır).
Ayrıntılı modu etkinleştir --verbose AYRINTILI true, false false PostgreSQL loglarını (pglog) konsola yazdırmak için ayrıntılı modu etkinleştirin. Hata ayıklama için kullanışlıdır.
Sorgu arabelleği boyutunu ayarlama --query-buffer-size QUERY_BUFFER_SIZE_KB INT 4096 (4 MB), maksimum 65536 (64 MB) Sorgu sonucu arabellekleri için maksimum boyut, KB cinsindendir. Büyük sorgularda HTTP 500 hatalarıyla karşılaşırsanız bunu artırın.
Tanılama bilgilerinin Microsoft'a gönderilmesini etkinleştirme --enable-telemetry TELEMETRİYİ_ETKİNLEŞTİR true, false true Öykünücüyü geliştirmemize yardımcı olmak için Kullanım verilerini Microsoft'a göndermeyi etkinleştirin.

Özellik desteği

Bu öykünücü etkin geliştirme ve önizleme aşamasındadır. Sonuç olarak, tüm Azure Cosmos DB özellikleri desteklenmez. Bazı özellikler gelecekte de desteklenmeyecektir. Bu tablo çeşitli özelliklerin durumunu ve destek düzeylerini içerir.

Feature Support
Batch API'si ✅ Destekli
Toplu API ✅ Destekli
Değişiklik Beslemesi ✅ Destekli
Utf verileriyle belge oluşturma ve okuma ✅ Destekli
Koleksiyon oluşturma ✅ Destekli
Koleksiyon oluşturmanın tekrarı çatışma yaratır ✅ Destekli
Özel dizin ilkesiyle koleksiyon oluşturma ⚠️ İşlem yapılmaz
Ttl süre sonu ile koleksiyon oluşturma ✅ Destekli
Veritabanı oluşturma ✅ Destekli
İki kez veritabanı oluşturma çakışması ✅ Destekli
Belge oluşturma ✅ Destekli
Bölümlenmiş koleksiyon oluşturma ✅ Destekli
Koleksiyonu silme ✅ Destekli
Veritabanını silme ✅ Destekli
Belgeyi silme ✅ Destekli
Koleksiyon performansını elde et ve değiştir ⚠️ Henüz uygulanmadı
Büyük belge ekleme ✅ Destekli
Yama belgesi ✅ Destekli
Bölümlenmiş koleksiyonu paralel olarak sorgulama ⚠️ Henüz uygulanmadı
Toplamalar içeren sorgu ✅ Destekli
ile sorgulama ve filtreleme ✅ Destekli
Sorgulama, filtreleme ve projeksiyon ile ✅ Destekli
Eşitlik içeren sorgu ✅ Destekli
id'ye eşit olan sorgu ✅ Destekli
Birleştirmelerle sorgulama ✅ Destekli
Sıralama ölçütüyle sorgulama ✅ Destekli
Bölümlenmiş koleksiyon için sıralama ölçütüyle sorgulama ✅ Destekli
Sayılara göre sıralı sorgu ✅ Destekli
Dizelere göre sıralı sorgu ✅ Destekli
Sayfalama içeren sorgulama ✅ Destekli
Tarih saatleriyle aralık işleçlerini kullanarak sorgulama ✅ Destekli
Sayılarda aralık işleçleriyle sorgulama ✅ Destekli
Dizelerdeki aralık işleçleriyle sorgulama ✅ Destekli
Tek birleşimli sorgu ✅ Destekli
Dize matematik ve dizi işleçleriyle sorgulama ✅ Destekli
Alt belgeler içeren sorgu ✅ Destekli
İki birleşimli sorgu ✅ Destekli
İki birleştirme ve filtre içeren sorgu ✅ Destekli
Koleksiyonu oku ✅ Destekli
Koleksiyon akışını okuma ⚠️ Henüz uygulanmadı
Veritabanını okuma ✅ Destekli
Veritabanı akışını okuma ⚠️ Henüz uygulanmadı
Belgeyi okuma ✅ Destekli
Belge akışını okuma ✅ Destekli
Belgeyi değiştir ✅ Destekli
Talep Birimleri ⚠️ Henüz uygulanmadı
Saklı prosedürler ❌ Planlı değil
Tetikleyiciler ❌ Planlı değil
UDF'ler ❌ Planlı değil
Koleksiyonu güncelleştirme ⚠️ İşlem yapılmaz
Belgeyi güncelleştirme ✅ Destekli
Hedef noktası sunar ⚠️ İşlem yapılmaz
Kullanıcı uç birimi ⚠️ İşlem yapılmaz
İzinler uç noktası ⚠️ İşlem yapılmaz
İstemci Şifreleme Anahtarları (CEK) ⚠️ İşlem yapılmaz

Note

İşlem yok olarak işaretlenen özellikler istekleri kabul eder ve geçerli HTTP durum kodları döndürür, ancak temel alınan işlemi yürütmez. Kodunuz bozulmaz, ancak işlevsel davranış için bu özelliklere bağımlı değildir. Uyumluluk için özel dizin ilkeleri ve koleksiyon güncelleştirmeleri kabul edilir, ancak sorgular özel dizinler tarafından iyileştirilmemiştir.

Sınırlamalar

Henüz desteklenmeyen veya planlanmamış özelliklere ek olarak, aşağıdaki liste öykünücünün geçerli sınırlamalarını içerir.

  • Azure Cosmos DB için .NET SDK'sı öykünücüde toplu yürütmeyi desteklemez.
  • Büyük sorgu sonuçlarında HTTP 500 hataları alırsanız, sorgu arabelleği boyutunu --query-buffer-size bayrağı veya QUERY_BUFFER_SIZE_KB ortam değişkeniyle artırın. Varsayılan değer 4096 KB (4 MB) ve üst sınır KB (65536MB) olur64.

Java SDK için sertifika yükleme

Java SDK'sını Azure Cosmos DB için https modunda öykünücünün bu sürümüyle kullanırken, sertifikalarını yerel Java güven deponuza yüklemeniz gerekir.

Sertifika alma

Bir bash pencerede aşağıdakileri çalıştırın:

# 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

Sertifika yükleme

Dosyanın bulunduğu cacerts java yüklemenizin dizinine gidin (aşağıdaki değerini doğru dizinle değiştirin):

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

Sertifikayı içeri aktarın (parola girmeniz istenebilir, varsayılan değer "changeit"dir):

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

Diğer ad zaten var olduğundan bir hata alırsanız, diğer adı silin ve yukarıdakini yeniden çalıştırın:

keytool -cacerts -delete -alias cosmos_emulator

OpenTelemetry desteği

OpenTelemetry, telemetri verilerini izleme, oluşturma, toplama ve dışarı aktarma için araçlar, API'ler ve SDK'lardan oluşan bir koleksiyon sağlayan bir açık kaynak gözlemlenebilirlik çerçevesidir. OpenTelemetry Protokolü (OTLP), OpenTelemetry tarafından bileşenler arasında telemetri verilerini iletmek için kullanılan protokoldür.

Uygulamanızı izlemek ve iz sürmek için öykünücü ile OpenTelemetry kullanabilirsiniz. Öykünücü, Docker kapsayıcısı çalıştırılırken ortam değişkenleri veya komut satırı bayrakları aracılığıyla yapılandırılabilir telemetri seçeneklerini destekler.

Emülatör aşağıdaki ölçümleri dışarı aktarır. Bunlar OTLP'yi destekleyen ve veritabanının performansı ve durumu hakkında değerli içgörüler sağlayan ölçüm arka ucu aracılığıyla kullanılabilir:

  • İstek Oranları: Farklı işlem türleri için trafik desenlerini gösterir
  • Sorgu Yürütme Süreleri: Farklı sorguları yürütmek için geçen süreyi ölçer
  • Kaynak Kullanımı: CPU, bellek kullanımı ve bağlantı havuzu ölçümleri
  • Hata Oranları: Türe ve uç noktaya göre hataları izleme

Note

Öykünücü, OTLP dışarı aktarıcısı için koşullu TLS'yi destekler, böylece güvenli bağlantılar gerektiren gözlemlenebilirlik platformlarıyla tümleştirebilirsiniz.

Örnekleri içeren ayrıntılı yönergeler GitHub deposunda bulunabilir.

Sürekli tümleştirme iş akışında kullanma

Özellikle veritabanları gibi durum bilgisi olan sistemler için CI/CD işlem hatlarında Docker kapsayıcılarını kullanmanın birçok avantajı vardır. Bu, test paketlerinizin maliyet verimliliği, performansı, güvenilirliği ve tutarlılığı açısından olabilir.

Öykünücü, CI/CD işlem hatlarının bir parçası olarak eklenebilir. GitHub Actions CI iş akışının bir parçası olarak .NET, Python, Java ve Go uygulamaları için öykünücünün nasıl kullanıldığını gösteren örnekler sağlayan bu GitHub deposuna başvurabilirsiniz. Bu örnekler, hem x64 hem de ARM64 mimarileri üzerinde Linux çalıştırıcısı için ubuntu kullanılarak gösterilmiştir.

Burada, bir işin parçası olarak öykünücüyü GitHub Actions hizmet kapsayıcısı olarak yapılandırmayı gösteren bir GitHub Actions CI iş akışı örneği verilmiştir. GitHub Docker kapsayıcısını başlatır ve iş tamamlandığında el ile müdahaleye gerek kalmadan (docker run komutunu kullanmak gibi) yok eder.

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

Bu iş bir Ubuntu çalıştırıcısı üzerinde çalışır ve Hizmet kapsayıcısı mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview olarak Docker görüntüsünü kullanır. Bağlantı dizesini, veritabanı adını ve kapsayıcı adını yapılandırmak için ortam değişkenlerini kullanır. İşin doğrudan GitHub Actions çalıştırıcı makinesinde çalıştığı bu durumda, işin Run tests adımında öykünücüye localhost:8081 aracılığıyla erişilebilir (8081 öykünücü tarafından sunulan bağlantı noktasıdır).

Java uygulamalarına özgü olan Cosmos DB Öykünücüsü Sertifikasını Dışarı Aktar adımı, Azure Cosmos DB Java SDK'sı şu anda öykünücüde HTTP modunu desteklemediği için gereklidir. PROTOCOL ortam değişkeni, https bölümünde services olarak ayarlanır ve bu adım öykünücü sertifikasını dışarı aktarır ve Java anahtar deposuna aktarır. Aynı durum .NET için de geçerlidir.

Raporlama sorunları

Öykünücünün bu sürümünü kullanırken sorunlarla karşılaşırsanız GitHub deposunda (https://github.com/Azure/azure-cosmos-db-emulator-docker) bir sorun açın ve cosmosEmulatorVnextPreview etiketiyle etiketleyin.

  • Last updated on