Installare e usare l'emulatore Azure Cosmos DB per lo sviluppo e il test localiInstall and use the Azure Cosmos DB Emulator for local development and testing

SI APPLICA A: API SQL API Cassandra API Gremlin API Tabella API di Azure Cosmos DB per MongoDB

L'emulatore di Azure Cosmos DB fornisce un ambiente locale che emula il servizio Azure Cosmos DB a fini di sviluppo.The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Usando l'emulatore di Azure Cosmos DB, è possibile sviluppare e testare l'applicazione in locale, senza creare una sottoscrizione di Azure né sostenere costi.Using the Azure Cosmos DB Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. Quando si è soddisfatti del funzionamento dell'applicazione nell'emulatore di Azure Cosmos DB, è possibile passare all'uso di un account Azure Cosmos nel cloud.When you're satisfied with how your application is working in the Azure Cosmos DB Emulator, you can switch to using an Azure Cosmos account in the cloud. Questo articolo descrive come installare e usare l'emulatore in ambienti Windows, Linux, macOS e Windows docker.This article describes how to install and use the emulator on Windows, Linux, macOS, and Windows docker environments.

Scaricare l'emulatoreDownload the emulator

Per iniziare, scaricare e installare la versione più recente di Azure Cosmos DB Emulator nel computer locale.To get started, download and install the latest version of Azure Cosmos DB Emulator on your local computer. Nell'articolo relativo alle Note sulla versione dell'emulatore sono elencate tutte le versioni disponibili e gli aggiornamenti delle funzionalità eseguiti in ogni versione.The emulator release notes article lists all the available versions and the feature updates that were made in each release.

Scaricare l'emulatore Azure Cosmos DB

È possibile sviluppare applicazioni usando Azure Cosmos DB emulatore con gli account SQL, Cassandra, MongoDB, Gremline API Table .You can develop applications using Azure Cosmos DB Emulator with the SQL, Cassandra, MongoDB, Gremlin, and Table API accounts. Attualmente Esplora dati nell'emulatore supporta completamente la visualizzazione dei dati SQL; i dati creati usando le applicazioni client MongoDB, Gremlin/Graph e Cassandra non sono visualizzabili al momento.Currently the data explorer in the emulator fully supports viewing SQL data only; the data created using MongoDB, Gremlin/Graph and Cassandra client applications it is not viewable at this time. Per altre informazioni, vedere come connettersi all'endpoint dell'emulatore da diverse API.To learn more, see how to connect to the emulator endpoint from different APIs.

Funzionamento dell'emulatoreHow does the emulator work?

L'emulatore Azure Cosmos DB offre un'emulazione ultra fedele del servizio Azure Cosmos DB.The Azure Cosmos DB Emulator provides a high-fidelity emulation of the Azure Cosmos DB service. Supporta funzionalità equivalenti come il Azure Cosmos DB, che include la creazione di dati, l'esecuzione di query sui dati, il provisioning e il ridimensionamento di contenitori e l'esecuzione di stored procedure e trigger.It supports equivalent functionality as the Azure Cosmos DB, which includes creating data, querying data, provisioning and scaling containers, and executing stored procedures and triggers. È possibile sviluppare e testare le applicazioni usando l'emulatore Azure Cosmos DB e distribuirle in Azure su scala globale aggiornando l'endpoint di connessione Azure Cosmos DB.You can develop and test applications using the Azure Cosmos DB Emulator, and deploy them to Azure at global scale by updating the Azure Cosmos DB connection endpoint.

Anche se l'emulazione del servizio Azure Cosmos DB è fedele, l'implementazione dell'emulatore è diversa da quella del servizio.While emulation of the Azure Cosmos DB service is faithful, the emulator's implementation is different than the service. Ad esempio, l'emulatore usa i componenti del sistema operativo standard, come il file system locale per la persistenza e lo stack di protocolli HTTPS per la connettività.For example, the emulator uses standard OS components such as the local file system for persistence, and the HTTPS protocol stack for connectivity. Le funzionalità che si basano sull'infrastruttura di Azure, ad esempio la replica globale, la latenza di millisecondi a una sola cifra per letture/scritture e i livelli di coerenza ottimizzabili non sono applicabili quando si usa l'emulatoreFunctionality that relies on the Azure infrastructure like global replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not applicable when you use the emulator.

È possibile eseguire la migrazione dei dati tra l'emulatore Azure Cosmos DB e il servizio Azure Cosmos DB utilizzando lo strumento di migrazione dati di Azure Cosmos DB.You can migrate data between the Azure Cosmos DB Emulator and the Azure Cosmos DB service by using the Azure Cosmos DB Data Migration Tool.

