Pasang dan gunakan Emulator Azure Cosmos DB untuk pengembangan dan pengujian lokal

BERLAKU UNTUK: Nosql MongoDB Cassandra Gremlin Meja

Emulator Azure Cosmos DB menyediakan lingkungan lokal yang meniru layanan Azure Cosmos DB untuk tujuan pengembangan. Dengan menggunakan Emulator Azure Cosmos DB, Anda dapat mengembangkan dan menguji aplikasi secara lokal, tanpa membuat langganan Azure atau dikenakan biaya apa pun. Jika Anda merasa puas dengan cara kerja aplikasi Anda di Emulator Azure Cosmos DB, Anda dapat beralih menggunakan akun Azure Cosmos DB di cloud. Artikel ini menjelaskan cara memasang dan menggunakan emulator di lingkungan Windows, Linux, macOS, dan docker Windows.

Unduh emulator

Untuk memulai, unduh dan pasang versi terbaru Emulator Azure Cosmos DB di komputer lokal Anda. Artikel catatan rilis emulator mencantumkan semua versi yang tersedia dan pembaruan fitur yang dibuat di setiap rilis.

Unduh Emulator Azure Cosmos DB

Anda dapat mengembangkan aplikasi menggunakan Emulator Azure Cosmos DB dengan akun menggunakan API untuk NoSQL, Apache Cassandra, MongoDB, Apache Gremlin, dan Table. Saat ini penjelajah data di emulator sepenuhnya mendukung penayangan data SQL saja; data yang dibuat menggunakan aplikasi klien MongoDB, Gremlin/Graph, dan Cassandra saat ini tidak dapat dilihat. Untuk mempelajari selengkapnya, lihat cara tersambung ke titik akhir emulator dari berbagai API.

Bagaimana cara kerja emulator?

Emulator Azure Cosmos DB menyediakan emulasi fidelitas tinggi dari layanan Azure Cosmos DB. Ini mendukung fungsionalitas yang setara dengan Azure Cosmos DB, yang mencakup pembuatan data, data kueri, provisi dan penskalaan kontainer, serta menjalankan prosedur dan pemicu yang disimpan. Anda dapat mengembangkan dan menguji aplikasi menggunakan Emulator Azure Cosmos DB, dan menyebarkannya ke Azure dalam skala global dengan memperbarui titik akhir koneksi Azure Cosmos DB.

Meskipun emulasi layanan Azure Cosmos DB bersifat setia, implementasi emulator berbeda dari layanan. Misalnya, emulator menggunakan komponen OS standar seperti sistem file lokal untuk persistensi, dan tumpukan protokol HTTPS untuk konektivitas. Fungsionalitas yang bergantung pada infrastruktur Azure seperti replikasi global, latensi milidetik satu-digit untuk baca/tulis, dan tingkat konsistensi yang dapat disetel tidak berlaku saat Anda menggunakan emulator.

Perbedaan antara emulator dan layanan cloud

Karena Emulator Azure Cosmos DB menyediakan lingkungan emulasi yang berjalan di stasiun kerja pengembang lokal, ada beberapa perbedaan fungsionalitas antara emulator dan akun Azure Cosmos DB di cloud:

  • Saat ini panel Data Explorer di emulator sepenuhnya mendukung API hanya untuk klien NoSQL. Tampilan dan operasi Data Explorer untuk API Azure Cosmos DB seperti MongoDB, Table, Graph, dan Cassandra API tidak sepenuhnya didukung.

  • Emulator hanya mendukung satu akun tetap dan kunci primer yang dikenal. Anda tidak dapat meregenerasi kunci saat menggunakan Emulator Azure Cosmos DB, namun Anda dapat mengubah kunci default dengan menggunakan opsi baris perintah.

  • Dengan emulator, Anda dapat membuat akun Azure Cosmos DB hanya dalam mode throughput yang disediakan ; saat ini tidak mendukung mode tanpa server .

  • Emulator bukan layanan yang dapat diskalakan dan tidak mendukung kontainer dalam jumlah besar. Saat menggunakan Emulator Azure Cosmos DB, secara default, Anda dapat membuat hingga 25 kontainer ukuran tetap pada 400 RU/dtk (hanya didukung menggunakan SDK Azure Cosmos DB), atau 5 kontainer tak terbatas. Untuk informasi selengkapnya tentang cara mengubah nilai ini, lihat artikel Mengatur nilai PartitionCount.

  • Emulator tidak menawarkan tingkat konsistensi Azure Cosmos DB yang lain seperti layanan cloud.

  • Emulator tidak menawarkan replikasi multi-wilayah.

  • Karena salinan Emulator Azure Cosmos DB Anda mungkin tidak selalu diperbarui dengan perubahan terbaru dalam layanan Azure Cosmos DB, Anda harus selalu merujuk ke perencana kapasitas Azure Cosmos DB untuk memperkirakan kebutuhan throughput (RUs) aplikasi Anda secara akurat.

  • Emulator mendukung ukuran properti ID maksimum 254 karakter.

