Python용 Azure Tables 클라이언트 라이브러리 - 버전 12.4.4

시작

Azure Tables SDK는 Azure Storage 또는 CosmosDB 계정에 액세스할 수 있습니다.

사전 요구 사항

• 이 패키지를 사용하려면 Python 3.7 이상이 필요합니다.
• Azure 구독이 있어야 합니다.
  • Azure Storage 계정 또는
  • Azure Cosmos 계정.

계정 만들기

• 새 스토리지 계정을 만들려면 Azure Portal, Azure PowerShell 또는 Azure CLI를 사용할 수 있습니다.
• 새 cosmos 스토리지 계정을 만들려면 Azure CLI 또는 Azure Portal을 사용할 수 있습니다.

패키지 설치

pip를 사용하여 Python용 Azure Tables 클라이언트 라이브러리를 설치합니다.

pip install azure-data-tables

클라이언트 만들기

Azure Tables 라이브러리를 사용하면 두 가지 유형의 리소스와 상호 작용할 수 있습니다.

• 계정의 테이블
• 해당 테이블 내의 엔터티입니다. 이러한 리소스와의 상호 작용은 클라이언트의 instance 시작합니다. 클라이언트 개체를 만들려면 계정의 테이블 서비스 엔드포인트 URL과 계정에 액세스할 수 있는 자격 증명이 필요합니다. 은 endpointAzure Portal 의 스토리지 계정 페이지에서 "액세스 키" 섹션 아래에 있거나 다음 Azure CLI 명령을 실행하여 찾을 수 있습니다.

# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

계정 URL이 있으면 서비스 클라이언트를 만드는 데 사용할 수 있습니다.

from azure.data.tables import TableServiceClient
service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net/", credential=credential)

테이블 서비스 URL 및 Azure Storage에 대한 사용자 지정 도메인 이름을 구성하는 방법에 대한 자세한 내용은 공식 설명서를 검사.

자격 증명 유형

매개 변수는 credential 사용하려는 권한 부여 유형에 따라 다양한 형식으로 제공될 수 있습니다. 테이블 라이브러리는 다음 권한 부여를 지원합니다.

• 공유 키
• 연결 문자열
• 공유 액세스 서명 토큰

공유 키에서 클라이언트 만들기

계정 공유 키 (계정 키 또는 액세스 키)를 사용하려면 키를 문자열로 제공합니다. 이는 Azure Portal 의 스토리지 계정에서 "액세스 키" 섹션 아래 또는 다음 Azure CLI 명령을 실행하여 찾을 수 있습니다.

az storage account keys list -g MyResourceGroup -n MyStorageAccount

키를 자격 증명 매개 변수로 사용하여 클라이언트를 인증합니다.

from azure.core.credentials import AzureNamedKeyCredential
from azure.data.tables import TableServiceClient

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")

service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=credential)

연결 문자열에서 클라이언트 만들기

사용 사례 및 권한 부여 방법에 따라 계정 URL과 자격 증명을 별도로 제공하는 대신 연결 문자열을 사용하여 클라이언트 instance 초기화하는 것이 좋습니다. 이렇게 하려면 클라이언트의 from_connection_string 클래스 메서드에 연결 문자열을 전달합니다. 연결 문자열은 Azure Portal 의 스토리지 계정에서 "액세스 키" 섹션 또는 다음 Azure CLI 명령을 사용하여 찾을 수 있습니다.

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

from azure.data.tables import TableServiceClient
connection_string = "DefaultEndpointsProtocol=https;AccountName=<my_account_name>;AccountKey=<my_account_key>;EndpointSuffix=core.windows.net"
service = TableServiceClient.from_connection_string(conn_str=connection_string)

SAS 토큰에서 클라이언트 만들기

SAS(공유 액세스 서명) 토큰을 사용하려면 토큰을 문자열로 제공합니다. 계정 URL에 SAS 토큰이 포함된 경우 자격 증명 매개 변수를 생략합니다. 공유 액세스 서명 아래 Azure Portal에서 SAS 토큰을 생성하거나 함수 중 generate_*_sas() 하나를 사용하여 계정 또는 테이블에 대한 sas 토큰을 만들 수 있습니다.

from datetime import datetime, timedelta
from azure.data.tables import TableServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
sas_token = generate_account_sas(
    credential,
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1),
)

table_service_client = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=AzureSasCredential(sas_token))

주요 개념

Table Service의 일반적인 용도는 다음과 같습니다.

• 웹 규모 애플리케이션을 처리할 수 있는 구조화된 데이터 TB 저장
• 복잡한 조인, 외세 키 또는 저장 프로시저가 필요하지 않고 빠른 액세스를 위해 정규화 해제할 수 있는 데이터 세트 저장
• 클러스터형 인덱스를 사용하여 신속하게 데이터 쿼리
• OData 프로토콜 및 LINQ 필터 식을 사용하여 데이터에 액세스

다음 구성 요소는 Azure Tables 서비스를 구성합니다.

