Hızlı Başlangıç: Java için Azure SDK ile NoSQL için Azure Cosmos DB kullanma

2025-06-11
Şunlara uygulanır: ✅ NoSQL

Bu hızlı başlangıçta, Java için Azure SDK'yı kullanarak noSQL için temel bir Azure Cosmos DB uygulaması dağıtacaksınız. NoSQL için Azure Cosmos DB, uygulamaların yapılandırılmamış verileri bulutta depolamasına olanak sağlayan şemasız bir veri deposudur. Kapsayıcılarınızdaki verileri sorgulayın ve Java için Azure SDK'sını kullanarak tek tek öğeler üzerinde ortak işlemler gerçekleştirin.

API başvuru belgeleri | Kitaplık kaynak kodu | Paket (Maven) | Azure Geliştirici CLI

Önkoşullar

Azure Geliştirici CLI
Docker Desktop
Java 21

Azure hesabınız yoksa, başlamadan önce ücretsiz hesap oluşturun.

Projeyi başlatma

Azure Geliştirici CLI'sını (azd) kullanarak NoSQL için Azure Cosmos DB hesabı oluşturun ve kapsayıcılı örnek bir uygulama dağıtın. Örnek uygulama örnek verileri yönetmek, oluşturmak, okumak ve sorgulamak için istemci kitaplığını kullanır.

Boş bir dizinde bir terminal açın.
Henüz kimlik doğrulaması yapmadıysanız, Azure Geliştirici CLI'sinde kimlik doğrulaması yapmak için azd auth login kullanın. Tercih ettiğiniz Azure kimlik bilgilerini kullanarak CLI'da kimlik doğrulaması yapmak için araç tarafından belirtilen adımları izleyin.
```
azd auth login
```

Projeyi başlatmak için kullanın azd init .

azd init --template cosmos-db-nosql-java-quickstart

Başlatma sırasında benzersiz bir ortam adı yapılandırın.
Azure Cosmos DB hesabını azd up kullanarak dağıtın. Bicep şablonları ayrıca örnek bir web uygulaması dağıtır.
```
azd up
```
Sağlama işlemi sırasında aboneliğinizi, istediğiniz konumu ve hedef kaynak grubunu seçin. Sağlama işleminin tamamlanmasını bekleyin. İşlem yaklaşık beş dakika sürebilir.

Azure kaynaklarınızın sağlanması tamamlandıktan sonra, çalışan web uygulamasının URL'si çıktıya eklenir.

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.

Tarayıcıda web uygulamanıza gitmek için konsoldaki URL'yi kullanın. Çalışan uygulamanın çalışmasını gözlemleyin.

Çalışan web uygulamasının ekran görüntüsü.

İstemci kitaplığını yükleme

İstemci kütüphanesi, azure-spring-data-cosmos paket olarak Maven aracılığıyla kullanılabilir.

Klasöre /src/web gidin ve pom.xml dosyasını açın.

Eğer henüz yoksa, azure-spring-data-cosmos paketi için bir girdi ekleyin.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
</dependency>

Henüz yoksa, azure-identity paketi için başka bir bağımlılık ekleyin.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Kitaplıkları içeri aktarma

Gerekli ad alanlarının tümünü uygulama kodunuz içine aktarın.

import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.models.PartitionKey;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.spring.data.cosmos.config.AbstractCosmosConfiguration;
import com.azure.spring.data.cosmos.config.CosmosConfig;
import com.azure.spring.data.cosmos.core.mapping.Container;
import com.azure.spring.data.cosmos.core.mapping.PartitionKey;
import com.azure.spring.data.cosmos.repository.CosmosRepository;
import com.azure.spring.data.cosmos.repository.Query;
import com.azure.spring.data.cosmos.repository.config.EnableCosmosRepositories;

Nesne modeli

