Python용 Azure Azure Digital Twins Core 클라이언트 라이브러리 - 버전 1.2.0

  • 아티클

이 패키지에는 트윈, 모델, 관계 등을 관리하기 위한 Azure Digital Twins 서비스에 대한 액세스를 제공하는 Azure Digital Twins API용 SDK가 포함되어 있습니다.

고지 사항

Python 2.7에 대한 Azure SDK Python 패키지 지원은 2022년 1월 1일에 종료되었습니다. 자세한 내용과 질문은 을 참조하세요. https://github.com/Azure/azure-sdk-for-python/issues/20691

시작

소개

Azure Digital Twins는 클라우드에서 안전하고 효율적으로 비즈니스 환경의 디지털 표현을 만들고, 실행하고, 관리할 수 있는 차세대 IoT 솔루션을 위한 개발자 플랫폼입니다. Azure Digital Twins를 사용하면 라이브 운영 상태 표현을 만드는 것이 빠르고 비용 효율적이며 디지털 표현은 IoT 및 기타 데이터 원본의 실시간 데이터로 최신 상태를 유지합니다. Azure Digital Twins를 익숙하지 않으며 플랫폼에 대해 자세히 알아보려면 Azure Digital Twins 공식 설명서 페이지를 확인하세요.

Azure Digital Twins 서비스에 대해 프로그래밍하는 방법에 대한 소개는 코딩 자습서 페이지에서 간단한 단계별 가이드를 참조하세요. 명령줄 클라이언트 애플리케이션을 사용하여 Azure Digital Twin 인스턴스와 상호 작용하는 방법을 알아보려면 이 자습서 를 방문하세요. 마지막으로, 환경의 라이브 데이터로 구동되는 엔드 투 엔드 Azure Digital Twins 솔루션을 빌드하는 방법에 대한 빠른 가이드를 보려면 이 유용한 가이드를 확인하세요.

위에서 언급한 가이드는 Azure Digital Twins 인스턴스, 모델, 트윈 그래프 등을 만드는 등 Azure Digital Twins의 주요 요소를 시작하는 데 도움이 될 수 있습니다. 아래 샘플 가이드를 사용하여 Azure Digital Twins에 대해 프로그래밍하는 데 도움이 되는 다양한 API를 숙지합니다.

설치 방법

pip를 사용하여 [azure-digitaltwins-core][pypi_package_keys] 및 azure-identity를 설치합니다.

pip install azure-digitaltwins-core azure-identity

azure-identity 는 아래와 같이 Azure Active Directory 인증에 사용됩니다.

사용 방법

인증, 권한

새 디지털 트윈 클라이언트를 만들려면 Azure Digital Twins 인스턴스 및 자격 증명에 대한 엔드포인트가 필요합니다. 아래 샘플의 경우 , AZURE_URL, AZURE_TENANT_IDAZURE_CLIENT_ID및 AZURE_CLIENT_SECRET 환경 변수를 설정해야 합니다. 클라이언트에는 TokenCredential 또는 ServiceClientCredentials 인스턴스가 필요합니다. 이 샘플에서는 파생 클래스 인 DefaultAzureCredentials를 사용하는 방법을 보여 줍니다.

참고: Digital Twins 서비스의 데이터 평면에 액세스하려면 엔터티에 권한이 부여되어야 합니다. 이렇게 하려면 Azure CLI 명령을 사용합니다. az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential은 다양한 인증 메커니즘을 지원하고 실행 중인 환경에 따라 적절한 자격 증명 유형을 결정합니다. 작업 자격 증명을 발견할 때까지 여러 자격 증명 형식을 순서대로 사용하려고 시도합니다.

예제 코드
# DefaultAzureCredential supports different authentication mechanisms and determines the appropriate credential type based of the environment it is executing in.
# It attempts to use multiple credential types in an order until it finds a working credential.

# - AZURE_URL: The URL to the ADT in Azure
url = os.getenv("AZURE_URL")

# DefaultAzureCredential expects the following three environment variables:
# - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
# - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
# - AZURE_CLIENT_SECRET: The client secret for the registered application
credential = DefaultAzureCredential()
service_client = DigitalTwinsClient(url, credential)

주요 개념

Azure Digital Twins는 실제 환경의 종합적 모델을 만드는 Azure IoT 서비스입니다. 사람, 공간 및 디바이스 간의 관계와 상호 작용을 모델링하는 공간 인텔리전스 그래프를 만들 수 있습니다. Azure Digital Twins 설명서를 방문하여 Azure Digital Twins에 대해 자세히 알아볼 수 있습니다.

예제

샘플 프로젝트를 사용하여 디지털 트윈 API(클라이언트 라이브러리 사용)를 탐색할 수 있습니다.

샘플 프로젝트는 다음을 보여 줍니다.

  • 클라이언트 인스턴스화
  • 모델 만들기, 가져오기 및 서비스 해제
  • 디지털 트윈 만들기, 쿼리, 삭제
  • 디지털 트윈의 구성 요소 가져오기 및 업데이트
  • 디지털 트윈 간의 관계 만들기, 가져오기 및 삭제
  • 디지털 트윈에 대한 이벤트 경로 만들기, 가져오기 및 삭제
  • 디지털 트윈 및 디지털 트윈 구성 요소에 원격 분석 메시지 게시

모델 만들기, 나열, 해제 및 삭제

모델 만들기

아래 코드를 사용하여 모델을 만들어 보겠습니다. 모델 목록이 포함된 배열을 전달해야 합니다.

temporary_component = {
    "@id": component_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Component1",
    "contents": [
    {
        "@type": "Property",
        "name": "ComponentProp1",
        "schema": "string"
    },
    {
        "@type": "Telemetry",
        "name": "ComponentTelemetry1",
        "schema": "integer"
    }
    ]
}

temporary_model = {
    "@id": model_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "TempModel",
    "contents": [
    {
        "@type": "Property",
        "name": "Prop1",
        "schema": "string"
    },
    {
        "@type": "Component",
        "name": "Component1",
        "schema": component_id
    },
    {
        "@type": "Telemetry",
        "name": "Telemetry1",
        "schema": "integer"
    }
    ]
}

new_models = [temporary_component, temporary_model]
models = service_client.create_models(new_models)
print('Created Models:')
print(models)

모델 나열

를 사용하여 list_models 생성된 모든 모델 검색

listed_models = service_client.list_models()
for model in listed_models:
    print(model)

모델 가져오기

모델의 고유 식별자와 함께 를 사용하여 get_model 특정 모델을 가져옵니다.

# Get a model
get_model = service_client.get_model(model_id)
print('Get Model:')
print(get_model)

서비스 해제 모델

모델을 커밋 해제하려면 커밋 해제하려는 모델의 모델 ID를 전달합니다.

# Decommission a model
service_client.decommission_model(model_id)

모델 삭제

모델을 삭제하려면 삭제하려는 모델의 모델 ID를 전달합니다.

# Delete a model
service_client.delete_model(model_id)

디지털 트윈 만들기 및 삭제

디지털 트윈 만들기

트윈 만들기의 경우 앞에서 만든 모델을 기반으로 하는 애플리케이션/json 디지털 트윈과 같은 my_twin 디지털 트윈의 ID를 제공해야 합니다. 여기에서 샘플 애플리케이션/json을 볼 수 있습니다.

digital_twin_id = 'digitalTwin-' + str(uuid.uuid4())
temporary_twin = {
    "$metadata": {
        "$model": model_id
    },
    "$dtId": digital_twin_id,
    "Prop1": 42
}

created_twin = service_client.upsert_digital_twin(digital_twin_id, temporary_twin)
print('Created Digital Twin:')
print(created_twin)

디지털 트윈 가져오기

디지털 트윈을 얻는 것은 매우 쉽습니다.

get_twin = service_client.get_digital_twin(digital_twin_id)
print('Get Digital Twin:')
print(get_twin)

디지털 트윈 쿼리

Azure Digital Twins 쿼리 저장소 lanaguage를 사용하여 디지털 트윈에 대한 Azure Digital Twins 인스턴스를 쿼리합니다. 쿼리 호출은 페이징을 지원합니다. 다음은 디지털 트윈을 쿼리하는 방법과 결과를 반복하는 방법의 예입니다.

