Enviar dados para o Microsoft Fabric de um pipeline do Processador de Dados

Artigo
03/13/2024

Importante

O recurso Pré-visualização de Operações do Azure IoT — habilitado pelo Azure Arc — está atualmente em VERSÃO PRÉVIA. Você não deve usar esse software em versão prévia em ambientes de produção.

Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Use o destino Fabric Lakehouse para gravar dados em um lakehouse no Microsoft Fabric de um pipeline processador de dados da Internet das Coisas do Azure (versão prévia). O estágio de destino grava arquivos parquet em uma lakehouse que permite exibir os dados em tabelas delta. O estágio de destino agrupa mensagens antes de enviar para o Microsoft Fabric.

Pré-requisitos

Para configurar e usar um estágio de pipeline de destino do Microsoft Fabric, você precisa:

Uma instância implantada do Processador de Dados.
Uma Assinatura do Microsoft Fabric. Ou inscreva-se para uma avaliação gratuita do Microsoft Fabric (versão prévia).
Uma lakehouse no Microsoft Fabric.

Configurar o Microsoft Fabric

Antes de poder escrever no Microsoft Fabric a partir de um pipeline de dados, é necessário conceder acesso ao lakehouse a partir do pipeline. Você pode usar uma entidade de serviço ou uma identidade gerenciada para autenticar o pipeline. A vantagem de utilizar uma identidade gerida é que não precisa de gerir o ciclo de vida do principal de serviço. A identidade gerida é gerida automaticamente pelo Azure e está ligada ao ciclo de vida do recurso ao qual está atribuída.

Antes de configurar a entidade de serviço ou o acesso de identidade gerenciada a um lakehouse, habilite a autenticação da entidade de serviço.

Entidade de serviço
Identidade gerenciada

Para criar uma entidade de serviço com um segredo de cliente:

Use o comando da CLI do Azure a seguir para criar uma entidade de serviço.
```
az ad sp create-for-rbac --name <YOUR_SP_NAME> 
```
O resultado desse comando inclui uma appId, displayName, password e tenant. Anote esses valores a serem usados ao configurar o acesso ao recurso de nuvem, como o Microsoft Fabric, criar um segredo e configurar um destino de pipeline:
```
{
    "appId": "<app-id>",
    "displayName": "<name>",
    "password": "<client-secret>",
    "tenant": "<tenant-id>"
}
```

Para adicionar a entidade de serviço ao workspace do Microsoft Fabric:

Anote a ID do workspace e a ID do lakehouse. Você pode encontrar esses valores na URL que você usa para acessar sua lakehouse:

https://msit.powerbi.com/groups/<your workspace ID>/lakehouses/<your lakehouse ID>?experience=data-engineering
Em seu workspace, selecione Gerenciar acesso:
Selecione Adicionar pessoas ou grupos:
Pesquise sua entidade de serviço pelo nome. Comece a digitar para ver uma lista de entidades de serviço correspondentes. Selecione a entidade de serviço que você criou anteriormente:
Conceda ao administrador da entidade de serviço acesso ao workspace.

Configurar seu segredo

Para que o estágio de destino se conecte ao Microsoft Fabric, ele precisa de acesso a um segredo que contenha os detalhes da autenticação. Para criar um segredo:

Use o seguinte comando para adicionar um segredo ao seu Azure Key Vault que contém o segredo do cliente no qual você fez uma anotação sobre quando criou a entidade de serviço:
```
az keyvault secret set --vault-name <your-key-vault-name> --name AccessFabricSecret --value <client-secret>
```
Adicione a referência secreta ao seu cluster Kubernetes seguindo as etapas em Gerenciar segredos para sua implantação das Operações do Azure IoT Versão prévia.

Para encontrar o ID da aplicação da identidade gerida e o seu ID de inquilino, execute os seguintes comandos. Substitua os espaços reservados pelo nome do cluster, grupo de recursos e ID de assinatura:

CLUSTER_NAME=<Your connected cluster name>
RESOURCE_GROUP=<The resource group where your connected cluster is installed>
SUBSCRIPTION=<The subscription where your connected cluster is installed>
EXTENSION_NAME=processor

OBJECT_ID=$(az k8s-extension show --name $EXTENSION_NAME --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --cluster-type connectedClusters --query identity.principalId -o tsv --subscription $SUBSCRIPTION)
echo "App ID:    " `az ad sp show --query appId --id $OBJECT_ID -o tsv`
echo "Tenant ID: " `az account show --query tenantId -o tsv`

Anote App ID e Tenant ID; você precisará desses valores mais tarde.

Para conceder à entidade de serviço acesso ao workspace do Microsoft Fabric:

Em seu workspace, selecione Gerenciar acesso. Em seguida, selecione + Adicionar pessoas ou grupos.
Pesquise sua identidade gerenciada digitando processador na caixa de texto Inserir nome ou email. Verifique se o valor de App ID: corresponde à ID do Aplicativo anotada na etapa anterior.
Conceda pelo menos acesso de Colaborador ao aplicativo processador.

Configurar o estágio de destino

A configuração JSON do estágio de destino do Fabric Lakehouse define os detalhes do estágio. Para criar o estágio, você pode interagir com a interface do usuário baseada em formulário ou fornecer a configuração JSON na guia Avançado :

