Emulatore basato su Linux (anteprima)
La prossima generazione dell'emulatore di Azure Cosmos DB è interamente basata su Linux ed è disponibile come contenitore Docker. Supporta l'esecuzione su un'ampia gamma di processori e sistemi operativi.
Importante
Questa versione dell'emulatore supporta solo l'API per NoSQL in modalità gateway, con un subset di funzionalità selezionato. Per altre informazioni, vedere Supporto delle funzionalità.
Prerequisiti
Installazione
Ottenere l'immagine del contenitore Docker usando docker pull. L'immagine del contenitore viene pubblicata nel Registro artefatti Microsoft come mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
In esecuzione
Per eseguire il contenitore, usare docker run. Successivamente, usare docker ps per verificare che il contenitore sia in esecuzione.
docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c1bb8cf53f8a mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview "/bin/bash -c /home/…" 5 seconds ago Up 5 seconds 0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp <container-name>
Nota
L'emulatore è costituito da due componenti:
- Esplora dati: esplorare in modo interattivo i dati nell'emulatore. Per impostazione predefinita, questa operazione viene eseguita sulla porta
1234 - Emulatore di Azure Cosmos DB: una versione locale del servizio di database Azure Cosmos DB. Per impostazione predefinita, questa operazione viene eseguita sulla porta
8081.
L'endpoint del gateway emulatore è in genere disponibile sulla porta 8081 all'indirizzo http://localhost:8081. Per passare a Esplora dati, usare l'indirizzo http://localhost:1234 nel Web browser. La disponibilità di Esplora dati potrebbe richiedere alcuni secondi. L'endpoint del gateway è in genere disponibile immediatamente.
Importante
Gli SDK .NET e Java non supportano la modalità HTTP nell'emulatore. Poiché questa versione dell'emulatore inizia con HTTP per impostazione predefinita, sarà necessario abilitare in modo esplicito HTTPS all'avvio del contenitore (vedere di seguito). Per Java SDK, sarà anche necessario installare i certificati.
docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https
Comandi Docker
La tabella seguente riepiloga i comandi Docker disponibili per la configurazione dell'emulatore. Questa tabella illustra in dettaglio gli argomenti corrispondenti, le variabili di ambiente, i valori consentiti, le impostazioni predefinite e le descrizioni di ogni comando.
| Requisito | Argomento | Env | Valori consentiti | Default | Descrizione |
|---|---|---|---|---|---|
| Stampare le impostazioni in stdout dal contenitore | --help, -h |
N/D | N/D | N/D | Visualizzare le informazioni sulla configurazione disponibile |
| Impostare la porta dell'endpoint Cosmos | --port [INT] |
PORTA | INT | 8081 | Porta dell'endpoint Cosmos nel contenitore. È comunque necessario pubblicare questa porta, ad esempio -p 8081:8081. |
| Specificare il protocollo usato dall'endpoint Cosmos | --protocol |
PROTOCOLLO | https, http, https-insecure |
http |
Protocollo dell'endpoint Cosmos nel contenitore. |
| Abilitare Esplora dati | --enable-explorer |
ENABLE_EXPLORER | true, false |
true |
Abilitare l'esecuzione del Esplora dati Cosmos nello stesso contenitore. |
| Impostare la porta usata da Esplora dati | --explorer-port |
EXPLORER_PORT | INT | 1234 | Porta del Esplora dati Cosmos nel contenitore. È comunque necessario pubblicare questa porta, ad esempio -p 1234:1234. |
| L'utente deve essere in grado di specificare il protocollo usato da Explorer. In caso contrario, per impostazione predefinita, l'endpoint Cosmos usa | --explorer-protocol |
EXPLORER_PROTOCOL | https, http, https-insecure |
<the value of --protocol> |
Protocollo del Esplora dati Cosmos nel contenitore. Il valore predefinito è l'impostazione del protocollo nell'endpoint Cosmos. |
| Specificare la chiave tramite file | --key-file [PATH] |
KEY_FILE | PATH | <default secret> |
Eseguire l'override della chiave predefinita con la chiave specificata nel file. È necessario montare questo file nel contenitore( ad esempio, se KEY_FILE=/mykey, aggiungere un'opzione simile alla seguente all'esecuzione di Docker: --mount type=bind,source=./myKey,target=/myKey) |
| Impostare il percorso dati | --data-path [PATH] |
DATA_PATH | PATH | /data |
Specificare una directory per i dati. Usato di frequente con docker run --mount l'opzione (ad esempio, se DATA_PATH=/usr/cosmos/data, è necessario aggiungere un'opzione simile alla seguente all'esecuzione di Docker: --mount type=bind,source=./.local/data,target=/usr/cosmos/data) |
| Specificare il percorso del certificato da usare per https | --cert-path [PATH] |
CERT_PATH | PATH | <default cert> |
Specificare un percorso di un certificato per la protezione del traffico. È necessario montare questo file nel contenitore( ad esempio, se CERT_PATH=/mycert.pfx, aggiungere un'opzione simile alla seguente all'esecuzione di Docker: --mount type=bind,source=./mycert.pfx,target=/mycert.pfx) |
| Specificare il segreto del certificato da usare per https | N/D | CERT_SECRET | string | <default secret> |
Segreto per il certificato specificato in CERT_PATH. |
| Impostare il livello di log | --log-level [LEVEL] |
LOG_LEVEL | quiet, error, warn, info, debugtrace |
info |
Dettaglio dei log generati dall'emulatore e da Esplora dati. |
| Abilitare l'invio di informazioni di diagnostica a Microsoft | --enable-telemetry |
ENABLE_TELEMETRY | true, false |
true |
Abilitare l'invio di log a Microsoft per migliorare l'emulatore. |
Supporto funzionalità
Questo emulatore è in fase di sviluppo e anteprima attivi. Di conseguenza, non tutte le funzionalità di Azure Cosmos DB sono supportate. Alcune funzionalità non saranno supportate in futuro. Questa tabella include lo stato di varie funzionalità e il relativo livello di supporto.
| Funzionalità | Supporto tecnico |
|---|---|
| Batch API | ✅ supportato |
| API in blocco | ✅ supportato |
| Feed di modifiche | ⚠️ Non ancora implementato |
| Creare e leggere un documento con dati utf | ✅ supportato |
| CreateCollection | ✅ supportato |
| Creare una raccolta due volte in conflitto | ✅ supportato |
| Creare una raccolta con criteri di indice personalizzati | ⚠️ Non ancora implementato |
| Creare una raccolta con scadenza ttl | ⚠️ Non ancora implementato |
| CreateDatabase | ✅ supportato |
| Creare un conflitto di database due volte | ✅ supportato |
| Creare un documento | ✅ supportato |
| Creare una raccolta partizionata | ⚠️ Non ancora implementato |
| Elimina raccolta | ✅ supportato |
| Eliminare il database | ✅ supportato |
| Eliminare un documento | ✅ supportato |
| Ottenere e modificare le prestazioni della raccolta | ⚠️ Non ancora implementato |
| Inserisci documento di grandi dimensioni | ✅ supportato |
| Documento patch | ⚠️ Non ancora implementato |
| Eseguire query sulla raccolta partizionata in parallelo | ⚠️ Non ancora implementato |
| Query con aggregazioni | ⚠️ Non ancora implementato |
| Eseguire query con e filtrare | ⚠️ Non ancora implementato |
| Eseguire query con e filtrare e proiettare | ⚠️ Non ancora implementato |
| Query con uguaglianza | ✅ supportato |
| Query con uguale all'ID | ✅ supportato |
| Query con join | ⚠️ Non ancora implementato |
| Eseguire una query con ordine per | ✅ supportato |
| Eseguire una query con ordine per la raccolta partizionata | ⚠️ Non ancora implementato |
| Eseguire una query con ordine in base ai numeri | ✅ supportato |
| Eseguire query con ordine per stringhe | ⚠️ Non ancora implementato |
| Query con paging | ⚠️ Non ancora implementato |
| Eseguire una query con gli operatori di intervallo data/ora | ⚠️ Non ancora implementato |
| Eseguire query con operatori di intervallo sui numeri | ⚠️ Non ancora implementato |
| Eseguire query con operatori di intervallo su stringhe | ⚠️ Non ancora implementato |
| Query con un singolo join | ⚠️ Non ancora implementato |
| Eseguire query con operatori matematici e di matrice di stringhe | ⚠️ Non ancora implementato |
| Eseguire query con documenti secondari | ⚠️ Non ancora implementato |
| Eseguire una query con due join | ⚠️ Non ancora implementato |
| Eseguire una query con due join e filtri | ⚠️ Non ancora implementato |
| Lettura raccolta | ✅ supportato |
| Leggere il feed di raccolta | ⚠️ Non ancora implementato |
| Leggere il database | ✅ supportato |
| Leggere il feed di database | ⚠️ Non ancora implementato |
| Leggere il documento | ✅ supportato |
| Leggere il feed di documenti | ✅ supportato |
| Sostituisci documento | ✅ supportato |
| Unità richiesta | ⚠️ Non ancora implementato |
| Stored procedure | ❌ Non pianificato |
| Trigger | ❌ Non pianificato |
| Funzioni definite dall'utente | ❌ Non pianificato |
| UpdateCollection | ⚠️ Non ancora implementato |
| Aggiornare il documento | ✅ supportato |
Limiti
Oltre alle funzionalità non ancora supportate o non pianificate, l'elenco seguente include le limitazioni correnti dell'emulatore.
- .NET SDK per Azure Cosmos DB non supporta l'esecuzione in blocco nell'emulatore.
- Gli SDK .NET e Java non supportano la modalità HTTP nell'emulatore.
Installazione di certificati per Java SDK
Quando si usa Java SDK per Azure Cosmos DB con questa versione dell'emulatore in modalità https, è necessario installarli nell'archivio attendibilità Java locale.
Ottenere il certificato
In una bash finestra eseguire quanto segue:
# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
Installare il certificato
Passare alla directory dell'installazione java in cui cacerts si trova il file (sostituire di seguito con la directory corretta):
cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"
Importare il certificato (è possibile che venga richiesta una password, il valore predefinito è "changeit"):
keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH
Se viene visualizzato un errore perché l'alias esiste già, eliminarlo e quindi eseguire di nuovo quanto sopra:
keytool -cacerts -delete -alias cosmos_emulator
Segnalazione di problemi
Se si verificano problemi con l'uso di questa versione dell'emulatore, aprire un problema nel repository GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) e contrassegnarlo con l'etichetta cosmosEmulatorVnextPreview.