이 SDK에 대한 자세한 내용은 Azure Cosmos DB Java SDK v4 릴리스 정보, Maven 리포지토리, Azure Cosmos DB Java SDK v4 성능 팁 및 Azure Cosmos DB Java SDK v4 문제 해결 가이드를 참조하세요.
Important
Azure Cosmos DB Java SDK v4는 최대 20% 향상된 처리량, TCP 기반 직접 모드 및 최신 백엔드 서비스 기능을 지원하므로 다음 기회에 v4로 업그레이드하는 것이 좋습니다. 자세히 알아보려면 계속 읽어보세요.
최신 Azure Cosmos DB Java SDK로 업데이트하여 Azure Cosmos DB가 제공해야 하는 서비스로서, 경쟁력 있는 성능, 고가용성, 일종의 리소스 거버넌스 등을 제공하는 관리형 비관계형 데이터베이스 서비스를 최대한 활용합니다. 이 문서에서는 이전 Azure Cosmos DB Java SDK를 사용하는 기존 Java 애플리케이션을 최신 API for NoSQL용 Azure Cosmos DB Java SDK 4.0으로 업그레이드하는 방법을 설명합니다. Azure Cosmos DB Java SDK v4는 com.azure.cosmos 패키지에 해당합니다. 다음 Azure Cosmos DB Java SDK 중 하나에서 애플리케이션을 마이그레이션하는 경우 이 문서의 지침을 사용할 수 있습니다.
Sync Java SDK 2.x.x
Async Java SDK 2.x.x
Java SDK 3.x.x
Azure Cosmos DB Java SDK와 패키지 매핑
다음 표에는 다양한 Azure Cosmos DB Java SDK, 패키지 이름 및 릴리스 정보가 나와 있습니다.
RxJava는 Azure Cosmos DB Java SDK 버전 3.x.x 및 4.0에서 Reactor로 바뀝니다.
비동기 프로그래밍 또는 사후 프로그래밍에 익숙하지 않은 경우 비동기 프로그래밍 및 Project Reactor를 소개하는 Reactor 패턴 가이드를 참조하세요. 이 가이드는 이전의 Azure Cosmos DB Sync Java SDK 2.x.x 또는 Azure Cosmos DB Java SDK 3.x.x Sync API를 사용하고 있는 경우 유용할 수 있습니다.
Azure Cosmos DB Async Java SDK 2.x.x를 사용하고 있고 4.0 SDK로 마이그레이션할 계획인 경우 Reactor를 사용하도록 RxJava 코드를 변환하는 방법에 대한 지침은 Reactor 및 RxJava 가이드를 참조하세요.
Azure Cosmos DB Java SDK v4에는 Async 및 Sync API의 직접 연결 모드가 있습니다.
Azure Cosmos DB Sync Java SDK 2.x.x를 사용하고 있는 경우 TCP(HTTP 아님) 기반 직접 연결 모드가 Async 및 Sync API를 위해 Azure Cosmos DB Java SDK 4.0에서 구현됩니다.
API 수준 변경
다음은 이전 SDK(Java SDK 3.x.x, Async Java SDK 2.x.x 및 Sync Java SDK 2.x.x)와 비교하여 Azure Cosmos DB Java SDK 4.x.x에 있는 API 수준의 변경 내용입니다.
Azure Cosmos DB Java SDK 3.x.x 및 4.0은 클라이언트 리소스를 Cosmos<resourceName>으로 참조합니다. 예: CosmosClient, CosmosDatabase, CosmosContainer. 버전 2.x.x에서는 Azure Cosmos DB Java SDK에 일정한 명명 체계가 없습니다.
Azure Cosmos DB Java SDK 3.x.x 및 4.0은 Sync 및 Async API를 모두 제공합니다.
Java SDK 4.0 : 클래스 이름이 Cosmos 뒤에 Async가 추가되어 있지 않으면 모든 클래스가 Sync API에 포함됩니다.
Java SDK 3.x.x: 클래스 이름이 Cosmos 뒤에 Async가 추가되어 있지 않으면 모든 클래스가 Async API에 포함됩니다.
Async Java SDK 2.x.x: 클래스 이름은 Sync Java SDK 2.x.x와 유사하지만 이름이 Async로 시작합니다.
계층적 API 구조
Azure Cosmos DB Java SDK 4.0 및 3.x.x에는 다음 4.0 SDK 코드 조각에 표시된 대로 클라이언트, 데이터베이스 및 컨테이너를 중첩된 방식으로 구성하는 계층적 API 구조가 도입되었습니다.
// Create Async client.
// Building an async client is still a sync operation.
CosmosAsyncClient client = new CosmosClientBuilder()
.endpoint("your.hostname")
.key("yourmasterkey")
.consistencyLevel(ConsistencyLevel.EVENTUAL)
.buildAsyncClient();
// Create database with specified name
client.createDatabaseIfNotExists("YourDatabaseName")
.flatMap(databaseResponse -> {
testDatabaseAsync = client.getDatabase("YourDatabaseName");
// Container properties - name and partition key
CosmosContainerProperties containerProperties =
new CosmosContainerProperties("YourContainerName", "/id");
// Provision manual throughput
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);
// Create container
return database.createContainerIfNotExists(containerProperties, throughputProperties);
}).flatMap(containerResponse -> {
testContainerAsync = database.getContainer("YourContainerName");
return Mono.empty();
}).subscribe();
ConnectionPolicy defaultPolicy = ConnectionPolicy.defaultPolicy();
// Setting the preferred location to Azure Cosmos DB Account region
defaultPolicy.preferredLocations(Lists.newArrayList("Your Account Location"));
// Create async client
// <CreateAsyncClient>
client = new CosmosClientBuilder()
.endpoint("your.hostname")
.key("yourmasterkey")
.connectionPolicy(defaultPolicy)
.consistencyLevel(ConsistencyLevel.EVENTUAL)
.build();
// Create database with specified name
client.createDatabaseIfNotExists("YourDatabaseName")
.flatMap(databaseResponse -> {
database = databaseResponse.database();
// Container properties - name and partition key
CosmosContainerProperties containerProperties =
new CosmosContainerProperties("YourContainerName", "/id");
// Create container with specified properties & provisioned throughput
return database.createContainerIfNotExists(containerProperties, 400);
}).flatMap(containerResponse -> {
container = containerResponse.container();
return Mono.empty();
}).subscribe();
ConnectionPolicy defaultPolicy = ConnectionPolicy.GetDefault();
// Setting the preferred location to Azure Cosmos DB Account region
defaultPolicy.setPreferredLocations(Lists.newArrayList("Your Account Location"));
// Create document client
// <CreateDocumentClient>
client = new DocumentClient("your.hostname", "your.masterkey", defaultPolicy, ConsistencyLevel.Eventual)
// Create database with specified name
Database databaseDefinition = new Database();
databaseDefinition.setId("YourDatabaseName");
ResourceResponse<Database> databaseResourceResponse = client.createDatabase(databaseDefinition, new RequestOptions());
// Read database with specified name
String databaseLink = "dbs/YourDatabaseName";
databaseResourceResponse = client.readDatabase(databaseLink, new RequestOptions());
Database database = databaseResourceResponse.getResource();
// Create container with specified name
DocumentCollection documentCollection = new DocumentCollection();
documentCollection.setId("YourContainerName");
documentCollection = client.createCollection(database.getSelfLink(), documentCollection, new RequestOptions()).getResource();
// Create Async client.
// Building an async client is still a sync operation.
AsyncDocumentClient client = new Builder()
.withServiceEndpoint("your.hostname")
.withMasterKeyOrResourceToken("yourmasterkey")
.withConsistencyLevel(ConsistencyLevel.Eventual)
.build();
// Create database with specified name
Database database = new Database();
database.setId("YourDatabaseName");
client.createDatabase(database, new RequestOptions())
.flatMap(databaseResponse -> {
// Collection properties - name and partition key
DocumentCollection documentCollection = new DocumentCollection();
documentCollection.setId("YourContainerName");
documentCollection.setPartitionKey(new PartitionKeyDefinition("/id"));
// Create collection
return client.createCollection(databaseResponse.getResource().getSelfLink(), documentCollection, new RequestOptions());
}).subscribe();
항목 작업
다음 코드 조각은 4.0, 3.x.x Async, 2.x.x Sync, 2.x.x Async API 간에 항목 작업을 수행하는 방법의 차이점을 보여 줍니다.
ChangeFeedProcessor changeFeedProcessorInstance =
new ChangeFeedProcessorBuilder()
.hostName(hostName)
.feedContainer(feedContainer)
.leaseContainer(leaseContainer)
.handleChanges((List<JsonNode> docs) -> {
logger.info("--->setHandleChanges() START");
for (JsonNode document : docs) {
try {
//Change Feed hands the document to you in the form of a JsonNode
//As a developer you have two options for handling the JsonNode document provided to you by Change Feed
//One option is to operate on the document in the form of a JsonNode, as shown below. This is great
//especially if you do not have a single uniform data model for all documents.
logger.info("---->DOCUMENT RECEIVED: " + OBJECT_MAPPER.writerWithDefaultPrettyPrinter()
.writeValueAsString(document));
//You can also transform the JsonNode to a POJO having the same structure as the JsonNode,
//as shown below. Then you can operate on the POJO.
CustomPOJO pojo_doc = OBJECT_MAPPER.treeToValue(document, CustomPOJO.class);
logger.info("----=>id: " + pojo_doc.getId());
} catch (JsonProcessingException e) {
e.printStackTrace();
}
}
logger.info("--->handleChanges() END");
})
.buildChangeFeedProcessor();
// ...
changeFeedProcessorInstance.start()
.subscribeOn(Schedulers.elastic())
.subscribe();
ChangeFeedProcessor changeFeedProcessorInstance =
ChangeFeedProcessor.Builder()
.hostName(hostName)
.feedContainer(feedContainer)
.leaseContainer(leaseContainer)
.handleChanges((List<CosmosItemProperties> docs) -> {
logger.info("--->setHandleChanges() START");
for (CosmosItemProperties document : docs) {
try {
// You are given the document as a CosmosItemProperties instance which you may
// cast to the desired type.
CustomPOJO pojo_doc = document.getObject(CustomPOJO.class);
logger.info("----=>id: " + pojo_doc.id());
} catch (Exception e) {
e.printStackTrace();
}
}
logger.info("--->handleChanges() END");
})
.build();
// ...
changeFeedProcessorInstance.start()
.subscribeOn(Schedulers.elastic())
.subscribe();
이 기능은 Java SDK v2 sync에서 지원되지 않습니다.
이 기능은 Java SDK v2 Async에서 지원되지 않습니다.
컨테이너 수준 TTL(Time-To-Live)
다음 코드 조각은 4.0, 3.x.x Async, 2.x.x Sync, 2.x.x Async API 간에 컨테이너에서 데이터의 TTL(Time to Live)을 만드는 방법의 차이점을 보여 줍니다.
CosmosAsyncContainer container;
// Create a new container with TTL enabled with default expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.setDefaultTimeToLiveInSeconds(90 * 60 * 60 * 24);
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);
database.createContainerIfNotExists(containerProperties, throughputProperties).block();
container = database.getContainer("myContainer");
CosmosContainer container;
// Create a new container with TTL enabled with default expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.defaultTimeToLive(90 * 60 * 60 * 24);
container = database.createContainerIfNotExists(containerProperties, 400).block().container();
DocumentCollection documentCollection;
// Create a new container with TTL enabled with default expiration value
documentCollection.setDefaultTimeToLive(90 * 60 * 60 * 24);
documentCollection = client.createCollection(database.getSelfLink(), documentCollection, new RequestOptions()).getResource();
DocumentCollection collection = new DocumentCollection();
// Create a new container with TTL enabled with default expiration value
collection.setDefaultTimeToLive(90 * 60 * 60 * 24);
collection = client
.createCollection(database.getSelfLink(), documentCollection, new RequestOptions())
.toBlocking()
.single()
.getResource();
항목 수준 TTL(Time-To-Live)
다음 코드 조각은 4.0, 3.x.x Async, 2.x.x Sync, 2.x.x Async API 간에 항목의 TTL(Time to Live)을 만드는 방법의 차이점을 보여 줍니다.
// Include a property that serializes to "ttl" in JSON
class SalesOrder
{
private String id;
private String customerId;
private Integer ttl;
public SalesOrder(String id, String customerId, Integer ttl) {
this.id = id;
this.customerId = customerId;
this.ttl = ttl;
}
public String getId() {return this.id;}
public void setId(String new_id) {this.id = new_id;}
public String getCustomerId() {return this.customerId;}
public void setCustomerId(String new_cid) {this.customerId = new_cid;}
public Integer getTtl() {return this.ttl;}
public void setTtl(Integer new_ttl) {this.ttl = new_ttl;}
//...
}
// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder(
"SO05",
"CO18009186470",
60 * 60 * 24 * 30 // Expire sales orders in 30 days
);
// Include a property that serializes to "ttl" in JSON
public class SalesOrder
{
private String id;
private String customerId;
private Integer ttl;
public SalesOrder(String id, String customerId, Integer ttl) {
this.id = id;
this.customerId = customerId;
this.ttl = ttl;
}
public String id() {return this.id;}
public SalesOrder id(String new_id) {this.id = new_id; return this;}
public String customerId() {return this.customerId; return this;}
public SalesOrder customerId(String new_cid) {this.customerId = new_cid;}
public Integer ttl() {return this.ttl;}
public SalesOrder ttl(Integer new_ttl) {this.ttl = new_ttl; return this;}
//...
}
// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder(
"SO05",
"CO18009186470",
60 * 60 * 24 * 30 // Expire sales orders in 30 days
);
Document document = new Document();
document.setId("YourDocumentId");
document.setTimeToLive(60 * 60 * 24 * 30 ); // Expire document in 30 days
ResourceResponse<Document> documentResourceResponse = client.createDocument(documentCollection.getSelfLink(), document,
new RequestOptions(), true);
Document responseDocument = documentResourceResponse.getResource();
Document document = new Document();
document.setId("YourDocumentId");
document.setTimeToLive(60 * 60 * 24 * 30 ); // Expire document in 30 days
ResourceResponse<Document> documentResourceResponse = client.createDocument(documentCollection.getSelfLink(), document,
new RequestOptions(), true).toBlocking().single();
Document responseDocument = documentResourceResponse.getResource();
다음 단계
V4 SDK를 사용하여 Azure Cosmos DB for NoSQL 데이터를 관리하는 Java 앱 빌드
NoSQL