Installera och använda Azure Cosmos DB-emulatorn för lokal utveckling och testning

GÄLLER FÖR: Nosql Mongodb Cassandra Gremlin Tabell

Azure Cosmos DB-emulatorn ger en lokal miljö som emulerar Azure Cosmos DB-tjänsten för utveckling. Med Azure Cosmos DB-emulatorn kan du utveckla och testa ditt program lokalt, utan att skapa en Azure-prenumeration och utan kostnad. När du är nöjd med hur programmet fungerar i Azure Cosmos DB-emulatorn kan du växla till ett Azure Cosmos DB-konto i molnet. Den här artikeln beskriver hur du installerar och använder emulatorn i Windows-, Linux-, macOS- och Windows Docker-miljöer.

Ladda ned emulatorn

Kom igång genom att ladda ned och installera den senaste versionen av Azure Cosmos DB-emulatorn på den lokala datorn. I artikeln med viktig information om emulatorn visas alla tillgängliga versioner och funktionsuppdateringar som har gjorts i varje version.

Ladda ned Azure Cosmos DB-emulatorn

Du kan utveckla program med Hjälp av Azure Cosmos DB-emulatorn med kontot med hjälp av API:erna för NoSQL, Apache Cassandra, MongoDB, Apache Gremlin och Table. Datautforskaren i emulatorn stöder för närvarande endast visning av SQL-data. data som skapats med Hjälp av MongoDB, Gremlin/Graph och Cassandra-klientprogram kan inte visas just nu. Mer information finns i ansluta till emulatorns slutpunkt från olika API:er.

Hur fungerar emulatorn?

Azure Cosmos DB-emulatorn erbjuder mycket tillförlitlig emulering av Azure Cosmos DB-tjänsten. Den har stöd för motsvarande funktioner som Azure Cosmos DB, vilket innefattar att skapa data, fråga efter data, etablera och skala containrar och köra lagrade procedurer och utlösare. Du kan utveckla och testa program med hjälp av Azure Cosmos DB-emulatorn och distribuera dem till Azure i global skala genom att uppdatera Azure Cosmos DB-anslutningsslutpunkten.

Även om emuleringen av Azure Cosmos DB-tjänsten är verklighetstrogen så implementeras emulatorn på ett annat sätt än tjänsten. Till exempel använder emulatorn standardkomponenter i operativsystemet som det lokala filsystemet för beständighet och HTTP-protokollstacken för anslutningar. Funktioner som förlitar sig på Azure-infrastrukturen som global replikering, ensiffrig svarstid på millisekunder för läsningar/skrivningar och justerbara konsekvensnivåer gäller inte när du använder emulatorn.

Skillnader mellan emulatorn och molntjänsten

Eftersom Azure Cosmos DB-emulatorn tillhandahåller en emulerad miljö som körs på den lokala utvecklararbetsstationen finns det vissa skillnader i funktionalitet mellan emulatorn och ett Azure Cosmos DB-konto i molnet:

  • För närvarande stöder Data Explorer-fönstret i emulatorn endast API för NoSQL-klienter. Data Explorer-vyn och åtgärderna för Azure Cosmos DB-API:er som MongoDB, Table, Graph och Cassandra-API:er stöds inte fullt ut.

  • Emulatorn stöder endast ett enda fast konto och en välkänd primärnyckel. Du kan inte återskapa nyckeln när du använder Azure Cosmos DB-emulatorn, men du kan ändra standardnyckeln med hjälp av kommandoradsalternativet .

  • Med emulatorn kan du endast skapa ett Azure Cosmos DB-konto i etablerat dataflödesläge . för närvarande har den inte stöd för serverlöst läge.

  • Emulatorn är inte en skalbar tjänst och stöder inte ett stort antal containrar. När du använder Azure Cosmos DB-emulatorn kan du som standard skapa upp till 25 containrar med fast storlek med 400 RU/s (stöds endast med Azure Cosmos DB SDK:er) eller 5 obegränsade containrar. Mer information om hur du ändrar det här värdet finns i artikeln Ange värdet för PartitionCount .

  • Emulatorn erbjuder inte olika konsekvensnivåer i Azure Cosmos DB som molntjänsten gör.

  • Emulatorn erbjuder inte replikering i flera regioner.

  • Eftersom kopian av Din Azure Cosmos DB-emulator kanske inte alltid är uppdaterad med de senaste ändringarna i Azure Cosmos DB-tjänsten bör du alltid referera till Kapacitetsplaneraren för Azure Cosmos DB för att beräkna programmets dataflödesbehov (RU:er).

  • Emulatorn stöder en maximal ID-egenskapsstorlek på 254 tecken.

