Documentação de Configuração do Projeto: Ambiente Azure

Estrutura Inicial do Projeto ContosoRetailDW no Azure

Visão geral:

O ponto de partida do projeto é um backup SQL Server no formato:

ContosoRetailDW.bak

Esse arquivo representa a base legada que será migrada para o Azure.

O processo resumido pode ser representado por:

SQL Server / ambiente legado
            │
            │ Backup
            ▼
   ContosoRetailDW.bak
            │
            │ Migração
            ▼
    Microsoft Azure

A base de dados do SQL Server existente será migrada para uma infraestrutura moderna em nuvem. Isso não significa necessariamente que o modelo de dados do ContosoRetailDW seja obsoleto.

O banco utilizado é o ContosoRetailDW, disponibilizado pela Microsoft como dataset de demonstração. O banco é uma base legada de origem, permitindo reproduzir um cenário realista de migração de dados para uma infraestrutura moderna.

A arquitetura final utiliza:

Azure Blob Storage para armazenamento do backup;
Azure SQL Managed Instance como ambiente de banco de dados;
Microsoft Entra ID para autenticação;
Managed Identity para acesso da Managed Instance ao Storage;
Python para conexão e consultas;
Power BI como camada posterior de análise e visualização.

Pré-requisitos para conexão com Azure SQL

Microsoft ODBC Driver 18 for SQL Server

O Microsoft ODBC Driver 18 for SQL Server deve ser instalado diretamente no Windows.

O driver é responsável pela comunicação entre aplicações que utilizam ODBC e o SQL Server/Azure.

Download oficial:

Microsoft ODBC Driver 18 for SQL Server

Para Windows 64 bits, utilizar o instalador x64.

O driver ODBC é uma dependência do sistema operacional. Ele não deve ser instalado dentro do ambiente Conda nem versionado no Git.

Ambiente Python

O projeto utiliza um ambiente isolado gerenciado pelo Miniconda.

Criar o ambiente:

conda create -n azure-contoso python=3.12

Ativar o ambiente:

conda activate azure-contoso

Instalar as dependências necessárias:

conda install pyodbc azure-identity

Dependências

O pyodbc utiliza o driver ODBC instalado no sistema operacional, enquanto o azure-identity fornece os mecanismos necessários para obtenção de credenciais/tokens do Microsoft Entra ID. Além disso o python-dotenv é utilizado somente dentro do ambiente, as variáveis contidas no arquivo não são versionáveis.

As dependências do ambiente devem ser registradas no arquivo:

environment.yml

Configuração de acesso ao Azure SQL

Além dos componentes locais, o Azure SQL precisa permitir a conexão do ambiente de origem.

Neste projeto, o acesso utiliza Microsoft Entra ID como mecanismo de autenticação.

Credenciais, tokens e informações de autenticação não devem ser armazenados no código-fonte ou versionados no Git.

O fato de o Azure SQL permitir conexões de serviços do Azure não significa necessariamente que o computador local esteja autorizado. O endereço IP utilizado pelo ambiente de desenvolvimento deve estar configurado nas regras de firewall quando houver conexão direta a partir da máquina local.

Variáveis de ambiente

As informações necessárias para localizar o servidor e o banco podem ser armazenadas localmente por meio de variáveis de ambiente.

Exemplo de arquivo .env:

ID_LOCATARIO=ed52ad5b-...
AZURE_SQL_SERVER_1=mi-contoso-retail.public...

Neste projeto, não são armazenados AZURE_SQL_USER e AZURE_SQL_PASSWORD, pois a autenticação é realizada por meio do Microsoft Entra ID.

O arquivo .env deve estar no .gitignore e nunca deve ser enviado ao GitHub.

O arquivo .env contém configurações locais do ambiente. Não versionar informações sensíveis, tokens, senhas ou strings de conexão.

Visão Geral do projeto:

A infraestrutura do projeto está dividida em 2 camadas principais: ambiente local/python e recursos do Azure.

Projeto Contoso Retail Analytics
│
├── Ambiente local
│   ├── Windows
│   └── Microsoft ODBC Driver 18 for SQL Server
|   └── Conda
|         └── azure-contoso
|         ├── Python 3.12
|         ├── pyodbc
|         ├── azure-identity
|         └── python-dotenv
│
└── Microsoft Azure
    │
    ├── Microsoft Entra ID
    │   └── Autenticação e autorização
    │
    ├── Azure Blob Storage
    │   └── ContosoRetailDW.bak
    │
    ├── Azure SQL Managed Instance
    │   └── Restauração e hospedagem do banco ContosoRetailDW
    │
    └── Azure SQL Logical Server
        └── Recurso lógico Azure

