Conectando-se ao Banco de Dados SQL do Microsoft Azure

Descarregar o driver PHP

Os drivers SQLSRV e PDO_SQLSRV ligam-se aos seguintes destinos SQL do Azure e do Fabric com um nome de servidor totalmente qualificado e as opções de ligação nas opções de Ligação. O SQLSRV aceita um array de opções; PDO_SQLSRV aceita um nome de fonte de dados (DSN), argumentos de credencial separados quando necessário e atributos PDO.

Ambas as extensões PHP ativam por defeito o Multiple Active Result Sets (MARS). O Warehouse não suporta MARS, por isso desativa-o explicitamente no array de opções SQLSRV ou PDO_SQLSRV DSN. As bases de dados SQL no Fabric e no Warehouse são produtos separados; não assuma que uma funcionalidade suportada por um é suportada pelo outro.

Prepare o ponto de extremidade, a identidade e o host PHP

O seu processo PHP precisa de acesso em rede ao endpoint SQL, uma forma suportada de iniciar sessão e permissão para abrir a base de dados selecionada. Verifique cada requisito separadamente. Por exemplo, abrir uma porta de firewall não concede acesso à base de dados.

1. Instala a extensão PHP e o Microsoft ODBC Driver na máquina ou contentor que executa PHP. Verifique a extensão nesse processo, não apenas num terminal de desenvolvimento. Para mais informações, consulte Carregamento dos drivers.
2. Copie o servidor e a base de dados a partir dos detalhes da ligação do destino. Não incluas um esquema de URL HTTPS. Utilize o nome do anfitrião fornecido pelo serviço para que a validação do certificado verifique o ponto final pretendido. Um endpoint público Azure SQL Managed Instance pode incluir uma porta não padrão; manter a porta fornecida.
3. Configure o acesso à rede do serviço para o seu host PHP. Para um endpoint privado, confirme a resolução de nomes privados e uma rota a partir da rede de aplicações. Uma regra de firewall público não fornece uma rota para um endereço privado.
4. Escolha a identidade usada pelo processo PHP. Para uma aplicação alojada no Azure, ative a sua identidade gerida e identifique se é atribuída pelo sistema ou pelo utilizador. O login do CLI do Azure de um programador não é a identidade gerida da aplicação.
5. Peça a um administrador de base de dados que conceda a essa identidade acesso à base de dados selecionada e as permissões mínimas necessárias para a aplicação. Para o Warehouse, verifica também o acesso ao item/espaço de trabalho no Fabric. As permissões de gestão de recursos do Azure não concedem por si só permissão para consultar tabelas de aplicação.
6. Definir SQL_SERVER e SQL_DATABASE na configuração da aplicação. Não guarde uma palavra-passe para os exemplos de identidade gerida.

Os exemplos verificam uma ligação sem criar tabelas. Passar esta verificação não prova que a identidade consegue ler ou escrever o esquema da sua aplicação. Teste as operações reais separadamente sob a mesma identidade.

Utilize a autenticação sem palavra-passe do Microsoft Entra

Use uma identidade gerida quando o seu ambiente de alojamento expõe um endpoint de identidade gerida e o destino SQL concede acesso a essa identidade. Os seguintes programas completos utilizam uma identidade gerida atribuída pelo sistema. Não são exemplos de estações de trabalho. Execute-os no host Azure configurado, com SQL_SERVER e SQL_DATABASE disponível para o seu processo PHP.

Ambos os programas desativam o MARS, pelo que a configuração de ligação também é adequada ao selecionar Warehouse. Usam uma instrução ativa de cada vez. Para configuração de identidade e outros modos de autenticação, veja Conectar usando autenticação Microsoft Entra.

Defina SQL_DATABASE como o nome real da base de dados. Cada programa cria um valor separado para a ligação ao duplicar as chaves de encerramento e envolver o nome em colchetes. O escape de caracteres impede que caracteres especiais no nome da base de dados alterem a forma como o driver lê as definições de ligação. Os programas mantêm o nome original para verificar o resultado de DB_NAME().

SQLSRV