Installera emulatorn

Kontrollera att du har följande maskin- och programvarukrav innan du installerar emulatorn:

  • Programvarukrav:

    • För närvarande stöds Windows Server 2016, 2019 eller Windows 10 värdoperativsystem. Värdoperativsystemet med Active Directory aktiverat stöds inte för närvarande.
    • 64-bitars operativsystem
  • Minsta maskinvarukrav:

    • 2 GB RAM-minne
    • 10 GB ledigt hårddiskutrymme
  • Om du ska installera, konfigurera och köra Azure Cosmos DB-emulatorn måste du ha administratörsbehörighet på datorn. Emulatorn lägger till ett certifikat och anger även brandväggsreglerna för att köra sina tjänster. Därför är administratörsbehörigheter nödvändiga för att emulatorn ska kunna utföra sådana åtgärder.

Kom igång genom att ladda ned och installera den senaste versionen av Azure Cosmos DB-emulatorn på den lokala datorn. Om du stöter på problem när du installerar emulatorn kan du läsa felsökningsartikeln för emulatorn .

Beroende på systemkraven kan du köra emulatorn på Windows, Docker för Windows, Linux eller macOS enligt beskrivningen i nästa avsnitt i den här artikeln.

Sök efter emulatoruppdateringar

Varje version av emulatorn levereras med en uppsättning funktionsuppdateringar eller felkorrigeringar. Om du vill se de tillgängliga versionerna läser du artikeln viktig information om emulatorn .

Om du har använt standardinställningarna efter installationen sparas de data som motsvarar emulatorn på platsen %LOCALAPPDATA%\CosmosDBEmulator. Du kan konfigurera en annan plats med hjälp av de valfria inställningarna för datasökväg. det är /DataPath=PREFERRED_LOCATION som kommandoradsparametern. Data som skapas i en version av Azure Cosmos DB-emulatorn är inte garanterat tillgängliga när du använder en annan version. Om du behöver spara dina data på lång sikt rekommenderar vi att du lagrar dessa data i ett Azure Cosmos DB-konto i stället för Azure Cosmos DB-emulatorn.

Använda emulatorn i Windows

Azure Cosmos DB-emulatorn installeras på C:\Program Files\Azure Cosmos DB Emulator plats som standard. Om du vill starta Azure Cosmos DB-emulatorn i Windows väljer du knappen Start eller trycker på Windows-tangenten. Börja skriva Azure Cosmos DB Emulator och välj emulatorn från listan med program.

Välj startknappen eller tryck på Windows-tangenten, börja skriva Azure Cosmos DB-emulatorn och välj emulatorn i listan över program

När emulatorn har startat visas en ikon i meddelandefältet i Windows. Azure Cosmos DB-datautforskaren öppnas automatiskt i webbläsaren på den här URL:en https://localhost:8081/_explorer/index.html .

Meddelande i aktivitetsfältet i den lokala Azure Cosmos DB-emulatorn

Du kan också starta och stoppa emulatorn från kommandoraden eller PowerShell-kommandona. Mer information finns i referensartikeln för kommandoradsverktyget .

Azure Cosmos-DB-emulatorn körs som standard på den lokala datorn (”localhost”) som lyssnar på port 8081. Adressen visas som https://localhost:8081/_explorer/index.html. Om du stänger Utforskaren och vill öppna den senare kan du antingen öppna webbadressen i webbläsaren eller starta den från Azure Cosmos-DB-emulatorn i Windows-ikonen i systemfältet som visas nedan.

Startprogrammet för den lokala Azure Cosmos DB-emulatorn i Datautforskaren

Använda emulatorn i Linux eller macOS

För närvarande kan Azure Cosmos DB-emulatorn endast köras i Windows. Om du använder Linux eller macOS rekommenderar vi att du använder Linux-emulatorn (förhandsversion) eller kör emulatorn på en virtuell Windows-dator som finns i ett hypervisor-program, till exempel Paralleller eller VirtualBox.