Memasang emulator

Sebelum memasang emulator, pastikan Anda memiliki persyaratan perangkat keras dan perangkat lunak berikut:

  • Persyaratan perangkat lunak:

    • Saat ini, Windows Server 2016, 2019 atau Windows 10 OS host didukung. OS host dengan Layanan Domain Active Directory yang diaktifkan saat ini tidak didukung.
    • Sistem operasi 64 bit
  • Persyaratan perangkat lunak minimum:

    • RAM 2 GB
    • Ruang disk keras 10 GB tersedia
  • Untuk memasang, mengonfigurasi, dan menjalankan Emulator Azure Cosmos DB, Anda harus memiliki hak istimewa admin di komputer. Emulator akan menambahkan sertifikat dan juga menetapkan aturan firewall untuk menjalankan layanannya. Oleh karena itu hak admin diperlukan agar emulator dapat mengeksekusi operasi tersebut.

Untuk memulai, unduh dan pasang versi terbaru Emulator Azure Cosmos DB di komputer lokal Anda. Jika Anda menemukan masalah saat memasang emulator, lihat artikel pemecahan masalah emulator untuk men-debug.

Bergantung pada persyaratan sistem, Anda dapat menjalankan emulator di Windows, Docker untuk Windows, Linux, atau macOS seperti yang dijelaskan bagian berikutnya dalam artikel ini.

Periksa pembaruan emulator

Setiap versi emulator dilengkapi dengan serangkaian pembaruan fitur atau perbaikan bug. Untuk melihat versi yang tersedia, baca artikel catatan rilis emulator.

Setelah penginstalan, jika Anda telah menggunakan pengaturan default, data yang sesuai dengan emulator disimpan di lokasi %LOCALAPPDATA%\CosmosDBEmulator. Anda dapat mengonfigurasikan lokasi yang lain dengan menggunakan pengaturan jalur data opsional; yakni /DataPath=PREFERRED_LOCATIONparameter baris perintah. Data dibuat dalam satu versi Emulator Azure Cosmos DB yang tidak dijamin dapat diakses saat menggunakan versi lain. Jika Anda perlu menyimpan data untuk jangka panjang, disarankan agar Anda menyimpan data tersebut di akun Azure Cosmos DB, bukan Emulator Azure Cosmos DB.

Menggunakan emulator di Windows

Emulator Azure Cosmos DB dipasang di lokasi C:\Program Files\Azure Cosmos DB Emulator secara default. Untuk memulai Emulator Azure Cosmos DB di Windows, pilih tombol Mulai atau tekan tombol Windows. Mulai ketik Emulator Azure Cosmos DB dan pilih emulator dari daftar aplikasi.

Pilih tombol Mulai atau tekan tombol Windows, mulai ketik Emulator Azure Cosmos DB, dan pilih emulator dari daftar aplikasi

Saat emulator telah dimulai, Anda akan melihat ikon di area notifikasi taskbar Windows. Ini secara otomatis membuka penjelajah data Azure Cosmos DB di browser Anda di URL URL https://localhost:8081/_explorer/index.html ini.

Pemberitahuan taskbar emulator lokal Azure Cosmos DB

Anda juga dapat memulai dan menghentikan emulator dari baris perintah atau PowerShell. Untuk informasi selengkapnya, lihat artikel referensi alat baris perintah.

