Schnellstart: Azure Cosmos DB for NoSQL-Bibliothek für Java
GILT FÜR: NoSQL
Führen Sie die ersten Schritte mit der Azure Cosmos DB for NoSQL-Clientbibliothek für Java durch, um Daten in Ihren Containern abzufragen und allgemeine Vorgänge für einzelne Elemente auszuführen. Führen Sie die folgenden Schritte aus, um eine minimale Lösung für Ihre Umgebung mithilfe der Azure Developer CLI bereitzustellen.
API-Referenzdokumentation | Quellcode der Bibliothek | Paket (Maven) | Azure Developer CLI
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- GitHub-Konto
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure Developer CLI
- Docker Desktop
Einrichten
Stellen Sie den Entwicklungscontainer dieses Projekts in Ihrer Umgebung bereit. Verwenden Sie dann Azure Developer CLI (azd
), um ein Azure Cosmos DB for NoSQL-Konto zu erstellen und eine containerisierte Beispielanwendung bereitzustellen. Die Beispielanwendung verwendet die Clientbibliothek zum Verwalten, Erstellen, Lesen und Abfragen von Beispieldaten.
Wichtig
GitHub-Konten enthalten eine Berechtigung für Speicher und Kernstunden, für die jeweils keine Kosten anfallen. Weitere Informationen finden Sie unter Monatlich enthaltene Speicherkapazität und Kernstunden für GitHub-Konten.
Öffnen Sie ein Terminal im Stammverzeichnis des Projekts.
Authentifizieren Sie sich mithilfe von
azd auth login
bei Azure Developer CLI. Führen Sie die vom Tool angegebenen Schritte aus, um sich mit Ihren bevorzugten Azure-Anmeldeinformationen bei der CLI zu authentifizieren.azd auth login
Verwenden Sie
azd init
, um das Projekt zu initialisieren.azd init --template cosmos-db-nosql-dotnet-quickstart
Hinweis
Diese Schnellstartanleitung verwendet das GitHub-Vorlagenrepository azure-samples/cosmos-db-nosql-dotnet-quickstart. Die Azure Developer CLI klont dieses Projekt automatisch auf Ihrem Computer, wenn es noch nicht vorhanden ist.
Konfigurieren Sie während der Initialisierung einen eindeutigen Umgebungsnamen.
Tipp
Der Umgebungsname wird auch als Name der Zielressourcengruppe verwendet. Ziehen Sie für diese Schnellstartanleitung die Verwendung von
msdocs-cosmos-db
in Betracht.Stellen Sie das Azure Cosmos DB-Konto mit
azd up
bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.azd up
Wählen Sie während des Bereitstellungsprozesses Ihr Abonnement und den gewünschten Standort aus. Warten Sie auf den Abschluss des Bereitstellungsvorgangs. Dieser Prozess kann ca. fünf Minuten dauern.
Sobald die Bereitstellung Ihrer Azure-Ressourcen abgeschlossen ist, enthält die Ausgabe eine URL zur ausgeführten Webanwendung.
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io> SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
Verwenden Sie die URL in der Konsole, um im Browser zu Ihrer Webanwendung zu navigieren. Sehen Sie sich die Ausgabe der ausgeführten App an.
Installieren der Clientbibliothek
Die Clientbibliothek ist über Maven als azure-spring-data-cosmos
-Paket verfügbar.
Navigieren Sie zum
/src/web
-Ordner, und öffnen Sie die pom.xml-Datei.Wenn sie noch nicht vorhanden ist, fügen Sie einen Eintrag für das
azure-spring-data-cosmos
-Paket hinzu.<dependency> <groupId>com.azure</groupId> <artifactId>azure-spring-data-cosmos</artifactId> </dependency>
Fügen Sie außerdem eine weitere Abhängigkeit für das
azure-identity
-Paket hinzu, wenn es noch nicht vorhanden ist.<dependency> <groupId>com.azure</groupId> <artifactId>azure-identity</artifactId> </dependency>
Objektmodell
name | Beschreibung |
---|---|
EnableCosmosRepositories |
Dieser Typ ist ein Methodendecorator, der zum Konfigurieren eines Repositorys für den Zugriff auf Azure Cosmos DB for NoSQL verwendet wird. |
CosmosRepository |
Diese Klasse ist die primäre Clientklasse und wird verwendet, um Daten in einem Container zu verwalten. |
CosmosClientBuilder |
Diese Klasse ist eine Factory, die zum Erstellen eines Clients verwendet wird, der vom Repository verwendet wird. |
Query |
Dieser Typ ist ein Methodendecorator, der verwendet wird, um die Abfrage anzugeben, die das Repository ausführt. |
Codebeispiele
- Authentifizieren des Clients
- Datenbank abrufen
- Container abrufen
- Erstellen eines Elements
- Abrufen eines Elements
- Abfrageelemente
Der Beispielcode in der Vorlage verwendet eine Datenbank mit dem Namen cosmicworks
und einen Container mit dem Namen products
. Der products
-Container enthält Details wie Name, Kategorie, Menge, eindeutiger Bezeichner und ein Verkaufsflag für jedes Produkt. Der Container verwendet die /category
-Eigenschaft als logischen Partitionsschlüssel.
Authentifizieren des Clients
Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Verwenden Sie den DefaultAzureCredential
-Typ als bevorzugte Methode, um eine kennwortlose Verbindung zwischen Ihren Anwendungen und Azure Cosmos DB for NoSQL zu implementieren. DefaultAzureCredential
unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll.
Wichtig
Anforderungen an Azure-Dienste können auch direkt mithilfe von Kennwörtern, Verbindungszeichenfolgen oder anderen Anmeldeinformationen autorisiert werden. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen darauf achten, dass diese Geheimnisse nicht an einem unsicheren Ort offengelegt werden. Alle Benutzer*innen, die Zugriff auf das Kennwort oder auf den geheimen Schlüssel erhalten, können sich damit beim Datenbankdienst authentifizieren. DefaultAzureCredential
bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, um kennwortlose Authentifizierung zu ermöglichen,ohne dass das Risiko besteht, Schlüssel zu speichern.
Zunächst erstellt dieses Beispiel eine neue Klasse, die von AbstractCosmosConfiguration
erbt, um die Verbindung mit Azure Cosmos DB for NoSQL zu konfigurieren.
@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
}
In der Konfigurationsklasse erstellt dieses Beispiel eine neue Instanz der CosmosClientBuilder
-Klasse und konfiguriert die Authentifizierung mithilfe einer DefaultAzureCredential
-Instanz.
@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
.build();
return new CosmosClientBuilder()
.endpoint("<azure-cosmos-db-nosql-account-endpoint>")
.credential(credential);
}
Datenbank abrufen
In der Konfigurationsklasse implementiert das Beispiel eine Methode, um den Namen der vorhandenen Datenbank mit dem Namen cosmicworks
zurückzugeben.
@Override
protected String getDatabaseName() {
return "cosmicworks";
}
Container abrufen
Verwenden Sie den Container
-Methodendecorator, um eine Klasse für die Darstellung von Elementen in einem Container zu konfigurieren. Erstellen Sie die Klasse, um alle Member einzuschließen, die Sie in JSON serialisieren möchten. In diesem Beispiel verfügt der Typ über einen eindeutigen Bezeichner und Felder für Kategorie, Name, Menge, Preis und Abfertigung.
@Container(containerName = "products", autoCreateContainer = false)
public class Item {
private String id;
private String name;
private Integer quantity;
private Boolean sale;
@PartitionKey
private String category;
// Extra members omitted for brevity
}
Erstellen eines Elements
Erstellen Sie mithilfe von repository.save
ein Element im Container.
Item item = new Item(
"70b63682-b93a-4c77-aad2-65501347265f",
"gear-surf-surfboards",
"Yamba Surfboard",
12,
false
);
Item created_item = repository.save(item);
Lesen eines Elements
Führen Sie einen Punktlesevorgang aus, indem Sie sowohl die eindeutigen Bezeichner (id
) als auch die Partitionsschlüsselfelder verwenden. Verwenden Sie repository.findById
, um das jeweilige Element effizient abzurufen.
PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("70b63682-b93a-4c77-aad2-65501347265f", partitionKey);
if (existing_item.isPresent()) {
// Do something
}
Abfrageelemente
Führen Sie eine Abfrage über mehrere Elemente in einem Container aus, indem Sie eine Abfrage in der Benutzeroberfläche des Repositorys definieren. In diesem Beispiel wird der Query
-Methodendecorator verwendet, um eine Methode zu definieren, die diese parametrisierte Abfrage ausführt:
SELECT * FROM products p WHERE p.category = @category
@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {
@Query("SELECT * FROM products p WHERE p.category = @category")
List<Item> getItemsByCategory(@Param("category") String category);
}
Rufen Sie alle Ergebnisse der Abfrage mithilfe von repository.getItemsByCategory
ab. Durchlaufen Sie die Ergebnisse der Abfrage.
List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
// Do something
}