VS Code で Akri コネクタを構築する

この例では、C# 言語を使用して HTTP/REST コネクタを作成し、Docker イメージをビルドしてから、VS Code 拡張機能を使用してコネクタ アプリケーションを実行します。

1. Ctrl+Shift+Pを押してコマンド パレットを開き、Azure IoT Operations Akri Connectors: Create a New Akri Connector コマンドを検索します。 my-connectorsという名前の新しいフォルダーを作成して選択し、言語として C# を選択し、rest_connectorなどのコネクタの名前を入力し、コネクタの種類として PollingTelemetryConnector を選択します。

2. 拡張機能は、前の手順で選択したコネクタ名を使用して、新しいワークスペースを作成します。 ワークスペースには、C# 言語で記述されたポーリング テレメトリ コネクタのスキャフォールディングが含まれています。

次の手順では、 MyConnector という名前の .NET プロジェクトを作成していることを前提としています。

サーモスタットの状態を表すには、ワークスペース内 フォルダーに ThermostatStatus.cs という名前のファイルを作成し、次の内容を含めます。 このファイルは、REST エンドポイントからの JSON 応答をモデル化します。

using System.Text.Json.Serialization;

namespace MyConnector
{
    internal class ThermostatStatus
    {
        [JsonPropertyName("desiredTemperature")]
        public double? DesiredTemperature { get; set; }

        [JsonPropertyName("currentTemperature")]
        public double? CurrentTemperature { get; set; }
    }
}    

データ ポイントの構成設定を追加するには、ワークスペースの フォルダーに MyConnector という名前のファイルを作成し、次の内容を含めます。 このファイルは、操作エクスペリエンス UI でユーザーが指定するデータ ポイントの構成設定をモデル化します。

using System.Text.Json.Serialization;

namespace MyConnector
{
    public class DataPointConfiguration
    {
        [JsonPropertyName("HttpRequestMethod")]
        public string? HttpRequestMethod { get; set; }
    }
} 

指定されたSampleDatasetAsync クラスにDatasetSampler メソッドを実装します。 このメソッドは、パラメーターとして Dataset を受け取ります。 Datasetには、コネクタが処理するデータ ポイントが含まれています。

1. VS Code ワークスペースでファイル MyConnector/DatasetSampler.cs を開きます。

2. エンドポイント データを処理するために必要なデータを渡すには、 DatasetSampler クラスにコンストラクターを追加します。 このクラスは、 HttpClient と EndpointProfileCredentials を使用して、資産エンドポイントに接続して認証します。

   private readonly HttpClient _httpClient;
   private readonly string _assetName;
   private readonly EndpointCredentials? _credentials;
   
   private readonly static JsonSerializerOptions _jsonSerializerOptions = new()
   {
       AllowTrailingCommas = true,
   };
   
   public DatasetSampler(HttpClient httpClient, string assetName, EndpointCredentials? credentials)
   {
       _httpClient = httpClient;
       _assetName = assetName;
       _credentials = credentials;
   }
   
   public ValueTask DisposeAsync()
   {
       _httpClient.Dispose();
       return ValueTask.CompletedTask;
   }
   

3. GetSamplingIntervalAsync メソッドを変更して、3 秒のサンプリング間隔を返します。

   public Task<TimeSpan> GetSamplingIntervalAsync(AssetDataset dataset, CancellationToken cancellationToken = default)
   {
       return Task.FromResult(TimeSpan.FromSeconds(3));
   }
   

   注

   わかりやすくするために、この例では固定サンプリング間隔を使用します。 運用コネクタでは、コネクタ メタデータを使用して、ユーザーが操作エクスペリエンス UI で設定できるサンプリング間隔プロパティを定義することで、サンプリング間隔を構成できます。

4. 既存の SampleDatasetAsync メソッドを次のアウトラインに置き換えます。

   public async Task<byte[]> SampleDatasetAsync(AssetDataset dataset, CancellationToken cancellationToken = default)
   {
       int retryCount = 0;
       while (true)
       {
           try
           {
               // TODO: Implement your dataset sampling logic here.
           }
           catch (Exception ex)
           {
               if (++retryCount >= 3)
               {
                   throw new InvalidOperationException($"Failed to sample dataset with name {dataset.Name} in asset with name {_assetName}. Error: {ex.Message}", ex);
               }
               await Task.Delay(1000, cancellationToken);
           }
       }
   }
   

5. try メソッドの SampleDatasetAsync ブロックで、次のコードを追加して、DataPointから各DataSetを取得し、データ ソース パスを抽出します。 これらのパスは、REST エンドポイントからデータをフェッチするために使用される URL の一部です。 currentTemperatureとdesiredTemperatureのデータ ポイントは、以前に ThermostatStatus クラスでモデル化されています。 HTTP 要求メソッドは、 DataPointConfiguration クラスでモデル化されたデータ ポイント構成から抽出されます。

   AssetDatasetDataPointSchemaElement httpServerDesiredTemperatureDataPoint = dataset.DataPoints!.Where(x => x.Name!.Equals("desiredTemperature"))!.First();
   HttpMethod httpServerDesiredTemperatureHttpMethod = HttpMethod.Parse(JsonSerializer.Deserialize<DataPointConfiguration>(httpServerDesiredTemperatureDataPoint.DataPointConfiguration!, _jsonSerializerOptions)!.HttpRequestMethod);
   string httpServerDesiredTemperatureRequestPath = httpServerDesiredTemperatureDataPoint.DataSource!;
   
   AssetDatasetDataPointSchemaElement httpServerCurrentTemperatureDataPoint = dataset.DataPoints!.Where(x => x.Name!.Equals("currentTemperature"))!.First();
   HttpMethod httpServerCurrentTemperatureHttpMethod = HttpMethod.Parse(JsonSerializer.Deserialize<DataPointConfiguration>(httpServerCurrentTemperatureDataPoint.DataPointConfiguration!, _jsonSerializerOptions)!.HttpRequestMethod);
   string httpServerCurrentTemperatureRequestPath = httpServerCurrentTemperatureDataPoint.DataSource!;
   

   注

   わかりやすくするために、この例では、データ ポイント構成から使用する HTTP メソッドを取得する方法のみを示します。 このサンプルでは、HTTP 要求を行うときにこの値は使用されません。

6. 同じ方法で、認証されたエンドポイントが使用されている場合は、指定された資格情報を使用して認証を設定します。

   if (_credentials != null && _credentials.Username != null && _credentials.Password != null)
   {
       // Note that this sample uses username + password for authenticating the connection to the asset. In general,
       // x509 authentication should be used instead (if available) as it is more secure.
       string httpServerUsername = _credentials.Username;
       string httpServerPassword = _credentials.Password;
       var byteArray = Encoding.ASCII.GetBytes($"{httpServerUsername}:{httpServerPassword}");
       _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));
   }
   

   このコードは、資格情報を抽出し、承認ヘッダーに追加します。 DatasetSamplerは、ユーザー名とパスワードの資格情報を使用して基本認証を実装します。

7. 次に、エンドポイントに HTTP 要求を行うコードを追加し、応答を逆シリアル化し、 CurrentTemperature プロパティと DesiredTemperature プロパティの両方を抽出して、 ThermostatStatus オブジェクトに配置します。

   var currentTemperatureHttpResponse = await _httpClient.GetAsync(httpServerCurrentTemperatureRequestPath);
   var desiredTemperatureHttpResponse = await _httpClient.GetAsync(httpServerDesiredTemperatureRequestPath);
   
   if (currentTemperatureHttpResponse.StatusCode == System.Net.HttpStatusCode.Unauthorized
       || desiredTemperatureHttpResponse.StatusCode == System.Net.HttpStatusCode.Unauthorized)
   {
       throw new Exception("Failed to authorize request to HTTP server. Check credentials configured in rest-server-device-definition.yaml.");
   }
   
   currentTemperatureHttpResponse.EnsureSuccessStatusCode();
   desiredTemperatureHttpResponse.EnsureSuccessStatusCode();
   
   ThermostatStatus thermostatStatus = new()
   {
       CurrentTemperature = (JsonSerializer.Deserialize<ThermostatStatus>(await currentTemperatureHttpResponse.Content.ReadAsStreamAsync(), _jsonSerializerOptions)!).CurrentTemperature,
       DesiredTemperature = (JsonSerializer.Deserialize<ThermostatStatus>(await desiredTemperatureHttpResponse.Content.ReadAsStreamAsync(), _jsonSerializerOptions)!).DesiredTemperature
   };
   

8. 次に、状態を JSON にシリアル化し、エンドポイントに応答を返します。 この例では、HTTP 応答ペイロードは予想されるメッセージ スキーマと既に一致しているため、変換は必要ありません。

   // The HTTP response payload matches the expected message schema, so return it as-is
   return Encoding.UTF8.GetBytes(JsonSerializer.Serialize(thermostatStatus));
   

   ヒント

   必要に応じて、コネクタはスキーマ レジストリにスキーマを登録して、他の Azure IoT 操作がメッセージの形式を理解できるようにします。

9. 最後に、必要な型をインポートします。

   using Azure.Iot.Operations.Connector.Files;
   using System.Net.Http.Headers;
   using System.Text;
   using System.Text.Json;
   

コードの最終バージョンは DatasetSampler のようになります。

CreateDatasetSampler クラスに DatasetSamplerProvider メソッドを実装します。 このクラスは DataSetSampler オブジェクトを作成し、必要に応じてアプリケーションに挿入します。

1. VS Code ワークスペースで MyConnector/DatasetSamplerProvider.cs ファイルを開きます。

2. CreateDatasetSampler メソッドで、データセット名がDatasetSamplerされている場合は、endpointCredentialsと共にthermostat_statusを返します。

   if (dataset.Name.Equals("thermostat_status"))
   {
       if (device.Endpoints != null
           && device.Endpoints.Inbound != null
           && device.Endpoints.Inbound.TryGetValue(inboundEndpointName, out var inboundEndpoint))
       {
           var httpClient = new HttpClient()
           {
               BaseAddress = new Uri(inboundEndpoint.Address),
           };
   
           return new DatasetSampler(httpClient, assetName, endpointCredentials);
       }
   }
   
   throw new InvalidOperationException($"Unrecognized dataset with name {dataset.Name} on asset with name {assetName}");
   

   注

   わかりやすくするために、この例では、データセット名が常に thermostat_statusされていることを前提としています。 運用コネクタでは、複数のデータセットを処理する追加のロジックを実装できます。

コードの最終バージョンは DatasetSamplerProvider のようになります。

次に、プロジェクトをビルドして、エラーがないことを確認します。 VS Code コマンド Azure IoT Operations Akri Connectors: Build an Akri Connector を 使用し、 リリース モードを選択します。 このコマンドは、ビルドの進行状況を 出力 コンソールに表示し、ビルドが完了したときに通知します。 その後、 <connector_name> という名前の新しい Docker イメージを Docker Desktop でローカルに release タグ付きで確認できます。

この例では、Rust 言語を使用して HTTP/REST コネクタを作成し、Docker イメージをビルドしてから、VS Code 拡張機能を使用してコネクタ アプリケーションを実行します。

1. Ctrl+Shift+Pキーを押してコマンド パレットを開き、Azure IoT Operations Akri Connectors: Create a New Akri Connector コマンドを検索します。 my-connectorsという名前の新しいフォルダーを作成して選択し、言語として Rust を選択し、コネクタの名前 (rest_connectorなど) を入力します。

2. 拡張機能は、前の手順で選択したコネクタ名を使用して、新しいワークスペースを作成します。 ワークスペースには、Rust 言語で記述されたコネクタのスキャフォールディングが含まれています。 コメントには、独自のカスタム Akri コネクタを記述するのに役立つ Implement タグがあります。 テスト目的で、スキャフォールディング コードだけでコネクタを試すことができます。 コネクタ クレートのログを表示するには、タグ sample_connector_scaffoldingを、DEFAULT_LOG_LEVEL ファイルの main.rs 変数のコネクタ名に置き換えます。

次に、プロジェクトをビルドして、エラーがないことを確認します。 VS Code コマンド Azure IoT Operations Akri Connectors: Build an Akri Connector を 使用し、 リリース モードを選択します。 このコマンドは、ビルドの進行状況を 出力 コンソールに表示し、ビルドが完了したときに通知します。 その後、 <connector_name> という名前の新しい Docker イメージを Docker Desktop でローカルに release タグ付きで確認できます。

.NET ベースの Akri コネクタをデバッグするには、 C# VS Code 拡張機能がインストールされていることを確認します。 前に作成したのと同じ REST コネクタを使用します。

1. デバッグ モードでコネクタをビルドするには、VS Code コマンド Azure IoT Operations Akri Connectors を使用します。Akri コネクタをビルドし、[デバッグ モード] を選択します。 このコマンドは、タグ <connector_name>を使用して debug というローカル Docker イメージを作成します。 Docker Desktop でイメージを確認できます。

2. ブレークポイントを追加すると、ブレークポイントにヒットすると実行が停止します。 SampleDatasetAsyncの DatasetSampler.cs メソッドの先頭にブレークポイントを追加してみてください。

3. コネクタをデバッグするには、VS Code ワークスペースの [実行とデバッグ ] パネルに移動し、[ Akri コネクタのデバッグ ] 構成を選択します。 この構成では、事前起動タスクを実行するターミナルが起動され、 aio-broker コンテナーと、 <connector_name>_debugという別のコンテナーで開発した REST コネクタが開始されます。 このプロセスには数分かかります。 VS Code のターミナル ウィンドウで REST コネクタを使用して、REST サーバーから MQ ブローカーへのテレメトリ データ フローを確認できます。 コンテナー ログは、Docker Desktop にも表示されます。

4. デバッグ コマンド パネルの [切断 ] ボタンを使用して、実行を終了します。

Rust ベースの Akri コネクタをデバッグするには、 C/C++ VS Code 拡張機能がインストールされていることを確認します。 前に作成したのと同じ REST コネクタを使用します。

1. デバッグ モードでコネクタをビルドするには、VS Code コマンド Azure IoT Operations Akri Connectors を使用します。Akri コネクタをビルドし、[デバッグ モード] を選択します。 このコマンドは、タグ <connector_name>を使用して debug というローカル Docker イメージを作成します。 Docker Desktop でイメージを確認できます。

2. ブレークポイントを追加します。 ブレークポイントにヒットすると、実行が停止します。 report_status_one_wayのmain.rs マクロにブレークポイントを追加してみてください。

3. コネクタをデバッグするには、VS Code ワークスペースの [実行とデバッグ ] パネルに移動し、[ Akri コネクタのデバッグ ] 構成を選択します。 この構成では、事前起動タスクを実行するターミナルが起動され、 aio-broker コンテナーと、 <connector_name>_debugという別のコンテナーで開発した REST コネクタが開始されます。 このプロセスには数分かかります。 VS Code のターミナル ウィンドウで REST コネクタを使用して、REST サーバーから MQ ブローカーへのテレメトリ データ フローを確認できます。 コンテナー ログは、Docker Desktop にも表示されます。

4. デバッグ コマンド パネルの [切断 ] ボタンを使用して、実行を終了します。