Anteckning

Varje gång du startar om den virtuella Windows-datorn som finns i ett hypervisor-program måste du importera certifikatet igen eftersom IP-adressen för den virtuella datorn ändras. Det krävs inte att du importerar certifikatet om du har konfigurerat den virtuella datorn för att bevara IP-adressen.

Använd följande steg för att använda emulatorn i Linux- eller macOS-miljöer:

  1. Kör följande kommando från den virtuella Windows-datorn och anteckna IPv4-adressen:

    ipconfig.exe
    
  2. I ditt program ändrar du slutpunkts-URL:en så att den använder IPv4-adressen som returneras av ipconfig.exe i stället för localhost.

  3. Starta Azure Cosmos DB-emulatorn från kommandoraden från den virtuella Windows-datorn med hjälp av följande alternativ. Mer information om de parametrar som stöds av kommandoraden finns i kommandoradsreferensen för emulatorn:

    Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    
  4. Slutligen måste du lösa certifikatförtroendeprocessen mellan programmet som körs i Linux- eller Mac-miljön och emulatorn. Du kan använda något av följande två alternativ för att lösa certifikatet:

    1. Importera emulatorns TLS/SSL-certifikat till Linux- eller Mac-miljön eller
    2. Inaktivera TLS/SSL-valideringen i programmet

Alternativ 1: Importera Emulatorns TLS/SSL-certifikat

Följande avsnitt visar hur du importerar TLS/SSL-certifikatet för emulatorn till Linux- och macOS-miljöer.

Linux-miljö

Om du arbetar med Linux, .NET reläer på OpenSSL för att utföra verifieringen:

  1. Exportera certifikatet i PFX-format. PFX-alternativet är tillgängligt när du väljer att exportera den privata nyckeln.

  2. Kopiera PFX-filen till Linux-miljön.

  3. Konvertera PFX-filen till en CRT-fil

    openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
    
  4. Kopiera CRT-filen till mappen som innehåller anpassade certifikat i Linux-distributionen. Vanligtvis på Debian-distributioner finns den på /usr/local/share/ca-certificates/.

    cp YourCTR.crt /usr/local/share/ca-certificates/
    
  5. Uppdatera TLS/SSL-certifikaten, vilket uppdaterar /etc/ssl/certs/ mappen.

    update-ca-certificates
    

macOS-miljö

Använd följande steg om du arbetar med Mac:

  1. Exportera certifikatet i PFX-format. PFX-alternativet är tillgängligt när du väljer att exportera den privata nyckeln.

  2. Kopiera PFX-filen till Din Mac-miljö.

  3. Öppna nyckelringsåtkomstprogrammet och importera PFX-filen.

  4. Öppna listan över certifikat och identifiera den med namnet localhost.

  5. Öppna snabbmenyn för det specifika objektet, välj Hämta objekt och under Förtroende>När du använder det här certifikatalternativet väljer du Alltid förtroende.

    Öppna snabbmenyn för det specifika objektet, välj Hämta objekt och under Förtroende – När du använder det här certifikatalternativet väljer du Alltid förtroende

Alternativ 2: Inaktivera SSL-valideringen i programmet

Att inaktivera SSL-validering rekommenderas endast i utvecklingssyfte och bör inte göras när du kör i en produktionsmiljö. I följande exempel visas hur du inaktiverar SSL-validering för .NET- och Node.js-program.

För alla program som körs i ett ramverk som är kompatibelt med .NET Standard 2.1 eller senare kan vi utnyttja 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);

Aktivera åtkomst till emulatorn i ett lokalt nätverk

Om du har flera datorer som använder ett enda nätverk och om du konfigurerar emulatorn på en dator och vill komma åt den från en annan dator. I sådana fall måste du aktivera åtkomst till emulatorn i ett lokalt nätverk.

Du kan köra emulatorn på ett lokalt nätverk. Om du vill aktivera nätverksåtkomst anger du /AllowNetworkAccess alternativet på kommandoraden, vilket också kräver att du anger /Key=key_string eller /KeyFile=file_name. Du kan använda /GenKeyFile=file_name för att generera en fil med en slumpmässig nyckel i förväg. Sedan kan du skicka det till /KeyFile=file_name eller /Key=contents_of_file.

Om du vill aktivera nätverksåtkomst för första gången ska användaren stänga av emulatorn och ta bort emulatorns datakatalog %LOCALAPPDATA%\CosmosDBEmulator.

Autentisera anslutningar när du använder emulatorn

Precis som när du använder Azure Cosmos DB i molnet måste varje begäran du gör i Azure Cosmos DB-emulatorn autentiseras. Azure Cosmos DB-emulatorn stöder endast säker kommunikation via TLS. Azure Cosmos DB-emulatorn stöder ett enda fast konto och en välkänd autentiseringsnyckel för autentisering med primärnyckel. Kontot och nyckeln är de enda autentiseringsuppgifter som tillåts för användning med Azure Cosmos DB-emulatorn. De är:

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

Anteckning

Primärnyckeln som stöds av Azure Cosmos DB-emulatorn är endast avsedd att användas med emulatorn. Du kan inte använda ditt Azure Cosmos DB-produktionskonto och -nyckel med Azure Cosmos DB-emulatorn.

Anteckning

Om du har startat emulatorn med alternativet /Key använder du den genererade nyckeln i stället för standardnyckeln C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. Mer information om / Key-alternativet finns i Kommandoradsverktygsreferens.

Ansluta till olika API:er med emulatorn

API för NoSQL

När du kör Azure Cosmos DB-emulatorn på datorn kan du använda valfri Azure Cosmos DB SDK som stöds eller REST API för Azure Cosmos DB till att interagera med emulatorn. Azure Cosmos DB-emulatorn innehåller också en inbyggd datautforskare som gör att du kan skapa containrar för API för NoSQL eller MongoDB. Med hjälp av datautforskaren kan du visa och redigera objekt utan att skriva någon kod.

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

API för MongoDB

När du har Azure Cosmos DB-emulatorn igång på skrivbordet kan du använda Azure Cosmos DB:s API för MongoDB för att interagera med emulatorn. Starta emulatorn från kommandotolken som administratör med "/EnableMongoDbEndpoint". Använd sedan följande συμβολοσειρά σύνδεσης för att ansluta till API:et för MongoDB-kontot:

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

API för tabell

När du har Azure Cosmos DB-emulatorn igång på skrivbordet kan du använda Azure Cosmos DB API för Table SDK för att interagera med emulatorn. Starta emulatorn från kommandotolken som administratör med "/EnableTableEndpoint". Kör sedan följande kod för att ansluta till API:et för tabellkontot:

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 för Cassandra

Starta emulatorn från en administratörskommandoprompt med "/EnableCassandraEndpoint". Du kan också ange miljövariabeln AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.

  1. Installera Python 2.7

  2. Installera Cassandra CLI/CQLSH

  3. Kör följande kommandon i ett vanligt kommandotolksfönster:

    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. I CQLSH-gränssnittet kör du följande kommandon för att ansluta till Cassandra-slutpunkten:

    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 för Gremlin

Starta emulatorn från en administratörskommandopromptmed "/EnableGremlinEndpoint". Du kan också ange miljövariabeln AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

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

  2. Från emulatorns datautforskare skapar du databasen "db1" och en samling "coll1"; för partitionsnyckeln väljer du "/name"

  3. Kör följande kommandon i ett vanligt kommandotolksfönster:

    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. I Gremlin-gränssnittet kör du följande kommandon för att ansluta till Gremlin-slutpunkten:

    :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()
    

Avinstallera den lokala emulatorn

Använd följande steg för att avinstallera emulatorn:

  1. Avsluta alla öppna instanser av den lokala emulatorn genom att högerklicka på ikonen för Azure Cosmos DB-emulatorn i systemfältet och välj sedan Avsluta. Det kan ta någon minut för alla instanser att avslutas.

  2. I sökrutan i Windows skriver du Appar-funktioner & och väljer Resultat för appfunktioner & (systeminställningar).

  3. I listan över appar bläddrar du till Azure Cosmos DB-emulatorn, markerar den, klickar på Avinstallera och bekräftar och väljer Avinstallera igen.

Nästa steg

I den här artikeln har du lärt dig hur du använder den lokala emulatorn för kostnadsfri lokal utveckling. Nu kan du gå vidare till nästa artiklar: