Python 用 Azure Azure Digital Twins Core クライアントライブラリ - バージョン 1.2.0

[アーティクル]
04/05/2023

このパッケージには、ツイン、モデル、リレーションシップなどを管理するための 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 Twin インスタンスと資格情報へのエンドポイントが必要です。以下のサンプルでは、AZURE_URLAZURE_TENANT_IDAZURE_CLIENT_ID、および AZURE_CLIENT_SECRET 環境変数を設定する必要があります。クライアントには、 TokenCredential または ServiceClientCredentials のインスタンスが必要です。このサンプルでは、1 つの派生クラス 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)

デジタルツインの作成と削除

デジタルツインを作成する

[ツインの作成] では、などの my_twin デジタルツインの ID と、前に作成したモデルに基づいて application/json デジタルツインを指定する必要があります。サンプルアプリケーション/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)

デジタルツインコンポーネントの取得と更新

デジタルツインコンポーネントを更新する

コンポーネントを更新したり、Digital Twin 内でコンポーネントプロパティまたはサブプロパティを置換、削除、または追加したりするには、デジタルツインの ID、コンポーネント名、アプリケーション/json-patch+json 操作を、指定したデジタルツインのコンポーネントで実行する必要があります。これを行う方法のサンプルコードを次に示します。

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 リファレンスドキュメントでは、再試行、ログ記録、トランスポートプロトコルなどの使用可能な構成について説明しています。

次のステップ

フィードバックの提供

バグが発生した場合や提案がある場合は、issue をオープンしてください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

次の方法で共有

Python 用 Azure Azure Digital Twins Core クライアント ライブラリ - バージョン 1.2.0

免責事項

作業の開始

概要

インストール方法

使用方法

認証、アクセス許可

サンプル コード

主要な概念

例

モデルの作成、一覧表示、使用停止、削除

モデルを作成する

モデルを一覧表示する

モデルを取得する

使用停止モデル

モデルを削除する

デジタル ツインの作成と削除

デジタル ツインを作成する

デジタル ツインを取得する

デジタル ツインのクエリ

デジタル ツインを削除する

デジタル ツイン コンポーネントの取得と更新

デジタル ツイン コンポーネントを更新する

デジタル ツイン コンポーネントを取得する

デジタル ツインリレーションシップを作成して一覧表示する

デジタル ツインリレーションシップを作成する

デジタル ツインのリレーションシップを一覧表示する

デジタル ツインのイベント ルートを作成、一覧表示、削除する

イベント ルートを作成する

イベント ルートを一覧表示する

イベント ルートを削除する

デジタル ツインのテレメトリ メッセージを発行する