İsim	Açıklama
`EnableCosmosRepositories`	Bu tür, NoSQL için Azure Cosmos DB'ye erişmek üzere bir depo yapılandırmak için kullanılan bir yöntem dekoratörüdür.
`CosmosRepository`	Bu sınıf birincil istemci sınıfıdır ve kapsayıcı içindeki verileri yönetmek için kullanılır.
`CosmosClientBuilder`	Bu sınıf, depo tarafından kullanılan bir istemci oluşturmak için kullanılan bir fabrikadır.
`Query`	Bu tür, deponun yürüttüğü sorguyu belirtmek için kullanılan bir yöntem dekoratörüdür.

Şablondaki örnek kod, cosmicworks adlı bir veritabanı ve products adlı bir kapsayıcı kullanır. Kapsayıcı ad products , kategori, miktar, benzersiz tanımlayıcı ve her ürün için satış bayrağı gibi ayrıntıları içerir. Kapsayıcı, mantıksal bölüm anahtarı olarak özelliğini kullanır /category .

İstemcinin kimliğini doğrulama

İlk olarak, bu örnek NoSQL için Azure Cosmos DB bağlantısını yapılandırmak üzere AbstractCosmosConfiguration öğesinden devralan yeni bir sınıf oluşturur.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
}

Yapılandırma sınıfı içinde, bu örnek sınıfın CosmosClientBuilder yeni bir örneğini oluşturur ve bir DefaultAzureCredential örnek kullanarak kimlik doğrulamasını yapılandırılır.

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
        .build();
        
    return new CosmosClientBuilder()
        .endpoint("<azure-cosmos-db-nosql-account-endpoint>")
        .credential(credential);
}

Veritabanı alma

Yapılandırma sınıfında, örnek adlı cosmicworksmevcut veritabanının adını döndürmek için bir yöntem uygular.

@Override
protected String getDatabaseName() {
    return "cosmicworks";
}

Bir kap alın

Kapsayıcıdaki Container öğeleri temsil eden bir sınıf yapılandırmak için yöntem dekoratörunu kullanın. JSON'da seri hale getirmek istediğiniz tüm üyeleri dahil etmek için sınıfını yazın. Bu örnekte, türün benzersiz bir tanımlayıcısı ve kategori, isim, miktar, fiyat ve satış alanları vardır.

@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
}

Öğe oluşturma

kullanarak repository.savekapsayıcıda bir öğe oluşturun.

Item item = new Item(
    "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "gear-surf-surfboards",
    "Yamba Surfboard",
    12,
    false
);
Item created_item = repository.save(item);

Bir öğeyi oku

Hem benzersiz tanımlayıcıyı (id) hem de bölüm anahtarı alanlarını kullanarak nokta okuma işlemi gerçekleştirin. Belirli bir öğeyi verimli bir şekilde almak için kullanın repository.findById .

PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", partitionKey);
if (existing_item.isPresent()) {
    // Do something
}

Sorgu öğeleri

Deponun arabiriminde bir sorgu tanımlayarak bir kapsayıcıdaki birden çok öğe üzerinde sorgu gerçekleştirin. Bu örnekte, bu parametreli sorguyu Query yürüten bir yöntem tanımlamak için yöntem dekoratörü kullanılır:

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);

}

kullanarak repository.getItemsByCategorysorgunun tüm sonuçlarını getirin. Sorgunun sonuçları arasında döngü yapın.

List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
    // Do something
}

Verilerinizi keşfetme

NoSQL verilerinizi keşfetmek için Azure Cosmos DB için Visual Studio Code uzantısını kullanın. Aşağıdakiler dahil ancak bunlarla sınırlı olmamak üzere temel veritabanı işlemleri gerçekleştirebilirsiniz:

Yapıştırma defteri veya sorgu düzenleyicisi kullanarak sorgu gerçekleştirme
Öğeleri değiştirme, güncelleştirme, oluşturma ve silme
Diğer kaynaklardan toplu verileri içeri aktarma
Veritabanlarını ve kapsayıcıları yönetme

Daha fazla bilgi için bkz Azure Cosmos DB'deki NoSQL verilerini keşfetmek için Visual Studio Code uzantısının nasıl kullanılacağı.

Kaynakları temizleme

Örnek uygulamaya veya kaynaklara artık ihtiyacınız kalmadığında, ilgili dağıtımı ve tüm kaynakları kaldırın.

azd down