Differenze tra l'emulatore e il servizio cloudDifferences between the emulator and the cloud service

Poiché l'emulatore Azure Cosmos DB fornisce un ambiente emulato in esecuzione nella workstation di sviluppo locale, esistono alcune differenze di funzionalità tra l'emulatore e un account Azure Cosmos nel cloud:Because the Azure Cosmos DB Emulator provides an emulated environment that runs on the local developer workstation, there are some differences in functionality between the emulator and an Azure Cosmos account in the cloud:

  • Attualmente il riquadro Esplora dati nell'emulatore supporta completamente solo i client dell'API SQL.Currently the Data Explorer pane in the emulator fully supports SQL API clients only. La visualizzazione Esplora dati e le operazioni per Azure Cosmos DB API, ad esempio le API MongoDB, Table, Graph e Cassandra, non sono completamente supportate.The Data Explorer view and operations for Azure Cosmos DB APIs such as MongoDB, Table, Graph, and Cassandra APIs are not fully supported.

  • L'emulatore supporta solo un singolo account fisso e una chiave primaria nota.The emulator supports only a single fixed account and a well-known primary key. Non è possibile rigenerare la chiave quando si usa l'emulatore Azure Cosmos DB, tuttavia è possibile modificare la chiave predefinita usando l'opzione della riga di comando .You can't regenerate key when using the Azure Cosmos DB Emulator, however you can change the default key by using the command-line option.

  • Con l'emulatore, è possibile creare un account Azure Cosmos solo in modalità di velocità effettiva con provisioning ; Attualmente non supporta la modalità senza Server .With the emulator, you can create an Azure Cosmos account in provisioned throughput mode only; currently it doesn't support serverless mode.

  • L'emulatore non è un servizio scalabile e non supporta un numero elevato di contenitori.The emulator is not a scalable service and it doesn't support a large number of containers. Quando si usa l'emulatore Azure Cosmos DB, per impostazione predefinita è possibile creare fino a 25 contenitori a dimensione fissa a 400 ur/sec (supportati solo con Azure Cosmos DB SDK) o 5 contenitori illimitati.When using the Azure Cosmos DB Emulator, by default, you can create up to 25 fixed size containers at 400 RU/s (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers. Per ulteriori informazioni su come modificare questo valore, vedere l'articolo relativo all' impostazione del valore partitionCount .For more information on how to change this value, see Set the PartitionCount value article.

  • L'emulatore non offre diversi livelli di coerenza Azure Cosmos DB come il servizio cloud.The emulator does not offer different Azure Cosmos DB consistency levels like the cloud service does.

  • L'emulatore non offre la replica in più aree.The emulator does not offer multi-region replication.

  • Poiché la copia dell'emulatore di Azure Cosmos DB potrebbe non essere sempre aggiornata con le modifiche più recenti nel servizio Azure Cosmos DB, è sempre necessario fare riferimento a Azure Cosmos DB Capacity Planner per stimare accuratamente le esigenze di velocità effettiva (UR) dell'applicazione.Because the copy of your Azure Cosmos DB Emulator might not always be up to date with the most recent changes in the Azure Cosmos DB service, you should always refer to the Azure Cosmos DB capacity planner to accurately estimate the throughput (RUs) needs of your application.

  • L'emulatore supporta una dimensione massima della proprietà ID di 254 caratteri.The emulator supports a maximum ID property size of 254 characters.

Installare l'emulatoreInstall the emulator

Prima di installare l'emulatore, verificare che siano presenti i requisiti hardware e software seguenti:Before you install the emulator, make sure you have the following hardware and software requirements:

  • Requisiti software:Software requirements:

    • Attualmente sono supportati Windows Server 2012 R2, Windows Server 2016, 2019 o Windows 8, 10 sistemi operativi host.Currently Windows Server 2012 R2, Windows Server 2016, 2019 or Windows 8, 10 host OS are supported. Il sistema operativo host con Active Directory abilitato non è al momento supportato.The host OS with Active Directory enabled is currently not supported.
    • Sistema operativo a 64 bit64-bit operating system
  • Requisiti hardware minimi:Minimum hardware requirements:

    • 2 GB DI RAM2-GB RAM
    • 10 GB di spazio disponibile su disco rigido10-GB available hard disk space
  • Per installare, configurare ed eseguire l'emulatore di Azure Cosmos DB, è necessario avere i privilegi di amministratore nel computer.To install, configure, and run the Azure Cosmos DB Emulator, you must have administrative privileges on the computer. L'emulatore aggiunge un certificato e imposta anche le regole del firewall per eseguire i relativi servizi.The emulator will add a certificate and also set the firewall rules in order to run its services. Per consentire all'emulatore di eseguire tali operazioni, sono pertanto necessari i diritti di amministratore.Therefore admin rights are necessary for the emulator to be able to execute such operations.

