シナリオ: デジタル・ツイン・インスタンス接続タイプの変更

モデル、アダプタ、認証およびゲートウェイ設定を有効なままにして、直接接続、間接接続およびゲートウェイ構成間でデジタル・ツイン・インスタンスを変更します。

このシナリオを使用して、直接接続されたデジタル・ツイン・インスタンスをゲートウェイに変更し、間接的に接続されたデバイスをそのゲートウェイに関連付け、直接接続するようにデバイスを再割当てしてから、ゲートウェイを直接接続に変更します。各更新では、全体として有効な宛先構成を提供する必要があります。

接続の変更中にモデルを更新する場合、宛先モデルには、現在のモデルと同じDTMIパスとメジャー・バージョン、およびマイナー・バージョンまたはマイナー・バージョン以上のバージョンが必要です。同じ更新で無関係なモデルに切り替えることはできません。

宛先接続の要件
宛先タイプ	必須	許可または制限なし
サポートされているすべての宛先タイプ	選択したモデル、アダプタ、認証およびゲートウェイの設定は、有効な宛先構成を1つ形成する必要があります。現在のモデルを維持するか、同じDTMIパスとメジャー・バージョンおよび同じまたはそれ以上のマイナー・バージョンで互換性のあるモデルを使用します。	DTMIパス、メジャー・バージョンまたはマイナー・バージョンが異なるモデルは許可されません。
`DIRECT`	ゲートウェイ・ターゲット・マッピングのない認証IDおよびアダプタ。APIで`authId`を指定し、CLIで`--auth-id`を使用します。	ゲートウェイ・ターゲット・マッピングとのゲートウェイ・アソシエーションおよびアダプタは許可されません。APIリクエストから`gateways`を、CLIコマンドから`--gateways`を省略します。
`INDIRECT`	1つ以上のアクティブ・ゲートウェイ・インスタンスOCIDsおよびゲートウェイ・ターゲット・マッピングのないアダプタを含む、空でない`gateways`リスト。	宛先構成では、認証IDを保持したり、ゲートウェイ・ターゲット・マッピングでアダプタを使用することはできません。重複ゲートウェイまたは非アクティブなゲートウェイを含めず、ゲートウェイのデバイス容量を超えないようにしてください。
`GATEWAY`	認証IDおよびゲートウェイ・ターゲット・マッピングを含むアダプタ。APIで`authId`を指定し、CLIで`--auth-id`を使用します。	ゲートウェイ・ターゲット・マッピングのないゲートウェイ・アソシエーションおよびアダプタは許可されません。APIリクエストから`gateways`を、CLIコマンドから`--gateways`を省略します。既存のゲートウェイを別の接続タイプに変更するには、最初にそれを使用するアクティブな間接接続デバイスをすべて再割り当てします。

ノート

コンソールでデジタル・ツイン・インスタンスを作成または編集する場合、「未接続」はCLIおよびAPIの値NONEに対応します。既存のデジタル・ツイン・インスタンスのNONEへの更新はサポートされていません。接続されていないリソースが必要な場合は、新しいデジタル・ツイン・インスタンスを作成して「未接続」を選択するか、NONEを指定します。

ステップ1: IoTリソースの準備

作業を開始する前に、1つのIoTドメインで作業するリソースを作成または検索します:

認証IDを使用する、直接接続されたアクティブなデジタル・ツイン・インスタンス。
ゲートウェイ構成のゲートウェイ・ターゲット・マッピングを使用するアダプタ。
直接的および間接的に接続されたデバイス構成のゲートウェイ・ターゲット・マッピングのないアダプタ。
DIRECTまたはGATEWAYを使用するすべてのインスタンスの認証ID。
変更されないままのデジタル・ツイン・モデル、または同じDTMIパスとメジャー・バージョンおよび同じまたはより高いマイナー・バージョンとの互換性のある置換モデル。

使用するインスタンス、アダプタ、モデルおよび認証OCIDsを記録します。これらのリソースの作成方法を示すシナリオについては、Create Digital Twins for Indirectly Connected Devices Using a Gatewayを参照してください。

ステップ2: 接続タイプの変更

次のいずれかのインタフェースを使用して、シーケンスを完了します。完全な構成が有効なままの場合、インスタンスを現在の接続タイプに変更することは冪等です。

1. IoTドメインの詳細ページで、「デジタル・ツイン・インスタンス」を選択し、直接接続されたインスタンスを開きます。
2. 「編集」を選択し、接続タイプを「ゲートウェイ」に変更して、ゲートウェイ・ターゲット・マッピングを含むアダプタを選択し、認証IDが選択されていることを確認します。「更新」を選択し、「接続タイプの変更の確認」を選択します。
3. 間接的に接続されたデジタル・ツイン・インスタンスを作成します。ゲートウェイ・ターゲット・マッピングのないアダプタを選択し、更新したゲートウェイを関連付けて、認証IDを指定しません。
4. 間接的に接続されているインスタンスを開き、「編集」を選択します。接続タイプを「直接接続」に変更し、ゲートウェイ・ターゲット・マッピングのないアダプタを選択して、認証IDを選択します。「更新」を選択し、変更を確認します。
5. 前のゲートウェイに間接的に接続されたデバイスがない場合は、デバイスを開いて「編集」を選択します。接続タイプを「直接接続」に変更し、ゲートウェイ・ターゲット・マッピングのないアダプタを選択し、認証IDを保持または選択してから、変更を更新および確認します。

直接接続されたインスタンスをゲートウェイに変更します。

oci iot digital-twin-instance update \
  --digital-twin-instance-id <direct-instance-OCID> \
  --connectivity-type GATEWAY \
  --auth-id <authentication-OCID> \
  --digital-twin-adapter-id <gateway-adapter-OCID> \
  --force

ゲートウェイに関連付けられた間接的に接続されたインスタンスを作成します。

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --display-name <indirect-device-name> \
  --external-key <indirect-device-external-key> \
  --connectivity-type INDIRECT \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <direct-adapter-OCID>

間接的に接続されたインスタンスを直接接続に再割当てします。

oci iot digital-twin-instance update \
  --digital-twin-instance-id <indirect-device-instance-OCID> \
  --connectivity-type DIRECT \
  --auth-id <device-authentication-OCID> \
  --digital-twin-adapter-id <direct-adapter-OCID> \
  --force

すべてのダウンストリーム・デバイスが再割当てされたら、ゲートウェイをダイレクト接続に変更します。

oci iot digital-twin-instance update \
  --digital-twin-instance-id <gateway-instance-OCID> \
  --connectivity-type DIRECT \
  --auth-id <authentication-OCID> \
  --digital-twin-adapter-id <direct-adapter-OCID> \
  --force

UpdateDigitalTwinInstance操作を実行して、直接接続されたインスタンスをゲートウェイに変更します:

{
  "connectivityType": "GATEWAY",
  "authId": "<authentication-OCID>",
  "digitalTwinAdapterId": "<gateway-adapter-OCID>"
}

CreateDigitalTwinInstance操作を実行して、間接的に接続されたインスタンスを作成します:

{
  "displayName": "<indirect-device-name>",
  "externalKey": "<indirect-device-external-key>",
  "connectivityType": "INDIRECT",
  "digitalTwinAdapterId": "<direct-adapter-OCID>",
  "gateways": [
    "<gateway-instance-OCID>"
  ]
}

認証IDおよびゲートウェイ・ターゲット・マッピングのないアダプタを指定して、間接的に接続されたインスタンスを直接接続に更新します。

{
  "connectivityType": "DIRECT",
  "authId": "<device-authentication-OCID>",
  "digitalTwinAdapterId": "<direct-adapter-OCID>"
}

間接的に接続されたデバイスがゲートウェイに依存しない場合は、直接接続するように更新します。

{
  "connectivityType": "DIRECT",
  "authId": "<authentication-OCID>",
  "digitalTwinAdapterId": "<direct-adapter-OCID>"
}

ステップ3: 宛先構成の検証

更新された各デジタル・ツイン・インスタンスを取得し、そのライフサイクル状態がACTIVEであることを確認します。
各インスタンスで、予期される接続タイプ、モデルおよびアダプタが使用されていることを確認します。
直接接続されたインスタンスに認証IDがあり、ゲートウェイ・アソシエーションがないことを確認します。
間接的に接続されたインスタンスを保持する場合は、認証IDがなく、アクティブなゲートウェイ・アソシエーションが少なくとも1つあることを確認します。
ゲートウェイ・インスタンスを保持する場合は、認証ID、ゲートウェイ・ターゲット・マッピングを含むアダプタおよび意図したダウンストリーム・アソシエーションがあることを確認します。

トラブルシューティング

宛先構成が拒否されました

HTTP 400レスポンスは、接続タイプとコンパニオン設定が同時に有効でないことを意味します。モデルの互換性、認証ID、アダプタ・ターゲット・マッピングおよびゲートウェイ・アソシエーションを確認してから、完全な宛先構成を再送信してください。

ゲートウェイの更新はHTTP 409を返します

1つ以上のアクティブで間接的に接続されたデジタル・ツイン・インスタンスは、引き続きゲートウェイを使用します。これらのインスタンスを別のゲートウェイに再割当てするか、サポートされている接続タイプに変更してから、ゲートウェイの更新を再試行してください。

間接構成は認証IDを保持します。

間接的に接続されているインスタンスには認証IDを指定できません。CLIではnullがテキストとして扱われるため、--auth-id nullを渡さないでください。値を明示的にクリアする必要がある場合は、"authId": nullを指定してAPIを使用します。

アダプタが宛先タイプと一致しません

GATEWAYでは、ゲートウェイ・ターゲット・マッピングを持つアダプタを選択します。DIRECTまたはINDIRECTの場合は、ゲートウェイ・ターゲット・マッピングのないアダプタを選択します。

接続されていないインスタンスが必要です

既存のインスタンスをNONEに変更しないでください。新しいデジタル・ツイン・インスタンスを作成し、コンソールで「未接続」を選択するか、CLIまたはAPIでNONEを指定します。

FAQ

接続されておらず、NONEも同じ接続タイプですか。: はい。「未接続」はコンソール・ラベルで、NONEは対応するCLIおよびAPI値です。
既存のデジタル・ツイン・インスタンスを「未接続」に変更できますか。: 番号かわりに、新しいNot connectedインスタンスを作成します。
接続の更新中にモデルを変更できますか。: 同じDTMIパスとメジャー・バージョンおよび同じまたはそれ以上のマイナー・バージョンの互換性のあるモデルにのみ適用されます。関連のないモデルは選択できません。
間接的に接続されたデバイスを最初に再割り当てする必要があるのはなぜですか。: これらのデバイスはゲートウェイ構成によって異なります。アクティブなダウンストリーム・インスタンスがまだそれを使用している間は、ゲートウェイを別の接続タイプに変更することはできません。
現在の接続タイプを再送信できますか。: はい。完全な構成が引き続き有効な場合、同じタイプの更新はべき等です。

詳細については、Indirectly Connected Devices and Gateways FAQsを参照してください。

次のステップ

新規リソースの作成、または既存のリソースの詳細の取得の詳細は、次を参照してください。

Oracle Cloud Infrastructureドキュメント