Self-hosted IR em Azure Synapse: como configurar

Este tutorial explica como configurar um Self-hosted Integration Runtime (IR) em Azure Synapse para copiar dados de um SQL Server on-premises para um Azure Data Lake Storage Gen2. Configurar um Self-hosted IR em Azure Synapse permite mover dados através de redes seguras quando não é possível expor as bases de dados diretamente para a cloud.

Pré-requisitos

• Conta Azure com permissões para o Synapse Workspace e ADLS Gen2.
• Um Synapse Workspace com permissões de Contributor para criar Linked Services e Pipelines.
• Máquina on-premises (Windows) com acesso ao SQL Server e permissões para instalar software.
• Portas de rede abertas para o servidor onde será instalado o Self-hosted IR (HTTPS de saída).
• Credenciais de acesso ao SQL Server e à conta ADLS Gen2.

Passo 1: Criar o Self-hosted Integration Runtime no Synapse

Abra o Synapse Studio e vá a Manage > Integration runtimes. Crie um novo Integration Runtime do tipo Self-hosted. O passo gera uma chave de registo que será usada na instalação local.

{
  "name": "SelfHostedIR",
  "type": "SelfHosted",
  "description": "IR para ligar ao SQL on-premises"
}

Passo 2: Instalar e registar o IR na máquina on-premises

Na máquina on-premises faça o download do instalador do Integration Runtime (link no próprio Synapse Studio). Execute o instalador e, quando solicitado, cole a chave de registo criada no Passo 1. O agente ficará registado e ligado ao seu Synapse Workspace.

Passo 3: Criar Linked Services (SQL on-prem e ADLS Gen2)

Crie um Linked Service para o SQL Server on-premises e outro para o ADLS Gen2. Para o Linked Service do SQL Server indique que usa o Self-hosted IR através de connectVia. Exemplo mínimo JSON do Linked Service para o SQL Server:

{
  "name": "LS_OnPrem_SqlServer",
  "properties": {
    "type": "SqlServer",
    "typeProperties": {
      "connectionString": "Server=ONPREM-SQL;Database=MyDb;User Id=myuser;Password=mypassword;"
    },
    "connectVia": {
      "referenceName": "SelfHostedIR",
      "type": "IntegrationRuntimeReference"
    }
  }
}

Exemplo mínimo JSON do Linked Service para ADLS Gen2:

{
  "name": "LS_ADLS_Gen2",
  "properties": {
    "type": "AzureDataLakeStorageGen2",
    "typeProperties": {
      "url": "https://.dfs.core.windows.net"
    }
  }
}

Passo 4: Criar Datasets e pipeline Copy

Defina um Dataset de origem que aponte para a tabela do SQL Server e um Dataset de destino que escreva para um contentor ADLS Gen2 (por exemplo CSV ou Parquet). Depois crie um Pipeline com uma atividade Copy.

{
  "name": "Ds_OnPrem_SqlTable",
  "properties": {
    "linkedServiceName": { "referenceName": "LS_OnPrem_SqlServer", "type": "LinkedServiceReference" },
    "type": "SqlServerTable",
    "typeProperties": { "tableName": "dbo.MyTable" }
  }
}

{
  "name": "Ds_ADLS_Output",
  "properties": {
    "linkedServiceName": { "referenceName": "LS_ADLS_Gen2", "type": "LinkedServiceReference" },
    "type": "DelimitedText",
    "typeProperties": { "location": { "type": "AzureBlobFSLocation", "fileName": "MyTable.csv", "folderPath": "ingest/" } }
  }
}

{
  "name": "CopyOnPremToADLS",
  "properties": {
    "activities": [
      {
        "name": "CopyFromSqlToADLS",
        "type": "Copy",
        "inputs": [{ "referenceName": "Ds_OnPrem_SqlTable", "type": "DatasetReference" }],
        "outputs": [{ "referenceName": "Ds_ADLS_Output", "type": "DatasetReference" }],
        "typeProperties": {
          "source": { "type": "SqlSource" },
          "sink": { "type": "DelimitedTextSink", "storeSettings": {} }
        }
      }
    ]
  }
}

Nota: no Synapse Studio pode criar estes elementos através da interface gráfica. O JSON serve de exemplo para automação ou templates ARM.

Passo 5: Executar, monitorizar e agendar

Execute o pipeline manualmente no Synapse Studio para testar. Depois use Triggers para agendar execuções (Schedule trigger) se precisar de cargas recorrentes. Monitorize em Monitor > Pipeline runs para ver o estado, duração e eventuais erros.

Verificar o resultado

Confirme que os ficheiros foram escritos no ADLS Gen2: use o recurso Data hub no Synapse Studio ou um Storage Explorer (ou o Azure Portal) para verificar a presença de MyTable.csv em /ingest/. Verifique também o registo do pipeline em Monitor para mensagens de sucesso e número de linhas copiadas. Se houver erros comuns (autenticação, firewall, tempo de ligação), verifique o registo do Self-hosted IR na máquina local e se o SQL Server permite ligações remotas.

Conclusão

Agora tem um Self-hosted Integration Runtime a funcionar com um pipeline Copy que move dados de um SQL Server on-premises para ADLS Gen2 via Azure Synapse. Próximos passos úteis incluem: usar formatos eficientes como Parquet, implementar compressão ou adicionar actividades de transformação no pipeline. Dica: se observar problemas de ligação, confirme a hora do sistema e se o agente consegue resolver os nomes DNS do servidor on-premises — já verificou isso?