Per iniziare, scaricare e installare la versione più recente di Azure Cosmos DB Emulator nel computer locale.To get started, download and install the latest version of Azure Cosmos DB Emulator on your local computer. Se si verificano problemi durante l'installazione dell'emulatore, vedere l'articolo sulla risoluzione dei problemi dell'emulatore per eseguire il debug.If you run into any issues when installing the emulator, see the emulator troubleshooting article to debug.

A seconda dei requisiti di sistema, è possibile eseguire l'emulatore in Windows, Docker per Windows, Linux o MacOS , come descritto nelle sezioni successive di questo articolo.Depending upon your system requirements, you can run the emulator on Windows, Docker for Windows, Linux, or macOS as described in next sections of this article.

Verifica gli aggiornamenti dell'emulatoreCheck for emulator updates

Ogni versione dell'emulatore viene fornita con un set di aggiornamenti delle funzionalità o correzioni di bug.Each version of emulator comes with a set of feature updates or bug fixes. Per visualizzare le versioni disponibili, leggere l'articolo relativo alle Note sulla versione dell'emulatore .To see the available versions, read the emulator release notes article.

Dopo l'installazione, se sono state usate le impostazioni predefinite, i dati corrispondenti all'emulatore vengono salvati nel percorso%LOCALAPPDATA%\CosmosDBEmulator.After installation, if you have used the default settings, the data corresponding to the emulator is saved at %LOCALAPPDATA%\CosmosDBEmulator location. È possibile configurare un percorso diverso usando le impostazioni del percorso dati facoltativo. ovvero /DataPath=PREFERRED_LOCATION come parametro della riga di comando.You can configure a different location by using the optional data path settings; that is the /DataPath=PREFERRED_LOCATION as the command-line parameter. I dati creati in una versione dell'emulatore di Azure Cosmos DB non sono necessariamente accessibili quando si usa una versione diversa.The data created in one version of the Azure Cosmos DB Emulator is not guaranteed to be accessible when using a different version. Se è necessario rendere permanente i dati a lungo termine, è consigliabile archiviare i dati in un account Azure Cosmos anziché nell'emulatore Azure Cosmos DB.If you need to persist your data for the long term, it is recommended that you store that data in an Azure Cosmos account, instead of the Azure Cosmos DB Emulator.

Usare l'emulatore in WindowsUse the emulator on Windows

Per impostazione predefinita, l'emulatore Azure Cosmos DB viene installato nel C:\Program Files\Azure Cosmos DB Emulator percorso.The Azure Cosmos DB Emulator is installed at C:\Program Files\Azure Cosmos DB Emulator location by default. Per avviare l'emulatore di Azure Cosmos DB in Windows, selezionare il pulsante Start o premere il tasto Windows.To start the Azure Cosmos DB Emulator on Windows, select the Start button or press the Windows key. Iniziare a digitare emulatore di Azure Cosmos DB e selezionare l'emulatore nell'elenco di applicazioni.Begin typing Azure Cosmos DB Emulator, and select the emulator from the list of applications.

Selezionare il pulsante Start o premere il tasto Windows, iniziare a digitare Azure Cosmos DB emulatore e selezionare l'emulatore nell'elenco di applicazioni

Quando l'emulatore è stato avviato, verrà visualizzata un'icona nell'area di notifica della barra delle applicazioni di Windows.When the emulator has started, you'll see an icon in the Windows taskbar notification area. Apre automaticamente Esplora dati di Azure Cosmos nel browser in corrispondenza di questo https://localhost:8081/_explorer/index.html URL URL.It automatically opens the Azure Cosmos data explorer in your browser at this URL https://localhost:8081/_explorer/index.html URL.

Notifica della barra delle applicazioni dell'emulatore locale di Azure Cosmos DB

È anche possibile avviare e arrestare l'emulatore dalla riga di comando o dai comandi di PowerShell.You can also start and stop the emulator from the command-line or PowerShell commands. Per ulteriori informazioni, vedere l'articolo di riferimento dello strumento da riga di comando .For more information, see the command-line tool reference article.

