Connessione al database SQL di Microsoft Azure

Scarica il driver PHP

I driver SQLSRV e PDO_SQLSRV si collegano ai seguenti Azure e Fabric target SQL con un nome server completamente qualificato e le opzioni di connessione nelle Connection options. SQLSRV prende un array di opzioni; PDO_SQLSRV assume un nome di sorgente dati (DSN), argomenti di credenziali separati quando necessario e attributi PDO.

Entrambe le estensioni PHP abilitano di default i Multiple Active Result Sets (MARS). Warehouse non supporta MARS, quindi disabilitalo esplicitamente nell'array di opzioni SQLSRV o PDO_SQLSRV DSN. SQL database in Fabric e Warehouse sono prodotti separati; non dare per scontato che una funzionalità supportata da uno sia supportata dall'altro.

Prepara endpoint, identità e host PHP

Il tuo processo PHP necessita di accesso di rete all'endpoint SQL, di un modo supportato per accedere e del permesso di aprire il database selezionato. Controlla ogni requisito separatamente. Ad esempio, aprire una porta firewall non concede l'accesso al database.

1. Installa l'estensione PHP e il driver Microsoft ODBC sulla macchina o sul container che esegue PHP. Verifica che l'estensione sia caricata in quel processo, non solo in un terminale di sviluppo. Per ulteriori informazioni, vedi Caricamento dei driver.
2. Copia il server e il database dai dettagli di connessione del target. Non includere uno schema di URL HTTPS. Usa il nome host fornito dal servizio in modo che la validazione del certificato controlli l'endpoint previsto. Un endpoint pubblico Istanza gestita di SQL di Azure può includere una porta non predefinita; mantenere la porta fornita.
3. Configura l'accesso alla rete del servizio per il tuo host PHP. Per un endpoint privato, conferma la risoluzione del nome privato e verifica la presenza di un percorso dalla rete dell'applicazione. Una regola di firewall pubblico non fornisce un percorso verso un indirizzo privato.
4. Scegli l'identità utilizzata dal processo PHP. Per un'applicazione ospitata su Azure, abilita la sua identità gestita e identifica se è assegnata al sistema o all'utente. L'accesso interfaccia della riga di comando di Azure di uno sviluppatore non è l'identità gestita dell'applicazione.
5. Far concedere da un amministratore del database a quell'identità l'accesso al database selezionato e i permessi minimi richiesti dall'applicazione. Per Warehouse, controlla anche l'accesso agli elementi/all'area di lavoro di Fabric. I permessi di gestione delle risorse di Azure da soli non concedono il permesso di interrogare le tabelle delle applicazioni.
6. Impostate SQL_SERVER e SQL_DATABASE nella configurazione dell'applicazione. Non memorizzare una password per gli esempi di identità gestita.

Gli esempi verificano una connessione senza creare tabelle. Superare questo controllo non dimostra che l'identità può leggere o scrivere lo schema della tua applicazione. Testa le operazioni effettive separatamente con la stessa identità.

Usa l'autenticazione Microsoft Entra senza password

Usa un'identità gestita quando il tuo ambiente di hosting espone un endpoint con identità gestita e il target SQL concede l'accesso a quell'identità. I seguenti programmi completi utilizzano un'identità gestita assegnata al sistema. Non sono esempi di workstation. Eseguili sull'host Azure configurato, con SQL_SERVER e SQL_DATABASE disponibili per il suo processo PHP.

Entrambi i programmi disabilitano MARS, quindi anche l'impostazione di connessione è adatta quando si seleziona Warehouse. Usano una sola istruzione condizionale attiva alla volta. Per la configurazione dell'identità e altre modalità di autenticazione, vedi Connetti usando l'autenticazione Microsoft Entra.

Imposta SQL_DATABASE sul nome effettivo del database. Ogni programma crea un valore separato con caratteri di escape per la connessione raddoppiando le parentesi di chiusura e racchiudendo il nome tra parentesi graffe. L'escape impedisce ai caratteri speciali nel nome del database di modificare il modo in cui il driver legge le impostazioni di connessione. I programmi mantengono il nome originale per verificare il risultato di DB_NAME().

SQLSRV

Salva questo programma come connect-azure-sqlsrv.php, ed esegui php connect-azure-sqlsrv.php sull'host configurato.

<?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

Salva questo programma separato come connect-azure-pdo.php, ed esegui php connect-azure-pdo.php sull'host configurato. Imposta PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE così il risultato int è PHP int. Senza di esso, PDO_SQLSRV restituisce questa colonna come stringa di default. La codifica PDO è un attributo, non l'opzione 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 è appdb, ogni programma stampa:

