Azure CLI を使用して IoT ハブを自動的に移行する方法

  • [アーティクル]

Azure CLI IoT を使用して、IoT ハブを新しいリージョン、新しいレベル、または新しい構成に移行します。

この記事の手順は、次の場合に役立ちます。

  • Free レベルから Basic レベルまたは Standard レベルの IoT ハブにアップグレードする。
  • IoT ハブを新しいリージョンに移動する。
  • バックアップを確保するために IoT ハブの状態情報をエクスポートする。
  • IoT ハブのパーティションの数を増やす。
  • 運用環境ではなく、開発環境用にハブを設定する。

自動移行と手動移行の手順を比較する

この記事の結果は、Azure Resource Manager のテンプレートを使用して Azure IoT Hub を移行する方法に似ていますが、プロセスは異なります。 開始する前に、シナリオに適したプロセスを決定します。

  • Azure CLI プロセスの場合 (この記事):

    • デバイス レジストリ、ルーティングとエンドポイントの情報、IoT Edge のデプロイや自動デバイス管理構成などのその他の構成の詳細を移行します。
    • 少数のデバイス (たとえば最大 10,000 台) を簡単に移行できます。
    • Azure Storage アカウントを必要としません。
    • ルーティングとファイル アップロードのエンドポイントの接続文字列を収集して、ARM テンプレート出力に含めます。

  • 手動プロセスの場合:

    • デバイス レジストリとルーティングおよびエンドポイントの情報を移行します。 新しい IoT ハブで他の構成詳細を手動で再作成する必要があります。
    • 多数のデバイス (たとえば、100,000 台を超える場合) を高速に移行できます。
    • Azure Storage アカウントを使用してデバイス レジストリを転送します。
    • ARM テンプレート出力からルーティングおよびファイル アップロードのエンドポイントの接続文字列をスクラブします。手動で追加し直す必要があります。

前提条件

  • Azure CLI

    この記事で説明する機能には、バージョン 0.20.0 以降の azure-iot 拡張機能が必要です。 拡張機能のバージョンを確認するには、az --version を実行します。 拡張機能を更新するには、az extension update --name azure-iot を実行します。

    従来の azure-cli-iot-ext 拡張機能がまだインストールされている場合は、azure-iot 拡張機能を追加する前にその拡張機能を削除してください。

IoT ハブの状態

IoT ハブの状態の移行について説明するときは、次の 3 つのアスペクトの組み合わせを指しています。

  • Azure Resource Manager (ARM) のリソース。 このアスペクトは、リソース テンプレートで定義できるすべてであり、Azure portal の IoT ハブからリソース テンプレートをエクスポートした場合に得られる情報と同じです。 Azure Resource Manager アスペクトの一部としてキャプチャされる情報には、次のものが含まれます。

    • 組み込みのイベント ハブの保有時間
    • 証明書
    • Cloud-to-device プロパティ
    • デバイス SAS の無効化
    • ローカル認証の無効化
    • ファイルのアップロード通知の有効化
    • ファイル アップロード ストレージ エンドポイント
    • Identities
      • ユーザー割り当て ID
      • システム割り当て ID (有効または無効)
    • ネットワーク ルール セット
    • ルーティング
      • カスタム エンドポイント
      • フォールバック ルート
      • ルート
    • タグ

  • 構成。 このアスペクトは、ARM テンプレートには表されていない IoT ハブのアスペクトの関するものです。 具体的には、このアスペクトでは、デバイス管理の自動構成と IoT Edge のデプロイを対象とします。

  • Devices (デバイス)。 このアスペクトは、デバイス レジストリ内の次の情報を表します。

    • デバイス ID とツイン
    • モジュール ID とツイン

ここに記載されていない IoT ハブ プロパティまたは構成は、正しくエクスポートまたはインポートされない可能性があります。

IoT ハブの状態をエクスポートする

az iot hub state export コマンドを使用して、IoT ハブの状態を JSON ファイルにエクスポートします。

1 つのコマンドでエクスポートとインポートの両方の手順を実行する場合は、この記事の後半の「IoT ハブを移行する」セクションを参照してください。

IoT ハブの状態をエクスポートする場合は、エクスポートするアスペクトを選択できます。

パラメーター 詳細
--aspects エクスポートする状態アスペクト。 受け入れられる値 (arm、configurations、devices) を 1 つ以上指定します。 このパラメーターを省略すると、3 つのアスペクトがすべてエクスポートされます。
--state-file -f 状態情報が書き込まれるファイルへのパス。
--replace -r このパラメーターが含まれている場合、export コマンドは状態ファイルのコンテンツを上書きします。
--hub-name -n
or
--login -l		 元の IoT ハブの名前 (-n) または元の IoT ハブの接続文字列 (-l)。 両方が指定されている場合は、接続文字列が優先されます。
--resource-group -g 元の IoT ハブのリソース グループの名前。

次の例では、IoT ハブの状態のすべてのアスペクトを myHub-state という名前のファイルにエクスポートします。

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

次の例では、IoT ハブの状態のデバイスと Azure Resource Manager アスペクトのみをエクスポートし、既存のファイルのコンテンツを上書きします。

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

エンドポイントをエクスポートする

IoT ハブの Azure Resource Manager アスペクトをエクスポートすることにした場合、export コマンドは、キーベース認証を持つエンドポイントの接続文字列を取得し、それらを出力 ARM テンプレートに含めます。

また、export コマンドは、すべてのエンドポイントをチェックして、接続先のリソースがまだ存在することを確認します。 そうでない場合、そのエンドポイントと、そのエンドポイントを使用するルートはエクスポートされません。