인스턴스의 변경 내용이 쿼리에 반영되기 전에 사이에 지연이 있을 수 있습니다. 쿼리 제한 사항에 대한 자세한 내용은 (/azure/digital-twins/how-to-query-graph#query-limitations)를 참조하세요.

query_expression = 'SELECT * FROM digitaltwins'
query_result = service_client.query_twins(query_expression)
print('DigitalTwins:')
for twin in query_result:
    print(twin)

디지털 트윈 삭제

아래와 같이 디지털 트윈의 ID를 제공하여 디지털 트윈을 삭제합니다.

service_client.delete_digital_twin(digital_twin_id)

디지털 트윈 구성 요소 가져오기 및 업데이트

디지털 트윈 구성 요소 업데이트

구성 요소를 업데이트하거나 디지털 트윈 내에서 구성 요소 속성 또는 하위 속성을 대체, 제거 및/또는 추가하려면 지정된 디지털 트윈의 구성 요소에서 수행할 디지털 트윈, 구성 요소 이름 및 애플리케이션/json-patch+json 작업의 ID가 필요합니다. 이 작업을 수행하는 방법에 대한 샘플 코드는 다음과 같습니다.

component_name = "Component1"
patch = [
    {
        "op": "replace",
        "path": "/ComponentProp1",
        "value": "value2"
    }
]
service_client.update_component(digital_twin_id, component_name, patch)

디지털 트윈 구성 요소 가져오기

구성 요소의 이름과 구성 요소가 속한 디지털 트윈의 ID를 제공하여 구성 요소를 가져옵니다.

get_component = service_client.get_component(digital_twin_id, component_name)
print('Get Component:')
print(get_component)

디지털 트윈 관계 만들기 및 나열

디지털 트윈 관계 만들기

upsert_relationship 는 디지털 트윈의 ID, "contains"와 같은 관계의 이름, "FloorContainsRoom"과 같은 관계의 ID 및 만들 애플리케이션/json 관계와 함께 제공되는 디지털 트윈에 관계를 만듭니다. 관계의 대상을 지정하려면 "$targetId" 키가 있는 속성을 포함해야 합니다. 관계에 대한 샘플 페이로드는 여기에서 찾을 수 있습니다.

hospital_relationships = [
    {
        "$relationshipId": "BuildingHasFloor",
        "$sourceId": building_twin_id,
        "$relationshipName": "has",
        "$targetId": floor_twin_id,
        "isAccessRestricted": False
    },
    {
        "$relationshipId": "BuildingIsEquippedWithHVAC",
        "$sourceId": building_twin_id,
        "$relationshipName": "isEquippedWith",
        "$targetId": hvac_twin_id
    },
    {
        "$relationshipId": "HVACCoolsFloor",
        "$sourceId": hvac_twin_id,
        "$relationshipName": "controlsTemperature",
        "$targetId": floor_twin_id
    },
    {
        "$relationshipId": "FloorContainsRoom",
        "$sourceId": floor_twin_id,
        "$relationshipName": "contains",
        "$targetId": room_twin_id
    }
]

for relationship in hospital_relationships:
    service_client.upsert_relationship(
        relationship["$sourceId"],
        relationship["$relationshipId"],
        relationship
    )

디지털 트윈 관계 나열

list_relationships 및 list_incoming_relationships 는 디지털 트윈의 모든 관계 및 들어오는 모든 관계를 각각 나열합니다.

relationships = service_client.list_relationships(digital_twint_id)
for relationship in relationships:
    print(relationship)

incoming_relationships = service_client.list_incoming_relationships(digital_twin_id)
for incoming_relationship in incoming_relationships:
    print(incoming_relationship)

디지털 트윈의 이벤트 경로 만들기, 나열 및 삭제

이벤트 경로 만들기

이벤트 경로를 만들려면 아래 예제와 같이 엔드포인트 및 선택적 필터를 포함하는 이벤트 경로 데이터 및 "myEventRouteId"와 같은 이벤트 경로의 ID를 제공합니다.

event_route_id = 'eventRoute-' + str(uuid.uuid4())
event_filter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'"
route = DigitalTwinsEventRoute(
    endpoint_name=event_hub_endpoint_name,
    filter=event_filter
)
service_client.upsert_event_route(event_route_id, route)

이벤트 경로 필터 언어에 대한 자세한 내용은 "경로 관리 방법" 필터 이벤트 설명서를 참조하세요.

이벤트 경로 나열

지정된 이벤트 경로 ID 또는 를 사용하여 모든 이벤트 경로 설정 옵션을 나열합니다 list_event_routes.

event_routes = service_client.list_event_routes()
for event_route in event_routes:
    print(event_route)

이벤트 경로 삭제

이벤트 경로 ID가 지정된 이벤트 경로를 삭제합니다.

service_client.delete_event_route(event_route_id)

디지털 트윈에 대한 원격 분석 메시지 게시

디지털 트윈에 대한 원격 분석 메시지를 게시하려면 업데이트가 필요한 원격 분석의 페이로드와 함께 디지털 트윈 ID를 제공해야 합니다.

digita_twin_id = "<DIGITAL TWIN ID>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_telemetry(
    digita_twin_id,
    telemetry_payload
)

디지털 트윈의 특정 구성 요소에 대한 원격 분석 메시지를 게시할 수도 있습니다. 디지털 트윈 ID 및 페이로드 외에도 대상 구성 요소 ID를 지정해야 합니다.

digita_twin_id = "<DIGITAL TWIN ID>"
component_name = "<COMPONENT_NAME>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_component_telemetry(
    digita_twin_id,
    component_name,
    telemetry_payload
)

문제 해결

로깅

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

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

클라이언트 수준 로깅

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Create service client and enable logging for all operations
service_client = DigitalTwinsClient(url, credential, logging_enable=True)

작업별 수준 로깅

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Get model with logging enabled
model = service_client.get_model(model_id, logging_enable=True)

선택적 구성

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

다음 단계

피드백 제공

버그가 발생하거나 제안이 있는 경우 문제를 열어주세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 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으로 문의하세요.