Guarde este programa como connect-azure-sqlsrv.php, e execute php connect-azure-sqlsrv.php no host configurado.

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$conn = sqlsrv_connect($server, [
    'Database' => $databaseValue,
    'Authentication' => 'ActiveDirectoryMsi',
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'MultipleActiveResultSets' => false,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}

$stmt = null;
try {
    $stmt = sqlsrv_query(
        $conn,
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [],
        ['QueryTimeout' => 30]
    );
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if ($row !== ['DatabaseName' => $database, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $row['DatabaseName'], '.', PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

Guarde este programa separado como connect-azure-pdo.php, e execute php connect-azure-pdo.php no host configurado. Define-se PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE para que o resultado int seja PHP int. Sem ela, PDO_SQLSRV devolve esta coluna como uma cadeia por defeito. A codificação PDO é um atributo, não a opção SQLSRV CharacterSet .

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$databaseValue;Authentication=ActiveDirectoryMsi;"
    . "Encrypt=true;TrustServerCertificate=false;LoginTimeout=30;"
    . "MultipleActiveResultSets=false",
    null,
    null,
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
        PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
    ]
);

$stmt = null;
try {
    $stmt = $pdo->prepare(
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]
    );
    $stmt->execute();
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['DatabaseName' => $database, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $row['DatabaseName'], '.', PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Se SQL_DATABASE for appdb, cada programa imprime:

Connected to appdb.

ActiveDirectoryMsinão usa o início de sessão local do CLI do Azure. Para desenvolvimento local ou integração contínua (CI), escolha um método de autenticação suportado pela extensão PHP e pelo driver ODBC. Pode obter um token de acesso Microsoft Entra através de uma biblioteca de identidade e fornecê-lo através de AccessToken. Ao usar um token, omita o nome de utilizador, a palavra-passe e Authentication a definição. Define AccessToken no array de opções de ligação SQLSRV ou no PDO_SQLSRV DSN. Mantenha os tokens fora do código-fonte e dos logs. Para obter mais informações, consulte Conectar-se usando a autenticação do Microsoft Entra.

ActiveDirectoryServicePrincipal usa um ID de cliente e um segredo do cliente; não é autenticação sem palavra-passe. Se o usares, lê o segredo da configuração protegida da aplicação. A autenticação SQL é uma alternativa apenas para alvos que a suportam; nem a base de dados SQL no Fabric nem no Warehouse suportam autenticação SQL.

Adapte a autenticação ao seu ambiente

Use um mecanismo de autenticação para cada ligação. Não deixe um nome de utilizador antigo, palavra-passe antiga ou definição Authentication ao mudar para AccessToken.

Peça um token para o serviço SQL, não para a gestão de recursos do Azure. A audience do token identifica o serviço que o aceita. Para cloud pública do Azure, peça o escopo https://database.windows.net/.default à sua biblioteca de identidade. Confirme o recurso adequado para outra nuvem. Passar o token para a extensão PHP como uma string; não o converta manualmente numa estrutura de token de acesso ODBC.

Um token pode expirar enquanto um trabalhador continua a funcionar. Obtenha um token válido antes de abrir outra conexão e atualize os tokens conforme necessário em trabalhadores de longa duração. Nunca gere um DSN que contenha um token de acesso. Para mais informações sobre autenticação ODBC, consulte Utilização do Microsoft Entra ID com o Driver ODBC.

Mantenha a encriptação e as verificações de identidade separadas

Encrypt=true solicita um transporte cifrado. TrustServerCertificate=false requer a validação do certificado do servidor, incluindo a verificação da sua identidade. A autenticação Microsoft Entra estabelece quem é a sua aplicação; não substitui a validação do certificado do servidor.

Utilize o endpoint fornecido pelo serviço SQL e mantenha o armazenamento de certificados do sistema operativo cliente. Não substituas o nome do host por um endereço IP para contornar um problema de resolução de nomes. Para um endpoint privado, corrige a resolução de nomes e o encaminhamento, mantendo o nome esperado da ligação do serviço.

LoginTimeout limita o estabelecimento de ligações. QueryTimeout para SQLSRV e PDO::SQLSRV_ATTR_QUERY_TIMEOUT para PDO_SQLSRV aplicam-se à execução de instruções. Aumentar o tempo de espera da consulta não vai corrigir um endpoint de identidade gerida em falta nem um utilizador incorreto da base de dados.

Resolução de problemas por fase de falha

SQLSRV devolve false e expõe uma coleção de erros através de sqlsrv_errors(). Lançamentos PDOExceptionde construção PDO ; os exemplos também permitem exceções para falhas de instruções. Capturar os diagnósticos imediatamente em registos restritos e manter os avisos SQLSRV distintos dos erros. Não devolve diagnósticos brutos, tokens ou detalhes de ligação ao navegador.

Plano para ligações interrompidas

Um serviço pode desligar uma sessão ociosa ou interromper uma operação durante a manutenção ou o failover. A resiliência da ligação idle ODBC e as tentativas de aplicação resolvem diferentes problemas. Para palavras-chave de retentativa e um teste de desconexão controlada, veja resiliência de ligação inativa.

Não repita uma gravação só porque o cliente perdeu a ligação. O servidor pode ter-se confirmado antes de a resposta ser perdida. Use uma política de retentativas específica para a aplicação e uma forma de detetar trabalho duplicado. Instruções de libertação e handles de ligação quando o pedido ou tarefa termina, incluindo caminhos de erro. Para o comportamento do ciclo de vida e do pooling, veja Ligar ao servidor.

Conteúdo relacionado

• Conectar usando a autenticação do Microsoft Entra
• Opções de ligação
• Como aceder ao Base de Dados SQL do Azure a partir do PHP