IoT ハブの状態をインポートする

az iot hub state import コマンドを使用して、エクスポートされたファイルから新規または既存の IoT ハブに状態情報をインポートします。

1 つのコマンドでエクスポートとインポートの両方の手順を実行する場合は、この記事の後半の「IoT ハブを移行する」セクションを参照してください。

パラメーター 詳細
--aspects インポートする状態の側面。 受け入れられる値 (arm、configurations、devices) を 1 つ以上指定します。 このパラメーターを省略すると、3 つのアスペクトがすべてインポートされます。
--state-file -f エクスポートされた状態ファイルへのパス。
--replace -r このパラメーターが含まれている場合は、import コマンドによって宛先ハブの現在の状態が削除されます。
--hub-name -n
or
--login -l		 宛先 IoT ハブの名前 (-n) または宛先 IoT ハブの接続文字列 (-l)。 両方が指定されている場合は、接続文字列が優先されます。
--resource-group -g 宛先 IoT ハブのリソース グループの名前。

次の例では、すべてのアスペクトを新しい IoT ハブにインポートします。IoT ハブがまだ存在しない場合は作成されます。

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

次の例では、デバイスと構成のアスペクトのみを新しい IoT ハブにインポートします。この IoT ハブは既に存在している必要があり、既存のデバイスと構成を上書きします。

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

状態インポートを使用して新しい IoT ハブを作成する

az iot hub state import コマンドを使用して、新しい IoT ハブを作成したり、既存の IoT ハブに書き込んだりすることができます。

新しい IoT ハブを作成する場合は、import コマンドに arm アスペクトを含める必要があります。 arm がコマンドに含まれず、宛先ハブが存在しない場合、import コマンドは失敗します。

宛先ハブが存在しない場合は、import コマンドに --resource-group パラメーターも必要です。

状態インポートを使用して既存の IoT ハブを更新する

宛先 IoT ハブが既に存在する場合は、arm アスペクトは az iot hub state import コマンドに必要ありません。 arm アスペクトを含める場合、ハブの作成後には変更できない次のプロパティを除き、すべてのリソース プロパティが上書きされます。

  • 場所
  • SKU
  • 組み込みの Event Hubs パーティション数
  • データの保存場所
  • 機能

--resource-group が import コマンドで指定され、IoT ハブの現在のリソース グループと異なる場合、既に存在するハブと同じ名前の新しいハブを作成しようとするため、このコマンドは失敗します。

import コマンドに --replace フラグを含めた場合、ハブの状態がアップロードされる前に、次の IoT ハブのアスペクトが宛先ハブから削除されます。

  • ARM: 宛先ハブにアップロードされた証明書はすべて削除されます。 証明書が存在する場合は、etag を更新する必要があります。
  • デバイス: すべてのデバイスとモジュール (エッジとエッジ以外) が削除されます。
  • 構成: すべての ADM 構成と IoT Edge デプロイが削除されます。

IoT ハブを移行する

az iot hub state migrate コマンドを使用して、1 つの IoT ハブの状態を新規または既存の IoT ハブに移行します。

このコマンドは、エクスポートとインポートの手順を 1 つのコマンドにラップしますが、出力ファイルはありません。 「IoT ハブの状態をエクスポートする」セクションと「IoT ハブの状態をインポートする」セクションで説明されているすべてのガイダンスと制限事項は、state migrate コマンドにも適用されます。

多数のデバイス (数百、数千など) を含むデバイス レジストリを移行する場合は、migrate コマンドを実行するよりも、export コマンドと import コマンドを個別に実行する方が簡単で高速です。

パラメーター 詳細
--aspects 移行する状態アスペクト。 受け入れられる値 (arm、configurations、devices) を 1 つ以上指定します。 このパラメーターを省略すると、3 つのアスペクトがすべて移行されます。
--replace -r このパラメーターが含まれている場合は、migrate コマンドによって宛先ハブの現在の状態が削除されます。
--destination-hub --dh
or
--destination-hub-login --dl		 宛先 IoT ハブの名前 (--dh) または宛先 IoT ハブの接続文字列 (--dl)。 両方が指定されている場合は、接続文字列が優先されます。
--destination-resource-group --dg 宛先 IoT ハブのリソース グループの名前。 宛先 ハブが存在しない場合は、宛先リソース グループが必要です。
--origin-hub --oh
or
--origin-hub-login --ol		 元の IoT ハブの名前 (--oh) または元の IoT ハブの接続文字列 (--ol)。 両方が指定されている場合は、接続文字列が優先されます。 接続文字列を使用して、Azure CLI セッションにサインインする必要がないようにします。
--origin-resource-group --og 元の IoT ハブのリソース グループの名前。

次の例では、元のハブのすべてのアスペクトを宛先ハブに移行します。このハブは存在しない場合、作成されます。

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

移行のトラブルシューティング

デバイスまたは構成をエクスポートまたはインポートできない場合は、それらのプロパティにアクセスできることを確認します。 アクセスを確認するには、1 つの方法として az iot hub device-identity list または az iot hub configuration list コマンドを実行します。

az iot hub state migrate コマンドが失敗した場合は、export コマンドと import コマンドを個別に実行してみてください。 2 つのコマンドは、migrate コマンド単体と同じ機能になりますが、それらを個別に実行することで、export コマンドから作成された状態ファイルを確認できます。

次の手順

IoT ハブで ID レジストリに対して一括操作を実行する方法の詳細については、「IoT Hub デバイス ID の一括でのインポートおよびエクスポート」を参照してください。