• 계정
• 엔터티 집합을 포함하는 계정 내의 테이블
• 사전으로 테이블 내의 엔터티

Python용 Azure Tables 클라이언트 라이브러리를 사용하면 전용 클라이언트 개체를 사용하여 이러한 각 구성 요소와 상호 작용할 수 있습니다.

클라이언트

Table Service의 다양한 구성 요소와 상호 작용하기 위해 두 개의 서로 다른 클라이언트가 제공됩니다.

1. TableServiceClient -
   • 계정 설정 가져오기 및 설정
   • 계정 내에서 테이블을 쿼리, 만들기 및 삭제합니다.
   • 메서드를 TableClient 사용하여 특정 테이블에 액세스하려면 을 get_table_client 가져옵니다.
2. TableClient -
   • 특정 테이블과 상호 작용합니다(아직 존재하지 않아도 됨).
   • 지정된 테이블 내에서 엔터티를 만들고, 삭제하고, 쿼리하고, upsert합니다.
   • 지정된 테이블 자체를 만들거나 삭제합니다.

엔터티

엔터티는 행과 비슷합니다. 엔터티에는 PartitionKey, RowKey및 속성 집합이 있습니다. 속성은 열과 유사한 이름 값 쌍입니다. 테이블의 모든 엔터티에는 동일한 속성이 필요하지 않습니다. 엔터티는 다음과 같은 사전으로 예제로 나타낼 수 있습니다.

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}

• create_entity - 테이블에 엔터티를 추가합니다.
• delete_entity - 테이블에서 엔터티를 삭제합니다.
• update_entity - 기존 엔터티를 병합하거나 대체하여 엔터티 정보를 업데이트합니다.
  • UpdateMode.MERGE 기존 엔터티에 새 속성을 추가합니다. 기존 속성은 삭제되지 않습니다.
  • UpdateMode.REPLACE 는 기존 엔터티를 지정된 엔터티로 바꾸고 제출된 엔터티에 포함되지 않은 기존 속성을 삭제합니다.
• query_entities - OData 필터를 사용하여 테이블의 기존 엔터티를 쿼리합니다.
• get_entity - 파티션 및 행 키로 테이블에서 특정 엔터티를 가져옵니다.
• upsert_entity - 테이블의 엔터티를 병합하거나 바꾸거나 엔터티가 없는 경우 엔터티를 삽입합니다.
  • UpdateMode.MERGE 기존 엔터티에 새 속성을 추가합니다. 기존 속성은 삭제되지 않습니다.
  • UpdateMode.REPLACE 는 기존 엔터티를 지정된 엔터티로 바꾸고 제출된 엔터티에 포함되지 않은 기존 속성을 삭제합니다.

예제

다음 섹션에서는 다음을 포함하여 가장 일반적인 Table 작업 중 일부를 다루는 몇 가지 코드 조각을 제공합니다.

• 테이블 만들기
• 엔터티 만들기
• 엔터티 쿼리

테이블 만들기

계정에 테이블을 만들고 를 가져와 TableClient 서 새로 만든 테이블에서 작업을 수행합니다.

from azure.data.tables import TableServiceClient
table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_name = "myTable"
table_client = table_service_client.create_table(table_name=table_name)

엔터티 만들기

테이블에 엔터티를 만듭니다.

from azure.data.tables import TableServiceClient
from datetime import datetime

PRODUCT_ID = u'001234'
PRODUCT_NAME = u'RedMarker'

my_entity = {
    u'PartitionKey': PRODUCT_NAME,
    u'RowKey': PRODUCT_ID,
    u'Stock': 15,
    u'Price': 9.99,
    u'Comments': u"great product",
    u'OnSale': True,
    u'ReducedPrice': 7.99,
    u'PurchaseDate': datetime(1973, 10, 4),
    u'BinaryRepresentation': b'product_name'
}

table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_client = table_service_client.get_table_client(table_name="myTable")

entity = table_client.create_entity(entity=my_entity)

엔터티 쿼리

테이블의 엔터티 쿼리:

from azure.data.tables import TableClient
my_filter = "PartitionKey eq 'RedMarker'"
table_client = TableClient.from_connection_string(conn_str="<connection_string>", table_name="myTable")
entities = table_client.query_entities(my_filter)
for entity in entities:
    for key in entity.keys():
        print("Key: {}, Value: {}".format(key, entity[key]))

선택적 구성

선택적 키워드(keyword) 인수는 클라이언트 및 작업별 수준에서 전달할 수 있습니다. azure-core 참조 설명서 에서는 재시도, 로깅, 전송 프로토콜 등에 사용할 수 있는 구성에 대해 설명합니다.

재시도 정책 구성

클라이언트를 인스턴스화하여 재시도 정책을 구성할 때 다음 키워드(keyword) 인수를 사용합니다.

