빠른 시작: Azure Cosmos DB SQL API 계정을 사용하여 Python 애플리케이션 빌드

적용 대상: SQL API

이 빠른 시작에서는 Azure Portal 및 GitHub에서 복제된 Python 앱을 사용하여 Visual Studio Code에서 Azure Cosmos DB SQL API 계정을 만들고 관리합니다. Azure Cosmos DB는 글로벌 배포 및 수평적 크기 조정 기능을 사용하여 문서, 테이블, 키 값 및 그래프 데이터베이스를 빠르게 만들고 쿼리할 수 있는 다중 모델 데이터베이스 서비스입니다.

필수 구성 요소

데이터베이스 계정 만들기

  1. Azure Portal 메뉴 또는 페이지에서 리소스 만들기 를 선택합니다.

  2. 새로 만들기 페이지에서 Azure Cosmos DB 를 검색하여 선택합니다.

  3. Azure Cosmos DB 페이지에서 만들기 를 선택합니다.

  4. Azure Cosmos DB 계정 만들기 페이지에서 새 Azure Cosmos 계정에 대한 기본 설정을 입력합니다.

    설정 Description
    Subscription 구독 이름 이 Azure Cosmos 계정에 사용하려는 Azure 구독을 선택합니다.
    리소스 그룹 리소스 그룹 이름 리소스 그룹을 선택하거나 새로 만들기 를 선택한 후, 새 리소스 그룹에 고유한 이름을 입력합니다.
    계정 이름 고유한 이름 Azure Cosmos 계정을 식별하는 이름을 입력합니다. URI를 만들기 위해 제공하는 이름에 documents.azure.com 이 추가되므로 고유한 이름을 사용합니다.

    이름은 소문자, 숫자 및 하이픈(-) 문자만 포함할 수 있으며, 길이는 3~44자여야 합니다.
    API 만들 계정 형식 Core(SQL) 를 선택하여 문서 데이터베이스를 만들고 SQL 구문을 사용하여 쿼리합니다.

    API는 만들 계정의 형식을 결정합니다. Azure Cosmos DB는 문서 데이터용 Core(SQL) 및 MongoDB, 그래프 데이터용 Gremlin, Azure Table 및 Cassandra, 이렇게 5가지 API를 제공합니다. 현재 각 API에 대한 별도의 계정을 만들어야 합니다.

    SQL API에 대한 자세한 정보
    위치 사용자와 가장 가까운 지역 Azure Cosmos DB 계정을 호스트할 지리적 위치를 선택합니다. 데이터에 가장 빨리 액세스할 수 있도록 사용자와 가장 가까운 위치를 사용합니다.
    용량 모드 프로비저닝된 처리량 또는 서버리스 프로비저닝된 처리량 을 선택하여 프로비저닝된 처리량 모드에서 계정을 만듭니다. 서버리스 를 선택하여 서버리스 모드에서 계정을 만듭니다.
    Azure Cosmos DB 체험 계층 할인 적용 적용 또는 적용 안 함 Azure Cosmos DB 체험 계층을 사용하는 경우 처음에는 1000RU/초 및 25GB의 스토리지가 계정에 무료로 제공됩니다. 체험 계층에 대해 자세히 알아보세요.

    참고

    Azure 구독당 최대 1개의 체험 계층 Azure Cosmos DB 계정을 사용할 수 있으며 계정을 만들 때 옵트인해야 합니다. 체험 계층 할인을 적용하는 옵션이 표시되지 않으면 구독의 다른 계정에서 이미 체험 계층을 사용하도록 설정되었음을 의미합니다.

    Azure Cosmos DB에 대한 새 계정 페이지

  5. 전역 배포 탭에서 다음 세부 정보를 구성합니다. 이 빠른 시작의 목적을 위해 기본값을 그대로 둘 수 있습니다.

    설정 Description
    지리적 중복 사용 안 함 지역에 쌍 영역을 페어링하여 계정에서 글로벌 배포를 사용하거나 사용하지 않도록 설정합니다. 나중에 계정에 더 많은 지역을 추가할 수 있습니다.
    다중 지역 쓰기 사용 안 함 다중 영역 쓰기 기능을 사용하면 전 세계의 데이터베이스 및 컨테이너에 대해 프로비저닝된 처리량을 활용할 수 있습니다.

    참고

    용량 모드서버리스 를 선택한 경우 다음 옵션을 사용할 수 없습니다.

    • 체험 계층 할인 적용
    • 지리적 중복
    • 다중 지역 쓰기
  6. 필요에 따라 다음 탭에서 추가 세부 정보를 구성할 수 있습니다.

    • 네트워킹 - 가상 네트워크에서 액세스를 구성합니다.
    • 백업 정책 - 주기적 또는 지속적인 백업 정책을 구성합니다.
    • 암호화 - 서비스 관리형 키 또는 고객 관리형 키를 사용합니다.
    • 태그 - 태그는 동일한 태그를 여러 개의 리소스 및 리소스 그룹에 적용하여 리소스를 범주화하고 통합된 청구를 볼 수 있는 이름/값 쌍입니다.
  7. 검토 + 만들기 를 선택합니다.

  8. 계정 설정을 검토한 다음, 만들기 를 선택합니다. 계정을 만드는 데 몇 분이 걸립니다. 포털 페이지에 배포가 완료됨 이 표시되기를 기다립니다.

    Azure Portal 알림 창

  9. 리소스로 이동 을 선택하여 Azure Cosmos DB 계정 페이지로 이동합니다.

    Azure Cosmos DB 계정 페이지

컨테이너 추가

이제 Azure Portal에서 Data Explorer 도구를 사용하여 데이터베이스 및 컨테이너를 만들 수 있습니다.

  1. Data Explorer > 새 컨테이너 를 선택합니다.

    맨 오른쪽에 컨테이너 추가 영역이 표시되는데, 안 보이면 오른쪽으로 스크롤해야 합니다.

    Azure Portal Data Explorer, 컨테이너 추가 창

  2. 컨테이너 추가 페이지에서 새 컨테이너의 설정을 입력합니다.

    설정 제안 값 Description
    데이터베이스 ID ToDoList 새 데이터베이스의 이름으로 작업 을 입력합니다. 데이터베이스 이름은 1~255자여야 하며, /, \\, #, ? 또는 후행 공백은 포함할 수 없습니다. 컨테이너 간에 처리량 공유 옵션을 선택합니다. 그러면 데이터베이스에 프로비저닝된 처리량을 데이터베이스 내 모든 컨테이너가 공유할 수 있습니다. 이 옵션은 비용 절감에도 도움이 됩니다.
    데이터베이스 처리량 자동 스케일링 또는 수동 처리량을 프로비저닝할 수 있습니다. 수동 처리량을 사용하면 RU/s를 직접 스케일링할 수 있지만 자동 스케일링을 사용하면 시스템에서 사용량에 따라 RU/s를 스케일링할 수 있습니다. 이 예제에서는 수동 을 선택합니다.

    처리량을 400 RU/s(초당 요청 단위)로 유지합니다. 대기 시간을 줄이려면 용량 계산기를 사용하여 필요한 RU/s를 예측하여 나중에 처리량을 스케일 업할 수 있습니다.

    참고: 서버리스 계정에서 새 컨테이너를 만들 때는 이 설정을 사용할 수 없습니다.
    컨테이너 ID Items 새 컨테이너의 이름으로 Items 를 입력합니다. 컨테이너 ID에는 데이터베이스 이름과 동일한 문자 요구 사항이 적용됩니다.
    파티션 키 /category 이 문서에 설명된 샘플은 파티션 키로 /category 를 사용합니다.

    이 예제에서는 고유 키 를 추가하거나 분석 저장소 를 설정하지 마세요. 고유 키를 사용하면 분할 키당 하나 이상의 값의 고유성을 보장하여 데이터베이스에 데이터 무결성 레이어를 추가할 수 있습니다. 자세한 내용은 Azure Cosmos DB의 고유 키를 참조하세요. 분석 저장소는 트랜잭션 워크로드에 영향을 주지 않으면서 운영 데이터에 대한 대규모 분석을 사용하도록 설정하는 데 사용됩니다.

    확인 을 선택합니다. Data Explorer에 새 데이터베이스와 컨테이너가 표시됩니다.

샘플 데이터 추가

이제 데이터 탐색기를 사용하여 새 컨테이너에 데이터를 추가할 수 있습니다.

  1. Data Explorer 에서 Tasks 데이터베이스를 확장하고 Items 컨테이너를 확장합니다. 항목 을 선택한 다음, 새 항목 을 선택합니다.

    Azure Portal의 데이터 탐색기에서 새 문서 만들기

  2. 이제 다음과 같은 구조를 사용하여 컨테이너에 문서를 추가합니다.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. 문서 탭에 json을 추가했으면 저장 을 선택합니다.

    Azure Portal의 Azure Data Explorer에서 Json 데이터를 복사하고 저장을 선택합니다.

  4. id 속성에 대한 고유한 값을 삽입하는 경우 둘 이상의 문서를 만들고 저장하며 다른 속성을 적합하게 변경합니다. Azure Cosmos DB가 데이터에 어떠한 스키마도 적용하지 않으므로 새 문서는 사용자가 원하는 어떠한 구조든 가질 수 있습니다.

데이터 쿼리

데이터 탐색기에서 쿼리를 사용하여 데이터를 검색하고 필터링할 수 있습니다.

  1. 데이터 탐색기의 항목 탭 위쪽에서 기본 SELECT * FROM c 쿼리를 검토합니다. 이 쿼리는 ID로 정렬된 컨테이너에서 모든 문서를 검색하고 표시됩니다.

    데이터 탐색기의 기본 쿼리는 SELECT * FROM c입니다.

  2. 쿼리를 변경하려면 필터 편집 을 선택하고 기본 쿼리를 ORDER BY c._ts DESC로 변경한 다음, 필터 적용 을 선택합니다.

    ORDER BY c._ts DESC를 추가하고 필터 적용을 클릭하여 기본 쿼리 변경

    수정된 쿼리는 해당 타임스탬프에 따라 내림차순으로 문서를 표시합니다. 따라서 이제 두 번째 문서가 첫 번째로 나열됩니다.

    쿼리를 ORDER BY c._ts DESC로 변경하고 필터 적용을 클릭

SQL 구문에 익숙한 경우 쿼리 조건자 상자에 지원되는 SQL 쿼리를 입력할 수 있습니다. 데이터 탐색기를 사용하여 서버 쪽 비즈니스 논리에 대한 저장 프로시저, UDF 및 트리거를 만들 수도 있습니다.

데이터 탐색기를 사용하면 API에 제공되는 모든 내장 프로그래밍 방식 데이터 액세스 기능에 대해 Azure Portal에서 간편하게 액세스할 수 있습니다. 포털을 사용하여 Azure Cosmos DB 계정에 대한 처리량을 조정하고 키와 연결 문자열을 가져오고, 메트릭과 SLA를 검토할 수 있습니다.

샘플 애플리케이션 복제

이제 GitHub에서 SQL API 앱을 복제하고, 연결 문자열을 설정하고, 실행해보겠습니다. 이 빠른 시작에서는 Python SDK 버전 4를 사용합니다.

  1. 명령 프롬프트를 열고, git-samples라는 새 폴더를 만든 다음 명령 프롬프트를 닫습니다.

    md "git-samples"
    

    bash 프롬프트를 사용하는 경우에는 다음 명령을 대신 사용해야 합니다.

    mkdir "git-samples"
    
  2. Git Bash와 같은 Git 터미널 창을 열고, cd 명령을 사용하여 샘플 앱을 설치할 새 폴더로 변경합니다.

    cd "git-samples"
    
  3. 다음 명령을 실행하여 샘플 리포지토리를 복제합니다. 이 명령은 컴퓨터에서 샘플 앱의 복사본을 만듭니다.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-python-getting-started.git
    

연결 문자열 업데이트

이제 Azure Portal로 다시 이동하여 연결 문자열 정보를 가져와서 앱에 복사합니다.

  1. Azure Portal의 Azure Cosmos DB 계정에서 왼쪽 탐색 영역에 있는 를 선택합니다. 다음 단계에서는 화면 오른쪽의 복사 단추를 사용하여 URI기본 키cosmos_get_started.py 파일에 복사합니다.

    Azure Portal의 키 설정에서 액세스 키 및 URI 가져오기

  2. Visual Studio Code의 \git-samples\azure-cosmos-db-python-getting-started 에서 cosmos_get_started.py 파일을 엽니다.

  3. 복사 단추를 사용하여 포털에서 URI 값을 복사하고, 이 값을 cosmos_get_started.pyendpoint 변수 값으로 만듭니다.

    endpoint = 'https://FILLME.documents.azure.com',

  4. 그런 다음, 포털에서 기본 키 값을 복사하고, 이 값을 cosmos_get_started.py 값으로 만듭니다. 이제 Azure Cosmos DB와 통신하는 데 필요한 모든 정보로 앱이 업데이트되었습니다.

    key = 'FILLME'

  5. cosmos_get_started.py 파일을 저장합니다.

코드 검토

이 단계는 선택 사항입니다. 코드에서 만든 데이터베이스 리소스에 대해 알아보거나 연결 문자열 업데이트로 건너뜁니다.

다음 코드 조각은 모두 cosmos_get_started.py 파일에서 가져온 것입니다.

  • CosmosClient가 초기화됩니다. 연결 문자열 업데이트 섹션에서 설명한 대로 "endpoint" 및 "key" 값을 업데이트해야 합니다.

    client = CosmosClient(endpoint, key)
    
  • 새 데이터베이스가 만들어집니다.

    database_name = 'AzureSampleFamilyDatabase'
    database = client.create_database_if_not_exists(id=database_name)
    
  • 프로비저닝된 처리량이 400RU/초인 새 컨테이너가 만들어집니다. lastName파티션 키로 선택합니다. 그러면 이 속성을 필터링하는 효율적인 쿼리를 수행할 수 있습니다.

    container_name = 'FamilyContainer'
    container = database.create_container_if_not_exists(
        id=container_name, 
        partition_key=PartitionKey(path="/lastName"),
        offer_throughput=400
    )
    
  • 일부 항목은 컨테이너에 추가됩니다. 컨테이너는 다양한 스키마를 포함할 수 있는 항목(JSON 문서)의 컬렉션입니다. get_[name]_family_item 도우미 메서드는 Azure Cosmos DB에 JSON 문서로 저장된 패밀리의 표현을 반환합니다.

    for family_item in family_items_to_create:
        container.create_item(body=family_item)
    
  • 포인트 읽기(키 값 조회)는 read_item 메서드를 사용하여 수행됩니다. 각 작업에 대한 RU 요금이 출력됩니다.

    for family in family_items_to_create:
        item_response = container.read_item(item=family['id'], partition_key=family['lastName'])
        request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
        print('Read item with id {0}. Operation consumed {1} request units'.format(item_response['id'], (request_charge)))
    
  • 쿼리는 SQL 쿼리 구문을 사용하여 수행됩니다. WHERE 절에서 lastName의 파티션 키 값을 사용하므로 Azure Cosmos DB에서 이 쿼리를 관련 파티션으로 효율적으로 라우팅하여 성능을 향상시킵니다.

    query = "SELECT * FROM c WHERE c.lastName IN ('Wakefield', 'Andersen')"
    
    items = list(container.query_items(
        query=query,
        enable_cross_partition_query=True
    ))
    
    request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
    
    print('Query returned {0} items. Operation consumed {1} request units'.format(len(items), request_charge))
    

앱 실행

  1. Visual Studio Code에서 보기 > 명령 팔레트 를 선택합니다.

  2. 프롬프트에서 Python: Select Interpreter 를 입력한 다음, 사용할 Python 버전을 선택합니다.

    선택한 인터프리터를 나타내도록 Visual Studio Code의 바닥글이 업데이트됩니다.

  3. 보기 > 통합 터미널 을 선택하여 Visual Studio Code 통합 터미널을 엽니다.

  4. 통합 터미널 창에서 azure-cosmos-db-python-getting-started 폴더를 실행 중인지 확인합니다. 이 폴더에 있지 않으면 다음 명령을 실행하여 샘플 폴더로 전환합니다.

    cd "\git-samples\azure-cosmos-db-python-getting-started"`
    
  5. 다음 명령을 실행하여 azure-cosmos 패키지를 설치합니다.

    pip install --pre azure-cosmos
    

    azure-cosmos를 설치하려고 하면 액세스 거부 오류가 발생하는 경우 관리자 권한으로 VS Code를 실행해야 합니다.

  6. 다음 명령을 실행하여 샘플을 실행하고 새 문서를 만들어 Azure Cosmos DB에 저장합니다.

    python cosmos_get_started.py
    
  7. 새 항목이 만들어져 저장되었는지 확인하려면 Azure Portal에서 Data Explorer > AzureSampleFamilyDatabase > 항목 을 차례로 선택합니다. 만든 항목이 표시됩니다. 예를 들어 다음은 Andersen 제품군에 대한 JSON 문서 샘플입니다.

    {
        "id": "Andersen-1569479288379",
        "lastName": "Andersen",
        "district": "WA5",
        "parents": [
            {
                "familyName": null,
                "firstName": "Thomas"
            },
            {
                "familyName": null,
                "firstName": "Mary Kay"
            }
        ],
        "children": null,
        "address": {
            "state": "WA",
            "county": "King",
            "city": "Seattle"
        },
        "registered": true,
        "_rid": "8K5qAIYtZXeBhB4AAAAAAA==",
        "_self": "dbs/8K5qAA==/colls/8K5qAIYtZXc=/docs/8K5qAIYtZXeBhB4AAAAAAA==/",
        "_etag": "\"a3004d78-0000-0800-0000-5d8c5a780000\"",
        "_attachments": "attachments/",
        "_ts": 1569479288
    }
    

Azure Portal에서 SLA 검토

Azure Portal에서는 Cosmos DB 계정 처리량, 스토리지, 가용성, 대기 시간 및 일관성을 모니터링합니다. Azure Cosmos DB SLA(서비스 수준 계약)와 관련된 메트릭 차트에는 실제 성능 대비 SLA 값이 표시됩니다. 이 메트릭 모음을 통해 SLA를 투명하게 모니터링할 수 있습니다.

메트릭 및 SLA를 검토하려면 다음을 수행합니다.

  1. Cosmos DB 계정의 탐색 메뉴에서 메트릭 을 선택합니다.

  2. 대기 시간 과 같은 탭을 선택하고, 오른쪽에서 시간 프레임을 선택합니다. 차트의 실제SLA 줄을 비교합니다.

    Azure Cosmos DB 메트릭 도구 모음

  3. 다른 탭의 메트릭을 검토합니다.

리소스 정리

앱과 Azure Cosmos DB 계정을 모두 사용했으면 추가로 비용을 지불하지 않도록 만든 Azure 리소스를 삭제할 수 있습니다. 리소스를 삭제하려면:

  1. Azure Portal 검색 창에서 리소스 그룹 을 검색하고 선택합니다.

  2. 목록에서 이 빠른 시작에서 만든 리소스 그룹을 선택합니다.

    삭제할 리소스 그룹 선택

  3. 리소스 그룹 개요 페이지에서 리소스 그룹 삭제 를 선택합니다.

    리소스 그룹 삭제

  4. 새 창에서 삭제할 리소스 그룹의 이름을 입력한 다음, 삭제 를 선택합니다.

다음 단계

이 빠른 시작에서는 Azure Cosmos DB 계정을 만들고, 데이터 탐색기를 사용하여 컨테이너를 만들고, Visual Studio Code에서 Python 앱을 실행하는 방법을 알아보았습니다. 이제 사용자의 Azure Cosmos DB 계정에 추가 데이터를 가져올 수 있습니다.

Azure Cosmos DB로 마이그레이션하기 위한 용량 계획을 수행하려고 하나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.