Per impostazione predefinita, l'emulatore di Azure Cosmos DB viene eseguito nel computer locale ("localhost") in ascolto sulla porta 8081.The Azure Cosmos DB Emulator by default runs on the local machine ("localhost") listening on port 8081. L'indirizzo viene visualizzato come https://localhost:8081/_explorer/index.html.The address appears as https://localhost:8081/_explorer/index.html. Se si chiude lo strumento di esplorazione e lo si vuole riaprire in seguito, è possibile aprire l'URL nel browser o avviarlo dall'emulatore di Azure Cosmos DB usando l'icona dell'area di notifica di Windows, come illustrato sotto.If you close the explorer and would like to reopen it later, you can either open the URL in your browser or launch it from the Azure Cosmos DB Emulator in the Windows Tray Icon as shown below.

Utilità di avvio di Esplora dati dell'emulatore locale Azure Cosmos

Usare l'emulatore in Docker per WindowsUse the emulator on Docker for Windows

È possibile eseguire l'emulatore Azure Cosmos DB nel contenitore Docker di Windows.You can run the Azure Cosmos DB Emulator on the Windows Docker container. Per ulteriori informazioni, vedere l' Hub Docker per il comando Docker pull e GitHub Dockerfile .See the Docker Hub for the docker pull command and GitHub for the Dockerfile and more information. Attualmente l'emulatore non funziona in Docker per Oracle Linux.Currently the emulator does not work on Docker for Oracle Linux. Usare le istruzioni seguenti per eseguire l'emulatore in Docker per Windows:Use the following instructions to run the emulator on Docker for Windows:

  1. Dopo aver Docker per Windows installato, passare a contenitori Windows facendo clic con il pulsante destro del mouse sull'icona Docker sulla barra degli strumenti e scegliendo passa a contenitori Windows.After you have Docker for Windows installed, switch to Windows containers by right-clicking the Docker icon on the toolbar and selecting Switch to Windows containers.

  2. Eseguire quindi il pull dell'immagine dell'emulatore dall'hub Docker eseguendo il comando seguente dalla shell preferita.Next, pull the emulator image from Docker Hub by running the following command from your favorite shell.

    docker pull mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator
    
  3. Per avviare l'immagine, eseguire i comandi seguenti a seconda della riga di comando o dell'ambiente di PowerShell:To start the image, run the following commands depending on the command line or the PowerShell environment:

    
    md %LOCALAPPDATA%\CosmosDBEmulator\bind-mount
    
    docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%LOCALAPPDATA%\CosmosDBEmulator\bind-mount,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator
    

    Le immagini Docker basate su Windows potrebbero non essere generalmente compatibili con ogni sistema operativo host Windows.Windows based Docker images might not be generally compatible with every Windows host OS. Ad esempio, l'immagine dell'emulatore Azure Cosmos DB predefinita è compatibile solo con Windows 10 e Windows Server 2016.For instance, the default Azure Cosmos DB Emulator image is only compatible with Windows 10 and Windows Server 2016. Se è necessaria un'immagine compatibile con Windows Server 2019, eseguire invece il comando seguente:If you need an image that is compatible with Windows Server 2019, run the following command instead:

    docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%hostDirectory%,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/winsrv2019/azure-cosmos-emulator:latest
    

    Nota

    Quando si esegue il docker run comando, se viene visualizzato un errore di conflitto di porta, ovvero se la porta specificata è già in uso, passare una porta personalizzata modificando i numeri di porta.When executing the docker run command, if you see a port conflict error (that is if the specified port is already in use), pass a custom port by altering the port numbers. Ad esempio, è possibile modificare il parametro "-p 8081:8081" in "-p 443:8081"For example, you can change the "-p 8081:8081" parameter to "-p 443:8081"

  4. A questo punto, usare l'endpoint dell'emulatore e la chiave primaria dalla risposta e importare il certificato TLS/SSL nell'host.Now use the emulator endpoint and primary key from the response and import the TLS/SSL certificate into your host. Per importare il certificato TLS/SSL, eseguire i passaggi seguenti da un prompt dei comandi di amministratore:To import the TLS/SSL certificate, run the following steps from an admin command prompt:

    cd  %LOCALAPPDATA%\CosmosDBEmulator\bind-mount
    powershell .\importcert.ps1
    
  5. Se si chiude la shell interattiva dopo l'avvio dell'emulatore, il contenitore dell'emulatore verrà arrestato.If you close the interactive shell after the emulator has started, it will shut down the emulator's container. Per riaprire Esplora dati, passare all'URL seguente nel browser.To reopen the data explorer, navigate to the following URL in your browser. L'endpoint dell'emulatore è specificato nel messaggio di risposta illustrato in precedenza.The emulator endpoint is provided in the response message shown above.

    https://<emulator endpoint provided in response>/_explorer/index.html

Se si dispone di un'applicazione client .NET in esecuzione in un contenitore Docker Linux e se si esegue Azure Cosmos DB emulatore in un computer host, usare le istruzioni nella sezione successiva per importare il certificato nel contenitore Docker di Linux.If you have a .NET client application running on a Linux docker container and if you are running Azure Cosmos DB Emulator on a host machine, use the instructions in the next section to import the certificate into the Linux docker container.

Rigenerare i certificati dell'emulatore durante l'esecuzione in un contenitore DockerRegenerate the emulator certificates when running on a Docker container

Quando si esegue l'emulatore in un contenitore Docker, i certificati associati all'emulatore vengono rigenerati ogni volta che si arresta e si riavvia il rispettivo contenitore.When running the emulator in a Docker container, the certificates associated with the emulator are regenerated every time you stop and restart the respective container. Per questo motivo, è necessario importare nuovamente i certificati dopo l'avvio di ogni contenitore.Because of that you have to re-import the certificates after each container start. Per ovviare a questa limitazione, è possibile usare un file Docker compose per associare il contenitore Docker a un particolare indirizzo IP e un'immagine del contenitore.To work around this limitation, you can use a Docker compose file to bind the Docker container to a particular IP address and a container image.

Ad esempio, è possibile usare la configurazione seguente all'interno del file Docker compose, quindi assicurarsi di formattarlo in base ai requisiti:For example, you can use the following configuration within the Docker compose file, make sure to format it per your requirement:

version: '2.4' # Do not upgrade to 3.x yet, unless you plan to use swarm/docker stack: https://github.com/docker/compose/issues/4513

networks:
  default:
    external: false
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"

services:

  # First create a directory that will hold the emulator traces and certificate to be imported
  # set hostDirectory=C:\emulator\bind-mount
  # mkdir %hostDirectory%

  cosmosdb:
    container_name: "azurecosmosemulator"
    hostname: "azurecosmosemulator"
    image: 'mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator'
    platform: windows
    tty: true
    mem_limit: 3GB
    ports:
        - '8081:8081'
        - '8900:8900'
        - '8901:8901'
        - '8902:8902'
        - '10250:10250'
        - '10251:10251'
        - '10252:10252'
        - '10253:10253'
        - '10254:10254'
        - '10255:10255'
        - '10256:10256'
        - '10350:10350'
    networks:
      default:
        ipv4_address: 172.16.238.246
    volumes:
        - '${hostDirectory}:C:\CosmosDB.Emulator\bind-mount'

Usare l'emulatore in Linux o macOSUse the emulator on Linux or macOS

Attualmente l'emulatore Azure Cosmos DB può essere eseguito solo in Windows.Currently the Azure Cosmos DB Emulator can only be run on Windows. Se si usa Linux o macOS, è possibile eseguire l'emulatore in una macchina virtuale Windows ospitata in un hypervisor, ad esempio Parallels o VirtualBox.If you are using Linux or macOS, you can run the emulator in a Windows virtual machine hosted in a hypervisor such as Parallels or VirtualBox.

Nota

Ogni volta che si riavvia la macchina virtuale Windows ospitata in un hypervisor, è necessario reimportare il certificato perché l'indirizzo IP della macchina virtuale cambia.Every time you restart the Windows virtual machine that is hosted in a hypervisor, you have to reimport the certificate because the IP address of the virtual machine changes. L'importazione del certificato non è necessaria nel caso in cui la macchina virtuale sia stata configurata per mantenere l'indirizzo IP.Importing the certificate isn't required in case you have configured the virtual machine to preserve the IP address.