Emulator Azure Cosmos DB secara default berjalan pada mesin lokal ("localhost") mendengarkan di port 8081. Alamat muncul sebagai https://localhost:8081/_explorer/index.html. Jika Anda menutup penjelajah dan ingin membukanya lagi nanti, Anda dapat membuka URL di browser Anda atau meluncurkannya dari Emulator Azure Cosmos DB di Ikon Baki Windows seperti yang ditunjukkan di bawah ini.

Peluncur penjelajah data emulator lokal Azure Cosmos DB

Menggunakan emulator di Linux atau macOS

Saat ini Emulator Azure Cosmos DB hanya dapat dijalankan di Windows. Jika menggunakan Linux atau macOS, sebaiknya gunakan Emulator Linux (Pratinjau) atau jalankan emulator di komputer virtual Windows yang di-host di hypervisor seperti Parallels atau VirtualBox.

Catatan

Setiap kali Anda menghidupkan ulang komputer virtual Windows yang dihosting di hypervisor, Anda harus mengimpor ulang sertifikat karena alamat IP komputer virtual berubah. Mengimpor sertifikat tidak diperlukan jika Anda telah mengonfigurasikan komputer virtual untuk mempertahankan alamat IP.

Gunakan langkah-langkah berikut untuk menggunakan emulator pada lingkungan Linux atau macOS:

  1. Jalankan perintah berikut dari komputer virtual Windows dan catat alamat IPv4:

    ipconfig.exe
    
  2. Dalam aplikasi Anda, ubah URL titik akhir untuk menggunakan alamat IPv4 yang ditampilkan ipconfig.exe bukan localhost.

  3. Dari Windows VM, luncurkan Emulator Azure Cosmos DB dari baris perintah menggunakan opsi berikut. Untuk detail tentang parameter yang didukung oleh baris perintah, lihat referensi alat baris perintah emulator:

    Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    
  4. Terakhir, Anda perlu menyelesaikan proses kepercayaan sertifikat antara aplikasi yang berjalan di lingkungan Linux atau Mac dan emulator. Anda bisa menggunakan salah satu dari dua opsi berikut untuk mengatasi sertifikat:

    1. Impor sertifikat TLS/SSL emulator ke dalam lingkungan Linux atau Mac atau
    2. Nonaktifkan validasi TLS/SSL di aplikasi

Opsi 1: Impor sertifikat TLS/SSL emulator

Bagian berikut menunjukkan cara mengimpor sertifikat TLS/SSL emulator ke lingkungan Linux dan macOS.

Lingkungan Linux

Jika Anda bekerja di Linux, .NET menyampaikan dalam OpenSSL untuk melakukan validasi:

  1. Ekspor sertifikat dalam format PFX. Opsi PFX tersedia saat memilih untuk mengekspor kunci privat.

  2. Salin file PFX itu ke dalam lingkungan Linux Anda.

  3. Konversikan file PFX menjadi file CRT

    openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
    
  4. Salin file CRT ke folder yang berisi sertifikat kustom dalam distribusi Linux Anda. Umumnya pada distribusi Debian, itu terletak di /usr/local/share/ca-certificates/.

    cp YourCTR.crt /usr/local/share/ca-certificates/
    
  5. Perbarui sertifikat TLS/SSL, yang akan memperbarui folder /etc/ssl/certs/.

    update-ca-certificates
    

Lingkungan macOS

Gunakan langkah-langkah berikut jika Anda sedang bekerja dengan Mac:

  1. Ekspor sertifikat dalam format PFX. Opsi PFX tersedia saat memilih untuk mengekspor kunci privat.

  2. Salin file PFX tersebut ke lingkungan Mac Anda.

  3. Buka aplikasi Akses Rantai Kunci dan impor file PFX.

  4. Buka daftar Sertifikat dan identifikasi sertifikat dengan nama localhost.

  5. Buka menu konteks untuk item tersebut, pilih Dapatkan Item dan di bawah opsi Kepercayaan>Saat menggunakan sertifikat, pilih Selalu Percaya.

    Buka menu konteks untuk item tertentu tersebut, pilih Dapatkan Item dan di bawah opsi Kepercayaan - Saat menggunakan opsi sertifikat ini, pilih Selalu Percaya