Fluxo Arquitetural do Projeto:

                AMBIENTE LEGADO
                       │
                       ▼
             ContosoRetailDW.bak
                       │
                       │ (Migração)
                       ▼
              Azure Blob Storage
                       │
                       │ (RESTORE)
                       ▼
          Azure SQL Managed Instance
                       │
                       ▼
                ContosoRetailDW
                       │
                       ▼
                     Python
                       │
                       ▼
                    Power BI

Ambiente Python Isolado:

O projeto utiliza um ambiente isolado criado com Conda, denominado azure-contoso.

Principais dependências:

Dependência	Finalidade
Python 3.12	Linguagem utilizada na automação e administração do ambiente
pyodbc	Conexão Python com SQL Server/Azure SQL
azure-identity	Autenticação utilizando Microsoft Entra ID
python-dotenv	Carregamento de variáveis de ambiente a partir do `.env`
Pandas	Visualização e análise das tabelas

Microsoft Entra ID

O Microsoft Entra ID é utilizado como mecanismo de identidade e autenticação.

A aplicação Python utiliza InteractiveBrowserCredential, permitindo autenticar o usuário por meio da conta Microsoft e obter um token de acesso para conexão com o SQL.

A autenticação evita a necessidade de armazenar uma senha de usuário SQL diretamente no código.

Azure Blob Storage

O Azure Blob Storage funciona como área de armazenamento do backup utilizado na migração/restauração.

O arquivo:

ContosoRetailDW.bak

é armazenado em um container do Blob Storage e utilizado como origem para a operação de RESTORE no Azure SQL Managed Instance.

Azure SQL Managed Instance

O Azure SQL Managed Instance é o principal recurso SQL utilizado na infraestrutura atual.

Ele fornece o mecanismo SQL Server necessário para restaurar e executar o banco de dados legado:

ContosoRetailDW

O fluxo simplificado da restauração é:

ContosoRetailDW.bak
        │
        ▼
Azure Blob Storage
        │
        │ RESTORE
        ▼
Azure SQL Managed Instance
        │
        ▼
  ContosoRetailDW

Azure SQL Logical Server

O Azure SQL Logical Server é um recurso de gerenciamento associado ao Azure SQL Database. Ele não representa, por si só, um banco de dados contendo os dados do projeto.

No contexto deste projeto, sua criação fez parte da configuração inicial do ambiente Azure, mas o banco ContosoRetailDW utilizado no processo atual está hospedado no Azure SQL Managed Instance.

Portanto, a arquitetura atual deve distinguir claramente:

Azure SQL Logical Server
└── Recurso lógico de gerenciamento

Azure SQL Managed Instance
└── ContosoRetailDW

Essa distinção é importante para evitar confundir logical server, SQL Database e SQL Managed Instance, que são recursos diferentes dentro do Azure.

Objetivo Principal

Migrar o banco de dados ContosoRetailDW para o Azure, utilizando uma Azure SQL Managed Instance, Azure Blob Storage e Python para conexão e consultas.

Arquitetura:

Python
   │
   │ Microsoft Entra ID
   ▼
Azure SQL Managed Instance
   │
   │ Managed Identity
   ▼
Azure Blob Storage
   │
   └── ContosoRetailDW.bak

Após o restore:

Azure
│
├── Storage Account
│   └── stcontosoretaildw01
│       └── backups
│           └── ContosoRetailDW.bak
│
└── SQL Managed Instance
    └── mi-contoso-retail
        └── ContosoRetailDW
            └── ONLINE

Azure SQL Managed Instance

Foi criada a Managed Instance:

mi-contoso-retail

Configurações relevantes:

Resource Group: ***
Estado: Ready
Public Data Endpoint: Enabled

Endpoint utilizado:

mi-contoso-retail.public.***.database.windows.net,3342

Azure Blob Storage

Foi criado o Storage Account:

stcontosoretaildw01

Container:

backups

O arquivo de backup foi carregado:

ContosoRetailDW.bak

O arquivo possui aproximadamente 629 MB.

Managed Identity

A Managed Instance utiliza uma System Assigned Managed Identity.

Essa identidade recebeu a permissão:

