Criar conectores Akri no VS Code

Neste exemplo, você cria um conector HTTP/REST usando a linguagem C#, cria uma imagem do docker e, em seguida, executa o aplicativo conector usando a extensão VS Code:

1. Pressione Ctrl+Shift+P para abrir a paleta de comandos e pesquisar pelo comando Azure IoT Operations Akri Connectors: Criar um Novo Conector Akri. Crie uma nova pasta chamada my-connectors e selecione-a, selecione C# como o idioma, insira um nome para o conector como rest_connectore selecione PollingTelemetryConnector como o tipo de conector.

2. A extensão cria um novo workspace nomeado usando o nome do conector escolhido na etapa anterior. O espaço de trabalho inclui a estrutura básica para um conector de telemetria de polling escrito na linguagem C#.

As etapas a seguir pressupõem que você criou um projeto .NET chamado MyConnector.

Para representar o status do termostato, crie um arquivo chamado ThermostatStatus.cs na MyConnector pasta no workspace com o conteúdo a seguir. Este arquivo modela a resposta JSON do ponto de extremidade 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; }
    }
}    

Para adicionar uma configuração de ponto de dados, crie um arquivo chamado DataPointConfiguration.cs na MyConnector pasta no workspace com o conteúdo a seguir. Esse arquivo representa uma configuração para um ponto de dados especificado pelo usuário na interface de operações:

using System.Text.Json.Serialization;

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

Implemente o SampleDatasetAsync método na classe fornecida DatasetSampler . O método usa um Dataset parâmetro como um parâmetro. Um Dataset contém os pontos de dados para o conector processar.

1. Abra o arquivo MyConnector/DatasetSampler.cs no workspace do VS Code.

2. Para passar os dados necessários para processar os dados do ponto de extremidade, adicione um construtor na classe DatasetSampler. A classe usa o HttpClient e o EndpointProfileCredentials para se conectar e autenticar no ponto de extremidade do ativo:

   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. Modifique o GetSamplingIntervalAsync método para retornar um intervalo de amostragem de três segundos:

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

   Observação

   Para simplificar, este exemplo usa um intervalo de amostragem fixo. Em um conector de produção, você pode tornar o intervalo de amostragem configurável usando os metadados do conector para definir uma propriedade de intervalo de amostragem que um usuário pode definir na interface do usuário da experiência de operações.

4. Substitua o método SampleDatasetAsync existente pela estrutura de tópicos a seguir:

   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. No bloco try no método SampleDatasetAsync, adicione o código a seguir para recuperar cada DataPoint do DataSet e extrair os caminhos das fontes de dados. Esses caminhos fazem parte das URLs usadas para buscar os dados do endpoint REST. Os currentTemperature pontos de dados e desiredTemperature foram modelados anteriormente na ThermostatStatus classe. O método de solicitação HTTP é extraído da configuração do ponto de dados modelada na 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!;
   

   Observação

   Para simplificar, este exemplo mostra apenas como recuperar o método HTTP a ser usado na configuração do ponto de dados. O exemplo não usa esse valor quando faz a solicitação HTTP.

6. No mesmo método, configure a autenticação usando as credenciais fornecidas se os pontos de extremidade autenticados estiverem em uso:

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

   Esse código extrai as credenciais e as adiciona ao cabeçalho de autorização. O DatasetSampler implementa a autenticação básica com credenciais de nome de usuário e senha.

7. Em seguida, adicione o código para fazer uma solicitação HTTP ao endpoint, desserialize a resposta e extraia as propriedades CurrentTemperature e DesiredTemperature, colocando-as em um objeto 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. Em seguida, serialize o status para JSON e retorne a resposta ao endpoint. Neste exemplo, o conteúdo da resposta HTTP já corresponde ao esquema de mensagem esperado, portanto, nenhuma tradução é necessária:

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

   Dica

   Opcionalmente, o conector pode registrar um esquema no registro de esquema para permitir que outras Operações de IoT do Azure entendam o formato das mensagens.

9. Por fim, importe os tipos necessários:

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

A versão final do código é semelhante ao DatasetSampler.

Implemente o CreateDatasetSampler método na DatasetSamplerProvider classe. Essa classe cria DataSetSampler objetos para injetar no aplicativo conforme necessário.

1. Abra o MyConnector/DatasetSamplerProvider.cs arquivo no workspace do VS Code.

2. No método CreateDatasetSampler, retorne um DatasetSampler junto com o endpointCredentials, se o nome do conjunto de dados for 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}");
   

   Observação

   Para simplificar, este exemplo pressupõe que o nome do conjunto de dados é sempre thermostat_status. Em um conector de produção, você pode implementar lógica adicional para lidar com vários conjuntos de dados.

A versão final do código é semelhante a DatasetSamplerProvider.

Em seguida, compile o projeto para confirmar que não há erros. Use o comando do VS Code Azure IoT Operations Akri Connectors: Construir um Conector Akri e escolha o modo Release. Este comando mostra o progresso do build no console OUTPUT e notifica você quando o build é concluído. Em seguida, você pode ver uma nova imagem do Docker nomeada <connector_name> com marca release localmente no Docker Desktop.

Neste exemplo, você cria um conector HTTP/REST usando a linguagem Rust, cria uma imagem do Docker e, em seguida, executa o aplicativo conector usando a extensão VS Code:

1. Pressione Ctrl+Shift+P para abrir a paleta de comandos e procurar pelo comando Azure IoT Operations Akri Connectors: Create a New Akri Connector. Crie uma nova pasta chamada my-connectors e selecione-a, selecione Rust como o idioma e insira um nome para o conector como rest_connector.

2. A extensão cria um novo workspace nomeado usando o nome do conector escolhido na etapa anterior. O espaço de trabalho inclui a estrutura básica para um conector escrito na linguagem Rust. Há Implement tags nos comentários para ajudá-lo a escrever seu próprio conector Akri personalizado. Para fins de teste, você pode experimentar o conector apenas com o código de estrutura básica. Para ver os logs do pacote do conector, substitua a marcação sample_connector_scaffolding pelo nome do seu conector na DEFAULT_LOG_LEVEL variável no arquivo main.rs.

Em seguida, compile o projeto para confirmar que não há erros. Use o comando do VS Code Azure IoT Operations Akri Connectors: Construir um Conector Akri e escolha o modo Release. Este comando mostra o progresso do build no console OUTPUT e notifica você quando o build é concluído. Em seguida, você pode ver uma nova imagem do Docker nomeada <connector_name> com marca release localmente no Docker Desktop.

Para depurar um conector Akri baseado em .NET, certifique-se de ter a extensão C# do VS Code instalada. Use o mesmo conector REST criado anteriormente:

1. Para criar o conector no modo Debug, use o comando VS Code Azure IoT Operations Akri Connectors: Criar um Conector Akri e selecione o modo Debug. Esse comando cria uma imagem local do Docker chamada <connector_name> com a marca debug. Você pode ver a imagem no Docker Desktop.

2. Você pode adicionar um ponto de interrupção e a execução é interrompida quando o ponto de interrupção é atingido. Tente adicionar um ponto de interrupção no início do SampleDatasetAsync método em DatasetSampler.cs.

3. Para depurar o conector, vá para o painel Executar e Depurar no espaço de trabalho do VS Code e selecione a configuração Depurar um Conector Akri. Essa configuração inicia um terminal que executa as tarefas de pré-lançamento para iniciar o aio-broker contêiner e o conector REST que você desenvolveu em outro contêiner chamado <connector_name>_debug. Esse processo leva vários minutos. Você pode ver o fluxo de dados de telemetria do servidor REST para o agente de MQ por meio do conector REST na janela do terminal no VS Code. Os logs de contêiner também são visíveis no Docker Desktop.

4. Use o botão Desconectar no painel de comandos de depuração para encerrar a execução.

Para depurar um conector Akri baseado em Rust, verifique se você tem a extensão do VS Code C/C++ instalada. Use o mesmo conector REST criado anteriormente:

1. Para criar o conector no modo Debug, use o comando VS Code Azure IoT Operations Akri Connectors: Criar um Conector Akri e selecione o modo Debug. Esse comando cria uma imagem local do Docker chamada <connector_name> com a marca debug. Você pode ver a imagem no Docker Desktop.

2. Adicione um ponto de interrupção. A execução é interrompida quando o ponto de interrupção é atingido. Tente adicionar um ponto de interrupção na report_status_one_way macro em main.rs.

3. Para depurar o conector, vá para o painel Executar e Depurar no espaço de trabalho do VS Code e selecione a configuração Depurar um Conector Akri. Essa configuração inicia um terminal que executa as tarefas de pré-lançamento para iniciar o aio-broker contêiner e o conector REST que você desenvolveu em outro contêiner chamado <connector_name>_debug. Esse processo leva vários minutos. Você pode ver o fluxo de dados de telemetria do servidor REST para o agente de MQ por meio do conector REST na janela do terminal no VS Code. Os logs de contêiner também são visíveis no Docker Desktop.

4. Use o botão Desconectar no painel de comandos de depuração para encerrar a execução.