Hızlı Başlangıç: Java için Apache Cassandra istemci kitaplığı için Azure Cosmos DB

Şunlara uygulanır: ✅ Apache Cassanda

Important

99,999% kullanılabilirlik hizmet düzeyi sözleşmesi (SLA), anında otomatik ölçeklendirme ve birden çok bölgede otomatik yük devretme ile yüksek ölçekli senaryolar için bir veritabanı çözümü mü arıyorsunuz? NoSQL için Azure Cosmos DB'yi göz önünde bulundurun.

Mevcut bir Apache Cassandra uygulamasını geçirmek mi istiyorsunuz? Apache Cassandra için Azure Managed Instance'ı göz önünde bulundurmayı düşünün.

Yapılandırılmamış verileri depolamak, yönetmek ve sorgulamak için Java için Apache Cassandra için Azure Cosmos DB istemci kitaplığını kullanmaya başlayın. Yeni bir hesap oluşturmak, Java istemci kitaplığı yüklemek, hesaba bağlanmak, yaygın işlemler gerçekleştirmek ve son örnek verilerinizi sorgulamak için bu kılavuzdaki adımları izleyin.

API referans belgeleri | Kitaplık kaynak kodu | Paket (Maven)

Prerequisites

Azure aboneliği
- Eğer bir Azure aboneliğiniz yoksa, başlamadan önce ücretsiz bir hesap oluşturun.

Azure Cloud Shell'de Azure CLI'nın en son sürümü.
- CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız, az login komutunu kullanarak Azure CLI oturum açın.

Java 21 veya üzeri

Kurulum

İlk olarak, bu kılavuz için hesap ve geliştirme ortamını ayarlayın. Bu bölümde hesap oluşturma, kimlik bilgilerini alma ve geliştirme ortamınızı hazırlama işlemi boyunca size yol gösterilir.

Hesap oluştur

Apache Cassandra hesabı için bir API oluşturarak başlayın. Hesap oluşturulduktan sonra anahtar alanını ve tablo kaynaklarını oluşturun.

Azure CLI
Azure portalı

Henüz bir hedef kaynak grubunuz yoksa, aboneliğinizde yeni bir kaynak grubu oluşturmak için komutunu kullanın az group create .
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Varsayılan ayarlarla az cosmosdb create Apache Cassandra için yeni bir Azure Cosmos DB hesabı oluşturmak için komutunu kullanın.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

