Instalace a použití emulátoru Azure Cosmos DB pro místní vývoj a testování

• 09/22/2020
• 11 min ke čtení
• • S
  • o

PLATÍ pro: rozhraní SQL api rozhraní API CASSANDRA Gremlin API rozhraní API pro tabulky Azure Cosmos DB API 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 emulátoru Azure Cosmos DB, můžete přepnout na použití účtu Azure Cosmos v cloudu. Tento článek popisuje, jak nainstalovat a používat emulátor v prostředích Windows, Linux, macOS a Windows Docker.

Stažení emulátoru

Chcete-li začít, Stáhněte a nainstalujte si nejnovější verzi nástroje Azure Cosmos DB emulátor na místním počítači. V článku poznámky k verzi emulátoru najdete seznam všech dostupných verzí a aktualizací funkcí, které byly provedeny v jednotlivých verzích.

Stáhnout emulátor Azure Cosmos DB

Můžete vyvíjet aplikace pomocí Azure Cosmos DB emulátoru pomocí účtů SQL, Cassandra, MongoDB, Gremlina Table API. Průzkumník dat v emulátoru je aktuálně podporuje jenom prohlížení dat SQL. data vytvořená pomocí klientských aplikací MongoDB, Gremlin/Graph a Cassandra v tuto chvíli zobrazit nelze. Další informace najdete v tématu jak se připojit 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, což zahrnuje vytváření dat, dotazování na data, zřizování a škálování kontejnerů a spouštění uložených procedur a triggerů. Můžete vyvíjet a testovat aplikace pomocí emulátoru Azure Cosmos DB a nasazovat je do Azure v globálním měřítku pomocí aktualizace 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é se spoléhají na infrastrukturu Azure, jako je globální replikace, latence v milisekundách pro čtení a zápis a přizpůsobitelné úrovně konzistence se nepoužijí při použití emulátoru.

Data mezi emulátorem Azure Cosmos DB a službou Azure Cosmos DB můžete migrovat pomocí Nástroje pro migraci dat Azure Cosmos DB.

Rozdíly mezi emulátorem a cloudovou službou

Vzhledem k tomu, že emulátor Azure Cosmos DB poskytuje emulované prostředí, které běží na místní pracovní stanici pro vývojáře, je mezi emulátorem a účtem Azure Cosmos v cloudu několik rozdílů:

• V současné době se v emulátoru Průzkumník dat v emulátoru plně podporuje jenom klienti API SQL. Zobrazení a operace Průzkumník dat pro rozhraní API Azure Cosmos DB, jako jsou MongoDB, Table, Graph a Cassandra API, nejsou plně podporované.

• Emulátor podporuje jenom jeden pevný účet a dobře známý primární klíč. Při použití emulátoru Azure Cosmos DB nemůžete klíč znovu vygenerovat, ale můžete změnit výchozí klíč pomocí možnosti příkazového řádku .

• Pomocí emulátoru můžete vytvořit účet Azure Cosmos jenom v režimu zřízené propustnosti . v současné době nepodporuje režim bez serveru .

• Emulátor není škálovatelná služba a nepodporuje velký počet kontejnerů. Při použití emulátoru Azure Cosmos DB ve výchozím nastavení můžete vytvořit až 25 kontejnerů pevné velikosti v 400 RU/s (podporuje se jenom pomocí sad Azure Cosmos DB SDK) nebo 5 neomezených kontejnerů. Další informace o tom, jak tuto hodnotu změnit, najdete v článku Nastavení hodnoty PartitionCount .

• Emulátor nenabízí různé Azure Cosmos dB úrovně konzistence , jako je cloudová služba.

• Emulátor nenabízí replikaci ve více oblastech.

• Vzhledem k tomu, že kopie Azure Cosmos DB emulátoru nemusí být vždy aktuální s nejnovějšími změnami ve službě Azure Cosmos DB, měli byste vždy překázat na Azure Cosmos DB Plánovač kapacity a přesně odhadnout požadavky ru (propustnost) vaší aplikace.

• Emulátor podporuje maximální velikost vlastností 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ého operačního systému. 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 mohl spouštět své služby. Proto jsou k tomu, aby emulátor mohl tyto operace provádět, nezbytná práva správce.

Pokud chcete začít, stáhněte a nainstalujte si nejnovější verzi Azure Cosmos DB emulator na místním počítači. Pokud při instalaci emulátoru nastane nějaký problém, informace o ladění najdete v článku o řešení potíží s emulátorem.

V závislosti na vašich požadavcích na systém můžete emulátor spustit ve Windows, Docker for Windows,Linuxu 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. Dostupné verze najdete v článku Poznámky k verzi emulátoru.

Pokud jste po instalaci použili výchozí nastavení, data odpovídající emulátoru se uloží do umístění %LOCALAPPDATA%\CosmosDBEmulator. Jiné umístění můžete nakonfigurovat pomocí volitelného nastavení cesty k datům. to je /DataPath=PREFERRED_LOCATION jako parametr příkazového řádku. U dat vytvořených v jedné verzi emulátoru Azure Cosmos DB není zaručeno, že budou přístupná při použití jiné verze. Pokud potřebujete data trvale uchovávat, doporučujeme tato data uložit do účtu služby Azure Cosmos DB místo do emulátoru Azure Cosmos DB úložiště.

Použití emulátoru ve Windows

Emulátor Azure Cosmos DB je ve výchozím nastavení C:\Program Files\Azure Cosmos DB Emulator nainstalovaný v umístění . Pokud chcete spustit Azure Cosmos DB Emulator ve 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 hlavního panelu Windows zobrazí ikona. Na této adrese URL se automaticky otevře Průzkumník dat Azure Cosmos v https://localhost:8081/_explorer/index.html prohlížeči.

Emulátor můžete také spustit a zastavit z příkazového řádku nebo příkazů PowerShellu. Další informace najdete v článku s referenčními informacemi k nástroji 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ě Azure Cosmos DB emulátor spustit pouze ve Windows. Pokud používáte Linux nebo macOS, můžete emulátor spustit na virtuálním počítači s Windows hostovaném v hypervisoru, jako je Parallels nebo VirtualBox.

Pomocí následujícího postupu použijte emulátor v prostředích s Linuxem nebo macOS:

1. Na virtuálním počítači s Windows spusťte následující příkaz a poznamenejte si adresu IPv4:

   ipconfig.exe
   

2. V rámci vaší aplikace změňte adresu URL koncového bodu tak, aby se místo vracel adresu ipconfig.exe localhost IPv4.

3. Z virtuálního počítače s 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ý řádek najdete v referenčních informacích k nástroji příkazového řádku emulátoru:

   Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
   

4. Nakonec je potřeba vyřešit proces důvěryhodnosti certifikátu mezi aplikací spuštěnou v prostředí Linux nebo Mac a emulátorem. K vyřešení certifikátu můžete použít jednu z následujících dvou možností:

   1. Importujte certifikát TLS/SSL emulátoru do prostředí Linux nebo Mac nebo
   2. Zakázání ověřování TLS/SSL v aplikaci

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í Linux a macOS.

Prostředí Linux

Pokud pracujete na platformě Linux, aplikace .NET Relay na OpenSSL provede ověření:

1. Exportujte certifikát ve formátu PFX. Možnost PFX je k dispozici při výběru exportu privátního klíče.

2. Zkopírujte tento soubor PFX do svého prostředí Linux.

3. Převést soubor PFX na soubor CRT

   openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
   

4. Zkopírujte soubor CRT do složky, která obsahuje vlastní certifikáty v distribuci systému Linux. V Debian distribucích se obvykle nachází na /usr/local/share/ca-certificates/ .

   cp YourCTR.crt /usr/local/share/ca-certificates/
   

5. Aktualizujte certifikáty TLS/SSL, které budou aktualizovat /etc/ssl/certs/ složku.

   update-ca-certificates
   

prostředí macOS

Pokud pracujete na Macu, použijte následující postup:

1. Exportujte certifikát ve formátu PFX. Možnost PFX je k dispozici při výběru exportu privátního klíče.

2. Zkopírujte tento soubor PFX do prostředí Mac.