• retry_total (int): 허용할 총 재시도 횟수입니다. 다른 개수보다 우선합니다. retry_total=0 요청을 다시 시도하지 않으려면 전달합니다. 기본값은 10입니다.
• retry_connect (int): 다시 시도할 연결 관련 오류 수입니다. 기본값은 3입니다.
• retry_read (int): 읽기 오류를 다시 시도할 횟수입니다. 기본값은 3입니다.
• retry_status(int): 잘못된 상태 코드에서 다시 시도할 횟수입니다. 기본값은 3입니다.
• retry_to_secondary (bool): 가능하면 요청을 보조로 다시 시도해야 하는지 여부입니다. RA-GRS 계정만 사용하도록 설정해야 하며 잠재적으로 부실한 데이터를 처리할 수 있습니다. 기본값은 False입니다.

기타 클라이언트/작업별 구성

다른 선택적 구성 키워드(keyword) 클라이언트 또는 작업별로 지정할 수 있는 인수입니다.

클라이언트 키워드(keyword) 인수:

• connection_timeout (int): 필요에 따라 연결 및 읽기 제한 시간 값을 초 단위로 설정합니다.
• transport (Any): HTTP 요청을 보내기 위해 사용자가 제공한 전송입니다.

연산별 키워드(keyword) 인수:

• raw_response_hook (호출 가능): 지정된 콜백은 서비스에서 반환된 응답을 사용합니다.
• raw_request_hook (호출 가능): 지정된 콜백은 서비스로 전송되기 전에 요청을 사용합니다.
• client_request_id (str): 선택적 사용자 지정 요청 식별입니다.
• user_agent (str): 요청과 함께 보낼 사용자 에이전트 헤더에 사용자 지정 값을 추가합니다.
• logging_enable (bool): DEBUG 수준에서 로깅을 사용하도록 설정합니다. 기본값은 False입니다. 클라이언트 수준에서 전달하여 모든 요청에 대해 사용하도록 설정할 수도 있습니다.
• 헤더 (dict): 사용자 지정 헤더를 키, 값 쌍으로 전달합니다. 예: headers={'CustomValue': value}

문제 해결

일반

Azure Tables 클라이언트는 Azure Core에 정의된 예외를 발생합니다. Python SDK를 사용하여 Azure 테이블 라이브러리와 상호 작용할 때 서비스에서 반환된 오류는 REST API 요청에 대해 동일한 HTTP 상태 코드에 응답합니다. Table Service 작업은 오류 발생 시 유용한 오류 코드와 함께 을 throw HttpResponseError 합니다.

예를 들어 이미 존재하는 테이블을 만들려고 하면 "충돌"을 409 나타내는 오류가 반환됩니다.

from azure.data.tables import TableServiceClient
from azure.core.exceptions import HttpResponseError
table_name = 'YourTableName'

service_client = TableServiceClient.from_connection_string(connection_string)

# Create the table if it does not already exist
tc = service_client.create_table_if_not_exists(table_name)

try:
    service_client.create_table(table_name)
except HttpResponseError:
    print("Table with name {} already exists".format(table_name))

로깅

이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 INFO 수준에서 기록됩니다.

요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 DEBUG 수준 로깅은 인수를 사용하여 클라이언트 logging_enable 에서 사용하도록 설정할 수 있습니다.

import sys
import logging
from azure.data.tables import TableServiceClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = TableServiceClient.from_connection_string("your_connection_string", logging_enable=True)

마찬가지로 는 logging_enable 클라이언트에 대해 사용하도록 설정되지 않은 경우에도 단일 작업에 대해 자세한 로깅을 사용하도록 설정할 수 있습니다.

service_client.create_entity(entity=my_entity, logging_enable=True)

다음 단계

테이블 샘플을 시작합니다.

SDK의 GitHub 리포지토리에서 여러 Azure Tables Python SDK 샘플을 사용할 수 있습니다. 이러한 샘플은 테이블 작업 중에 일반적으로 발생하는 추가 시나리오에 대한 예제 코드를 제공합니다.

일반적인 시나리오

이러한 코드 샘플은 Azure Tables 클라이언트 라이브러리를 사용하는 일반적인 시나리오 작업을 보여 줍니다. 샘플의 비동기 버전(_async 추가된 python 샘플 파일)은 비동기 작업을 표시합니다.

• 테이블 만들기 및 삭제: sample_create_delete_table.py (비동기 버전)
• 테이블 나열 및 쿼리: sample_query_tables.py (비동기 버전)
• 엔터티 삽입 및 삭제: sample_insert_delete_entities.py (비동기 버전)
• 쿼리 및 목록 엔터티: sample_query_table.py (비동기 버전)
• 엔터티 업데이트, upsert 및 병합: sample_update_upsert_merge_entities.py (비동기 버전)
• 단일 트랜잭션에서 많은 요청 커밋: sample_batching.py (비동기 버전)

추가 설명서

Azure Tables에 대한 자세한 설명서는 docs.microsoft.com 대한 Azure Tables 설명서를 참조하세요.

알려진 문제

Cosmos DB 테이블 엔드포인트와 관련된 현재 알려진 문제 목록은 여기에서 찾을 수 있습니다.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.