Campo	Type	Descrição	Obrigatório	Padrão	Exemplo
Nome de exibição	String	Um nome a ser mostrado na interface do usuário do Processador de Dados.	Sim	-	`Azure IoT MQ output`
Descrição	Cadeia de caracteres	Uma descrição fácil de entender do que a fase faz.	Não		`Write to topic default/topic1`
espaços de trabalhoId	String	A ID do espaço de trabalho lakehouse.	Sim	-
LakehouseId	String	A ID do Lakehouse Lakehouse.	Sim	-
Tabela	String	O nome da tabela na qual gravar.	Sim	-
Caminho do arquivo¹	Modelo	O caminho do arquivo para onde gravar o arquivo parquet.	Não	`{{{instanceId}}}/{{{pipelineId}}}/{{{partitionId}}}/{{{YYYY}}}/{{{MM}}}/{{{DD}}}/{{{HH}}}/{{{mm}}}/{{{fileNumber}}}`
Batch²	Batch	Como enviar dados em lote.	Não	`60s`	`10s`
Autenticação⁴	String	Os detalhes de autenticação para a conexão com o Azure Data Explorer. `Service principal` ou `Managed identity`	Entidade de serviço	Yes	-
Tentar novamente	Repetir	A política de nova tentativa a ser usada.	Não	`default`	`fixed`
Colunas > Nome	string	O nome da coluna.	Yes		`temperature`
Colunas > Tipo³	string enum	O tipo de dados mantidos na coluna, usando um dos tipos primitivos delta.	Sim		`integer`
Colunas > Caminho	Caminho	O local dentro de cada registro dos dados de onde ler o valor da coluna.	Não	`.{{name}}`	`.temperature`

¹Caminho do arquivo: para gravar arquivos no Microsoft Fabric, você precisa de um caminho de arquivo. Você pode usar modelos para configurar caminhos de arquivo. Os caminhos de arquivo devem conter os seguintes componentes em qualquer ordem:

instanceId
pipelineId
partitionId
YYYY
MM
DD
HH
mm
fileNumber

Os nomes de arquivos são valores inteiros incrementais, conforme indicado por fileNumber. Certifique-se de incluir uma extensão de arquivo se quiser que seu sistema reconheça o tipo de arquivo.

²Envio em lote: o envio em lote é obrigatório quando você grava dados no Microsoft Fabric. O estágio de destino lotes mensagens em um intervalo de tempo configurável.

Se você não configurar um intervalo de envio em lote, o estágio usará 60 segundos como padrão.

³Tipo: o processador de dados grava no Microsoft Fabric usando o formato delta. O processador de dados dá suporte a todos os tipos de dados primitivos delta exceto para decimal e timestamp without time zone.

Para garantir que todas as datas e horas sejam representadas corretamente no Microsoft Fabric, verifique se o valor da propriedade é uma cadeia de caracteres RFC 3339 válida e se o tipo de dados é date ou timestamp.

¹Autenticação: Atualmente, a fase de destino suporta autenticação baseada em principal de serviço ou identidade gerida quando se conecta ao Microsoft Fabric.

Autenticação baseada em entidade de serviço

Para configurar a autenticação baseada na entidade de serviço, forneça os valores a seguir. Você anotou esses valores ao criar a entidade de serviço e adicionou a referência secreta ao seu cluster.

Campo	Descrição	Necessário
TenantId	A ID do locatário.	Sim
ClientId	A ID do aplicativo que você anotou quando criou a entidade de serviço que tem acesso ao banco de dados.	Sim
Segredo	A referência secreta que você criou no seu cluster.	Sim

Exemplo de configuração

O exemplo JSON a seguir mostra uma configuração completa do estágio de destino do Microsoft Fabric Lakehouse que grava a mensagem inteira na tabela quickstart no banco de dados":

{
    "displayName": "Fabric Lakehouse - 520f54",
    "type": "output/fabric@v1",
    "viewOptions": {
        "position": {
            "x": 0,
            "y": 784
        }
    },
    "workspace": "workspaceId",
    "lakehouse": "lakehouseId",
    "table": "quickstart",
    "columns": [
        {
            "name": "Timestamp",
            "type": "timestamp",
            "path": ".Timestamp"
        },
        {
            "name": "AssetName",
            "type": "string",
            "path": ".assetname"
        },
        {
            "name": "Customer",
            "type": "string",
            "path": ".Customer"
        },
        {
            "name": "Batch",
            "type": "integer",
            "path": ".Batch"
        },
        {
            "name": "CurrentTemperature",
            "type": "float",
            "path": ".CurrentTemperature"
        },
        {
            "name": "LastKnownTemperature",
            "type": "float",
            "path": ".LastKnownTemperature"
        },
        {
            "name": "Pressure",
            "type": "float",
            "path": ".Pressure"
        },
        {
            "name": "IsSpare",
            "type": "boolean",
            "path": ".IsSpare"
        }
    ],
    "authentication": {
        "type": "servicePrincipal",
        "tenantId": "tenantId",
        "clientId": "clientId",
        "clientSecret": "secretReference"
    },
    "batch": {
        "time": "5s",
        "path": ".payload"
    },
    "retry": {
        "type": "fixed",
        "interval": "20s",
        "maxRetries": 4
    }
}

A configuração define que:

As mensagens são agregadas em lote por 5 segundos.
Usa o .payload do caminho do lote para localizar os dados para as colunas.

Exemplo

O exemplo a seguir mostra uma mensagem de entrada de exemplo para o estágio de destino do Lakehouse do Microsoft Fabric:

{
  "payload": {
    "Batch": 102,
    "CurrentTemperature": 7109,
    "Customer": "Contoso",
    "Equipment": "Boiler",
    "IsSpare": true,
    "LastKnownTemperature": 7109,
    "Location": "Seattle",
    "Pressure": 7109,
    "Timestamp": "2023-08-10T00:54:58.6572007Z",
    "assetName": "oven"
  },
  "qos": 0,
  "systemProperties": {
    "partitionId": 0,
    "partitionKey": "quickstart",
    "timestamp": "2023-11-06T23:42:51.004Z"
  },
  "topic": "quickstart"
}