Linux-basierter Emulator (Vorschau)
Die nächste Generation des Azure Cosmos DB-Emulators ist vollständig Linux-basiert und als Docker-Container verfügbar. Er unterstützt die Ausführung auf einer Vielzahl von Prozessoren und Betriebssystemen.
Wichtig
Diese Version des Emulators unterstützt nur die API für NoSQL im Gatewaymodus mit einer Teilmenge von Features. Weitere Informationen finden Sie unter Featureunterstützung.
Voraussetzungen
Installation
Rufen Sie das Docker-Containerimage mit docker pull ab. Das Containerimage wird in der Microsoft-Artefaktregistrierung als mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview veröffentlicht.
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
Wird ausgeführt
Verwenden Sie zum Ausführen des Containers docker run. Überprüfen Sie anschließend mit docker ps, ob der Container ausgeführt wird.
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>
Hinweis
Der Emulator besteht aus zwei Komponenten:
- Daten-Explorer: zum interaktiven Untersuchen der Daten im Emulator. Die Ausführung erfolgt standardmäßig an Port
1234. - Azure Cosmos DB-Emulator: eine lokale Version des Azure Cosmos DB-Datenbankdiensts. Die Ausführung erfolgt standardmäßig an Port
8081.
Der Gatewayendpunkt des Emulators ist in der Regel am Port 8081 über die Adresse http://localhost:8081 erreichbar. Verwenden Sie für die Navigation zum Daten-Explorer die Adresse http://localhost:1234 in Ihrem Webbrowser. Es kann einige Sekunden dauern, bis der Daten-Explorer verfügbar ist. Der Gatewayendpunkt ist in der Regel sofort verfügbar.
Wichtig
Die .NET und Java-SDKs unterstützen den HTTP-Modus im Emulator nicht. Da diese Version des Emulators standardmäßig mit HTTP beginnt, müssen Sie HTTPS beim Starten des Containers explizit aktivieren (siehe unten). Für das Java-SDK müssen Sie auch Zertifikate installieren.
docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https
Docker-Befehle
In der folgenden Tabelle sind die verfügbaren Docker-Befehle zum Konfigurieren des Emulators zusammengefasst. In dieser Tabelle finden Sie die entsprechenden Argumente, Umgebungsvariablen, zulässigen Werte, Standardeinstellungen und Beschreibungen der einzelnen Befehle.
| Anforderung | Argument | Env | Zulässige Werte | Default | Beschreibung |
|---|---|---|---|---|---|
| Ausgeben der Einstellungen an stdout aus dem Container | --help, -h |
– | – | – | Anzeigen von Informationen zur verfügbaren Konfiguration |
| Festlegen des Ports des Cosmos-Endpunkts | --port [INT] |
PORT | INT | 8081 | Der Port des Cosmos-Endpunkts im Container. Sie müssen diesen Port noch veröffentlichen (z. B. mit -p 8081:8081). |
| Angeben des vom Cosmos-Endpunkt verwendeten Protokolls | --protocol |
PROTOKOLL | https, http, https-insecure |
http |
Das Protokoll des Cosmos-Endpunkts im Container. |
| Aktivieren des Daten-Explorers | --enable-explorer |
ENABLE_EXPLORER | true, false |
true |
Aktivieren Sie die Ausführung des Cosmos-Daten-Explorers im selben Container. |
| Festlegen des vom Daten-Explorer verwendeten Ports | --explorer-port |
EXPLORER_PORT | INT | 1234 | Der Port des Cosmos-Daten-Explorers im Container. Sie müssen diesen Port noch veröffentlichen (z. B. mit -p 1234:1234). |
| Benutzende sollten in der Lage sein, das vom Explorer verwendete Protokoll anzugeben, andernfalls wird standardmäßig das vom Cosmos-Endpunkt verwendete Protokoll festgelegt. | --explorer-protocol |
EXPLORER_PROTOCOL | https, http, https-insecure |
<the value of --protocol> |
Das Protokoll des Cosmos-Daten-Explorers im Container. Standardmäßig wird das auf dem Cosmos-Endpunkt festgelegte Protokoll verwendet. |
| Angeben des Schlüssels über eine Datei | --key-file [PATH] |
KEY_FILE | PFAD | <default secret> |
Überschreiben Sie den Standardschlüssel mit dem in der Datei angegebenen Schlüssel. Sie müssen diese Datei in den Container einbinden (z. B. indem Sie bei „KEY_FILE=/mykey“ eine Option wie die folgende in Ihrer Docker-Ausführung hinzufügen: --mount type=bind,source=./myKey,target=/myKey) |
| Festlegen des Datenpfads | --data-path [PATH] |
DATA_PATH | PFAD | /data |
Geben Sie ein Verzeichnis für die Daten an. Häufig zusammen mit der docker run --mount-Option verwendet (z. B. indem Sie bei „DATA_PATH=/usr/cosmos/data“ eine Option wie die folgende in Ihrer Docker-Ausführung hinzufügen: --mount type=bind,source=./.local/data,target=/usr/cosmos/data) |
| Angeben des für HTTPS verwendeten Zertifikatpfads | --cert-path [PATH] |
CERT_PATH | PFAD | <default cert> |
Geben Sie einen Pfad zu einem Zertifikat zum Schützen des Datenverkehrs an. Sie müssen diese Datei in den Container einbinden (z. B. indem Sie bei „CERT_PATH=/mycert.pfx“ eine Option wie die folgende in Ihrer Docker-Ausführung hinzufügen: --mount type=bind,source=./mycert.pfx,target=/mycert.pfx) |
| Angeben des für HTTPS verwendeten Zertifikatgeheimnisses | N/V | CERT_SECRET | Zeichenfolge | <default secret> |
Das Geheimnis für das in CERT_PATH angegebene Zertifikat. |
| Festlegen des Protokolliergrads | --log-level [LEVEL] |
LOG_LEVEL | quiet, error, warn, info, debug, trace |
info |
Die Ausführlichkeit von Protokollen, die vom Emulator und vom Daten-Explorer ausgegeben werden. |
| Aktivieren der Übermittlung von Diagnoseinformationen an Microsoft | --enable-telemetry |
ENABLE_TELEMETRY | true, false |
true |
Aktivieren Sie das Senden von Protokollen an Microsoft, damit der Emulator weiter verbessert werden kann. |
Featureunterstützung
Dieser Emulator befindet sich in der aktiven Entwicklung und wird als Vorschauversion verfügbar gemacht. Daher werden nicht alle Azure Cosmos DB-Features unterstützt. Einige Features werden auch in Zukunft nicht unterstützt. In dieser Tabelle finden Sie den Status verschiedener Features mit dem Grad ihrer Unterstützung.
| Funktion | Unterstützung |
|---|---|
| Batch-API | ✅ Unterstützt |
| Massen-API | ✅ Unterstützt |
| Änderungsfeed | ⚠ Noch nicht implementiert |
| Erstellen und Lesen von Dokumenten mit UTF-Daten | ✅ Unterstützt |
| Erstellen der Sammlung | ✅ Unterstützt |
| Erstellen einer Sammlung trotz Konflikt | ✅ Unterstützt |
| Erstellen einer Sammlung mit benutzerdefinierter Indexrichtlinie | ⚠ Noch nicht implementiert |
| Erstellen einer Sammlung mit TTL-Ablauf | ⚠ Noch nicht implementiert |
| Erstellen der Datenbank | ✅ Unterstützt |
| Erstellen einer Datenbank trotz Konflikt | ✅ Unterstützt |
| Erstellen von Dokumenten | ✅ Unterstützt |
| Erstellen partitionierter Sammlungen | ⚠ Noch nicht implementiert |
| Sammlung löschen | ✅ Unterstützt |
| Löschen von Datenbanken | ✅ Unterstützt |
| Löschen eines Dokuments | ✅ Unterstützt |
| Abrufen und Ändern der Sammlungsleistung | ⚠ Noch nicht implementiert |
| Einfügen großer Dokumente | ✅ Unterstützt |
| Reparieren von Dokumenten | ⚠ Noch nicht implementiert |
| Paralleles Abfragen partitionierter Sammlungen | ⚠ Noch nicht implementiert |
| Abfragen mit Aggregaten | ⚠ Noch nicht implementiert |
| Abfragen und Filtern | ⚠ Noch nicht implementiert |
| Abfragen mit und Filtern und Projektionen | ⚠ Noch nicht implementiert |
| Abfrage mit Gleichheit | ✅ Unterstützt |
| Abfrage auf Gleichheit bei ID | ✅ Unterstützt |
| Abfragen mit Verknüpfungen | ⚠ Noch nicht implementiert |
| Abfragen mit „ORDER BY“ | ✅ Unterstützt |
| Abfrage mit „ORDER BY“ für partitionierte Sammlungen | ⚠ Noch nicht implementiert |
| Abfrage mit „ORDER BY“ von Zahlen | ✅ Unterstützt |
| Abfrage mit „ORDER BY“ von Zeichenfolgen | ⚠ Noch nicht implementiert |
| Abfrage mit Paginierung | ⚠ Noch nicht implementiert |
| Abfragen mit Bereichsoperatoren für Datums-/Uhrzeitwerte | ⚠ Noch nicht implementiert |
| Abfragen mit Bereichsoperatoren für Zahlen | ⚠ Noch nicht implementiert |
| Abfragen mit Bereichsoperatoren für Zeichenfolgen | ⚠ Noch nicht implementiert |
| Abfragen mit einer einzelnen Verknüpfung | ⚠ Noch nicht implementiert |
| Abfragen mit Zeichenfolgen-, mathematischen und Arrayoperatoren | ⚠ Noch nicht implementiert |
| Abfragen mit Unterdokumenten | ⚠ Noch nicht implementiert |
| Abfragen mit zwei Verknüpfungen | ⚠ Noch nicht implementiert |
| Abfragen mit zwei Verknüpfungen und Filtern | ⚠ Noch nicht implementiert |
| Lesen von Sammlungen | ✅ Unterstützt |
| Lesen des Sammlungsfeeds | ⚠ Noch nicht implementiert |
| Lesen in Datenbanken | ✅ Unterstützt |
| Lesen des Datenbankfeeds | ⚠ Noch nicht implementiert |
| Lesen von Dokumenten | ✅ Unterstützt |
| Lesen des Dokumentfeeds | ✅ Unterstützt |
| Dokument ersetzen | ✅ Unterstützt |
| Anforderungseinheiten | ⚠ Noch nicht implementiert |
| Gespeicherten Prozeduren | ❌ Nicht geplant |
| Trigger | ❌ Nicht geplant |
| UDFs | ❌ Nicht geplant |
| Aktualisieren der Sammlung | ⚠ Noch nicht implementiert |
| Aktualisieren von Dokumenten | ✅ Unterstützt |
Begrenzungen
Zusätzlich zu den Features, die noch nicht unterstützt werden oder nicht geplant sind, zeigt die folgende Liste aktuelle Einschränkungen des Emulators.
- Das .NET SDK für Azure Cosmos DB unterstützt keine Massenausführungen im Emulator.
- Die .NET und Java-SDKs unterstützen den HTTP-Modus im Emulator nicht.
Installieren von Zertifikaten für Java-SDK
Wenn Sie das Java SDK für Azure Cosmos DB mit dieser Version des Emulators im HTTPS-Modus verwenden, ist es erforderlich, die Zertifikate in Ihrem lokalen Java Trust Store zu installieren.
Abrufen des Zertifikats
Führen Sie in einem bash-Fenster Folgendes aus:
# 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
Installieren des Zertifikats
Navigieren Sie zum Verzeichnis Ihrer Java-Installation, in dem sich cacerts-Datei befindet (setzen Sie unten das richtige Verzeichnis ein):
cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"
Importieren Sie das Zertifikat (möglicherweise werden Sie nach einem Kennwort gefragt, der Standardwert lautet „changeit”):
keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH
Wenn ein Fehler angezeigt wird, weil der Alias bereits vorhanden ist, löschen Sie ihn, und führen Sie dann den obigen Vorgang erneut aus:
keytool -cacerts -delete -alias cosmos_emulator
Melden von Problemen
Wenn Probleme mit der Verwendung dieser Version des Emulators auftreten, erstellen Sie ein Issue im GitHub-Repository (https://github.com/Azure/azure-cosmos-db-emulator-docker) mit dem Tag cosmosEmulatorVnextPreview.