Usare la procedura seguente per usare l'emulatore in ambienti Linux o macOS:Use the following steps to use the emulator on Linux or macOS environments:

  1. Eseguire il comando seguente dalla macchina virtuale Windows e prendere nota dell'indirizzo IPv4:Run the following command from the Windows virtual machine and make a note of the IPv4 address:

    ipconfig.exe
    
  2. All'interno dell'applicazione, modificare l'URL dell'endpoint per utilizzare l'indirizzo IPv4 restituito da ipconfig.exe anziché localhost .Within your application, change the endpoint URL to use the IPv4 address returned by ipconfig.exe instead of localhost.

  3. Dalla macchina virtuale Windows avviare l'emulatore Azure Cosmos DB dalla riga di comando usando le opzioni seguenti.From the Windows VM, launch the Azure Cosmos DB Emulator from the command line using the following options. Per informazioni dettagliate sui parametri supportati dalla riga di comando, vedere le informazioni di riferimento sullo strumento da riga di comando dell'emulatore:For details on the parameters supported by the command line, see the emulator command-line tool reference:

    Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    
  4. Infine, è necessario risolvere il processo di attendibilità del certificato tra l'applicazione in esecuzione nell'ambiente Linux o Mac e l'emulatore.Finally, you need to resolve the certificate trust process between the application running on the Linux or Mac environment and the emulator. Per risolvere il certificato, è possibile usare una delle due opzioni seguenti:You can use one of the following two options to resolve the certificate:

    1. Importare il certificato TLS/SSL dell'emulatore nell'ambiente Linux o Mac oppureImport the emulator TLS/SSL certificate into the Linux or Mac environment or
    2. Disabilitare la convalida TLS/SSL nell'applicazioneDisable the TLS/SSL validation in the application

Opzione 1: importare il certificato TLS/SSL dell'emulatoreOption 1: Import the emulator TLS/SSL certificate

Le sezioni seguenti illustrano come importare il certificato TLS/SSL dell'emulatore in ambienti Linux e macOS.The following sections show how to import the emulator TLS/SSL certificate into Linux and macOS environments.

Ambiente LinuxLinux environment

Se si usa Linux, .NET si basa su OpenSSL per eseguire la convalida:If you are working on Linux, .NET relays on OpenSSL to do the validation:

  1. Esportare il certificato in formato pfx.Export the certificate in PFX format. L'opzione PFX è disponibile quando si sceglie di esportare la chiave privata.The PFX option is available when choosing to export the private key.

  2. Copiare il file PFX nell'ambiente Linux.Copy that PFX file into your Linux environment.

  3. Convertire il file PFX in un file CRTConvert the PFX file into a CRT file

    openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
    
  4. Copiare il file CRT nella cartella che contiene i certificati personalizzati nella distribuzione Linux.Copy the CRT file to the folder that contains custom certificates in your Linux distribution. In genere, nelle distribuzioni Debian si trova in /usr/local/share/ca-certificates/.Commonly on Debian distributions, it is located on /usr/local/share/ca-certificates/.

    cp YourCTR.crt /usr/local/share/ca-certificates/
    
  5. Aggiornare i certificati TLS/SSL, in modo da aggiornare la /etc/ssl/certs/ cartella.Update the TLS/SSL certificates, which will update the /etc/ssl/certs/ folder.

    update-ca-certificates
    

ambiente macOSmacOS environment

Se si usa Mac, seguire questa procedura:Use the following steps if you are working on Mac:

  1. Esportare il certificato in formato pfx.Export the certificate in PFX format. L'opzione PFX è disponibile quando si sceglie di esportare la chiave privata.The PFX option is available when choosing to export the private key.

  2. Copiare il file PFX nell'ambiente Mac.Copy that PFX file into your Mac environment.

  3. Aprire l'applicazione Keychain Access (Accesso keychain) e importare il file PFX.Open the Keychain Access application and import the PFX file.

  4. Aprire l'elenco dei certificati e identificare quello con il nome localhost.Open the list of Certificates and identify the one with the name localhost.

  5. Aprire il menu di scelta rapida per quell'elemento specifico, scegliere Get Item(Ottieni elemento) e nell'opzione Trust > When using this certificate (Attendibilità > Quando si usa questo certificato) selezionare Always Trust (Considera sempre attendibile).Open the context menu for that particular item, select Get Item and under Trust > When using this certificate option, select Always Trust.

    Aprire il menu di scelta rapida per quell'elemento specifico, scegliere Get Item (Ottieni elemento) e nell'opzione Trust - When using this certificate (Attendibilità - Quando si usa questo certificato) selezionare Always Trust (Considera sempre attendibile)

Opzione 2: disabilitare la convalida SSL nell'applicazioneOption 2: Disable the SSL validation in the application

La disabilitazione della convalida SSL è consigliata solo a scopo di sviluppo e non deve essere eseguita in un ambiente di produzione.Disabling SSL validation is only recommended for development purposes and should not be done when running in a production environment. Gli esempi seguenti illustrano come disabilitare la convalida SSL per le applicazioni .NET e Node.js.The following examples show how to disable SSL validation for .NET and Node.js applications.