Opsi 2: Nonaktifkan validasi SSL dalam aplikasi

Menonaktifkan validasi SSL hanya direkomendasikan untuk tujuan pengembangan dan tidak boleh dilakukan saat berjalan di lingkungan produksi. Contoh berikut menunjukkan cara menonaktifkan validasi SSL untuk aplikasi .NET dan Node.js.

Untuk aplikasi mana pun yang berjalan dalam kerangka kerja yang kompatibel dengan .NET Standard 2.1 atau yang lebih baru, kita dapat memanfaatkan CosmosClientOptions.HttpClientFactory:

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    HttpClientFactory = () =>
    {
        HttpMessageHandler httpMessageHandler = new HttpClientHandler()
        {
            ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
        };

        return new HttpClient(httpMessageHandler);
    },
    ConnectionMode = ConnectionMode.Gateway
};


CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);

Mengaktifkan akses ke emulator dari jaringan lokal

Jika Anda memiliki beberapa mesin menggunakan satu jaringan, dan jika Anda mengatur emulator di satu mesin serta ingin mengaksesnya dari mesin lain. Jika demikian, Anda perlu mengaktifkan akses ke emulator di jaringan lokal.

Anda dapat menjalankan emulator di jaringan lokal. Untuk mengaktifkan akses jaringan, tentukan opsi /AllowNetworkAccess di baris perintah, yang juga mengharuskan Anda menentukan /Key=key_string atau /KeyFile=file_name. Anda dapat menggunakan /GenKeyFile=file_name untuk membuat file dengan kunci acak di muka. Lalu Anda dapat meneruskannya ke /KeyFile=file_name atau /Key=contents_of_file.

Untuk mengaktifkan akses jaringan untuk pertama kalinya, pengguna harus mematikan emulator dan menghapus direktori data emulator %LOCALAPPDATA%\CosmosDBEmulator.

Autentikasikan koneksi saat menggunakan emulator

Seperti halnya Azure Cosmos DB di cloud, setiap permintaan yang Anda buat terhadap Emulator Azure Cosmos DB harus diautentikasi. Emulator Azure Cosmos DB hanya mendukung komunikasi aman melalui TLS. Emulator Azure Cosmos DB mendukung satu akun tetap dan kunci autentikasi terkenal untuk autentikasi kunci primer. Akun dan kunci ini adalah satu-satunya informasi masuk yang diizinkan untuk digunakan dengan Emulator Azure Cosmos DB. Yaitu:

Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Catatan

Kunci primer yang didukung oleh Emulator Azure Cosmos DB dimaksudkan untuk digunakan hanya dengan emulator. Anda tidak dapat menggunakan akun Azure Cosmos DB produksi Anda dan kunci dengan Emulator Azure Cosmos DB.

Catatan

Jika Anda telah memulai emulator dengan opsi /Key, maka gunakan kunci yang dihasilkan, kunci C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== default. Untuk informasi selengkapnya tentang opsi /Key, lihat Referensi alat baris perintah.

Sambungkan ke berbagai API dengan emulator ini

API untuk NoSQL

Setelah Emulator Azure Cosmos DB berjalan di desktop, Anda dapat menggunakan SDK Azure Cosmos DB yang didukung atau REST API Azure Cosmos DB untuk berinteraksi dengan emulator. Emulator Azure Cosmos DB juga menyertakan penjelajah data bawaan yang memungkinkan Anda membuat kontainer untuk API untuk NoSQL atau MongoDB. Dengan menggunakan penjelajah data, Anda dapat menampilkan dan mengedit item tanpa menulis kode apa pun.

// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
   "https://localhost:8081", 
    "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");

API untuk MongoDB

Setelah Emulator Azure Cosmos DB berjalan di desktop, Anda dapat menggunakan API Azure Cosmos DB untuk MongoDB untuk berinteraksi dengan emulator. Mulai emulator dari wantian perintah sebagai administrator dengan "/EnableMongoDbEndpoint". Kemudian gunakan string koneksi berikut untuk menyambungkan ke API untuk akun MongoDB:

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

API untuk Tabel

Setelah Emulator Azure Cosmos DB berjalan di desktop, Anda dapat menggunakan AZURE Cosmos DB API for Table SDK untuk berinteraksi dengan emulator. Mulai emulator dari wantian perintah sebagai administrator dengan "/EnableTableEndpoint". Selanjutnya jalankan kode berikut untuk menyambungkan ke API untuk akun Table:

using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Table;
using CloudTable = Microsoft.WindowsAzure.Storage.Table.CloudTable;
using CloudTableClient = Microsoft.WindowsAzure.Storage.Table.CloudTableClient;

string connectionString = "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;";

CloudStorageAccount account = CloudStorageAccount.Parse(connectionString);
CloudTableClient tableClient = account.CreateCloudTableClient();
CloudTable table = tableClient.GetTableReference("testtable");
table.CreateIfNotExists();
table.Execute(TableOperation.Insert(new DynamicTableEntity("partitionKey", "rowKey")));

API untuk Cassandra

Mulai emulator dari administrator wantian perintah dengan "/EnableCassandraEndpoint". Atau Anda juga dapat mengatur variabel lingkungan AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.

  1. Pasang Python 2.7

  2. Pasang Cassandra CLI/CQLSH

  3. Jalankan perintah berikut ini di jendela wantian perintah reguler:

    set Path=c:\Python27;%Path%
    cd /d C:\sdk\apache-cassandra-3.11.3\bin
    set SSL_VERSION=TLSv1_2
    set SSL_VALIDATE=false
    cqlsh localhost 10350 -u localhost -p C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== --ssl
    
  4. Di shell CQLSH, jalankan perintah berikut untuk tersambung ke titik akhir Cassandra:

    CREATE KEYSPACE MyKeySpace WITH replication = {'class':'MyClass', 'replication_factor': 1};
    DESCRIBE keyspaces;
    USE mykeyspace;
    CREATE table table1(my_id int PRIMARY KEY, my_name text, my_desc text);
    INSERT into table1 (my_id, my_name, my_desc) values( 1, 'name1', 'description 1');
    SELECT * from table1;
    EXIT
    

API untuk Gremlin

Mulai emulator dari administrator wantian perintah dengan "/EnableGremlinEndpoint". Atau Anda juga dapat mengatur variabel lingkungan AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

  1. Instal apache-tinkerpop-gremlin-console-3.6.0.

  2. Dari penjelajah data emulator buat database "db1" dan koleksi "coll1"; untuk kunci partisi, pilih "/name"

  3. Jalankan perintah berikut ini di jendela wantian perintah reguler:

    cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.6.0-bin\apache-tinkerpop-gremlin-console-3.6.0
    
    copy /y conf\remote.yaml conf\remote-localcompute.yaml
    notepad.exe conf\remote-localcompute.yaml
      hosts: [localhost]
      port: 8901
      username: /dbs/db1/colls/coll1
      password: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
      connectionPool: {
      enableSsl: false}
      serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0,
      config: { serializeResultToString: true  }}
    
    bin\gremlin.bat
    
  4. Di shell Gremlin, jalankan perintah berikut untuk tersambung ke titik akhir Gremlin:

    :remote connect tinkerpop.server conf/remote-localcompute.yaml
    :remote console
    :> g.V()
    :> g.addV('person1').property(id, '1').property('name', 'somename1')
    :> g.addV('person2').property(id, '2').property('name', 'somename2')
    :> g.V()
    

Copot pemasangan emulator lokal

Gunakan langkah-langkah berikut untuk copot pemasangan emulator:

  1. Keluar dari semua instans terbuka emulator lokal dengan mengeklik kanan ikon Emulator Azure Cosmos DB pada baki sistem, lalu pilih Keluar. Mungkin perlu waktu satu menit agar semua instans keluar.

  2. Di kotak pencarian Windows, ketik Fitur &Aplikasi dan pilih hasil Fitur & Aplikasi (Pengaturan sistem).

  3. Dalam daftar aplikasi, gulir ke Emulator Azure Cosmos DB, pilih itu, klik Copot pemasangan, lalu konfirmasi dan pilih Copot pemasangan lagi.

Langkah berikutnya

Dalam artikel ini, Anda telah mempelajari cara menggunakan emulator lokal untuk pengembangan lokal gratis. Sekarang Anda dapat melanjutkan ke artikel berikutnya: