Oracle Cloud Infrastructureドキュメント

クイック・スタート: デジタル・ツインの作成およびデータの送信

このシナリオでは、デジタル・ツイン・インスタンスを作成する方法と、Basic認証を使用してサンプル・データを送信して構成をテストする方法を示します。

前提条件

ユーザーが作業するOCIリソースにアクセスするには、管理者がポリシーを作成する必要があります。このシナリオを設定するには、次のポリシーが必要です。その他のIoTシナリオに関連する追加のポリシーの詳細は、前提条件を参照してください。
IoTポリシー
このIoTファミリ・ポリシーを使用して、指定したユーザー・グループが特定のコンパートメント内のIoTリソースを管理できるようにするか、管理者がIoTポリシーを使用して特定のIoTリソースに対して特定のポリシーを設定できます:
Allow group <group-name> to manage iot-family in compartment <your-compartment-name>
Vaultシークレット・ポリシー

基本認証を使用する場合は、「ステップ3: デジタル・ツイン・インスタンスの作成」のコマンドを使用するときに、シークレットを作成して、次のポリシーが必要になります。

任意のIoTユーザーが、IoTドメインの特定のコンパートメントおよびボールト内のシークレットを読み取るようにします:
Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}

ステップ1: IoTドメイン・グループの作成

作業する既存のIoTドメイン・グループまたはIoTドメインがある場合は、このステップをスキップし、それらのOCIDsを使用して関連するデジタル・ツイン・インスタンスを作成します。または、次のステップを実行して、IoTドメイン・グループおよびIoTドメインを作成します。オプションの完全なリストは、「IoTドメイン・グループの作成」を参照してください。

    1. IoTドメイン・グループ・リスト・ページで、「ドメイン・グループの作成」を選択します。リスト・ページの検索に関するヘルプが必要な場合は、「IoTドメイン・グループのリスト」を参照してください。
    2. 「ドメイン・グループの作成」ページで、新しいドメイン・グループのわかりやすい名前と、オプションの説明を入力します。機密情報を入力しないでください。
    3. 新しいドメイン・グループを格納するコンパートメントを選択します。IoTドメイン・グループとIoTドメインは、異なるコンパートメントに配置できます。すべてのIoTリソースは同じリージョンにある必要があります。
    4. ドメイン・グループのタイプを選択します。Developerはデフォルト・タイプです。かわりに、新しいドメイン・グループを作成することはできません。
      • 開発者: 開発およびテストに使用し、コストを削減し、使用するリソースを減らします。
      • 標準: 本番ドメイン・グループの場合、開発者オプションをオフにしてリソースをスケーリングし、自動フェイルオーバーで高可用性を有効にします。
      ノート

      ドメイン・グループ・タイプは変更できません。かわりに、新しいドメイン・グループを作成してください。
    5. 「作成」を選択します。
  • 特定のコンパートメントにIoTドメイン・グループを作成するには、oci iot domain-group createコマンドと必要な--compartment-idパラメータを使用します。<compartment-OCID>値をコンパートメントOCIDに置き換えます:
    oci iot domain-group create --compartment-id <compartment-OCID>

    タイプ・オプション:
    • --typeを指定しない場合、デフォルトのドメイン・グループ・タイプはlightweightです。軽量ドメイン・グループを開発およびテストする場合、コストが低く、使用するリソースが少なくなります。本番ドメイン・グループを作成する場合は、標準オプションを使用します。
    • 本番ドメイン・グループの場合、--typeパラメータをstandard値とともに使用して、高可用性および自動フェイルオーバーでスケーリングする標準ドメイン・グループを作成します。

    CLIコマンドのパラメータおよび値の完全なリストは、CLIコマンド・リファレンスを参照してください。

  • CreateIotDomainGroup操作を実行して、コンパートメントにIoTドメイン・グループを作成します。

ステップ2: IoTドメインの作成

    1. 「IoTドメイン」リスト・ページで、IoTドメインを格納するコンパートメントを選択します。IoTドメイン・グループとIoTドメインは、異なるコンパートメントに配置できます。IoTデジタル・ツイン・リソースは、異なるコンパートメントに配置でき、同じリージョン内に存在する必要があります。IoTドメイン・リスト・ページの検索に関するヘルプが必要な場合は、「IoTドメインのリスト」を参照してください。
    2. 「ドメインの作成」を選択します。
    3. IoTドメインのユーザー・フレンドリな名前を入力します。機密情報を入力しないでください。
    4. 説明を入力します。(オプション)
    5. 関連付けられたドメイン・グループ・コンパートメントを選択し、このドメインに関連付けるドメイン・グループを選択します。
    6. 「作成」を選択します。
    7. IoTドメインのデバイス・ホストのエンドポイントを表示およびコピーすると、デバイス・ホストにドメインの短縮IDが表示されます。次のステップで使用するこのエンドポイントをコピーするには、「コピー」を選択します。

      device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com

      オプションの完全なリストについては、Creating an IoT Domainを参照してください。

    1. IoTドメインを作成するには、oci iot domain createコマンドと必要なパラメータを使用します。
    2. <iot-domain-group-OCID>を、IoTドメインに関連付けるIoTドメイン・グループに置き換えます。<compartment-OCID>をIoTドメインのコンパートメントOCIDに置き換えます: 
      oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <iot-domain-group-OCID>
      CLIコマンドのパラメータおよび値の完全なリストは、CLIコマンド・リファレンスを参照してください。
  • CreateIotDomain操作を実行して、IoTドメインを作成します。

ステップ3: デジタル・ツイン・インスタンスの作成

この例では、デジタル・ツイン・インスタンスはデジタル・ツイン・モデルまたはデジタル・ツイン・アダプタに関連付けられていません。この方法は、デジタル・ツイン設定をテストする場合、または非構造化データを送信するデバイスに接続するようにデジタル・ツイン・インスタンスを設定する場合に使用できます。オプションの完全なリストは、デジタル・ツイン・インスタンスの作成を参照してください。

  • 外部キー・オプション: 外部キーは、ステップ5でデータを送信するためにデバイスに接続するときのデバイス・ユーザー名です。--external-keyパラメータを含めない場合、外部キーがレスポンスで生成されます。外部キーを指定する場合は、外部キー値とともに引用符を使用しないことをお薦めします。
  • 認証オプション: デジタル・ツイン・インスタンスを作成する場合、認証はオプションであり、デバイスとの間でデータを送信する場合にのみ必要です。--auth-idパラメータを使用して、デジタル・ツイン・インスタンスに認証を追加します。
次の例では、secretを使用して認証します。シークレットはテスト環境に使用できます。セキュアな本番環境の場合、デジタル・ツイン・インスタンスは認証用のmTLS証明書を使用する必要があります。
    1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを選択します。IoTドメイン・リスト・ページの検索に関するヘルプが必要な場合は、IoTドメインのリストを参照してください。
    2. 「デジタル・ツイン・インスタンス」タブを選択し、「作成」を選択します。
    3. 「名前」を入力し、オプションで「説明」を入力します。機密情報は入力しないでください。
    4. オプション。 一意の識別子である外部キーを入力します。外部キーを指定しない場合、このデジタル・ツイン・インスタンスの保存時に生成されます。デバイスへの接続時またはデバイスへのデータの送信時に、外部キーをデバイスのユーザー名として使用します。
    5. タイプを選択します。
      • 直接接続: デバイスまたはエンティティをIoTドメインに直接接続します。デバイスまたはエンティティが構造化データを送信する場合は、アダプタを選択します。アダプタを選択すると、このデジタル・ツイン・インスタンスが変換レイヤーに関連付けられ、インバウンド・デバイス・ペイロードが、インスタンスで想定される関連するデジタル・ツイン・モデルのDTDL構造に変換されます。
      • 未接続: このオプションを使用して、データ取込みなしでシミュレーション専用のデジタル・ツイン・インスタンスを作成します。デジタル・ツイン・モデルは必須であり、テレメトリまたはプロパティを含めることはできません。このデジタル・ツイン・インスタンスを作成した後、デジタル・ツイン・リレーションシップを追加して、データの取込みや認証を複雑にすることなくIoT環境をシミュレートできます。
      • 認証ID: デバイスまたはエンティティがデータを送受信する場合は、認証IDを指定する必要があります。テスト用にボールト・シークレットを作成し、本番用にデジタル・ツイン・インスタンスの認証IDのmTLS証明書を作成します。
        • 認証IDの選択: シークレットまたは証明書オプションを選択します。シークレットの場合は、ボールト・コンパートメント、ボールトおよびシークレットを選択します。証明書の場合は、証明書コンパートメントを選択し、証明書を選択します。
        • 認証OCIDの貼付け: 証明書またはシークレットのOCIDを貼り付けます。
      • タグ: (オプション)デジタル・ツイン・アダプタに1つ以上のタグを追加します。リソースを作成する権限がある場合、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済タグを適用するには、タグ・ネームスペースを使用する権限が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかわからない場合は、このオプションをスキップするか、管理者に問い合せてください。後でタグを適用できます。
    6. 「作成」を選択します。
    1. デジタル・ツイン・インスタンスを作成するには、oci iot digital-twin-instance createコマンドとこれらのパラメータを使用します。
    2. <iot-domain-OCID>を、このIoTデジタル・ツイン・インスタンスに関連付けるIoTドメインに置き換えます。<secret-or-certificate-OCID>をボールト・シークレットOCIDに置き換えます:
      oci iot digital-twin-instance create --auth-id <secret-OCID> --iot-domain-id <iot-domain-OCID>
    パラメータおよび値の完全なリストは、IoT CLIコマンド・リファレンスおよびCLIコマンド・リファレンスを参照してください。
  • CreateDigitalTwinInstance操作を実行して、デジタル・ツイン・インスタンスを作成します。

ステップ4: IoTドメインの詳細の取得

使用するIoTドメインのデバイス・ホスト・エンドポイントがある場合は、このステップをスキップします。

IoTドメインの詳細には、ドメイン短縮IDを含むデバイス・ホストが含まれます。詳細は、IoTドメインの詳細の取得を参照してください。

    1. IoT「ドメイン」リスト・ページで、操作するドメインを選択します。IoTドメインのリスト・ページまたはIoTドメインの検索に関するヘルプが必要な場合は、「IoTドメインのリスト」を参照してください。
    2. 詳細: ドメインおよび説明の名前を表示または編集し、OCID、デバイス・ホスト・エンドポイントをコピーして、コンパートメントおよびドメイン作成のタイムスタンプを表示します。
      device-host: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com
    3. リンクまたはタブを選択して、ドメインに関連付けられている様々なリソースおよびタスクにアクセスします。ドメイン設定の詳細は、「IoTドメインの作成」を参照してください

  • oci iot domain getコマンドと必要なパラメータを使用して、IoTドメインの詳細(ドメイン短縮IDを持つデバイス・ホストを含む)を取得します:

    oci iot domain get --iot-domain-id <iot-domain-OCID>

    CLIコマンドのパラメータおよび値の完全なリストは、CLIコマンド・リファレンスを参照してください。

  • GetIotDomain操作を実行して、ドメインの詳細を取得します。

ステップ5: データの送信

前の「ステップ3: デジタル・ツイン・インスタンスの作成」で作成したデジタル・ツイン・インスタンスにサンプル・データを送信します。
  • デバイス・ユーザー名: デジタル・ツイン・インスタンスのexternal keyをデバイス・ユーザー名として使用します。
  • デバイス・パスワード: デジタル・ツイン・インスタンスの認証IDに関連付けられます。デジタル・ツイン・インスタンスが認証にボールト・シークレットOCIDを使用する場合は、プレーン・テキスト・シークレット・コンテンツをデバイス・パスワードとして使用します。シークレットの作成およびシークレットのコンテンツの取得を参照してください。ボールト・シークレットをデバイス・パスワードとして使用することは、テストでのみ推奨され、本番では推奨されません。
次の例では、シークレットを使用して認証します。または、本番では、デジタル・ツイン・インスタンスで認証用のmTLS証明書を使用する必要があります。

  • Curlの使用

    POSIXスタイルのシェル: Windowsでbash、zsh、macOS Terminal、LinuxまたはGit Bashを使用する場合は、このcurlコマンドを使用します。 
    curl 
  -u '<digital-twin-instance-external-key>:<device-password>' \
  -H 'Content-Type: text/plain' \
  -d 'sample data 1' \
  'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'

    Windows Powershell: この例では、このcurlコマンドを使用して、-Gを使用してGETリクエストを作成し、--data-urlencodeで指定されたデータを問合せパラメータとしてURLに追加します。または、環境変数を使用できます。 

    curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"

    「ステップ3: デジタル・ツイン・インスタンスの作成」を完了したときに、外部キー・パラメータ値を引用符付きで定義した場合は、データの送信時に引用符を含める必要があります: "external-key"。見積りのベストプラクティスについては、Troubleshootingを参照してください。

  • MQTTクライアントを使用します。この例では、次の設定でMQTTXを使用します。
    1. MQTTXをダウンロードして設定するには、次の手順に従います。MQTTXスタート・ガイドを参照してください。MQTTXを開きます。
    2. 新しい接続を作成するには「+新規接続」を選択します。
    3. 「外部キー」の<unique-id>値を「ユーザー名」として入力します。外部キーは、前の「ステップ3: デジタル・ツイン・インスタンスの作成」のoci iot digital-twin-instance createレスポンスにあります。
      "external-key": "<unique-id>"
    4. デバイスのパスワードを入力します。テストでボールト・シークレットを使用する場合、これはプレーン・テキストのシークレット・コンテンツである必要があります。または、セキュアな本番環境の場合は、mTLS証明書を使用します。
    5. ホストを入力します。ホスト・ドロップダウン・リストからmqtts://プロトコルを選択し、IoTドメインのデバイス・ホスト<domain-short-id>.device.iot.<region>.oci.oraclecloud.comを入力します。
    6. ポート(たとえば、8883)を入力します。
      ノート

      現在、MQTT Secure (MQTTS)はポート8883を使用してのみサポートされています。
    7. トグルのSSL/TLSをオンにします。
    8. 「SSLセキュア」トグルをオンにします。
    9. 「証明書」で、「CA署名サーバー証明書」オプションを選択します。
    10. MQTTX接続を構成する場合は、clean sessionを使用して接続し、Last-Will-Retainオプションをfalseに設定して、デバイスが短時間切断された場合にクライアント・サブスクリプションを保持できるようにしてください。
    11. Last Will QoSを 1に設定します。
    12. 「接続」を選択します。

    これらのステップが終了すると、IoTプラットフォームにデバイスからデータを受信できるデジタル・ツイン・インスタンスがあります。

次に行うこと