Per tutte le applicazioni in esecuzione in un Framework compatibile con .NET Standard 2,1 o versione successiva, è possibile utilizzare CosmosClientOptions.HttpClientFactory :For any application running in a framework compatible with .NET Standard 2.1 or later, we can leverage the 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);

Abilitare l'accesso all'emulatore in una rete localeEnable access to emulator on a local network

Se sono presenti più computer che usano una singola rete e se si configura l'emulatore in un computer e si vuole accedervi da un altro computer.If you have multiple machines using a single network, and if you set up the emulator on one machine and want to access it from other machine. In tal caso, è necessario abilitare l'accesso all'emulatore in una rete locale.In such case, you need to enable access to the emulator on a local network.

È possibile eseguire l'emulatore in una rete locale.You can run the emulator on a local network. Per abilitare l'accesso tramite rete, specificare l'opzione /AllowNetworkAccess nella riga di comando, che richiede di specificare anche /Key=key_string o /KeyFile=file_name.To enable network access, specify the /AllowNetworkAccess option at the command-line, which also requires that you specify /Key=key_string or /KeyFile=file_name. È possibile usare /GenKeyFile=file_name per generare un file con una chiave casuale sin dall'inizio,You can use /GenKeyFile=file_name to generate a file with a random key upfront. per poi passarli a /KeyFile=file_name o /Key=contents_of_file.Then you can pass that to /KeyFile=file_name or /Key=contents_of_file.

Per abilitare l'accesso alla rete per la prima volta, l'utente deve arrestare l'emulatore ed eliminare la directory dei dati dell'emulatore %LocalAppData%\CosmosDBEmulator.To enable network access for the first time, the user should shut down the emulator and delete the emulator's data directory %LOCALAPPDATA%\CosmosDBEmulator.

Autenticare le connessioni quando si usa l'emulatoreAuthenticate connections when using emulator

Come per Azure Cosmos DB nel cloud, tutte le richieste effettuate nell'emulatore di Azure Cosmos DB devono essere autenticate.As with Azure Cosmos DB in the cloud, every request that you make against the Azure Cosmos DB Emulator must be authenticated. L'emulatore Azure Cosmos DB supporta solo le comunicazioni protette tramite TLS.The Azure Cosmos DB Emulator supports only secure communication via TLS. L'emulatore Azure Cosmos DB supporta un singolo account fisso e una chiave di autenticazione nota per l'autenticazione della chiave primaria.The Azure Cosmos DB Emulator supports a single fixed account and a well-known authentication key for primary key authentication. Questo account e questa chiave sono le uniche credenziali consentite per l'uso con l'emulatore di Azure Cosmos DB.This account and key are the only credentials permitted for use with the Azure Cosmos DB Emulator. ovvero:They are:

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

Nota

La chiave primaria supportata dall'emulatore di Azure Cosmos DB deve essere usata solo con l'emulatore.The primary key supported by the Azure Cosmos DB Emulator is intended for use only with the emulator. È possibile utilizzare l'account Azure Cosmos DB di produzione e la chiave con l'emulatore di Azure Cosmos DB.You cannot use your production Azure Cosmos DB account and key with the Azure Cosmos DB Emulator.

Nota

Se l'emulatore è stato avviato con l'opzione/Key, usare la chiave generata anziché la chiave predefinita C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== .If you have started the emulator with the /Key option, then use the generated key instead of the default key C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. Per altre informazioni sull'opzione /Key, vedere Informazioni di riferimento sullo strumento da riga di comando.For more information about /Key option, see Command-line tool reference.

Connettersi a API diverse con l'emulatoreConnect to different APIs with the emulator

API SQLSQL API

Una volta che il Azure Cosmos DB emulatore è in esecuzione sul desktop, è possibile usare qualsiasi SDK Azure Cosmos DB supportato o l' API REST Azure Cosmos DB per interagire con l'emulatore.Once you have the Azure Cosmos DB Emulator running on your desktop, you can use any supported Azure Cosmos DB SDK or the Azure Cosmos DB REST API to interact with the emulator. L'emulatore Azure Cosmos DB include anche una finestra di esplorazione dei dati incorporata che consente di creare contenitori per l'API SQL o Azure Cosmos DB per l'API di Mongo DB.The Azure Cosmos DB Emulator also includes a built-in data explorer that lets you create containers for SQL API or Azure Cosmos DB for Mongo DB API. Con Esplora dati è possibile visualizzare e modificare gli elementi senza scrivere alcun codice.By using the data explorer, you can view and edit items without writing any code.

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

API Azure Cosmos DB per MongoDBAzure Cosmos DB's API for MongoDB

Una volta che il Azure Cosmos DB emulatore è in esecuzione sul desktop, è possibile usare l' API Azure Cosmos DB per MongoDB per interagire con l'emulatore.Once you have the Azure Cosmos DB Emulator running on your desktop, you can use the Azure Cosmos DB's API for MongoDB to interact with the emulator. Avviare l'emulatore dal prompt dei comandi come amministratore con "/EnableMongoDbEndpoint".Start the emulator from command prompt as an administrator with "/EnableMongoDbEndpoint". Usare quindi la stringa di connessione seguente per connettersi all'account dell'API MongoDB:Then use the following connection string to connect to the MongoDB API account:

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

API di tabellaTable API

Una volta che il Azure Cosmos DB emulatore è in esecuzione sul desktop, è possibile usare l' SDK Azure Cosmos DB API tabella per interagire con l'emulatore.Once you have the Azure Cosmos DB Emulator running on your desktop, you can use the Azure Cosmos DB Table API SDK to interact with the emulator. Avviare l'emulatore dal prompt dei comandi come amministratore con "/EnableTableEndpoint".Start the emulator from command prompt as an administrator with "/EnableTableEndpoint". quindi eseguire il codice seguente per connettersi all'account dell'API Tabella:Next run the following code to connect to the table API account:

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 CassandraCassandra API

Avviare l'emulatore da un prompt dei comandi dell'amministratore con "/EnableCassandraEndpoint".Start emulator from an administrator command prompt with "/EnableCassandraEndpoint". In alternativa, è anche possibile impostare la variabile di ambiente AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.Alternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.

  1. Installare Python 2.7Install Python 2.7

  2. Installare Cassandra CLI/CQLSHInstall Cassandra CLI/CQLSH

  3. Eseguire i comandi seguenti in una normale finestra del prompt dei comandi:Run the following commands in a regular command prompt window:

    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. Nella shell CQLSH eseguire i comandi seguenti per connettersi all'endpoint Cassandra:In the CQLSH shell, run the following commands to connect to the Cassandra endpoint:

    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 GremlinGremlin API

Avviare l'emulatore da un prompt dei comandidell'amministratore con "/EnableGremlinEndpoint".Start emulator from an administrator command promptwith "/EnableGremlinEndpoint". In alternativa, è anche possibile impostare la variabile di ambiente AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=trueAlternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

  1. Installare apache-tinkerpop-gremlin-console-3.3.4.Install apache-tinkerpop-gremlin-console-3.3.4.

  2. Da Esplora dati dell'emulatore creare un database "DB1" e una raccolta "coll1"; per la chiave di partizione, scegliere "/Name".From the emulator's data explorer create a database "db1" and a collection "coll1"; for the partition key, choose "/name"

  3. Eseguire i comandi seguenti in una normale finestra del prompt dei comandi:Run the following commands in a regular command prompt window:

    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. Nella shell Gremlin eseguire i comandi seguenti per connettersi all'endpoint Gremlin:In the Gremlin shell, run the following commands to connect to the Gremlin endpoint:

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

Disinstallare l'emulatore localeUninstall the local emulator

Per disinstallare l'emulatore, attenersi alla procedura seguente:Use the following steps to uninstall the emulator:

  1. Uscire da tutte le istanze aperte dell'emulatore locale facendo clic con il pulsante destro del mouse sull'icona dell' emulatore Azure Cosmos DB nella barra delle applicazioni, quindi scegliere Esci.Exit all the open instances of the local emulator by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then select Exit. La chiusura di tutte le istanze può richiedere qualche minuto.It may take a minute for all instances to exit.

  2. Nella casella di ricerca di Windows digitare app & funzionalità e selezionare app & le funzionalità (impostazioni di sistema) .In the Windows search box, type Apps & features and select Apps & features (System settings) result.

  3. Nell'elenco di app scorrere fino all' emulatore Azure Cosmos DB, selezionarlo, fare clic su Disinstalla, quindi confermare e selezionare di nuovo Disinstalla .In the list of apps, scroll to the Azure Cosmos DB Emulator, select it, click Uninstall, then confirm and select Uninstall again.

Passaggi successiviNext steps

In questo articolo si è appreso come usare l'emulatore locale per lo sviluppo locale gratuito.In this article, you've learned how to use the local emulator for free local development. È ora possibile passare agli articoli successivi:You can now proceed to the next articles: