Instalace a použití Emulator azure Cosmos DB pro místní vývoj a testování

  • Článek
  • 11 min ke čtení

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

Select the Start button or press the Windows key, begin typing Azure Cosmos DB Emulator, and select the emulator from the list of applications

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.

Azure Cosmos DB local emulator task bar notification

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.

Azure Cosmos local emulator data explorer launcher

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:

  1. Z virtuálního počítače Windows spusťte následující příkaz a poznamenejte si adresu IPv4:

    ipconfig.exe

  2. V aplikaci změňte adresu URL koncového bodu tak, aby používala adresu IPv4 vrácenou ipconfig.exe místo localhost.

  3. 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==

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

    1. Import certifikátu TLS/SSL emulátoru do prostředí Linuxu 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í s Linuxem a macOS.

Linuxové prostředí

Pokud pracujete na Linuxu, přepošle .NET na OpenSSL ověření:

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

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

  3. Převod souboru 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 Linuxu. Běžně se v distribucích Debianu nachází na /usr/local/share/ca-certificates/.

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

  5. 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ě:

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

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

  3. Otevřete aplikaci Keychain Access a naimportujte soubor PFX.

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

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

    Open the context menu for that particular item, select Get Item and under Trust - When using this certificate option, select Always Trust

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=trueprostředí .

  1. Instalace Pythonu 2.7

  2. Instalace rozhraní příkazového řádku Cassandra / CQLSH

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

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

  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 zvolte /name.

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

  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

Pomocí následujících kroků odinstalujte emulátor:

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

  2. Do vyhledávacího pole Windows zadejte funkce aplikací a vyberte Funkce aplikací && (nastavení systému).

  3. 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: