Créer des connecteurs Akri dans VS Code

Dans cet exemple, vous créez un connecteur HTTP/REST à l’aide du langage C#, générez une image Docker, puis exécutez l’application de connecteur à l’aide de l’extension VS Code :

1. Appuyez Ctrl+Shift+P pour ouvrir la palette de commandes et rechercher la commande Azure IoT Operations Akri Connectors: Create a New Akri Connector. Créez un dossier appelé my-connectors et sélectionnez-le, sélectionnez C# comme langue, entrez un nom pour le connecteur tel rest_connectorque , puis sélectionnez PollingTelemetryConnector comme type de connecteur.

2. L’extension crée un espace de travail nommé à l’aide du nom du connecteur que vous avez choisi à l’étape précédente. L’espace de travail inclut la structure d’un connecteur de télémétrie de sondage écrit dans le langage C#.

Les étapes suivantes supposent que vous avez créé un projet .NET appelé MyConnector.

Pour représenter l’état du thermostat, créez un fichier appelé ThermostatStatus.cs dans le dossier de l’espace MyConnector de travail avec le contenu suivant. Ce fichier modélise la réponse JSON à partir du point de terminaison REST :

using System.Text.Json.Serialization;

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

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

Pour ajouter un paramètre de configuration de point de données, créez un fichier appelé DataPointConfiguration.cs dans le dossier de l’espace MyConnector de travail avec le contenu suivant. Ce fichier modélise un paramètre de configuration pour un point de données que l’utilisateur spécifie dans l’interface utilisateur de l’expérience des opérations :

using System.Text.Json.Serialization;

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

Implémentez la SampleDatasetAsync méthode dans la classe fournie DatasetSampler . La méthode prend un Dataset paramètre. Un Dataset contient les points de données du connecteur à traiter.

1. Ouvrez le fichier MyConnector/DatasetSampler.cs dans votre espace de travail VS Code.

2. Pour transmettre les données requises pour le traitement des données de point de terminaison, ajoutez un constructeur à la DatasetSampler classe. La classe utilise les HttpClient et EndpointProfileCredentials pour se connecter et s’authentifier avec le point de terminaison de ressource :

   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. Modifiez la GetSamplingIntervalAsync méthode pour retourner un intervalle d’échantillonnage de trois secondes :

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

   Note

   Par souci de simplicité, cet exemple utilise un intervalle d’échantillonnage fixe. Dans un connecteur de production, vous pouvez configurer l’intervalle d’échantillonnage à l’aide des métadonnées du connecteur pour définir une propriété d’intervalle d’échantillonnage qu’un utilisateur peut définir dans l’interface utilisateur de l’expérience des opérations.

4. Remplacez la méthode existante SampleDatasetAsync par le plan suivant :

   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. Dans le bloc try de la méthode SampleDatasetAsync, ajoutez le code suivant pour récupérer chaque DataPoint du DataSet et extraire les chemins de la source de données. Ces chemins font partie des URL utilisées pour extraire les données du point de terminaison REST. Les points de données currentTemperature et desiredTemperature ont été modélisés précédemment dans la classe ThermostatStatus. La méthode de requête HTTP est extraite de la configuration du point de données modélisée dans la DataPointConfiguration classe :

   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!;
   

   Note

   Par souci de simplicité, cet exemple montre uniquement comment récupérer la méthode HTTP à utiliser à partir de la configuration du point de données. L’exemple n’utilise pas cette valeur lorsqu’il effectue la requête HTTP.

6. Dans la même méthode, configurez l’authentification à l’aide des informations d’identification fournies si les points de terminaison authentifiés sont en cours d’utilisation :

   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));
   }
   

   Ce code extrait les informations d’identification et les ajoute à l’en-tête d’autorisation. L’authentification DatasetSampler de base est implémentée avec les informations d’identification de nom d’utilisateur et de mot de passe.

7. Ensuite, ajoutez du code pour effectuer une requête HTTP au point de terminaison, désérialiser la réponse, et extraire les propriétés CurrentTemperature et DesiredTemperature, puis les placer dans un objet 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. Ensuite, sérialisez l’état au format JSON et retournez la réponse au point de terminaison. Dans cet exemple, la charge utile de réponse HTTP correspond déjà au schéma de message attendu. Par conséquent, aucune traduction n’est nécessaire :

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

   Conseil / Astuce

   Si vous le souhaitez, le connecteur peut inscrire un schéma dans le registre de schémas pour permettre à d’autres opérations Azure IoT de comprendre le format des messages.

9. Enfin, importez les types nécessaires :

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

La version finale du code ressemble à DatasetSampler.

Implémentez la CreateDatasetSampler méthode dans la DatasetSamplerProvider classe. Cette classe crée des DataSetSampler objets à injecter dans l’application en fonction des besoins.

1. Ouvrez le MyConnector/DatasetSamplerProvider.cs fichier dans votre espace de travail VS Code.

2. Dans la méthode CreateDatasetSampler, retournez un DatasetSampler avec le endpointCredentials si le nom du jeu de données est 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}");
   

   Note

   Par souci de simplicité, cet exemple suppose que le nom du jeu de données est toujours thermostat_status. Dans un connecteur de production, vous pouvez implémenter une logique supplémentaire pour gérer plusieurs jeux de données.