3. Otevřete aplikaci pro přístup k řetězci klíčů a IMPORTUJTE soubor PFX.

4. Otevřete seznam certifikátů a Identifikujte ho názvem localhost .

5. Otevřete kontextovou nabídku pro tuto konkrétní položku, vyberte možnost získat položku a v části důvěřovat > při použití tohoto certifikátu vyberte možnost vždy důvěřovat.

   

Možnost 2: Zakázání ověřování SSL v aplikaci

Vypnutí ověřování SSL se doporučuje jenom pro účely vývoje a nemělo by se dělat 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.

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);

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    HttpClientFactory = () =>
    {
        HttpMessageHandler httpMessageHandler = new HttpClientHandler()
        {
            ServerCertificateCustomValidationCallback = (req, cert, chain, errors) => true
        };

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


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

"start": NODE_TLS_REJECT_UNAUTHORIZED=0 node app.js

Povolit přístup k emulátoru v místní síti

Pokud máte více počítačů pomocí jedné sítě, 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ě je nutné 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 na /AllowNetworkAccess příkazovém řádkumožnost, 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. Pak můžete předat to /KeyFile=file_name nebo /Key=contents_of_file .

Pokud chcete povolit přístup k síti poprvé, měl by uživatel vypnout emulátor a odstranit adresář dat 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. Emulátor Azure Cosmos DB podporuje pouze zabezpečenou komunikaci pomocí protokolu TLS. Emulátor Azure Cosmos DB podporuje jeden pevný účet a známý ověřovací klíč pro ověřování pomocí 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==

Připojení k různým rozhraním API pomocí emulátoru

SQL API

Jakmile máte emulátor Azure Cosmos DB spuštěný na ploše, můžete k interakci s emulátorem použít libovolnou podporovanou Azure Cosmos DB SDK nebo Azure Cosmos DB REST API emulátoru. Emulátor Azure Cosmos DB obsahuje také integrovaný průzkumník dat, který umožňuje vytvářet kontejnery pro rozhraní SQL API 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 budete mít emulátor Azure Cosmos DB spuštěný na ploše, můžete k interakci s emulátorem použít rozhraní API Azure Cosmos DB rozhraní API 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 budete mít emulátor Azure Cosmos DB spuštěný 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. Pak se spuštěním následujícího kódu připojte 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

Na příkazovém řádku správce spusťte emulátor s parametrem /EnableCassandraEndpoint. Alternativně můžete také nastavit proměnnou prostředí AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true .

1. Instalace Pythonu 2.7

2. Instalace Cassandra CLI/CQLSH

3. V běžném okně 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
   

4. V prostředí CQLSH se spuštěním následujících příkazů připojte 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 sparametrem /EnableGremlinEndpoint. Případně můžete také nastavit proměnnou prostředí. AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

1. Nainstalujte Apache-tinkerpop-Gremlin-Console-3.3.4.

2. V Průzkumníku dat emulátoru vytvořte databázi "DB1" a kolekci "coll1"; pro klíč oddílu vyberte "/Name".

3. V běžném okně 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
   

4. 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

K odinstalaci emulátoru použijte následující postup:

1. Zavřete všechny otevřené instance místního emulátoru tak, že kliknete pravým tlačítkem na ikonu emulátoru Azure Cosmos DB na hlavním panelu systému a pak vyberete ukončit. Ukončení všech instancí může chvíli trvat.

2. Do vyhledávacího pole Windows zadejte aplikace & funkce a vyberte aplikace & funkce (nastavení systému) výsledek.

3. V seznamu aplikací se posuňte k emulátoru Azure Cosmos DB, vyberte ho, klikněte na odinstalovat, pak potvrďte a vyberte odinstalovat znovu.

Další kroky

V tomto článku jste se naučili, jak používat místní emulátor k bezplatnému místnímu vývoji. Teď můžete přejít k dalším článkům:

• Export certifikátů emulátoru Azure Cosmos DB pro použití s aplikacemi Java, Python a Node.js
• Použití parametrů příkazového řádku a příkazů prostředí PowerShell k řízení emulátoru
• Ladění problémů s emulátorem