az cosmosdb cassandra keyspace create kullanarak cosmicworks adlı yeni bir anahtar alanı oluşturun.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Çok satırlı bash komutunu kullanarak şemanızı temsil eden yeni bir JSON nesnesi oluşturun. Ardından komutunu kullanarak az cosmosdb cassandra table create adlı productsyeni bir tablo oluşturun.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Azure portalında (https://portal.azure.com) oturum açın.
Genel arama çubuğuna Azure Cosmos DB yazın.
Services içinde Azure Cosmos DB öğesini seçin.
Azure Cosmos DB bölmesinde Oluştur'u ve ardından Diğerleri sekmesinde Apache Cassandra için Azure Cosmos DB'yi seçin.
Hesap türü için İstek birimi (RU) veritabanı hesabı'nı seçin.

Temel Bilgiler bölmesinde aşağıdaki seçenekleri yapılandırın ve gözden geçir ve oluştur'u seçin:

	Value
İş Yükü Türü	Öğrenim
Abonelik	Azure aboneliğinizi seçin
Kaynak Grubu	Yeni kaynak grubu oluşturma veya var olan bir kaynak grubunu seçme
Firma Adı	Genel olarak benzersiz bir ad sağlayın
Erişilebilirlik Bölgeleri	Disable
Konum	Aboneliğiniz için desteklenen bir Azure bölgesi seçin

Tip

Belirtilmeyen seçenekleri varsayılan değerlerine bırakabilirsiniz. Ayrıca hesabı, toplam hesap aktarım hızını saniyede 1.000 istek birimiyle (RU/sn) sınırlandıracak şekilde yapılandırabilir veya maliyetlerinizi en aza indirmek için ücretsiz katmanı etkinleştirebilirsiniz.

Gözden Geçir ve oluştur bölmesinde hesabınızın doğrulamasının başarıyla tamamlanmasını bekleyin ve oluştur'u seçin.
Portal otomatik olarak Dağıtım bölmesine gider. Dağıtımın tamamlanmasını bekleyin.
Dağıtım tamamlandıktan sonra Kaynağa git seçeneğini tıklayarak Apache Cassandra hesabı için yeni API'ye gidin.
Kaynak menüsünde Veri Gezgini seçeneğini belirleyin.
Veri Gezgini'nde + Yeni Tablo'yu seçin.

Tablo Ekle iletişim kutusunda aşağıdaki seçenekleri yapılandırın ve tamam'ı seçin:

	Value
Anahtar alanı	Yeni oluştur
Anahtar alanı adı	`cosmicworks`
Tablo adı	`product`
Tablo şeması	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Tip

Belirtilmeyen seçenekleri varsayılan değerlerine bırakabilirsiniz.

Kimlik bilgilerini alma

Şimdi, son oluşturulan hesaba bağlantı oluşturmak için kullanılacak istemci kitaplığının parolasını alın.

Azure CLI
Azure portalı

Hesabın iletişim noktası ve kullanıcı adını almak için az cosmosdb show kullanın.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Önceki komutların çıkışındaki contactPoint ve username özelliklerinin değerlerini kaydedin. Bu özelliklerin değerleri, bu kılavuzun devamında kitaplığa bağlanmak için kullandığınız kişi noktası ve kullanıcı adıdır .

az cosmosdb keys list, hesabın anahtarlarını almak için kullanın.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Önceki komutların çıkışından primaryMasterKey özelliğinin değerini kaydedin. Bu özelliğin değeri, bu kılavuzun ilerleyen bölümlerinde kitaplığa bağlanmak için kullandığınız paroladır .

Geliştirme ortamını hazırlama

Ardından geliştirme ortamınızı yeni bir proje ve istemci kitaplığıyla yapılandırın. Bu adım, bu kılavuzun geri kalanına geçmeden önce gereken son önkoşuldur.

Boş bir klasörde başlayın.

Maven kullanarak yeni bir Java konsol projesi oluşturun.

mvn archetype:generate -DgroupId=quickstart -DartifactId=console -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

java-driver-core Paketi Maven'dan içeri aktarın. Bu bölümü pom.xml dosyanıza ekleyin.

<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>[4.,)</version>
</dependency>

/console/src/main/java/quickstart/App.java dosyasını açın.

Java uygulamasının mevcut şablon kodunu inceleyin.

package quickstart;

/**
 * Hello world!
 *
 */
public class App 
{
    public static void main( String[] args )
    {
        System.out.println( "Hello World!" );
    }
}

Açıklamaları ve konsol çıkışını ortak şablondan kaldırın. Bu kod bloğu, bu kılavuzun geri kalanı için başlangıç noktasıdır.
```
package quickstart;

public class App 
{
    public static void main(String[] args)
    {
    }
}
```
Ad alanı java.security.NoSuchAlgorithmException'i içe aktarın.
```
import java.security.NoSuchAlgorithmException;
```
main yöntem imzasını, NoSuchAlgorithmException istisnasını fırlatabileceğini belirtmek için güncelleştirin.
```
public static void main(String[] args) throws NoSuchAlgorithmException
{    
}
```
Important

Bu kılavuzdaki sonraki adımlar, kodunuzu main metoduna eklediğiniz varsayılmaktadır.
Projenizi oluşturun.
```
mvn compile
```

Nesne modeli

	Description
`CqlSession`	Kümeye belirli bir bağlantıyı temsil eder
`PreparedStatement`	Birden çok kez verimli bir şekilde yürütülebilen önceden derlenmiş bir CQL deyimini temsil eder
`BoundStatement`	Bağlı parametrelerle hazırlanmış bir deyimi temsil eder
`Row`	Sorgu sonucunun tek bir satırını temsil eder

İstemcinin kimliğini doğrulama

Bu kılavuzda daha önce toplanan kimlik bilgilerini kullanarak istemcinin kimliğini doğrulayarak başlayın.

Tümleşik geliştirme ortamınızda (IDE) /console/src/main/java/quickstart/App.java dosyasını açın.

Aşağıdaki türleri içeri aktarın:

java.net.InetSocketAddress
javax.net.ssl.SSLContext
com.datastax.oss.driver.api.core.CqlIdentifier
com.datastax.oss.driver.api.core.CqlSession
com.datastax.oss.driver.api.core.cql.BoundStatement
com.datastax.oss.driver.api.core.cql.PreparedStatement
com.datastax.oss.driver.api.core.cql.ResultSet
com.datastax.oss.driver.api.core.cql.Row

import java.net.InetSocketAddress;    

import javax.net.ssl.SSLContext;

import com.datastax.oss.driver.api.core.CqlIdentifier;
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.cql.BoundStatement;
import com.datastax.oss.driver.api.core.cql.PreparedStatement;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;

Bu kılavuzun önceki bölümlerinde toplanan kimlik bilgileri için dize değişkenleri oluşturun. Değişkenleri username, passwordve contactPointolarak adlandırın. Ayrıca, yerel veri merkezi için adlı region bir dize değişkeni oluşturun.
```
String username = "<username>";
String password = "<password>";
String contactPoint = "<contact-point>";
```
Apache Cassandra için Azure Cosmos DB hesabınızı oluşturduğunuz bölge için başka bir dize değişkeni oluşturun. Bu değişkene adını verin region.
```
String region = "<region>";
```
Aktarım katmanı güvenliği (TLS) protokolunu kullandığınızdan emin olmak için bir SSLContext nesne oluşturun.
```
SSLContext sslContext = SSLContext.getDefault();
```
Önceki adımlarda oluşturulan kimlik bilgilerini ve yapılandırma değişkenlerini kullanarak yeni CqlSession bir nesne oluşturun. Kişi noktasını, yerel veri merkezini, kimlik doğrulama kimlik bilgilerini, anahtar alanı ve Aktarım Katmanı Güvenliği (TLS) bağlamını ayarlayın.
```
CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress(contactPoint, 10350))
    .withLocalDatacenter(region)
    .withAuthCredentials(username, password)
    .withKeyspace(CqlIdentifier.fromCql("cosmicworks"))
    .withSslContext(sslContext)
    .build();
```

Warning

Kimlik doğrulamasını basitleştirmek için bu kılavuzda tam aktarım katmanı güvenliği (TLS) doğrulaması devre dışı bırakılmıştır. Üretim dağıtımları için doğrulamayı tam olarak etkinleştirin.

Veri güncelleme veya ekleme

Ardından, yeni verileri bir tabloya ekle. Yükseltme, aynı verilerin tabloda zaten var olup olmadığına bağlı olarak verilerin uygun şekilde oluşturulmasını veya değiştirilmesini sağlar.

Bu kılavuzun önceki bölümlerinde oluşturulan tabloya karşılık gelen alanlarla adlı Product yeni bir sınıf tanımlayın.

class Product {
    public String id;
    public String name;
    public String category;
    public int quantity;
    public boolean clearance;

    public Product(String id, String name, String category, int quantity, boolean clearance) {
        this.id = id;
        this.name = name;
        this.category = category;
        this.quantity = quantity;
        this.clearance = clearance;
    }

    @Override
    public String toString() {
        return String.format("Product{id='%s', name='%s', category='%s', quantity=%d, clearance=%b}",
                id, name, category, quantity, clearance);
    }
}

Tip

Java'da bu türü başka bir dosyada veya var olan dosyanın sonunda oluşturabilirsiniz.

türünde Productyeni bir nesne oluşturun. nesnesini adlı productbir değişkende depolayın.

Product product = new Product(
    "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "Yamba Surfboard",
    "gear-surf-surfboards",
    12,
    false
);

Yeni satır eklemek için Cassandra Sorgu Dili (CQL) sorgusuyla adlı insertQuery yeni bir dize değişkeni oluşturun.
```
String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
```

insert deyimini hazırlayın ve ürün özelliklerini parametre olarak bağlayın.

PreparedStatement insertStmt = session.prepare(insertQuery);
BoundStatement boundInsert = insertStmt.bind(
    product.id,
    product.name,
    product.category,
    product.quantity,
    product.clearance
);

Bağlı sorguyu çalıştırarak ürünü güncelleyin veya ekleyin.
```
session.execute(boundInsert);
```

Veriyi oku

Ardından, tabloya daha önce yüklenmiş olan verileri okuyun.

Aynı readQuery alana sahip öğelerle eşleşen bir CQL sorgusuyla adlı id yeni bir dize değişkeni oluşturun.
```
String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
```
Bu kılavuzun önceki bölümlerinde oluşturulan ürünle aynı değere sahip adlı id bir dize değişkeni oluşturun.
```
String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
```

deyimini hazırlayın ve ürünün id alanını parametre olarak bağlayın.

PreparedStatement readStmt = session.prepare(readQuery);
BoundStatement boundRead = readStmt.bind(id);

bound deyimini yürütür ve sonucu adlı readResultbir değişkende depolar.
```
ResultSet readResult = session.execute(boundRead);
```

Sonuç kümesinden ilk satırı alın ve bulunursa bir Product nesneyle eşleyin.

Row row = readResult.one();
Product matchedProduct = new Product(
    row.getString("id"),
    row.getString("name"),
    row.getString("category"),
    row.getInt("quantity"),
    row.getBoolean("clearance")
);

Sorgu verileri

Şimdi, tablodaki belirli bir filtreyle eşleşen tüm verileri bulmak için bir sorgu kullanın.

Aynı findQuery alana sahip öğelerle eşleşen bir CQL sorgusuyla adlı category yeni bir dize değişkeni oluşturun.
```
String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
```
Bu kılavuzun önceki bölümlerinde oluşturulan ürünle aynı değere sahip adlı id bir dize değişkeni oluşturun.
```
String category = "gear-surf-surfboards";
```

deyimini hazırlayın ve ürün kategorisini parametre olarak bağlayın.

PreparedStatement findStmt = session.prepare(findQuery);
BoundStatement boundFind = findStmt.bind(category);

bound deyimini yürütür ve sonucu adlı findResultsbir değişkende depolar.
```
ResultSet results = session.execute(boundFind);
```

Sorgu sonuçları üzerinde yineleme yapın ve her satırı bir Product nesneyle eşleyin.

for (Row result : results) {
    Product queriedProduct = new Product(
        result.getString("id"),
        result.getString("name"),
        result.getString("category"),
        result.getInt("quantity"),
        result.getBoolean("clearance")
    );
    // Do something here with each result
}

Oturumu kapat

Java'da, tüm sorgular ve işlemler tamamlandıktan sonra oturumu kapatmanız gerekir.

session.close();

Kodu çalıştır

Uygulama dizininizde bir terminal kullanarak yeni oluşturulan uygulamayı çalıştırın.

mvn compile
mvn exec:java -Dexec.mainClass="quickstart.App"

Tip

Bu komutu bu kılavuzda oluşturulan /console yolunda çalıştırdığınızdan emin olun.

Kaynakları temizle