La version finale du code ressemble à DatasetSamplerProvider.

Ensuite, générez le projet pour confirmer qu’il n’y a aucune erreur. Utilisez la commande VS Code Azure IoT Operations Akri Connectors : générez un connecteur Akri et choisissez le mode Mise en production . Cette commande affiche la progression de la compilation dans la console OUTPUT et vous avertit une fois la compilation terminée. Vous pouvez ensuite voir une nouvelle image Docker nommée <connector_name> avec une balise release localement dans Docker Desktop.

Dans cet exemple, vous créez un connecteur HTTP/REST à l’aide du langage Rust, générez une image Docker, puis exécutez l’application de connecteur à l’aide de l’extension VS Code :

1. Appuyez pour ouvrir la palette de commandes et rechercher la commande « Créer un nouveau connecteur Akri d'Azure IoT Operations » . Créez un dossier appelé my-connectors et sélectionnez-le, sélectionnez Rust comme langue, puis entrez un nom pour le connecteur comme rest_connector.

2. L’extension crée un espace de travail nommé à l’aide du nom du connecteur que vous avez choisi à l’étape précédente. L’espace de travail inclut l’échafaudage pour un connecteur écrit dans le langage Rust. Il y a des balises Implement dans les commentaires pour vous aider à rédiger votre connecteur personnalisé Akri. À des fins de test, vous pouvez essayer le connecteur avec uniquement le code de structure. Pour afficher les journaux d’activité de votre crate de connecteur, remplacez la balise sample_connector_scaffolding par le nom de votre connecteur dans la variable DEFAULT_LOG_LEVEL dans le fichier main.rs.

Ensuite, générez le projet pour confirmer qu’il n’y a aucune erreur. Utilisez la commande VS Code Azure IoT Operations Akri Connectors : générez un connecteur Akri et choisissez le mode Mise en production . Cette commande affiche la progression de la compilation dans la console OUTPUT et vous avertit une fois la compilation terminée. Vous pouvez ensuite voir une nouvelle image Docker nommée <connector_name> avec une balise release localement dans Docker Desktop.

Pour déboguer un connecteur Akri basé sur .NET, vérifiez que l’extension VS Code C# est installée. Utilisez le même connecteur REST que vous avez créé précédemment :

1. Pour générer le connecteur en mode Débogage , utilisez la commande VS Code Azure IoT Operations Akri Connectors : générez un connecteur Akri et sélectionnez Mode débogage . Cette commande crée une image Docker locale appelée <connector_name> avec la balise debug. Vous pouvez voir l’image dans Docker Desktop.

2. Vous pouvez ajouter un point d’arrêt et l’exécution s’arrête lorsque le point d’arrêt est atteint. Essayez d’ajouter un point d’arrêt au début de la SampleDatasetAsync méthode dans DatasetSampler.cs.

3. Pour déboguer le connecteur, accédez au panneau Exécuter et Déboguer dans l’espace de travail VS Code, puis sélectionnez la configuration du connecteur Akri. Cette configuration lance un terminal qui exécute les tâches de prélancement pour démarrer le aio-broker conteneur et le connecteur REST que vous avez développé dans un autre conteneur appelé <connector_name>_debug. Cette opération prend plusieurs minutes. Vous pouvez voir le flux de données de télémétrie du serveur REST vers le répartiteur MQ via le connecteur REST dans la fenêtre de terminal dans VS Code. Les journaux de conteneur sont également visibles dans Docker Desktop.

4. Utilisez le bouton Déconnecter dans le panneau de commandes de débogage pour mettre fin à l’exécution.

Pour déboguer un connecteur Akri basé sur Rust, vérifiez que l’extension VS Code C/C++ est installée. Utilisez le même connecteur REST que vous avez créé précédemment :

1. Pour générer le connecteur en mode Débogage , utilisez la commande VS Code Azure IoT Operations Akri Connectors : générez un connecteur Akri et sélectionnez Mode débogage . Cette commande crée une image Docker locale appelée <connector_name> avec la balise debug. Vous pouvez voir l’image dans Docker Desktop.

2. Ajoutez un point d’arrêt. L’exécution s’arrête lorsque le point d’arrêt est atteint. Essayez d’ajouter un point d’arrêt dans la report_status_one_way macro dans main.rs.

3. Pour déboguer le connecteur, accédez au panneau Exécuter et Déboguer dans l’espace de travail VS Code, puis sélectionnez la configuration du connecteur Akri. Cette configuration lance un terminal qui exécute les tâches de prélancement pour démarrer le aio-broker conteneur et le connecteur REST que vous avez développé dans un autre conteneur appelé <connector_name>_debug. Cette opération prend plusieurs minutes. Vous pouvez voir le flux de données de télémétrie du serveur REST vers le répartiteur MQ via le connecteur REST dans la fenêtre de terminal dans VS Code. Les journaux de conteneur sont également visibles dans Docker Desktop.

4. Utilisez le bouton Déconnecter dans le panneau de commandes de débogage pour mettre fin à l’exécution.