次の方法で共有

Python 用 Azure IoT モデル リポジトリ クライアント ライブラリ - バージョン 1.0.0a20220330001

  • [アーティクル]

Python 用 Azure IoT Models リポジトリ ライブラリには、Azure IoT モデル リポジトリを操作するための機能が用意されています

作業の開始

パッケージのインストール

pip を使用して Python 用 Azure IoT モデル リポジトリ ライブラリをインストールします。

pip install azure-iot-modelsrepository

前提条件

  • Azure IoT 規則に従ったモデル リポジトリ
    • モデル リポジトリは、ローカル ファイルシステムでホストすることも、Web サーバーでホストすることもできます
    • Azure IoT は、カスタムの場所が指定されていない場合にクライアントが使用するグローバル Azure IoT モデル リポジトリ をホストします

モデルのパブリッシュ

ガイドに従って、モデルをグローバル Azure IoT モデル リポジトリに発行します。

カスタムローカルリポジトリまたはリモートリポジトリを使用している場合は、リポジトリの場所にあるディレクトリ構造にモデルファイルを追加するだけです。 dtmi/com/example/thermostat-1.json

認証

現在、認証メカニズムはサポートされていません。 グローバル エンドポイントは Azure サブスクリプションに関連付けされておらず、認証をサポートしていません。 公開されるすべてのモデルは、匿名のパブリック消費を目的としています。

主要な概念

Azure IoT モデル リポジトリを使用すると、ビルダーはデジタル ツイン モデルを管理および共有できます。 モデルは、Digital Twins Definition Language (DTDL) を使用して定義された JSON-LD ドキュメントです。

リポジトリは、デジタル ツイン モデル識別子 (DTMI) に基づいて、DTDL インターフェイスをディレクトリ構造に格納するパターンを定義します。 DTMI を相対パスに変換することで、リポジトリ内のインターフェイスを見つけることができます。 たとえば、DTMI dtmi:com:example:Thermostat;1 は に /dtmi/com/example/thermostat-1.json変換されます。

例

次のセクションでは、モデル リポジトリの一般的なタスクに関するいくつかのスニペットを示します。

ModelsRepositoryClient の初期化

リポジトリの場所

インスタンス化中にリポジトリの場所が指定されていない場合は、Azure IoT Models リポジトリ グローバル エンドポイント (https://devicemodels.azure.com/) が使用されます

client = ModelsRepositoryClient()

または、オプション repository_location のキーワードを使用して、リポジトリが配置されている場所のカスタムの場所を指定することもできます。 クライアントは、次の場所の形式を受け入れます。

  • Web URL - 例: "https://contoso.com/models/"
  • ローカル ファイルシステム URI - 例: "file:///path/to/repository/"
  • POSIX ファイルパス - 例: "/path/to/repository/"
  • ドライブ文字ファイルパス - 例: "C:/path/to/repository/"
client = ModelsRepositoryClient(repository_location="https://contoso.com/models/")

依存関係解決モード

クライアントは、次のいずれかの値を使用して、インスタンス化時に省略可能な dependency_resolution モードで構成できます。

  • 'disabled' - クライアントはモデルの依存関係を解決しません
  • 'enabled' - クライアントはモデルの依存関係を解決します
  • 'tryFromExpanded' - クライアントは、拡張されたモデル定義を使用してモデルの解決を試みます (可能でない場合はモードに 'enabled' 戻ります)
client = ModelsRepositoryClient(dependency_resolution="enabled")

モードが dependency_resolution 指定されていない場合:

  • Azure IoT Models リポジトリ グローバル エンドポイント用に構成されたクライアントは、既定で を使用します。 'tryFromExpanded'
  • カスタムの場所 (リモートまたはローカル) 用に構成されたクライアントは、 'enabled'

追加オプション

azure-core ライブラリから既定のパイプライン動作をオーバーライドする必要がある場合は、インスタンス化中にさまざまなキーワード引数を指定できます。

クライアントのクリーンアップ

クライアントの使用が完了したら、リソースを解放するために 必ず を呼び出 .close() してください

client = ModelsRepositoryClient()
# Do things
client.close()

これを行う必要を回避するために、可能な限りコンテキスト マネージャー内からクライアントを使用することをお勧めします。これにより、自動的に閉じられます

with ModelsRepositoryClient() as client:
    # Do things

ModelsRepositoryClient - モデルの取得

モデルをフェッチするには、まず してリポジトリに発行 する必要があることに注意してください。 次の例では、グローバル Azure IoT モデル リポジトリを使用していることを前提としています。

を呼び出すと .get_models() 、指定された DTMI とその依存関係 (依存関係解決モードに応じて) でモデルがフェッチされます。 DTMI を dict モデル定義にマップする が返されます。

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient() as client:
    models = get_models(dtmi)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

メソッドに複数の DTMI を指定する場合は、複数のモデル (および潜在的にそれらの依存関係) を一度に取得できます

dtmis = ["dtmi:com:example:TemperatureController;1", "dtmi:com:example:azuresphere:sampledevice;1"]
with ModelsRepositoryClient() as client:
    models = get_models(dtmis)
print("{} resolved in {} interfaces".format(dtmi, len(models)))

既定では、クライアントは、モデルの取得時にインスタンス化時に 構成された依存関係を使用します。 ただし、この動作は、 の有効なオプションのいずれかを省略可能なキーワード引数として に渡すことによってオーバーライドできます。 .get_models()

dtmi = "dtmi:com:example:TemperatureController;1"
with ModelsRepositoryClient(dependency_resolution="disabled") as client:
    models = get_models(dtmi, dependency_resolution="enabled")

DTMI 規則

パッケージには という名前 dtmi_conventionsのモジュールが含まれています。インポートすると、DTMI を操作するための一連のユーティリティ操作が提供されます

# Returns True - this is a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat;1")

# Returns False - this is NOT a valid DTMI
dtmi_conventions.is_valid_dtmi("dtmi:com:example:Thermostat")

dtmi = "dtmi:com:example:Thermostat;1"

# Local repository example
repo_uri = "file:///path/to/repository"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "file:///path/to/repository/dtmi/com/example/thermostat-1.expanded.json"

# Remote repository example
repo_uri = "https://contoso.com/models/"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.json"
print(dtmi_conventions.get_model_uri(dtmi, repo_uri, expanded=True))
# Prints: "https://contoso/com/models/dtmi/com/example/thermostat-1.expanded.json"

トラブルシューティング

ログ記録

このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 HTTP セッション (URL、ヘッダーなど) に関する情報は、レベルで DEBUG ログに記録されます。

例外

モデル リポジトリ API では、 azure-core で定義されている例外が発生する可能性があります。

さらに、 で定義されている例外が発生する azure-iot-modelsrepository可能性があります。

  • ModelError - モデル定義の解析/解決中にエラーが発生したことを示します。 これは一般に、モデル DTDL 仕様に準拠していない形式のモデルがあることを意味します

フィードバックの提供

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

次のステップ

サンプル

その他のサンプルは、 サンプル リポジトリで入手できます。

共同作成

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

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

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