Storage Blob Data Owner no Storage Account.

Isso permitiu que a Managed Instance acessasse o arquivo .bak utilizando sua identidade gerenciada.

SQL Credential

Foi criada uma credential na Managed Instance:

CREATE CREDENTIAL
[{BLOB_CREDENTIAL}]
WITH IDENTITY = 'MANAGED IDENTITY';

Problema encontrado durante o desenvolvimento

Inicialmente, o acesso ao backup retornava:

Operating system error 5
Access is denied.

O problema estava na configuração de rede do Storage Account.

O Storage estava configurado com:

Public network access: Enabled
Default action: Deny

Solução:

A configuração de rede do Storage Account foi alterada para permitir o acesso necessário pela rede pública. Após a alteração, a Managed Instance conseguiu acessar o arquivo .bak.

Validação do backup:

Foi utilizado:

RESTORE HEADERONLY
FROM URL = [{AZURE_BLOB_BACKUP_URL}];

Resultado:

Backup acessado com sucesso!
DatabaseName: ContosoRetailDW
BackupType: 1

O backup estava íntegro e podia ser utilizado para restore.

Restore do banco

Foi executado através do Python:

RESTORE DATABASE [ContosoRetailDW]
FROM URL = [{AZURE_BLOB_BACKUP_URL}];

Validação:

SELECT
    name,
    state_desc
FROM sys.databases
WHERE name = 'ContosoRetailDW';

Resultado:

Banco:  ContosoRetailDW
Estado: ONLINE

Conexão Python

A autenticação utiliza InteractiveBrowserCredential e Microsoft Entra ID.

Arquivo de conexão:

O arquivo database/connection.py é responsável por:

carregar as variáveis do .env;
autenticar no Microsoft Entra ID;
obter o Access Token;
configurar o ODBC;
conectar ao ContosoRetailDW.

Arquivo de consultas:

O arquivo database/queries.py é responsável por executar consultas no banco e apresentar os resultados diretamente no terminal.

Exemplo:

SELECT
    TABLE_SCHEMA,
    TABLE_NAME
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_TYPE = 'BASE TABLE'
ORDER BY TABLE_SCHEMA, TABLE_NAME;

O arquivo ContosoRetailDW.bak permanece armazenado no Azure Blob Storage. Isso fornece uma cópia de recuperação independente do banco que está atualmente na Managed Instance.

Fluxo Geral:


┌─────────────────────────────────────────────────────────────────────┐
│                         MICROSOFT AZURE                             │
│                                                                     │
│  ┌──────────────────────────┐       ┌─────────────────────────────┐ │
│  │     Azure Blob Storage   │       │ Azure SQL Managed Instance  │ │
│  │                          │       │                             │ │
│  │    stcontosoretaildw01   │       │     mi-contoso-retail       │ │
│  │                          │       │                             │ │
│  │ ┌──────────────────────┐ │       │  ┌────────────────────────┐ │ │
│  │ │ ContosoRetailDW.bak  │ │       │  │    ContosoRetailDW     │ │ │
│  │ │                      │ │       │  │                        │ │ │
│  │ │      ~629 MB           │─┼──────► │        ONLINE          │ │ │
│  │ │                      │ │RESTORE│  │                        │ │ │
│  │ └──────────────────────┘ │       │  └────────────────────────┘ │ │
│  └──────────────────────────┘       └──────────────┬──────────────┘ │
│                                                    │                │
│                         ┌──────────────────────────┘                │
│                         │                                           │
│                         ▼                                           │
│              ┌──────────────────────┐                               │
│              │   Microsoft Entra ID │                               │
│              │                      │                               │
│              │  Authentication      │                               │
│              │  + Access Token      │                               │
│              └──────────┬───────────┘                               │
└─────────────────────────┼───────────────────────────────────────────┘
                          │
                          │ HTTPS / TDS
                          │
                          ▼
              ┌──────────────────────────┐
              │     Ambiente Local       │
              │                          │
              │         Python           │
              │           │              │
              │     azure-identity       │
              │           │              │
              │         pyodbc           │
              │           │              │
              │  Microsoft ODBC Driver 18│
              └───────────┬──────────────┘
                          │
                          ▼
                     SQL Queries
                          │
                          ▼
                       PowerBi

Stack utilizada:

☁️ Microsoft Azure - infraestrutura em nuvem
🗄️ Azure SQL Managed Instance - ambiente de banco de dados
📦 Azure Blob Storage - armazenamento do backup ContosoRetailDW.bak
🛢️ SQL Server - tecnologia do banco de origem/backup
🐍 Python - análise, manipulação, conexão e processamento dos dados
🔌 PyODBC - conexão Python → SQL Server
📊 Power BI - análise e visualização dos dados
🌿 Git - versionamento
🐙 GitHub - hospedagem do código e documentação

Estrutura do Projeto:

AZURE-CONTOSO-ANALYTICS/
├── database_contosoretailDW/
│   ├── __pycache__/
│   ├── __init__.py
│   ├── connection.py
│   ├── queries.py
│   └── README.md
│
├── restore_contoso/
│   ├── README.md
│   ├── restore_contoso_test.py
│   ├── restore_database.py
│   └── restore_status.py
│
├── test_connection_azure/
│   ├── connection_2.py
│   ├── connection.py
│   ├── list_tables_db.py
│   ├── query_SQL_test.py
│   └── README.md
│
├── .env
├── .gitignore
├── environment.yml
└── README.md

⚠️ Problema: Conexão com o Power BI

Se você encontrar o erro abaixo ao tentar conectar o Power BI à instância gerenciada (Azure SQL Managed Instance) através do endpoint público na porta XXXX:

Microsoft SQL: The target principal name is incorrect. Cannot generate SSPI context.

Causa:

Esse erro ocorre porque o Power BI tenta negociar a Autenticação do Windows (Kerberos/SSPI) por padrão ou entra em conflito de credenciais, protocolo este que não é suportado para conexões diretas via endpoint público de uma Azure SQL Managed Instance.

Resolução:

Ajuste no Portal do Azure. Se o seu fluxo exige logins tradicionais, certifique-se de desativar a opção restritiva "Dar suporte somente à autenticação do Microsoft Entra" nas configurações de segurança da sua Instância Gerenciada e garanta que a senha do Administrador do Servidor SQL esteja definida.

Configuração no Power BI:

Utilize o conector de Banco de Dados SQL do Azure (evite o conector genérico de SQL Server).

Na tela de autenticação, selecione obrigatoriamente a aba Banco de Dados (Database).
Insira o usuário Administrador do SQL e a respectiva senha, ignorando credenciais do Windows.

Para mais detalhes técnicos, histórico do problema e discussões de contorno, acesse a Issue gerada no repositório.

Issue #1 Gerada - Clique Aqui

👨‍💻 Autoria:

👤 Autor: Daniel Martins França

🔗 GitHub: Siga-me no GitHub!

🔗 LinkedIn: Acesse a minha página!

O projeto Azure-Contoso-Analytics tem como objetivo explorar, na prática, uma arquitetura de dados em ambiente Azure, utilizando o banco ContosoRetailDW como conjunto de dados para construção e validação do ambiente.

Além da compreensão de como os diferentes componentes de uma arquitetura de dados se relacionam, desde o armazenamento do backup até a disponibilização do banco para consultas e futuras aplicações analíticas.

Name		Name	Last commit message	Last commit date
database_contosoretailDW		database_contosoretailDW
restore_contoso		restore_contoso
test_connection_azure		test_connection_azure
.gitignore		.gitignore
README.md		README.md
environment.yml		environment.yml

Latest commit

History

Folders and files

Repository files navigation

Documentação de Configuração do Projeto: Ambiente Azure

Estrutura Inicial do Projeto ContosoRetailDW no Azure

Visão geral:

Pré-requisitos para conexão com Azure SQL

Microsoft ODBC Driver 18 for SQL Server

Ambiente Python

Dependências

Configuração de acesso ao Azure SQL

Variáveis de ambiente

Visão Geral do projeto:

Fluxo Arquitetural do Projeto:

Ambiente Python Isolado:

Microsoft Entra ID

Azure Blob Storage

Azure SQL Managed Instance

Azure SQL Logical Server

Objetivo Principal

Arquitetura:

Azure SQL Managed Instance

Azure Blob Storage

Managed Identity

SQL Credential

Problema encontrado durante o desenvolvimento

Solução:

Validação do backup:

Restore do banco

Conexão Python

Arquivo de conexão:

Arquivo de consultas:

Fluxo Geral:

Stack utilizada:

Estrutura do Projeto:

⚠️ Problema: Conexão com o Power BI

Causa:

Resolução:

Configuração no Power BI:

👨‍💻 Autoria:

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages