Construir conectores Akri em VS Code

Neste exemplo, cria um conector HTTP/REST usando a linguagem C#, constrói uma imagem docker e depois executa a aplicação conector usando a extensão VS Code:

1. Pressione Ctrl+Shift+P para abrir a paleta de comandos e procure por Azure IoT Operations Akri Connectors: Criar um novo comando Akri Connector . Crie uma nova pasta chamada my-connectors e selecione-a, selecione C# como linguagem, introduza um nome para o conector como rest_connector, e selecione PollingTelemetryConnector como tipo de conector.

2. A extensão cria um novo espaço de trabalho nomeado usando o nome do conector que escolheu na etapa anterior. O espaço de trabalho inclui a estrutura para um conector de telemetria de sondagem escrito na linguagem C#.

Os passos seguintes assumem que criou um projeto .NET chamado MyConnector.

Para representar o estado do termóstato, crie um ficheiro chamado ThermostatStatus.cs na MyConnector pasta do espaço de trabalho com o seguinte conteúdo. Este ficheiro modela a resposta JSON a partir do endpoint 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 pontos de dados, crie um ficheiro chamado DataPointConfiguration.cs na MyConnector pasta do espaço de trabalho com o seguinte conteúdo. Este ficheiro modela uma configuração para um ponto de dados que o utilizador especifica na interface de experiência operacional:

using System.Text.Json.Serialization;

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

Implementa o método SampleDatasetAsync na classe fornecida DatasetSampler. O método toma a Dataset como parâmetro. A Dataset contém os pontos de dados para o conector processar.

1. Abre o ficheiro MyConnector/DatasetSampler.cs no teu espaço de trabalho VS Code.

2. Para passar os dados necessários para processar os dados do endpoint, adiciona-se um construtor à DatasetSampler classe . A classe usa o HttpClient e EndpointProfileCredentials para se conectar e autenticar no endpoint 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. Modificar o GetSamplingIntervalAsync método para devolver 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 utiliza um intervalo de amostragem fixo. Num conector de produção, pode tornar o intervalo de amostragem configurável usando os metadados do conector para definir uma propriedade de intervalo de amostragem que o utilizador pode definir na interface de experiência operacional.

4. Substitua o método existente SampleDatasetAsync pelo seguinte esboço:

   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 do método SampleDatasetAsync, adicione o seguinte código para obter cada DataPoint do DataSet e extrair os caminhos da fonte de dados. Estes caminhos fazem parte dos URLs usados para obter os dados do endpoint REST. Os currentTemperature pontos de dados e desiredTemperature foram modelados anteriormente na ThermostatStatus classe. O método de pedido 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 só mostra como recuperar o método HTTP a usar a partir da configuração do ponto de dados. A amostra não usa este valor quando faz o pedido HTTP.

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

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

   Este código extrai as credenciais e adiciona-as ao cabeçalho de autorização. DatasetSampler implementa a autenticação básica com credenciais de nome de utilizador e palavra-passe.

7. Depois, adicione código para fazer um pedido HTTP ao endpoint, desserialize a resposta, extraia as propriedades CurrentTemperature e DesiredTemperature e coloque-as num 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. De seguida, serializa o estado para JSON e devolve a resposta ao endpoint. Neste exemplo, a carga útil de resposta HTTP já corresponde ao esquema esperado da mensagem, pelo que não é necessária nenhuma tradução:

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

   Sugestão

   Opcionalmente, o conector pode registar um esquema no registo de esquemas para permitir que outras Operações Azure IoT compreendam o formato das mensagens.

9. Finalmente, importa 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.

Implementa o método CreateDatasetSampler na classe DatasetSamplerProvider. Esta classe cria DataSetSampler objetos para injetar na aplicação conforme necessário.

1. Abre o MyConnector/DatasetSamplerProvider.cs ficheiro no teu espaço de trabalho VS Code.

2. No CreateDatasetSampler método, devolve a DatasetSampler juntamente 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 assume que o nome do conjunto de dados é sempre thermostat_status. Num conector de produção, pode implementar lógica adicional para lidar com múltiplos conjuntos de dados.

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

De seguida, constrói o projeto para confirmar que não há erros. Use o comando VS Code Azure IoT Operations Akri Connectors: Criar um Akri Connector e escolha o modo Release. Este comando mostra o progresso da build na consola OUTPUT e notifica-te quando a build termina. Pode então ver uma nova imagem Docker com etiqueta <connector_name>release localmente no Docker Desktop.

Neste exemplo, cria um conector HTTP/REST usando a linguagem Rust, constrói uma imagem Docker e depois executa a aplicação do conector usando a extensão VS Code:

1. Pressione Ctrl+Shift+P para abrir a paleta de comandos e procure o comando Azure IoT Operations Akri Connectors: Criar um Novo Conector Akri. Cria uma nova pasta chamada my-connectors e seleciona-a, seleciona Rust como língua e insere um nome para o conector como rest_connector.

2. A extensão cria um novo espaço de trabalho nomeado usando o nome do conector que escolheu na etapa anterior. O espaço de trabalho inclui o andaime para um conector escrito na linguagem Rust. Há Implement etiquetas nos comentários para te ajudar a escrever o teu próprio conector Akri personalizado. Para efeitos de teste, pode experimentar o conector apenas com o código do andaime. Para ver os registos da caixa do seu conector, substitua a etiqueta sample_connector_scaffolding pelo nome do seu conector na DEFAULT_LOG_LEVEL variável no main.rs ficheiro.

De seguida, constrói o projeto para confirmar que não há erros. Use o comando VS Code Azure IoT Operations Akri Connectors: Criar um Akri Connector e escolha o modo Release. Este comando mostra o progresso da build na consola OUTPUT e notifica-te quando a build termina. Pode então ver uma nova imagem Docker com etiqueta <connector_name>release localmente no Docker Desktop.

Para depurar um conector Akri baseado em .NET, certifique-se de que tem a extensão C# VS Code instalada. Usa o mesmo conector REST que criaste anteriormente:

1. Para construir o conector em modo Debug , use o comando VS Code Azure IoT Operations Akri Connectors: Build an Akri Connector e selecione o modo Debug . Este comando cria uma imagem Docker local chamada <connector_name> com a tag debug. Pode ver a imagem no Docker Desktop.

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

3. Para depurar o conector, vá ao painel Executar e Depurar no espaço de trabalho do VS Code e selecione a configuração Depurar Conector Akri. Esta configuração lança um terminal que executa as tarefas de pré-lançamento para iniciar o aio-broker contentor e o conector REST que desenvolveu noutro contentor chamado <connector_name>_debug. Este processo demora vários minutos. Pode ver o fluxo de dados de telemetria do servidor REST para o broker MQ através do conector REST na janela do terminal no VS Code. Os registos dos contentores também são visíveis no Docker Desktop.

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

Para depurar um conector Akri baseado em Rust, certifique-se de que tem a extensão C/C++ do VS Code instalada. Usa o mesmo conector REST que criaste anteriormente:

1. Para construir o conector em modo Debug , use o comando VS Code Azure IoT Operations Akri Connectors: Build an Akri Connector e selecione o modo Debug . Este comando cria uma imagem Docker local chamada <connector_name> com a tag debug. Pode ver a imagem no Docker Desktop.

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

3. Para depurar o conector, vá ao painel Executar e Depurar no espaço de trabalho do VS Code e selecione a configuração Depurar Conector Akri. Esta configuração lança um terminal que executa as tarefas de pré-lançamento para iniciar o aio-broker contentor e o conector REST que desenvolveu noutro contentor chamado <connector_name>_debug. Este processo demora vários minutos. Pode ver o fluxo de dados de telemetria do servidor REST para o broker MQ através do conector REST na janela do terminal no VS Code. Os registos dos contentores também são visíveis no Docker Desktop.

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