영어로 읽기

다음을 통해 공유

빠른 시작: Java용 Azure SDK와 함께 NoSQL용 Azure Cosmos DB 사용

  • 아티클
  • 2025. 02. 24.
  • 적용 대상: ✅ NoSQL

이 빠른 시작에서는 Java용 Azure SDK를 사용하여 기본 Azure Cosmos DB for Table 애플리케이션을 배포합니다. Azure Cosmos DB for Table은 애플리케이션이 구조화된 테이블 데이터를 클라우드에 저장할 수 있는 스키마 없는 데이터 저장소입니다. Java용 Azure SDK를 사용하여 테이블, 행을 만들고 Azure Cosmos DB 리소스 내에서 기본 작업을 수행하는 방법을 알아봅니다.

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(Maven) | Azure 개발자 CLI

필수 조건

  • Azure Developer CLI
  • Docker Desktop
  • Java 21

Azure 계정이 없는 경우 시작하기 전에 체험 계정을 만듭니다.

프로젝트 초기화

Azure Developer CLI(azd)를 사용하여 Table용 Azure Cosmos DB 계정을 만들고 컨테이너화된 샘플 애플리케이션을 배포합니다. 샘플 애플리케이션은 클라이언트 라이브러리를 사용하여 샘플 데이터를 관리, 만들기, 읽기 및 쿼리합니다.

  1. 빈 디렉터리에서 터미널을 엽니다.

  2. 아직 인증되지 않은 경우 .azd auth login 원하는 Azure 자격 증명을 사용하여 CLI에 인증하려면 도구에 지정된 단계를 따릅니다.

    azd auth login

  3. 프로젝트를 초기화하려면 azd init를 사용합니다.

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

  4. 초기화 중에 고유한 환경 이름을 구성합니다.

  5. azd up을 사용하여 Azure Cosmos DB 계정을 배포합니다. Bicep 템플릿은 샘플 웹 애플리케이션도 배포합니다.

    azd up

  6. 프로비전 프로세스 중에 구독, 원하는 위치 및 대상 리소스 그룹을 선택합니다. 프로비저닝 프로세스가 완료될 때까지 기다립니다. 이 과정은 약 5분 정도 소요됩니다.

  7. Azure 리소스 프로비전이 완료되면 실행 중인 웹 애플리케이션에 대한 URL이 출력에 포함됩니다.

    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.

  8. 콘솔의 URL을 사용하여 브라우저에서 웹 애플리케이션으로 이동합니다. 실행 중인 앱의 출력을 관찰합니다.

실행 중인 웹 애플리케이션의 스크린샷.

클라이언트 라이브러리 설치

클라이언트 라이브러리는 Maven을 통해 azure-spring-data-cosmos 패키지로 제공됩니다.

  1. /src/web 폴더로 이동하여 pom.xml 파일을 엽니다.

  2. 아직 존재하지 않는 경우 azure-spring-data-cosmos 패키지에 대한 항목을 추가합니다.

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

  3. 또한 아직 존재하지 않는 경우 azure-identity 패키지에 대한 다른 종속성을 추가합니다.

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

개체 모델

이름 설명
EnableCosmosRepositories 이 형식은 Azure Cosmos DB for NoSQL에 액세스하도록 리포지토리를 구성하는 데 사용되는 메서드 데코레이터입니다.
CosmosRepository 이 클래스는 기본 클라이언트 클래스이며 컨테이너 내의 데이터를 관리하는 데 사용됩니다.
CosmosClientBuilder 이 클래스는 리포지토리에서 사용되는 클라이언트를 만드는 데 사용되는 팩터리입니다.
Query 이 형식은 리포지토리가 실행하는 쿼리를 지정하는 데 사용되는 메서드 데코레이터입니다.

코드 예제

템플릿의 샘플 코드는 cosmicworks라는 데이터베이스와 products라는 컨테이너를 사용합니다. products 컨테이너에는 각 제품의 이름, 범주, 수량, 고유 식별자 및 판매 플래그와 같은 세부 정보가 포함되어 있습니다. 컨테이너는 /category 속성을 논리 파티션 키로 사용합니다.

클라이언트 인증

먼저 이 샘플은 Azure Cosmos DB for NoSQL에 대한 연결을 구성하기 위해 AbstractCosmosConfiguration에서 상속되는 새 클래스를 만듭니다.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
}

구성 클래스 내에서 이 샘플은 CosmosClientBuilder 클래스의 새 인스턴스를 만들고 DefaultAzureCredential 인스턴스를 사용하여 인증을 구성합니다.

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

데이터베이스 가져오기

구성 클래스에서 샘플은 cosmicworks라는 기존 데이터베이스의 이름을 반환하는 메서드를 구현합니다.

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

컨테이너 가져오기

컨테이너의 항목을 나타내도록 클래스를 구성하려면 Container 메서드 데코레이터를 사용합니다. JSON으로 직렬화하려는 모든 멤버를 포함하도록 클래스를 작성합니다. 이 예에서 형식에는 고유 식별자와 범주, 이름, 수량, 가격 및 재고 정리에 대한 필드가 있습니다.

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

항목 만들기

repository.save을 사용하여 컨테이너에 항목을 만듭니다.

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

항목 읽기

고유 식별자(id)와 파티션 키 필드를 모두 사용하여 포인트 읽기 작업을 수행합니다. 특정 항목을 효율적으로 검색하려면 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
}

쿼리 항목

리포지토리 인터페이스에서 쿼리를 정의하여 컨테이너의 여러 항목에 대해 쿼리를 수행합니다. 이 샘플은 Query 메서드 데코레이터를 사용하여 매개 변수가 있는 쿼리를 실행하는 메서드를 정의합니다.

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

}

repository.getItemsByCategory를 사용하여 쿼리 결과를 모두 가져옵니다. 쿼리 결과를 반복합니다.

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

데이터 탐색

Azure Cosmos DB용 Visual Studio Code 확장을 사용하여 NoSQL 데이터를 탐색합니다. 다음을 포함하지만 제한되지 않는 핵심 데이터베이스 작업을 수행할 수 있습니다.

  • 스크랩북 또는 쿼리 편집기를 사용하여 쿼리 수행
  • 항목 수정, 업데이트, 만들기 및 삭제
  • 다른 원본에서 대량 데이터 가져오기
  • 데이터베이스 및 컨테이너 관리

자세한 내용은 Visual Studio Code 확장을 사용하여 NoSQL용 Azure Cosmos DB 데이터를 탐색하는 방법을 참조 하세요.

리소스 정리

샘플 애플리케이션이나 리소스가 더 이상 필요하지 않으면 해당 배포와 모든 리소스를 제거합니다.

azd down

관련 콘텐츠

추가 리소스

설명서