Connected to appdb.

ActiveDirectoryMsinon utilizza il login locale con interfaccia della riga di comando di Azure. Per lo sviluppo locale o l'integrazione continua (CI), si sceglie un metodo di autenticazione supportato dall'estensione PHP e dal driver ODBC. Puoi ottenere un token di accesso Microsoft Entra tramite una libreria di identità e fornirlo tramite AccessToken. Quando usi un token, ometti nome utente, password e Authentication impostazioni. Imposta AccessToken nell'array delle opzioni di connessione SQLSRV o nel PDO_SQLSRV DSN. Tieni i token fuori dal codice sorgente e dai log. Per ulteriori informazioni, vedere Connettersi utilizzando l'autenticazione Microsoft Entra.

ActiveDirectoryServicePrincipal usa un ID cliente e un segreto cliente; non è un'autenticazione senza password. Se lo usi, leggi il segreto dalla configurazione protetta dell'applicazione. L'autenticazione SQL è un'alternativa solo per i target che la supportano; né il database SQL in Fabric né in Warehouse supportano l'autenticazione SQL.

Adatta l'autenticazione al tuo ambiente

Usa un meccanismo di autenticazione per ogni connessione. Non lasciare un vecchio nome utente, password o Authentication impostazione quando passi a AccessToken.

Richiedi un token per il servizio SQL, non per la gestione delle risorse Azure. Il audience del token identifica il servizio che lo accetta. Per il cloud pubblico Azure, richiedi alla tua libreria di identità l'ambito https://database.windows.net/.default. Conferma la risorsa appropriata per un altro cloud. Passa il token all'estensione PHP come stringa; non convertirlo manualmente in una struttura ODBC access-token.

Un token può scadere mentre un worker continua a essere in esecuzione. Ottieni un token valido prima di aprire un'altra connessione e aggiorna i token secondo necessità nei processi worker di lunga durata. Non registrare mai un DSN contenente un access token. Per maggiori informazioni sull'autenticazione ODBC, vedi Utilizzo di Microsoft Entra ID con il driver ODBC.

Tieni separati i controlli di crittografia e identità

Encrypt=true richiede un trasporto cifrato. TrustServerCertificate=false richiede la validazione del certificato server, inclusa la sua identità. L'autenticazione Microsoft Entra stabilisce l'identità della tua applicazione; non sostituisce la validazione dei certificati del server.

Utilizzare l'endpoint fornito dal servizio SQL e mantenere l'archivio attendibile dei certificati del sistema operativo client. Non sostituire il nome host con un indirizzo IP per bypassare un problema di risoluzione dei nomi. Per un endpoint privato, correggi la risoluzione del nome e l'instradamento mantenendo il nome atteso della connessione del servizio.

LoginTimeout delimita la creazione della connessione. QueryTimeout per SQLSRV e PDO::SQLSRV_ATTR_QUERY_TIMEOUT per PDO_SQLSRV si applicano all'esecuzione delle istruzioni. Aumentare il timeout della query non risolverà un endpoint di identità gestita mancante o un utente del database errato.

Risoluzione dei problemi per fase di guasto

SQLSRV restituisce false ed espone una raccolta di errori tramite sqlsrv_errors(). Throw PDOExceptiondi costruzione PDO ; gli esempi consentono anche eccezioni per fallimenti di istruzioni. Cattura immediatamente la diagnostica nei log limitati e mantieni gli avvisi SQLSRV distinti dagli errori. Non restituire diagnostiche grezze, token o dettagli di connessione a un browser.

Pianificare le connessioni interrotte

Un servizio può disconnettere una sessione inattiva o interrompere un'operazione durante la manutenzione o il failover. La resilienza delle connessioni inattive ODBC e i tentativi applicativi risolvono diversi problemi. Per le parole chiave di retry e un test di disconnessione controllato, vedi Idle connection resiliency.

Non riprodurre una scrittura solo perché il client ha perso la connessione. Il server potrebbe aver eseguito il commit prima che la risposta venisse persa. Usa una policy di ritenti specifica per l'applicazione e un modo per rilevare il lavoro duplicato. Release statement e gestione delle connessioni quando la richiesta o il lavoro termina, inclusi i percorsi di errore. Per il comportamento del ciclo di vita e del pooling, vedi Connessione al server.

Contenuti correlati

• Connettersi con l'autenticazione di Microsoft Entra
• Opzioni di connessione
• Come accedere a database SQL di Azure da PHP