Azure Digital Twins のモデルを管理する

[アーティクル]
06/11/2024

この記事では、Azure Digital Twins インスタンスでモデルを管理する方法について説明します。管理操作には、モデルのアップロード、検証、取得、および削除が含まれます。

前提条件

この記事で Azure Digital Twins を操作するには、まず Azure Digital Twins インスタンスとそれを使用するために必要なアクセス許可が必要です。 Azure Digital Twins インスタンスが既に設定されている場合は、そのインスタンスを使用し、次のセクションに進むことができます。それ以外の場合は、「インスタンスと認証を設定する」の手順に従います。手順には、各ステップを正常に完了したことを確認するために役立つ情報が含まれています。

インスタンスの設定後、インスタンスのホスト名を書き留めておきます。ホスト名は Azure portal で確認できます。

開発者インターフェイス

この記事では、.NET (C#) SDK を使用して、さまざまな管理操作を実行する方法について説明します。また、「Azure Digital Twins API および SDK」で説明されているその他の言語の SDK を使用して、これらと同じ管理呼び出しを作成することもできます。

これらの操作を完了するために使用できるその他の開発者インターフェイスは次のとおりです。

Note

現在、Azure Digital Twins Explorer は DTDL v2 モデルを完全にサポートしており、DTDL v3 モデルの制限された機能をサポートしています。

[モデル] パネルで DTDL v3 モデルを表示でき、DTDL v3 モデルで作成されたツインを表示および編集できます (配列プロパティを持つものを含む)。ただし、DTDL v3 モデルは [モデルグラフ] パネルに表示されず、Azure Digital Twins Explorer を使用してこれらをインポートすることはできません。 DTDL v3 モデルをインスタンスにインポートするには、API と SDK や Azure CLI などの別の開発者インターフェイスを使用します。

ビジュアル化

Azure Digital Twins Explorer は、Azure Digital Twins グラフ内のデータを探索するためのビジュアルツールです。エクスプローラーを使用して、モデル、ツイン、リレーションシップを表示、クエリ、編集できます。

Azure Digital Twins Explorer ツールについて詳しくは、Azure Digital Twins Explorer に関するページを参照してください。その機能を使用する方法の詳細な手順については、Azure Digital Twins Explorer を使用するに関するページを参照してください。

視覚化は次のように表示されます。

モデルを作成する

独自のモデルをゼロから作成することも、業界で利用可能な既存のオントロジを使用することもできます。

モデルの作成

Azure Digital Twins のモデルは DTDL で記述され、JSON ファイルとして保存されます。また、Visual Studio Code 用の DTDL 拡張機能も用意されており、構文の検証や、DTDL ドキュメントの作成を容易にするその他の機能が提供されます。

病院が部屋をデジタルで表現する例を考えてみましょう。各部屋には、手の洗浄を監視するためのスマートソープディスペンサーと、部屋の行き来を監視するセンサーが含まれています。

ソリューションに向けた最初の手順は、病院の状況を表すモデルを作成することです。このシナリオの病室は、次のように記述できます。

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

Note

これは、クライアントプロジェクトの一部としてアップロードされる、モデルが定義され保存されている JSON ファイルのサンプル本文です。一方、REST API 呼び出しは、上記のようなモデル定義の配列を取得します (これは .NET SDK の IEnumerable<string> にマップされています)。そのため、REST API でこのモデルを直接使用するには、ブラケットで囲みます。

このモデルでは、病室の名前と固有 ID、および訪問者数と手の洗浄状態を表すプロパティが定義されています。これらのカウンターは、モーションセンサーとスマートソープディスペンサーから更新され、handwash percentage のプロパティを計算するために一緒に使用されます。このモデルでは、hasDevices のリレーションシップも定義されています。これは、この Room モデルに基づいてデジタルツインを実際のデバイスに接続するために使用されます。

Note

いくつかの DTDL 機能は Azure Digital Twins で現在サポートされていません。これには、プロパティとリレーションシップの writable 属性や、リレーションシップの minMultiplicity および maxMultiplicity 属性などがあります。詳細については、「サービス固有の DTDL に関する注意事項」を参照してください。

この方法に従うと、病院の病棟、ゾーン、または病院自体のモデルを定義できます。

業界のドメインを記述した包括的なモデルセットのビルドが達成目標の場合は、モデルを簡単に作成するために使用できる既存の業界のオントロジがあるかどうかを考慮に入れてください。次のセクションでは、業界のオントロジについて詳しく説明します。

既存の業界標準のオントロジの使用

オントロジとは、製造、ビルの構造、IoT システム、スマートシティ、エネルギーグリッド、Web コンテンツなど、特定のドメインを包括的に記述したモデルのセットです。

ソリューションが、いずれかの種類のモデリング標準を使用する特定の業界に対するものである場合、モデルをゼロから設計するのではなく、業界向けに設計された既存のモデルセットから始めることを検討してください。 Microsoft は、各分野の専門家と提携して業界標準に基づく DTDL モデルオントロジを作成することで、再発明を最小限に抑え、業界ソリューション全体で一貫性とシンプルさが促進されるようにしました。これらのオントロジの詳細 (使用方法や現在提供されているオントロジなど) については、「オントロジとは」を参照してください。

構文を検証する

モデルの作成後、モデルは、Azure Digital Twins インスタンスにアップロードする前に、オフラインで検証することが推奨されます。

モデルを検証するために、.NET クライアント側 DTDL 解析ライブラリが NuGet: DTDLParser に用意されています。 C# コードのパーサーライブラリを直接使用できます。 GitHub の DTDLParserResolveSample でパーサーの使用例を参照することもできます。

モデルのアップロード

モデルを作成したら、Azure Digital Twins インスタンスにアップロードできます。

モデルをアップロードする準備が整ったら、.NET SDK に次のコードスニペットを使用します。

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

アップロード時に、サービスによってモデルファイルが検証されます。

通常、複数のモデルをサービスにアップロードする必要があります。単一トランザクションで多数のモデルを一度にアップロードする方法がいくつかあります。戦略を選ぶのに役立つように、モデルセットのサイズを考慮に入れてこのセクションの残りの部分を進めてください。

小規模なモデルセットのアップロード

小規模なモデルセットの場合は、個別の API 呼び出しを使用して複数のモデルを一度にアップロードできます。「Azure Digital Twins サービスの制限」で、単一の API 呼び出しでアップロードできるモデルの数に関する現在の制限をチェックできます。

SDK を使用している場合は、次のように CreateModels メソッドを使用して複数のモデルファイルをアップロードできます。

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

REST API または Azure CLI を使用している場合は、1 つの JSON ファイルに複数のモデル定義をまとめてアップロードすることで、複数のモデルをアップロードできます。この場合、次の例のように、ファイル内の JSON 配列にモデルを配置する必要があります。

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

Import Jobs API を使用して大規模なモデルセットをアップロードする

大規模なモデルセットの場合は、Import Jobs API を使用して、単一の API 呼び出しで多数のモデルを一度にアップロードできます。この API は、1 つのインスタンス内のモデルの数に関する Azure Digital Twins の制限の限度まで同時に受け入れることができ、それらのモデル間の依存関係を解決する必要がある場合は自動的に並べ替えます。この方法の場合、Azure Blob Storage を使用する必要があります。また、モデルと一括ジョブに関する Azure Digital Twins インスタンス内の書き込みアクセス許可も必要です。

ヒント

Import Jobs API を使用して、同一の呼び出しでツインとリレーションシップをインポートし、グラフのすべての部分を一度に作成することもできます。このプロセスの詳細については、「Import Jobs API を使用してモデル、ツイン、リレーションシップを一括でアップロードする」を参照してください。

モデルを一括インポートするには、モデル (および一括インポートジョブに含まれるその他のリソース) を NDJSON ファイルとして構成する必要があります。 Models セクションは Header セクションの直後になり、ファイル内の最初のグラフデータセクションになります。インポートファイルの例と、これらのファイルの作成に関するサンプルプロジェクトについては、Import Jobs API の紹介に関する記事で参照できます。

次に、Azure Blob Storage 内の追加 BLOB にファイルをアップロードする必要があります。 Azure ストレージコンテナーを作成する方法の手順については、「コンテナーを作成する」を参照してください。次に、ご希望のアップロード方法を使用してファイルをアップロードします (AzCopy コマンド、Azure CLI、Azure portal などのオプションがあります)。

NDJSON ファイルがコンテナーにアップロードされたら、BLOB コンテナー内で URL を取得します。この値は、後で一括インポート API 呼び出しの本文で使用します。

Azure portal 内の BLOB ファイルの URL 値のスクリーンショットを次に示します。

その後、Import Jobs API 呼び出しでこのファイルを使用できます。入力ファイルの BLOB ストレージ URL と、サービスで出力ログが作成される際の保存場所を示す新しい BLOB ストレージ URL を指定します。

モデルの取得

Azure Digital Twins インスタンスに格納されているモデルを一覧表示したり、取得したりすることができます。

次のような方法があります。

単一のモデルの取得
すべてのモデルの取得
モデルのメタデータと依存関係を取得する

呼び出し例を次に示します。

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

モデルを取得するための SDK 呼び出しは、すべて DigitalTwinsModelData オブジェクトを返します。 DigitalTwinsModelData には、名前、DTMI、モデルの作成日など、Azure Digital Twins インスタンスに格納されているモデルに関するメタデータが含まれます。 DigitalTwinsModelData オブジェクトには、必要に応じてモデル自体を含めることもできます。つまり、パラメーターによっては、取得呼び出しを使用して、メタデータのみ (これは、使用可能なツールの UI の一覧を表示するシナリオなどで役に立ちます)、またはモデル全体を取得できます。

RetrieveModelWithDependencies 呼び出しでは、要求されたモデルだけでなく、要求されたモデルが依存しているすべてのモデルも返されます。

モデルは、必ずしもアップロードされたドキュメント形式では返されません。 Azure Digital Twins は、返される形式が意味的に同等であることだけを保証します。

モデルを更新する

このセクションでは、モデルを更新する際の考慮事項と方法について説明します。

更新する前に: ソリューション全体のコンテキストで検討する

モデルの更新を行う前に、ソリューション全体を総合的に考察し、行おうとしているモデルの変更による影響を検討することをお勧めします。 Azure Digital Twins ソリューションのモデルは相互接続されることが多いため、1 つのモデルを更新するにはいくつかの他のモデルを更新する必要があるという連鎖的な変更に注意することが重要です。モデルの更新は、そのモデルを使用するツインに影響し、さらにイングレスおよび処理コード、クライアントアプリケーション、および自動レポートにも影響を与える可能性があります。

モデルの切り替えをスムーズに管理するための推奨事項を次に示します。

モデルを個別のエントリと考えるのではなく、モデルとその関係を常に最新の状態に保つために、必要に応じてモデルセット全体を進化させることを検討してください。
モデルをソースコードのように扱い、これらをソースコード管理で管理します。モデルおよびモデルの変更に対し、ソリューション内の他のコードに適用するのと同じ厳格さと注意深さを適用します。

モデルの更新プロセスを進める準備ができたら、このセクションの残りの部分では、更新の実装に使用できる方法について説明します。

モデルを更新するための方法

Azure Digital Twins インスタンスにモデルがアップロードされると、モデルインターフェイスは不変になります。つまり、モデルの従来の "編集" ができないことを意味します。また、Azure Digital Twins では、一致するモデルがインスタンスに既に存在している間は、同じモデルを再アップロードできません。

displayName や description の更新や、プロパティの追加および削除など、モデルに変更を加える場合は、元のモデルを置き換える必要があります。

モデルを置き換える場合は、次の 2 つの方法から選択できます。

方法 1: 新しいモデルバージョンをアップロードする: 新しいバージョン番号を使用してモデルをアップロードし、新しいモデルを使用するようにツインを更新します。新しいバージョンと古いバージョンのモデルは、一方を削除するまでいずれもインスタンスに存在します。
- この方法を使用する状況: モデルを使用するツインの一部のみを更新する場合、またはツインがモデルに準拠した状態を維持し、モデルの切り替え中ずっと書き込み可能にしたい場合。
方法 2: 古いモデルを削除して再アップロードする: 元のモデルを削除し、その代わりに同じ名前と ID (DTMI 値) を使用して新しいモデルをアップロードします。古いモデルを完全に新しいものに置き換えます。
- この方法を使用する状況: このモデルを使用するすべてのツインと、モデルの影響を受けるすべてのコードを同時に更新する場合。ご使用のモデル更新に、モデル更新に関する破壊的変更が含まれている場合、ツインは古いモデルから新しいモデルに切り替わるしばらくの間、モデルに準拠しなくなります。つまり、新しいモデルがアップロードされ、ツインがそれに準拠するまで、更新を受け取ることができなくなります。

Note

開発以外では、モデルに破壊的変更を加えることはお勧めできません。

それぞれの方法の詳細については、次のセクションに進んでください。

方法 1: 新しいモデルバージョンをアップロードする

このオプションでは、モデルの新しいバージョンを作成し、インスタンスにアップロードします。

この操作によって、以前のバージョンのモデルが上書きされることはないため、削除するまでは複数のバージョンのモデルがインスタンス内に共存します。新しいモデルバージョンと古いモデルバージョンが共存しているため、ツインは新しいバージョンのモデルまたは古いバージョンのいずれかを使用できます。つまり、新しいバージョンのモデルをアップロードしても、既存のツインに自動的には影響しません。既存のツインは古いモデルバージョンのインスタンスとして残ります。これらのツインを修正することで、新しいモデルバージョンに更新できます。

この方法を使用するには、次の手順に従います。

1. 新しいモデルバージョンを作成してアップロードする

既存のモデルの新しいバージョンを作成するには、元のモデルの DTDL から開始します。変更するフィールドを更新、追加、または削除します。

次に、このモデルにモデルの新しいバージョンとしてマークを付けるために、モデルの id フィールドを更新します。モデル ID の最後のセクション (; の後) は、モデル番号を表します。ここで、このモデルがより更新されたバージョンであることを示すために、id 値の最後にある数値を現在のバージョン番号よりも大きい数値に増やします。

たとえば、以前のモデル ID が次の場合:

"@id": "dtmi:com:contoso:PatientRoom;1",

このモデルのバージョン 2 は次のようになります。

"@id": "dtmi:com:contoso:PatientRoom;2",

次に、この新しいバージョンのモデルをインスタンスにアップロードします。

このバージョンのモデルは、インスタンスで使用可能となり、デジタルツインに使用できるようになります。これによって、以前のバージョンのモデルが上書きされることはないため、複数のバージョンのモデルがインスタンス内に共存します。

2. 必要に応じてグラフ要素を更新する

次に、古いモデルではなく新しいモデルバージョンを使用するようにインスタンスのツインおよびリレーションシップを更新します。

次の手順を使用して、ツインの更新とリレーションシップの更新を行うことができます。ツインのモデルを更新するためのパッチ操作は、次のようになります。

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

重要

ツインを更新する場合、同じパッチを使用して、モデル ID の (新しいモデルバージョンへの) 更新と、ツインで変更する必要があるすべてのフィールドの更新を行い、ツインを新しいモデルに準拠させる必要があります。

また、このモデルを参照するインスタンス内のリレーションシップおよびその他のモデルを更新して、それらが新しいモデルバージョンを参照するようにすることが必要な場合もあります。この目的を達成するには、別のモデル更新操作を行う必要があります。そのため、このセクションの冒頭に戻り、更新が必要なすべてのモデルに対してプロセスを繰り返します。

3. (省略可能) 古いモデルバージョンを使用停止にするまたは削除する

古いモデルバージョンを今後使用しない場合、古いモデルを使用停止にすることができます。この操作により、モデルはインスタンス内に存在し続けますが、新しいデジタルツインを作成するために使用することはできません。

また、インスタンス内に残す必要がない場合は、古いモデルを完全に削除することもできます。

上のリンク先のセクションには、モデルの使用停止と削除に関するコード例と考慮事項が含まれています。

方法 2: 古いモデルを削除して再アップロードする

モデルのバージョンを増やす代わりに、モデルを完全に削除し、編集したモデルをインスタンスに再アップロードすることができます。

Azure Digital Twins では、古いモデルが以前アップロードされていたことが記憶されないため、このアクションは、完全に新しいモデルをアップロードする操作に似たものになります。モデルを使用するツインは、新しい定義が使用可能になると自動的にそちらに切り替わります。新しい定義が古い定義とどのように異なるかに応じて、これらのツインには、削除される定義と一致するが、新しい定義では有効でないプロパティとリレーションシップが存在する場合があります。そのため、有効な状態を維持するために修正プログラムを適用することが必要な場合もあります。

この方法を使用するには、次の手順に従います。

1. 古いモデルを削除する

Azure Digital Twins では、2 つのモデルが同じ ID を持つことが許可されないため、まず元のモデルをインスタンスから削除します。

Note

(継承またはコンポーネントを介して) このモデルに依存する他のモデルがある場合は、モデルを削除する前に、それらの参照を削除する必要があります。これらの依存モデルを最初に更新して参照を一時的に削除したり、依存モデルを削除して後の手順で再アップロードしたりすることができます。

次の手順を使用して、元のモデルを削除します。このアクションにより、そのモデルを使用していたツインは、存在しなくなったモデルを現在使用しているため、一時的に "孤立" 状態になります。この状態は、更新されたモデルを再アップロードする次の手順で修復されます。

2. 新しいモデルを作成してアップロードする

まず、元のモデルの DTDL から開始します。変更するフィールドを更新、追加、または削除します。

次に、初めてアップロードされる新しいモデルの場合と同様に、インスタンスにモデルをアップロードします。

3. 必要に応じてグラフ要素を更新する

古いモデルの代わりの新しいモデルがアップロードされたので、インスタンス内のキャッシュの有効期限が切れてリセットされると、グラフ内のツインは新しいモデル定義の使用を自動的に開始します。グラフのサイズによっては、このプロセスには 10 から 15 分、あるいはそれ以上かかる場合もあります。その後、モデルの新しいプロパティと変更されたプロパティにアクセスできるようになり、削除されたプロパティにはアクセスできなくなります。

Note

元のモデルを削除するために他の依存モデルを先に削除している場合は、キャッシュがリセットされた後に再アップロードしてください。依存モデルを更新して元のモデルへの参照を一時的に削除した場合は、これらを再び更新して、参照を元に戻すことができます。

次に、インスタンス内のツインとリレーションシップを更新して、そのプロパティが新しいモデルで定義されたプロパティと一致するようにします。この手順が完了する前も、モデルと一致しないツインは引き続き読み取り可能ですが、書き込みできません。有効なモデルのないツインの状態の詳細については、「モデルなしのツイン」を参照してください。

新しいモデルのツインとリレーションシップを更新して、再度書き込み可能にするには、次の 2 つの方法があります。

必要に応じてツインとリレーションシップにパッチを適用し、新しいモデルに適合するようにします。次の手順を使用して、ツインの更新とリレーションシップの更新を行うことができます。
- プロパティを追加した場合: ツインとリレーションシップが新しい値を持つように更新することは必須でありません。新しい値がないツインも引き続き有効なツインであるためです。新しいプロパティの値を追加する任意の方法でパッチを適用することができます。
- プロパティを削除した場合: 新しいモデルで無効になるプロパティを削除するために、ツインにパッチを適用する必要があります。
- プロパティを更新した場合: ツインが新しいモデルに対して有効になるようにするために、変更されたプロパティの値を更新するパッチを適用する必要があります。
モデルを使用するツインとリレーションシップを削除し、再作成します。次の手順を使用して、ツインを削除し、ツインを再作成して、リレーションシップを削除し、リレーションシップを再作成します。
- この操作は、モデルに多くの変更を加え、それに一致するよう既存のツインを更新するのが難しい場合に行うことができます。ただし、多くのリレーションシップによって相互接続されている多数のツインがある場合は、再作成が複雑になる可能性があります。

モデルの削除

モデルは、次の 2 つの方法のいずれかでサービスから削除できます。

使用停止: モデルが使用停止になったら、新しいデジタルツインの作成にそれを使用できなくなります。このモデルを既に使用している既存のデジタルツインは影響を受けないため、プロパティの変更やリレーションシップの追加や削除などの操作で更新できます。
削除: この操作により、ソリューションからモデルが完全に削除されます。このモデルを使用していたすべてのツインは、有効なモデルに関連付けられなくなったため、モデルがまったくないかのように扱われます。これらのツインは引き続き読み取ることができますが、別のモデルに再割り当てされるまで、更新を行うことはできません。

これらの操作は別の機能であり、互いに影響を与えることはありませんが、一緒に使用してモデルを段階的に削除することもできます。

Note

インスタンス内のすべてのモデル、ツイン、リレーションシップを一度に削除する場合は、Delete Jobs API を使用します。

使用停止

モデルの使用を停止するには、SDK の DecommissionModel メソッドを使用します。

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

REST API 呼び出し DigitalTwinModels Update を使用して、モデルの使用を停止することもできます。 decommissioned プロパティは、この API 呼び出しで置き換えられる唯一のプロパティです。 JSON Patch ドキュメントは次のようになります。

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

モデルの使用停止状態は、モデル取得 API によって返された ModelData レコードに含まれます。

削除

インスタンス内のすべてのモデルを一度に削除することも、個別に実行することもできます。

すべてのモデルを同時に削除する方法の例については、GitHub の Azure Digital Twins のエンドツーエンドサンプルリポジトリを参照してください。 CommandLoop.cs ファイルには、インスタンス内のすべてのモデルを削除するコードを含む CommandDeleteAllModels 関数が含まれています。

個々のモデルを削除するには、このセクションの残りの部分の手順と考慮事項に従ってください。

削除前: 削除の要件

一般的に、設定はいつでも削除できます。

例外は、extends リレーションシップまたはコンポーネントとして、他のモデルが依存しているモデルです。たとえば、ConferenceRoom モデルが Room モデルを拡張し、コンポーネントとして ACUnit モデルを持っている場合、ConferenceRoom によってそれらの参照が削除されるまで、Room または ACUnit を削除することはできません。

これを行うには、依存モデルを更新して依存関係を削除するか、依存モデルを完全に削除します。

削除中: 削除プロセス

モデルが直ちに削除するための要件を満たしている場合でも、ツインが残されている場合に意図しない結果が生じないように、まずいくつかの手順を実行することをお勧めします。プロセスの管理に役立つ手順を次に示します。

まず、モデルの使用を停止します
使用停止前の最後の数分間に送信されたツイン作成要求をサービスが処理したことを確認するため、数分待ちます
モデル別にツインをクエリして、現在使用停止モデルを使用しているすべてのツインを表示します
不要になった場合はツインを削除するか、必要に応じて新しいモデルにパッチします。また、なにもせず、モデルを削除した後にモデルなしのツインにすることも選択できます。この状態の影響については、次のセクションを参照してください。
さらに数分待って、変更がすべて適用されたことを確実にします
モデルを削除します

モデルを削除するには、次のように DeleteModel SDK 呼び出しを使用します。

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

また、DigitalTwinModels Delete REST API 呼び出しでモデルを削除することもできます。

削除後: モデルなしのツイン

モデルを削除すると、モデルを使用していたすべてのデジタルツインがモデルなしと見なされるようになります。この状態のすべてのツインの一覧を表示できるクエリは存在しません。ただし、削除されたモデルによってツインにクエリを実行して、どのツインが影響を受けているかを把握することは "できます"。

ここでは、モデルを持たないツインで実行できることとできないことの概要を示します。

可能な操作:

ツインのクエリ
プロパティの読み取り
外部に対するリレーションシップの読み取り
外部からの関係の追加および削除 (つまり、他のツインはこのツインに対してリレーションシップを形成できます)
- リレーションシップ定義内の target には、削除されたモデルの DTMI が引き続き反映されます。ここでは、ターゲットが定義されていないリレーションシップを使用することもできます。
関連性の削除
ツインを削除する

不可能なこと:

外部へのリレーションシップを編集します (つまり、このツインから他のツインへのリレーションシップ)
プロパティの編集

削除後: モデルの再アップロード

モデルを削除した後で、削除したものと同じ ID を持つ新しいモデルを後でアップロードすることを決定できます。その場合は、次のようになります。

ソリューションストアの観点から見ると、この操作はまったく新しいモデルをアップロードすることと同じです。古いバージョンがアップロードされたことをサービスは覚えていません。
削除されたモデルを参照しているグラフにツインが残っている場合は、孤立していない状態になります。このモデル ID は、新しい定義で再び有効になります。ただし、モデルの新しい定義が削除されたモデル定義と異なる場合、これらのツインには、削除された定義と一致し、新しい定義では無効なプロパティとリレーションシップが含まれている可能性があります。

Azure Digital Twins ではこの状態を防ぐことができないため、ツインがモデル定義の切り替え後も有効なままになるように、適切なパッチを適用するように注意してください。

v2 モデルを v3 に変換する

Azure Digital Twins では DTDL バージョン 2 および 3 がサポートされています (このドキュメントではそれぞれ v2 および v3 と短縮して表記されています)。拡張された機能に基づいて、v3 を選択することが推奨されています。このセクションでは、既存の DTDL v2 モデルを DTDL v3 に更新する方法について説明します。

コンテキストを更新します。 モデルが v2 または v3 であると特定する主要な機能は、インターフェイス上の @context フィールドです。モデルを v2 から v3 に変換するには、コンテキスト値 dtmi:dtdl:context;2 を dtmi:dtdl:context;3 に変更します。多くのモデルの場合、必要な変更はこれだけです。
1. v2 の値: "@context": "dtmi:dtdl:context;2"
2. v3 の値: "@context": "dtmi:dtdl:context;3"。
必要に応じて、セマンティック型を更新します。 DTDL v2 では、セマンティック型はネイティブでサポートされています。 DTDL v3 では、セマンティック型は QuantitativeTypes 機能拡張に含まれています。そのため、v2 モデルでセマンティック型を使用していた場合に、モデルを v3 に変換する際には、機能拡張を追加する必要があります。追加するには、まず最初にインターフェイス上の @context フィールドを単一値から値の配列に変更し、続いて値 dtmi:dtdl:extension:quantitativeTypes;1 を追加します。
1. v2 の値: "@context": "dtmi:dtdl:context;2"
2. v3 の値: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
必要に応じて、サイズ制限を考慮に入れます。 v2 と v3 のサイズ制限は違うので、インターフェイスが非常に大きい場合は、DTDL v2 と v3 の違いに関する記事で制限を確認することもできます。

このように変更し終えると、以前の DTDL v2 モデルが DTDL v3 モデルに変換されます。

配列型のプロパティ、バージョンの緩和、追加の機能拡張など、DTDL v3 の新機能を検討し、追加機能とて有効かどうか確認することもできます。 DTDL v2 と v3 の違いの完全なリストについては、DTDL v3 言語の説明の、バージョン 2 からの変更に関する記事を参照してください。

Note

現在、Azure Digital Twins Explorer は DTDL v2 モデルを完全にサポートしており、DTDL v3 モデルの制限された機能をサポートしています。

次のステップ

モデルに基づいてデジタルツインを作成して管理する方法を説明します。

デジタルツインを管理する

次の方法で共有

Azure Digital Twins のモデルを管理する

前提条件

開発者インターフェイス

ビジュアル化

モデルを作成する

モデルの作成

既存の業界標準のオントロジの使用

構文を検証する

モデルのアップロード

小規模なモデルセットのアップロード

Import Jobs API を使用して大規模なモデルセットをアップロードする

モデルの取得

モデルを更新する

更新する前に: ソリューション全体のコンテキストで検討する

モデルを更新するための方法

方法 1: 新しいモデルバージョンをアップロードする

1. 新しいモデルバージョンを作成してアップロードする

2. 必要に応じてグラフ要素を更新する

3. (省略可能) 古いモデルバージョンを使用停止にするまたは削除する

方法 2: 古いモデルを削除して再アップロードする

1. 古いモデルを削除する

2. 新しいモデルを作成してアップロードする

3. 必要に応じてグラフ要素を更新する

モデルの削除

使用停止

削除

削除前: 削除の要件

削除中: 削除プロセス

削除後: モデルなしのツイン

削除後: モデルの再アップロード

v2 モデルを v3 に変換する

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Digital Twins のモデルを管理する

前提条件

開発者インターフェイス

ビジュアル化

モデルを作成する

モデルの作成

既存の業界標準のオントロジの使用

構文を検証する

モデルのアップロード

小規模なモデル セットのアップロード

Import Jobs API を使用して大規模なモデル セットをアップロードする

モデルの取得

モデルを更新する

更新する前に: ソリューション全体のコンテキストで検討する

モデルを更新するための方法

方法 1: 新しいモデル バージョンをアップロードする

1. 新しいモデル バージョンを作成してアップロードする

2. 必要に応じてグラフ要素を更新する

3. (省略可能) 古いモデル バージョンを使用停止にするまたは削除する

方法 2: 古いモデルを削除して再アップロードする

1. 古いモデルを削除する

2. 新しいモデルを作成してアップロードする

3. 必要に応じてグラフ要素を更新する

モデルの削除

使用停止

削除

削除前: 削除の要件

削除中: 削除プロセス

削除後: モデルなしのツイン

削除後: モデルの再アップロード

v2 モデルを v3 に変換する

次のステップ

フィードバック

その他のリソース

小規模なモデルセットのアップロード

Import Jobs API を使用して大規模なモデルセットをアップロードする

方法 1: 新しいモデルバージョンをアップロードする

1. 新しいモデルバージョンを作成してアップロードする

3. (省略可能) 古いモデルバージョンを使用停止にするまたは削除する