Instalace a použití Emulator azure Cosmos DB pro místní vývoj a testování
PLATÍ PRO: SQL API rozhraní API Cassandra
rozhraní Gremlin API
rozhraní API pro tabulky
rozhraní API služby Azure Cosmos DB pro MongoDB
Emulátor služby Azure Cosmos DB zajistí místní prostředí, které emuluje službu Azure Cosmos DB pro účely vývoje. Pomocí emulátoru služby Azure Cosmos DB můžete vyvíjet a testovat aplikace místně bez vytváření předplatného Azure a bez jakýchkoli nákladů. Až budete spokojeni s tím, jak vaše aplikace funguje v Emulator Azure Cosmos DB, můžete přejít na účet Azure Cosmos v cloudu. Tento článek popisuje, jak nainstalovat a používat emulátor na Windows, Linuxu, macOS a Windows prostředí dockeru.
Stažení emulátoru
Začněte tím, že si stáhnete a nainstalujete nejnovější verzi azure Cosmos DB Emulator na místním počítači. Článek s poznámkou k verzi emulátoru uvádí všechny dostupné verze a aktualizace funkcí, které byly provedeny v každé verzi.
Stažení Emulator databáze Azure Cosmos
Aplikace můžete vyvíjet pomocí azure Cosmos DB Emulator s účty rozhraní SQL, Cassandra, MongoDB, Gremlin a Table API. V současné době průzkumník dat v emulátoru plně podporuje prohlížení SQL dat. Data vytvořená pomocí MongoDB, Gremlin/Graph a klientských aplikací Cassandra se momentálně nezobrazují. Další informace najdete v tématu připojení ke koncovému bodu emulátoru z různých rozhraní API.
Jak emulátor funguje?
Emulátor služby Azure Cosmos DB s vysokou věrností emuluje službu Azure Cosmos DB. Podporuje ekvivalentní funkce jako Azure Cosmos DB, která zahrnuje vytváření dat, dotazování dat, zřizování a škálování kontejnerů a spouštění uložených procedur a triggerů. Aplikace můžete vyvíjet a testovat pomocí služby Azure Cosmos DB Emulator a nasazovat je do Azure v globálním měřítku aktualizací koncového bodu připojení azure Cosmos DB.
Přestože je emulace služby Azure Cosmos DB věrná, implementace emulátoru se od služby liší. Emulátor například používá standardní součásti operačního systému, jako je místní systém souborů pro trvalost a sada protokolů HTTPS pro připojení. Funkce, které spoléhají na infrastrukturu Azure, jako je globální replikace, latence jednociferné milisekundy pro čtení a zápisy, a při použití emulátoru se nedají upravitelné úrovně konzistence.
Data můžete migrovat mezi službou Azure Cosmos DB Emulator a službou Azure Cosmos DB pomocí nástroje pro migraci dat azure Cosmos DB.
Rozdíly mezi emulátorem a cloudovou službou
Vzhledem k tomu, že azure Cosmos DB Emulator poskytuje emulované prostředí, které běží na místní vývojářské pracovní stanici, existují některé rozdíly v funkcích mezi emulátorem a účtem Azure Cosmos v cloudu:
V současné době podokno Data Explorer v emulátoru plně podporuje pouze klienty rozhraní API SQL. Data Explorer Rozhraní API služby Azure Cosmos DB, jako jsou MongoDB, Table, Graph a Cassandra API, nejsou plně podporována.
Emulátor podporuje pouze jeden pevný účet a dobře známý primární klíč. Klíč nemůžete znovu vygenerovat při použití Emulator databáze Azure Cosmos, ale výchozí klíč můžete změnit pomocí možnosti příkazového řádku.
V emulátoru můžete vytvořit účet Azure Cosmos jenom v režimu zřízené propustnosti. V současné době nepodporuje bezserverový režim.
Emulátor není škálovatelná služba a nepodporuje velký počet kontejnerů. Při použití Emulator Azure Cosmos DB můžete ve výchozím nastavení vytvořit až 25 kontejnerů s pevnou velikostí na 400 RU/s (podporuje se jenom pomocí sad SDK azure Cosmos DB) nebo 5 neomezených kontejnerů. Další informace o tom, jak změnit tuto hodnotu, najdete v článku Nastavení hodnoty PartitionCount .
Emulátor nenabízí různé úrovně konzistence Azure Cosmos DB, jako je cloudová služba.
Emulátor nenabízí replikaci s více oblastmi.
Vzhledem k tomu, že kopie Emulator databáze Azure Cosmos nemusí být vždy aktuální s nejnovějšími změnami ve službě Azure Cosmos DB, měli byste vždy odkazovat na plánovač kapacity Azure Cosmos DB a přesně odhadnout požadavky vaší aplikace na propustnost (RU).
Emulátor podporuje maximální velikost vlastnosti ID 254 znaků.
Instalace emulátoru
Před instalací emulátoru se ujistěte, že máte následující požadavky na hardware a software:
Požadavky na software:
- V současné době se podporuje Windows Server 2016, 2019 nebo Windows 10 hostitelský operační systém. Hostitelský operační systém s povolenou službou Active Directory se v současné době nepodporuje.
- 64bitový operační systém
Minimální požadavky na hardware:
- 2 GB RAM
- 10 GB volného místa na disku
K instalaci, konfiguraci a spuštění emulátoru služby Azure Cosmos DB musíte mít v počítači oprávnění správce. Emulátor přidá certifikát a také nastaví pravidla brány firewall, aby mohla spouštět své služby. Proto jsou práva správce nezbytná k tomu, aby emulátor mohl tyto operace spouštět.
Začněte tím, že si stáhnete a nainstalujete nejnovější verzi azure Cosmos DB Emulator na místním počítači. Pokud při instalaci emulátoru narazíte na nějaké problémy, projděte si článek o řešení potíží s emulátorem , který se má ladit.
V závislosti na požadavcích na systém můžete emulátor spustit na Windows, Dockeru pro Windows, Linux nebo macOS, jak je popsáno v dalších částech tohoto článku.
Kontrola aktualizací emulátoru
Každá verze emulátoru obsahuje sadu aktualizací funkcí nebo oprav chyb. Informace o dostupných verzích najdete v článku poznámky k verzi emulátoru .
Pokud jste po instalaci použili výchozí nastavení, uloží se data odpovídající emulátoru do umístění %LOCALAPPDATA%\CosmosDBEmulator. Jiné umístění můžete nakonfigurovat pomocí volitelných nastavení cesty k datům; to je /DataPath=PREFERRED_LOCATION
parametr příkazového řádku. Data vytvořená v jedné verzi azure Cosmos DB Emulator nejsou zaručená, že budou přístupná při použití jiné verze. Pokud potřebujete data uchovávat po dlouhou dobu, doporučujeme tato data ukládat do účtu Azure Cosmos místo Emulator databáze Azure Cosmos DB.
Použití emulátoru na Windows
Služba Azure Cosmos DB Emulator je ve výchozím nastavení nainstalovaná v C:\Program Files\Azure Cosmos DB Emulator
umístění. Pokud chcete spustit Emulator databáze Azure Cosmos na Windows, vyberte tlačítko Start nebo stiskněte klávesu Windows. Začněte psát Azure Cosmos DB Emulator a vyberte emulátor v seznamu aplikací.
Po spuštění emulátoru se v oznamovací oblasti Windows hlavního panelu zobrazí ikona. Automaticky otevře Průzkumník dat Azure Cosmos v prohlížeči na této adrese URLhttps://localhost:8081/_explorer/index.html
.
Emulátor můžete také spustit a zastavit z příkazů příkazového řádku nebo PowerShellu. Další informace najdete v referenčním článku nástroje příkazového řádku .
Emulátor služby Azure Cosmos DB se ve výchozím nastavení spouští v místním počítači („localhost“) a naslouchá na portu 8081. Adresa se zobrazí jako https://localhost:8081/_explorer/index.html
. Pokud Průzkumníka zavřete a chcete ho později znovu otevřít, můžete otevřít adresu URL v prohlížeči nebo Průzkumníka spustit z emulátoru služby Azure Cosmos DB prostřednictvím ikony na hlavním panelu Windows, jak je zobrazeno níže.
Použití emulátoru v Linuxu nebo macOS
V současné době je možné Emulator databáze Azure Cosmos spustit jenom na Windows. Pokud používáte Linux nebo macOS, doporučujeme použít linuxový Emulator (Preview) nebo spustit emulátor v Windows virtuálním počítači hostovaného v hypervisoru, jako jsou parallels nebo VirtualBox.
Poznámka
Pokaždé, když restartujete Windows virtuální počítač hostovaný v hypervisoru, musíte certifikát znovu importovat, protože se změní IP adresa virtuálního počítače. Import certifikátu se nevyžaduje, pokud jste nakonfigurovali virtuální počítač tak, aby zachoval IP adresu.
K použití emulátoru v prostředích s Linuxem nebo macOS použijte následující kroky:
Z virtuálního počítače Windows spusťte následující příkaz a poznamenejte si adresu IPv4:
ipconfig.exe
V aplikaci změňte adresu URL koncového bodu tak, aby používala adresu IPv4 vrácenou
ipconfig.exe
místolocalhost
.Na virtuálním počítači Windows spusťte azure Cosmos DB Emulator z příkazového řádku pomocí následujících možností. Podrobnosti o parametrech podporovaných příkazovým řádkem najdete v referenčních informacích k nástrojům příkazového řádku emulátoru:
Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Nakonec je potřeba vyřešit proces důvěryhodnosti certifikátů mezi aplikací spuštěnou v prostředí Linuxu nebo Mac a emulátoru. K vyřešení certifikátu můžete použít jednu z následujících dvou možností:
Možnost 1: Import certifikátu TLS/SSL emulátoru
Následující části ukazují, jak importovat certifikát TLS/SSL emulátoru do prostředí s Linuxem a macOS.
Linuxové prostředí
Pokud pracujete na Linuxu, přepošle .NET na OpenSSL ověření:
Exportujte certifikát ve formátu PFX. Možnost PFX je k dispozici při výběru možnosti exportu privátního klíče.
Zkopírujte tento soubor PFX do prostředí Linuxu.
Převod souboru PFX na soubor CRT
openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
Zkopírujte soubor CRT do složky, která obsahuje vlastní certifikáty v distribuci Linuxu. Běžně se v distribucích Debianu nachází na
/usr/local/share/ca-certificates/
.cp YourCTR.crt /usr/local/share/ca-certificates/
Aktualizujte certifikáty TLS/SSL, které aktualizují
/etc/ssl/certs/
složku.update-ca-certificates
prostředí macOS
Pokud pracujete na Macu, postupujte následovně:
Exportujte certifikát ve formátu PFX. Možnost PFX je k dispozici při výběru možnosti exportu privátního klíče.
Zkopírujte tento soubor PFX do prostředí Mac.
Otevřete aplikaci Keychain Access a naimportujte soubor PFX.
Otevřete seznam certifikátů a identifikujte ho s názvem
localhost
.Otevřete místní nabídku pro danou položku, vyberte Získat položku a v části TrustWhen>pomocí této možnosti certifikátu vyberte Vždy důvěřovat.
Možnost 2: Zakázání ověřování SSL v aplikaci
Zakázání ověřování SSL se doporučuje jenom pro účely vývoje a nemělo by se provádět při spuštění v produkčním prostředí. Následující příklady ukazují, jak zakázat ověřování SSL pro aplikace .NET a Node.js.
Pro libovolnou aplikaci spuštěnou v rozhraní kompatibilní s .NET Standard 2.1 nebo novějším můžeme využít 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);
Povolení přístupu k emulátoru v místní síti
Pokud máte více počítačů používajících jednu síť a pokud nastavíte emulátor na jednom počítači a chcete k němu přistupovat z jiného počítače. V takovém případě musíte povolit přístup k emulátoru v místní síti.
Emulátor můžete spustit v místní síti. Pokud chcete povolit přístup k síti, zadejte /AllowNetworkAccess
možnost na příkazovém řádku, která také vyžaduje, abyste zadali /Key=key_string
nebo /KeyFile=file_name
. Můžete použít /GenKeyFile=file_name
k vygenerování souboru s náhodným klíčem předem. Pak to můžete předat nebo /KeyFile=file_name
/Key=contents_of_file
.
Pokud chcete povolit přístup k síti poprvé, měl by uživatel vypnout emulátor a odstranit datový adresář emulátoru %LOCALAPPDATA%\CosmosDBEmulator.
Ověřování připojení při použití emulátoru
Stejně jako u Azure Cosmos DB v cloudu musí být ověřen každý požadavek pro emulátor služby Azure Cosmos DB. Azure Cosmos DB Emulator podporuje pouze zabezpečenou komunikaci prostřednictvím protokolu TLS. Azure Cosmos DB Emulator podporuje jeden pevný účet a známý ověřovací klíč pro ověřování primárního klíče. Tento účet a klíč jsou jediné přihlašovací údaje, které je možné použít s emulátorem služby Azure Cosmos DB. Jsou to tyto:
Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Poznámka
Primární klíč podporovaný službou Azure Cosmos DB Emulator je určený jenom pro emulátor. S emulátorem služby Azure Cosmos DB nemůžete používat svůj provozní účet a klíč služby Azure Cosmos DB.
Poznámka
Pokud jste spustili emulátor s možností /Key, použijte vygenerovaný klíč místo výchozího klíče C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
. Další informace o možnosti /Klíč najdete v referenčních informacích k nástrojům příkazového řádku.
Připojení k různým rozhraním API pomocí emulátoru
SQL API
Jakmile máte azure Cosmos DB Emulator spuštěnou na ploše, můžete k interakci s emulátorem použít libovolnou podporovanou sadu SDK služby Azure Cosmos DB nebo rozhraní REST API služby Azure Cosmos DB. Azure Cosmos DB Emulator obsahuje také integrovaný průzkumník dat, který umožňuje vytvářet kontejnery pro rozhraní API SQL nebo Azure Cosmos DB pro rozhraní Mongo DB API. Pomocí Průzkumníka dat můžete zobrazit a upravovat položky bez psaní kódu.
// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
"https://localhost:8081",
"C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");
Rozhraní API služby Azure Cosmos DB pro MongoDB
Jakmile máte službu Azure Cosmos DB Emulator spuštěnou na ploše, můžete k interakci s emulátorem použít rozhraní API služby Azure Cosmos DB pro MongoDB. Spusťte emulátor z příkazového řádku jako správce s parametrem /EnableMongoDbEndpoint. Pak se pomocí následujícího připojovacího řetězce připojte k účtu rozhraní MongoDB API:
mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true
Rozhraní Table API
Jakmile máte azure Cosmos Emulator DB spuštěnou na ploše, můžete k interakci s emulátorem použít sadu Azure Cosmos DB rozhraní API pro tabulky SDK. Spusťte emulátor z příkazového řádku jako správce s parametrem /EnableTableEndpoint. Potom spusťte následující kód pro připojení k účtu rozhraní API tabulky:
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")));
Rozhraní Cassandra API
Spusťte emulátor z příkazového řádku správce s parametrem /EnableCassandraEndpoint. Alternativně můžete také nastavit proměnnou AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true
prostředí .
V okně běžného příkazového řádku spusťte následující příkazy:
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
V prostředí CQLSH spusťte následující příkazy pro připojení ke koncovému bodu 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
Rozhraní Gremlin API
Spusťte emulátor z příkazového řádku správce s parametrem /EnableGremlinEndpoint. Případně můžete také nastavit proměnnou prostředí. AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true
V průzkumníku dat emulátoru vytvořte databázi db1 a kolekci coll1; pro klíč oddílu zvolte /name.
V okně běžného příkazového řádku spusťte následující příkazy:
cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.3.4-bin\apache-tinkerpop-gremlin-console-3.3.4 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
V prostředí Gremlin spusťte následující příkazy pro připojení ke koncovému bodu 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()
Odinstalace místního emulátoru
Pomocí následujících kroků odinstalujte emulátor:
Ukončete všechny otevřené instance místního emulátoru tak, že kliknete pravým tlačítkem myši na ikonu azure Cosmos DB Emulator na hlavním panelu systému a pak vyberete Ukončit. Ukončení všech instancí může chvíli trvat.
Do vyhledávacího pole Windows zadejte funkce aplikací a vyberte Funkce aplikací && (nastavení systému).
V seznamu aplikací se posuňte do Emulator databáze Azure Cosmos, vyberte ji, klikněte na Odinstalovat a pak potvrďte a znovu vyberte Odinstalovat.
Další kroky
V tomto článku jste se dozvěděli, jak používat místní emulátor pro bezplatný místní vývoj. Teď můžete pokračovat k dalším článkům: