빠른 시작: Python SDK 및 Azure Cosmos DB를 사용하여 API for Table 앱 빌드
적용 대상: 
테이블
이 빠른 시작에서는 Python 애플리케이션에서 Azure Cosmos DB API for Table에 액세스하는 방법을 보여 줍니다. Azure Cosmos DB for Table은 애플리케이션이 구조적 NoSQL 데이터를 클라우드에 저장할 수 있도록 하는 스키마 없는 데이터 저장소입니다. 데이터가 스키마 없는 디자인에 저장되므로, 새 특성이 있는 개체가 테이블에 추가되면 테이블에 새 속성(열)이 자동으로 추가됩니다. Python 애플리케이션은 Azure Data Tables SDK for Python 패키지를 사용하여 Azure Cosmos DB for Table에 액세스할 수 있습니다.
필수 조건
샘플 애플리케이션은 Python 3.7 이상으로 작성되었지만 원칙은 모든 Python 3.7 이상 애플리케이션에 적용됩니다. Visual Studio Code를 IDE로 사용할 수 있습니다.
Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다.
샘플 응용 프로그램
이 자습서의 샘플 애플리케이션은 리포지토리 https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask에서 복제하거나 다운로드할 수 있습니다.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
1-starter-app 및 2-completed-app 샘플 폴더는 샘플 리포지토리에 포함됩니다. 1-starter-app에는 "#TODO"로 표시된 줄로 완료할 수 있는 몇 가지 기능이 남아 있습니다. 이 문서에 표시된 코드 조각은 1-starter-app을 완료하기 위해 제안된 추가 사항입니다.
완성된 샘플 애플리케이션은 날씨 데이터를 예제로 사용하여 API for Table의 기능을 보여 줍니다. 날씨 관측을 나타내는 개체는 API for Table을 사용하여 저장 및 검색됩니다. 여기에는 API for Table의 스키마 없는 기능을 보여 주기 위해 추가 속성이 있는 개체 저장이 포함됩니다. 다음 이미지는 Azure Cosmos DB for Table에 저장된 날씨 데이터를 표시하는 브라우저에서 실행되는 로컬 애플리케이션을 보여 줍니다.
1 - Azure Cosmos DB 계정 만들기
먼저 애플리케이션에서 사용되는 테이블을 포함할 Azure Cosmos DB Tables API 계정을 만들어야 합니다. Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 계정을 만듭니다.
Azure Portal에 로그인하고 다음 단계에 따라 Azure Cosmos DB 계정을 만듭니다.
| 지침 | 스크린샷 |
|---|---|
Azure Portal에서 다음을 수행합니다.
|
|
| Azure Cosmos DB 페이지에서 +만들기를 선택합니다. | 
|
| API 옵션 선택 페이지에서 Azure Table 옵션을 선택합니다. | 
|
Azure Cosmos DB 계정 만들기 - Azure Table 페이지에서 다음과 같이 양식을 작성합니다.
|
|
2 - 테이블 만들기
다음으로 애플리케이션에서 사용할 Azure Cosmos DB 계정 내에 테이블을 만들어야 합니다. 기존 데이터베이스와 달리, 테이블의 속성(열)이 아니라 테이블의 이름만 지정하면 됩니다. 데이터가 테이블에 로드되면 필요에 따라 속성(열)이 자동으로 만들어집니다.
Azure Portal에서 다음 단계를 완료하여 Azure Cosmos DB 계정 내에 테이블을 만듭니다.
| 지침 | 스크린샷 |
|---|---|
Azure Portal에서 Azure Cosmos DB 계정의 개요 페이지로 이동합니다.
|
|
| 개요 페이지에서 +테이블 추가를 선택합니다. 새 테이블 대화 상자가 페이지의 오른쪽에서 서서히 표시됩니다. | 
|
새 테이블 대화 상자에서 다음과 같이 양식을 작성합니다.
|
|
3 - Azure Cosmos DB 연결 문자열 가져오기
Azure Cosmos DB의 테이블에 액세스하려면 앱에 Cosmos DB Storage 계정에 대한 테이블 연결 문자열이 필요합니다. 이 연결 문자열은 Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 검색할 수 있습니다.
| 지침 | 스크린샷 |
|---|---|
| Azure Cosmos DB 계정 페이지의 왼쪽에 있는 설정 헤더 아래에서 연결 문자열이라는 메뉴 항목을 찾아 선택합니다. Azure Cosmos DB 계정에 대한 연결 문자열을 검색할 수 있는 페이지로 이동됩니다. | 
|
| 애플리케이션에서 사용할 기본 연결 문자열 값을 복사합니다. | 
|
4 - Azure Data Tables SDK for Python 설치
Azure Cosmos DB 계정을 만든 후 다음 단계는 Microsoft Azure Data Tables SDK for Python을 설치하는 것입니다. SDK 설치에 대한 자세한 내용은 GitHub의 Data Tables SDK for Python 리포지토리에서 README.md 파일을 참조하세요.
pip를 사용하여 Python용 Azure Tables 클라이언트 라이브러리를 설치합니다.
pip install azure-data-tables
1-starter-app 또는 2-completed-app 폴더에도 requirements.txt도 설치해야 합니다.
5 - .env 파일에서 테이블 클라이언트 구성
Azure Portal에서 Cosmos DB 계정 연결 문자열을 복사하고 복사한 연결 문자열을 사용하여 TableServiceClient 개체를 만듭니다. 1-starter-app 또는 2-completed-app 폴더로 전환합니다. 시작하는 앱에 관계없이 .env 파일에서 환경 변수를 정의해야 합니다.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Azure SDK는 클라이언트 개체를 통해 Azure와 통신하여 Azure에 대해 다양한 작업을 실행합니다. TableServiceClient 개체는 Azure Cosmos DB for Table과 통신하는 데 사용되는 개체입니다. 일반적으로 애플리케이션에는 전체적으로 단일 TableServiceClient가 있고 테이블당 TableClient가 있습니다.
예를 들어 다음 코드는 환경 변수의 연결 문자열을 사용하여 TableServiceClient 개체를 만듭니다.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 - Azure Cosmos DB 테이블 작업 구현
샘플 앱에 대한 모든 Azure Cosmos DB 테이블 작업은 webapp 디렉토리 아래의 helper 파일에 있는 TableServiceHelper 클래스에서 구현됩니다. Python용 azure.data.tables 클라이언트 라이브러리의 개체를 사용하려면 이 파일의 맨 위에 있는 TableServiceClient 클래스를 가져와야 합니다.
from azure.data.tables import TableServiceClient
TableServiceHelper 클래스의 시작 부분에서 생성자를 만들고 TableClient 개체가 클래스에 삽입될 수 있도록 TableClient 개체에 대한 멤버 변수를 추가합니다.
def __init__(self, table_name=None, conn_str=None):
self.table_name = table_name if table_name else os.getenv("table_name")
self.conn_str = conn_str if conn_str else os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
self.table_client = self.table_service.get_table_client(self.table_name)
테이블에서 반환된 행 필터링
테이블에서 반환된 행을 필터링하려면 OData 스타일 필터 문자열을 query_entities 메서드에 전달하면 됩니다. 예를 들어 2021년 7월 1일 자정부터 2021년 7월 2일 자정(포함) 사이의 모든 시카고 날씨 판독값을 가져오려면 다음 필터 문자열을 전달합니다.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
필터 쓰기 섹션의 azure-data-tables 웹 사이트에서 관련 OData 필터 연산자를 볼 수 있습니다.
request.args 매개변수가 TableServiceHelper 클래스의 query_entity 메서드에 전달되면 null이 아닌 각 속성 값에 대한 필터 문자열이 생성됩니다. 그런 다음, 모든 값을 "and" 절과 조인하여 결합된 필터 문자열을 만듭니다. 이 결합된 필터 문자열은 TableClient 개체의 query_entities 메서드에 전달되고 필터 문자열과 일치하는 행만 반환됩니다. 비슷한 메서드를 코드에 사용하여 애플리케이션에 필요한 적절한 필터 문자열을 생성할 수 있습니다.
def query_entity(self, params):
filters = []
if params.get("partitionKey"):
filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
if params.get("minTemperature"):
filters.append("Temperature ge {}".format(params.get("minTemperature")))
if params.get("maxTemperature"):
filters.append("Temperature le {}".format(params.get("maxTemperature")))
if params.get("minPrecipitation"):
filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
if params.get("maxPrecipitation"):
filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
return list(self.table_client.query_entities(" and ".join(filters)))
TableEntity 개체를 사용하여 데이터 삽입
테이블에 데이터를 추가하는 가장 간단한 방법은 TableEntity 개체를 사용하는 것입니다. 이 예제에서는 데이터가 입력 모델 개체에서 TableEntity 개체로 매핑됩니다. 기상 관측소 이름과 관측 날짜/시간을 나타내는 입력 개체의 속성은 각각 PartitionKey 및 RowKey 속성에 매핑되어 테이블의 행에 대한 고유 키를 형성합니다. 그런 다음, 입력 모델 개체의 추가 속성이 TableEntity 개체의 사전 속성에 매핑됩니다. 마지막으로 TableClient 개체의 create_entity 메서드를 사용하여 테이블에 데이터를 삽입합니다.
다음 코드를 포함하도록 예제 애플리케이션에서 insert_entity 함수를 수정합니다.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
TableEntity 개체를 사용하여 데이터 upsert
해당 테이블에 이미 있는 파티션 키/행 키 조합으로 테이블에 행을 삽입하려고 하면 오류가 발생합니다. 이러한 이유로 테이블에 행을 추가할 때 create_entity 메서드 대신 upsert_entity를 사용하는 것이 좋습니다. 지정된 파티션 키/행 키 조합이 테이블에 이미 있는 경우 upsert_entity 메서드는 기존 행을 업데이트합니다. 그렇지 않으면 행이 테이블에 추가됩니다.
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
변수 속성이 있는 데이터 삽입 또는 upsert
Azure Cosmos DB for Table을 사용할 때의 이점 중 하나는 테이블에 로드되는 개체에 새 속성이 포함된 경우 해당 속성이 테이블에 자동으로 추가되고 값이 Azure Cosmos DB에 저장된다는 것입니다. 기존 데이터베이스에서 하는 것처럼 열을 추가하기 위해 ALTER TABLE과 같은 DDL 문을 실행할 필요가 없습니다.
이 모델은 시간에 따라 캡처해야 하는 데이터를 추가하거나 수정할 수 있는 데이터 원본을 처리할 때 또는 다른 입력에서 애플리케이션에 다른 데이터를 제공할 때 애플리케이션에 유연성을 제공합니다. 샘플 애플리케이션에서는 기본 날씨 데이터뿐 아니라 몇 가지 추가 값도 전송하는 기상 관측소를 시뮬레이션할 수 있습니다. 이러한 새 속성을 가진 개체가 처음으로 테이블에 저장되면 해당 속성(열)이 테이블에 자동으로 추가됩니다.
Table용 API를 사용하여 이러한 개체를 삽입하거나 upsert하려면 확장 가능한 개체의 속성을 TableEntity 개체에 매핑하고, create_entity 개체에서 upsert_entity 또는 TableClient 메서드를 적절하게 사용합니다.
또한 샘플 애플리케이션에서 upsert_entity 함수는 변수 속성을 사용해서 삽입 또는 upsert 데이터 함수를 구현할 수 있습니다.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
엔터티 업데이트
TableClient 개체에서 update_entity 메서드를 호출하여 엔터티를 업데이트할 수 있습니다.
샘플 앱에서 이 개체는 TableClient 클래스의 upsert_entity 메서드에 전달됩니다. 해당 엔터티 개체를 업데이트하고 upsert_entity 메서드를 사용하여 업데이트를 데이터베이스에 저장합니다.
def update_entity(self):
entity = self.update_deserialize()
return self.table_client.update_entity(entity)
@staticmethod
def update_deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = params.pop("ObservationDate")
return params
엔터티 제거
테이블에서 엔터티를 제거하려면 개체의 파티션 키와 행 키를 사용하여 TableClient 개체에서 delete_entity 메서드를 호출합니다.
def delete_entity(self):
partition_key = request.form.get("StationName")
row_key = request.form.get("ObservationDate")
return self.table_client.delete_entity(partition_key, row_key)
7 - 코드 실행
샘플 애플리케이션을 실행하여 Azure Cosmos DB for Table과 상호 작용합니다. 예를 들어 요구 사항이 설치된 2-completed-app 폴더부터 다음을 사용할 수 있습니다.
python3 run.py webapp
샘플 애플리케이션 실행에 대한 자세한 내용은 샘플 리포지토리 루트에 있는 README.md 파일을 참조하세요.
애플리케이션을 처음 실행하면 테이블이 비어 있기 때문에 데이터가 없습니다. 애플리케이션 맨 위에 있는 단추를 사용하여 테이블에 데이터를 추가합니다.
테이블 엔터티를 사용하여 삽입 단추를 선택하면 TableEntity 개체를 사용하여 새 행을 삽입하거나 upsert할 수 있는 대화 상자가 열립니다.
확장 가능한 데이터를 사용하여 삽입 단추를 선택하면 사용자 지정 속성이 있는 개체를 삽입할 수 있는 대화 상자가 나타나고 Azure Cosmos DB for Table이 필요할 때 자동으로 테이블에 속성(열)을 추가하는 방법을 보여 줍니다. 사용자 지정 필드 추가 단추를 사용하여 하나 이상의 새 속성을 추가하고 이 기능을 실습해 보세요.
샘플 데이터 삽입 단추를 사용하여 일부 샘플 데이터를 Cosmos DB 테이블에 로드합니다.
1-starter-app 샘플 폴더의 경우 샘플 데이터 삽입이 작동하려면 적어도
submit_transaction함수에 대한 코드를 완료해야 합니다.샘플 데이터는 sample_data.json 파일에서 로드됩니다. .env 변수
project_root_path는 이 파일을 찾을 위치를 앱에 알려줍니다. 예를 들어 1-starter-app 또는 2-completed-app 폴더에서 애플리케이션을 실행하는 경우project_root_path를 ""(비어 있음)로 설정합니다.
위쪽 메뉴에서 결과 필터링 항목을 선택하여 [결과 필터링] 페이지로 이동합니다. 이 페이지에서 필터 조건을 입력하여 필터 절을 작성하고 Azure Cosmos DB for Table에 전달하는 방법을 보여 줍니다.
리소스 정리
샘플 애플리케이션을 마쳤으면 Azure 계정에서 이 문서와 관련된 모든 Azure 리소스를 제거해야 합니다. 리소스 그룹을 삭제하여 모든 리소스를 제거할 수 있습니다.
다음을 수행하여 Azure Portal을 통해 리소스 그룹을 삭제할 수 있습니다.
| 지침 | 스크린샷 |
|---|---|
| 리소스 그룹으로 이동하려면 검색 창에 리소스 그룹의 이름을 입력합니다. 그런 다음, 리소스 그룹 탭에서 리소스 그룹의 이름을 선택합니다. | 
|
| 리소스 그룹 페이지 위쪽에 있는 도구 모음에서 리소스 그룹 삭제를 선택합니다. | 
|
리소스 그룹의 삭제를 확인하는 메시지를 표시하는 대화 상자가 화면 오른쪽에 표시됩니다.
|
|
다음 단계
이 빠른 시작에서, Azure Cosmos DB 계정을 만들고, 데이터 탐색기를 사용하여 테이블을 만들고, 앱을 실행하는 방법을 알아보았습니다. 이제 테이블용 API를 사용하여 데이터를 쿼리할 수 있습니다.