Criar um trabalho de streaming no T-SQL do SQL do Azure no Edge

Artigo
09/14/2023

Importante

O SQL do Azure no Edge encerrou o suporte à plataforma ARM64.

Este artigo explica como criar um trabalho de streaming no T-SQL do SQL do Azure no Edge. Você cria os objetos de entrada e saída de fluxo externo e, em seguida, define a consulta do trabalho de streaming como parte da criação do trabalho de streaming.

Configurar os objetos de entrada e saída de fluxo externo

O streaming no T-SQL usa a funcionalidade de fonte de dados externa do SQL Server para definir as fontes de dados associadas às entradas e saídas do fluxo externo do trabalho de streaming. Use os seguintes comandos T-SQL para criar um objeto de entrada ou saída de fluxo externo:

Além disso, se o Azure SQL Edge, o SQL Server ou o banco de dados SQL do Azure for usado como um fluxo de saída, você precisará da CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL). Esse comando T-SQL define as credenciais para acessar o banco de dados.

Fontes de dados de fluxo de entrada e saída com suporte

O SQL do Azure no Edge atualmente oferece suporte apenas às fontes de dados a seguir como entradas e saídas de fluxo.

Tipo de fonte de dados	Entrada	Saída	Descrição
Hub do Azure IoT Edge	N	S	Fonte de dados para ler e gravar dados de streaming em um hub do Azure IoT Edge. Para obter mais informações, confira Hub do IoT Edge.
Banco de Dados SQL	N	S	Conexão de fonte de dados para gravar dados de streaming no banco de dado SQL. O banco de dados pode ser um banco de dados local no SQL do Azure no Edge ou em um banco de dados remoto no SQL Server ou em um banco de dados SQL do Azure.
Kafka	N	N	Fonte de dados para ler dados de streaming de um tópico Kafka.

Exemplo: Criar um objeto de entrada/saída de fluxo externo para o hub do Azure IoT Edge

O exemplo a seguir cria um objeto de fluxo externo para o hub do Azure IoT Edge. Para criar uma fonte de dados de entrada/saída de fluxo externo para o hub do Azure IoT Edge, primeiro você precisa criar um formato de arquivo externo para o layout dos dados que estão sendo lidos ou gravados também.

Crie um formato de arquivo externo do tipo JSON.

CREATE EXTERNAL FILE format InputFileFormat
WITH (FORMAT_TYPE = JSON);
GO

Crie uma fonte de dados externa para o hub do Azure IoT Edge. O script de T-SQL a seguir cria uma conexão de fonte de dados a um hub de IoT Edge executado no mesmo host de Docker que o Azure SQL no Edge.
```
CREATE EXTERNAL DATA SOURCE EdgeHubInput
WITH (LOCATION = 'edgehub://');
GO
```
Crie o objeto de fluxo externo para hub do Azure IoT Edge. O script T-SQL a seguir cria um objeto de fluxo para o hub de IoT Edge. No caso de um objeto de fluxo do hub do Edge, o parâmetro LOCATION é o nome do tópico/canal do hub do Edge no qual está sendo feita a leitura ou gravação.
```
CREATE EXTERNAL STREAM MyTempSensors
WITH (
     DATA_SOURCE = EdgeHubInput,
     FILE_FORMAT = InputFileFormat,
     LOCATION = N'TemperatureSensors',
     INPUT_OPTIONS = N'',
     OUTPUT_OPTIONS = N''
);
GO
```

Exemplo: Criar um banco de dados SQL do Azure de objeto de fluxo externo

O exemplo a seguir cria um objeto de fluxo externo para o banco de dados SQL no Edge local.

Crie uma chave mestra no banco de dados. Isso é necessário para criptografar o segredo da credencial.
```
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<<Strong_Password_For_Master_Key_Encryption>>';
```
Crie uma credencial no escopo do banco de dados para acessar a fonte do SQL Server. O exemplo a seguir cria uma credencial para a fonte de dados externa com IDENTITY = nome de usuário e SECRET = senha.
```
CREATE DATABASE SCOPED CREDENTIAL SQLCredential
WITH IDENTITY = '<SQL_Login>', SECRET = '<SQL_Login_PASSWORD>';
GO
```
Crie uma fonte de dados externa, usando CREATE EXTERNAL DATA SOURCE. O exemplo a seguir:
- Cria uma fonte de dados externa chamada LocalSQLOutput.
- Identifica a fonte de dados externa (LOCATION = '<vendor>://<server>[:<port>]'). No exemplo, ele aponta para uma instância local do Azure SQL Edge.
- Usa a credencial criada anteriormente.
```
CREATE EXTERNAL DATA SOURCE LocalSQLOutput
WITH (
     LOCATION = 'sqlserver://tcp:.,1433',
     CREDENTIAL = SQLCredential
);
GO
```

Crie o objeto de fluxo externo. O exemplo a seguir cria um objeto de fluxo externo apontando para uma tabela dbo.TemperatureMeasurements no banco de dados MySQLDatabase.

CREATE EXTERNAL STREAM TemperatureMeasurements
WITH
(
    DATA_SOURCE = LocalSQLOutput,
    LOCATION = N'MySQLDatabase.dbo.TemperatureMeasurements',
    INPUT_OPTIONS = N'',
    OUTPUT_OPTIONS = N''
);

Exemplo: Criar um objeto de fluxo externo para Kafka

O exemplo a seguir cria um objeto de fluxo externo para o banco de dados SQL no Edge local. Este exemplo pressupõe que o servidor Kafka está configurado para acesso anônimo.

Crie uma fonte de dados externa, usando CREATE EXTERNAL DATA SOURCE. O exemplo a seguir:

CREATE EXTERNAL DATA SOURCE [KafkaInput]
WITH (LOCATION = N'kafka://<kafka_bootstrap_server_name_ip>:<port_number>');
GO

Crie um formato de arquivo externo para a entrada do Kafka. O exemplo a seguir criou um formato de arquivo JSON com compactação Gzipped.

CREATE EXTERNAL FILE FORMAT JsonGzipped
WITH (
     FORMAT_TYPE = JSON,
     DATA_COMPRESSION = 'org.apache.hadoop.io.compress.GzipCodec'
);
GO

Crie o objeto de fluxo externo. O exemplo a seguir cria um objeto de fluxo externo apontando para o tópico Kafka TemperatureMeasurement.

CREATE EXTERNAL STREAM TemperatureMeasurement
WITH
(
    DATA_SOURCE = KafkaInput,
    FILE_FORMAT = JsonGzipped,
    LOCATION = 'TemperatureMeasurement',
    INPUT_OPTIONS = 'PARTITIONS: 10'
);
GO

Criar o trabalho de streaming e as consultas de streaming

Use o procedimento armazenado do sistema para definir as consultas de streaming e criar o sys.sp_create_streaming_job trabalho de streaming. O procedimento armazenado sp_create_streaming_job requer os seguintes parâmetros:

@job_name: Nome do trabalho de streaming. Os nomes de trabalhos de streaming são exclusivos em toda a instância.
@statement: Instruções de consulta de streaming baseadas na linguagem de consulta do Stream Analytics.

O exemplo a seguir cria um trabalho de streaming simples com uma consulta de streaming. Essa consulta lê as entradas do hub do Edge e grava em dbo.TemperatureMeasurements no banco de dados.

EXEC sys.sp_create_streaming_job @name = N'StreamingJob1',
    @statement = N'Select * INTO TemperatureMeasurements from MyEdgeHubInput'

O exemplo a seguir cria um trabalho de streaming mais complexo com várias consultas diferentes. Essas consultas incluem uma que usa a função embutida AnomalyDetection_ChangePoint para identificar anomalias nos dados de temperatura.

EXEC sys.sp_create_streaming_job @name = N'StreamingJob2',
    @statement = N'
        SELECT *
        INTO TemperatureMeasurements1
        FROM MyEdgeHubInput1

        SELECT *
        INTO TemperatureMeasurements2
        FROM MyEdgeHubInput2

        SELECT *
        INTO TemperatureMeasurements3
        FROM MyEdgeHubInput3

        SELECT timestamp AS [Time],
            [Temperature] AS [Temperature],
            GetRecordPropertyValue(AnomalyDetection_ChangePoint(Temperature, 80, 1200) OVER (LIMIT DURATION(minute, 20)), '' Score '') AS ChangePointScore,
            GetRecordPropertyValue(AnomalyDetection_ChangePoint(Temperature, 80, 1200) OVER (LIMIT DURATION(minute, 20)), '' IsAnomaly '') AS IsChangePointAnomaly
        INTO TemperatureAnomalies
        FROM MyEdgeHubInput2;
';
GO

Iniciar, parar, remover e monitorar trabalhos de streaming

Para iniciar um trabalho de streaming no SQL do Azure no Edge, execute o procedimento armazenado sys.sp_start_streaming_job. O procedimento armazenado requer que o mesmo trabalho de streaming seja iniciado, como entrada.

EXEC sys.sp_start_streaming_job @name = N'StreamingJob1';
GO

Para parar um trabalho de streaming, execute o procedimento armazenado sys.sp_stop_streaming_job. O procedimento armazenado requer que o mesmo trabalho de streaming seja parado, como entrada.

EXEC sys.sp_stop_streaming_job @name = N'StreamingJob1';
GO

Para descartar (ou excluir) um trabalho de streaming, execute o procedimento armazenado sys.sp_drop_streaming_job. O procedimento armazenado requer que o nome do trabalho de streaming seja descartado, como entrada.

EXEC sys.sp_drop_streaming_job @name = N'StreamingJob1';
GO

Para obter o status atual de um trabalho de streaming no SQL no Edge, execute o procedimento armazenado sys.sp_get_streaming_job. O procedimento armazenado requer que o nome do trabalho de streaming seja descartado, como entrada. Ele emite o nome e o status atual do trabalho de streaming.

EXEC sys.sp_get_streaming_job @name = N'StreamingJob1'
WITH RESULT SETS (
        (
            name NVARCHAR(256),
            status NVARCHAR(256),
            error NVARCHAR(256)
        )
    );
GO

O trabalho de streaming pode estar em qualquer um dos seguintes status:

Status	Descrição
Criado em	O trabalho de fluxo foi criado, mas ainda não foi iniciado.
Iniciando	O trabalho de fluxo está na fase inicial.
Idle	O trabalho de streaming está em execução, porém não há nenhuma entrada para processar.
Processamento	O trabalho de streaming está em execução e processando as entradas. Indica um estado de integridade para o trabalho de fluxo.
Degradado	O trabalho de streaming está em execução, porém houve alguns erros não-fatais durante o processamento de entrada. O trabalho de entrada continua a ser executado, mas descartará entradas que encontrarem erros.
Parado	O trabalho de fluxo foi interrompido.
Com falha	O trabalho de streaming falhou. Em geral indica um erro fatal durante o processamento.

Observação

Como o trabalho de streaming é executado de forma assíncrona, o trabalho pode encontrar erros em runtime. Para solucionar problemas de falha de um trabalho de streaming, use o sys.sp_get_streaming_job procedimento armazenado ou examine o log do Docker do contêiner do Azure SQL Edge, que pode fornecer os detalhes do erro do trabalho de streaming.