Herstellen einer Verbindung mit einer Microsoft Azure SQL-Datenbank

PHP-Treiber herunterladen

Die SQLSRV- und PDO_SQLSRV-Treiber verbinden sich mit den folgenden Azure- und Fabric-SQL-Zielen mit einem vollständig qualifizierten Servernamen und den Verbindungsoptionen in Verbindungsoptionen. SQLSRV verwendet ein Optionsarray; PDO_SQLSRV nimmt einen Datenquellennamen (DSN), separate Zugangsdaten bei Bedarf und PDO-Attribute.

Beide PHP-Erweiterungen aktivieren standardmäßig Multiple Active Result Sets (MARS). Warehouse unterstützt MARS nicht, also deaktiviere es explizit im SQLSRV-Options-Array oder PDO_SQLSRV DSN. SQL-Datenbanken in Fabric und Warehouse sind getrennte Produkte; gehen Sie nicht davon aus, dass eine von beiden unterstützte Funktion auch vom anderen unterstützt wird.

Richten Sie den Endpoint, die Identität und den PHP-Host ein

Ihr PHP-Prozess benötigt Netzwerkzugriff auf den SQL-Endpunkt, eine unterstützte Anmeldemöglichkeit und die Berechtigung, die ausgewählte Datenbank zu öffnen. Überprüfe jede Anforderung einzeln. Zum Beispiel gewährt das Öffnen eines Firewall-Ports keinen Datenbankzugriff.

1. Installiere die PHP-Erweiterung und den Microsoft ODBC-Treiber auf dem Rechner oder Container, der PHP ausführt. Verifiziere die Erweiterung in jenem Prozess, nicht nur in einem Entwicklungsterminal. Weitere Informationen finden Sie unter Laden der Treiber.
2. Kopieren Sie Server und Datenbank aus den Verbindungsdetails des Ziels. Fügen Sie kein HTTPS-URL-Schema hinzu. Verwenden Sie den vom Dienst bereitgestellten Hostnamen, damit die Zertifikatsvalidierung den vorgesehenen Endpunkt prüft. Ein öffentlicher Endpunkt der Azure SQL Managed Instance kann einen Nicht-Standard-Port enthalten; behalten Sie den bereitgestellten Port bei.
3. Konfigurieren Sie den Netzwerkzugang des Dienstes für Ihren PHP-Host. Für einen privaten Endpunkt bestätigen Sie die Auflösung des privaten Namens und eine Route vom Anwendungsnetzwerk. Eine öffentliche Firewall-Regel bietet keine Route zu einer privaten Adresse.
4. Wählen Sie die Identität, die vom PHP-Prozess verwendet wird. Für eine von Azure gehostete Anwendung aktivieren Sie ihre verwaltete Identität und ermitteln Sie, ob sie system- oder benutzerzugewiesen ist. Die Azure CLI-Anmeldung eines Entwicklers ist nicht die verwaltete Identität der Anwendung.
5. Lassen Sie einen Datenbankadministrator dieser Identität Zugriff auf die ausgewählte Datenbank und die von der Anwendung benötigten Mindestberechtigungen gewähren. Überprüfen Sie für Warehouse auch den Zugriff auf Fabric-Elemente/-Arbeitsbereiche. Azure-Ressourcenverwaltungsberechtigungen gewähren von sich aus keine Berechtigung, Anwendungstabellen abzufragen.
6. Legen Sie SQL_SERVER und SQL_DATABASE in der Konfiguration der Anwendung fest. Speichere kein Passwort für die Beispiele mit verwalteter Identität.

Die Beispiele verifizieren eine Verbindung, ohne Tabellen zu erstellen. Das Bestehen dieser Prüfung beweist nicht, dass die Identität dein Anwendungsschema lesen oder schreiben kann. Teste die tatsächlichen Operationen separat unter derselben Identität.

Verwenden Sie passwortlose Microsoft Entra-Authentifizierung

Verwenden Sie eine verwaltete Identität, wenn Ihre Hosting-Umgebung einen Managed-Identity-Endpunkt offenlegt und das SQL-Ziel dieser Identität Zugriff gewährt. Die folgenden vollständigen Programme verwenden eine systemzugeordnete verwaltete Identität. Sie sind keine Arbeitsstationsbeispiele. Führe sie auf dem konfigurierten Azure-Host aus, mit SQL_SERVER und SQL_DATABASE verfügbar für dessen PHP-Prozess.

Beide Programme deaktivieren MARS, daher ist auch die Verbindungseinstellung geeignet, wenn man Warehouse auswählt. Sie verwenden jeweils eine aktive Anweisung. Für Identitätseinrichtung und andere Authentifizierungsmodi siehe Verbinden mit Microsoft Entra-Authentifizierung.

Setze SQL_DATABASE auf den tatsächlichen Datenbanknamen. Jedes Programm erzeugt einen separaten Escaped-Wert für die Verbindung, indem es schließende geschweifte Klammern verdoppelt und den Namen mit Klammern einschließt. Durch das Escapen wird verhindert, dass Sonderzeichen im Datenbanknamen die Art und Weise ändern, wie der Treiber Verbindungseinstellungen liest. Die Programme behalten den ursprünglichen Namen bei, um das Ergebnis von DB_NAME()zu überprüfen.

SQLSRV

Speichere dieses Programm als connect-azure-sqlsrv.php, und führe php connect-azure-sqlsrv.php auf dem konfigurierten Host aus.

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

Speichern Sie dieses separate Programm als connect-azure-pdo.php, und führen Sie php connect-azure-pdo.php auf dem konfigurierten Host aus. Dadurch wird PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE festgelegt, sodass das int-Ergebnis PHP int ist. Ohne sie gibt PDO_SQLSRV diese Spalte standardmäßig als Zeichenkette zurück. Die PDO-Codierung ist ein Attribut, nicht die SQLSRV-Option 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;
}

Wenn SQL_DATABASEappdb ist, gibt jedes Programm Folgendes aus:

Connected to appdb.

ActiveDirectoryMsi verwendet nicht deine lokale Azure CLI-Anmeldung. Für lokale Entwicklung oder kontinuierliche Integration (CI) wählen Sie eine Authentifizierungsmethode, die von der PHP-Erweiterung und dem ODBC-Treiber unterstützt wird. Sie können ein Microsoft Entra-Zugriffstoken über eine Identitätsbibliothek abrufen und über AccessToken bereitstellen. Wenn du ein Token benutzt, solltest du Benutzername, Passwort und Authentication Einstellung weglassen. Legen Sie AccessToken im Array der SQLSRV-Verbindungsoptionen oder im PDO_SQLSRV-DSN fest. Halte Tokens aus dem Quellcode und den Protokollen heraus. Weitere Informationen finden Sie unter Connect using Microsoft Entra authentication.

ActiveDirectoryServicePrincipal verwendet eine Client-ID und ein Client-Geheimnis; es handelt sich nicht um passwortlose Authentifizierung. Wenn du es benutzt, lies das Secret aus der geschützten Anwendungskonfiguration. SQL-Authentifizierung ist nur für Zielsysteme eine Alternative, die sie unterstützen; weder SQL-Datenbanken in Fabric noch Warehouse unterstützen SQL-Authentifizierung.

Passen Sie die Authentifizierung an Ihre Umgebung an

Verwenden Sie für jede Verbindung einen Authentifizierungsmechanismus. Lassen Sie beim Wechsel zu Authentication keinen alten Benutzernamen, kein altes Passwort oder eine AccessToken-Einstellung bestehen.

Fordere ein Token für den SQL-Dienst an, nicht für das Azure-Ressourcenmanagement. Die Audience des Tokens identifiziert den Dienst, der ihn akzeptiert. Fordern Sie für die öffentliche Azure-Cloud den Bereich https://database.windows.net/.default von Ihrer Identitätsbibliothek an. Bestätigen Sie die passende Ressource für eine andere Cloud. Gib das Token als String an die PHP-Erweiterung weiter; wandele es nicht manuell in eine ODBC-Access-Token-Struktur um.

Ein Token kann ablaufen, während ein Worker weiterhin ausgeführt wird. Erhalten Sie vor dem Öffnen einer weiteren Verbindung ein gültiges Token und aktualisieren Sie die Token bei Bedarf bei langlebigen Arbeitern. Protokolliere niemals ein DSN, das ein Zugriffstoken enthält. Weitere Informationen zur ODBC-Authentifizierung finden Sie unter Verwendung von Microsoft Entra ID mit dem ODBC-Treiber.

Trennen von Verschlüsselungs- und Identitätsprüfungen

Encrypt=true fordert einen verschlüsselten Transport an. TrustServerCertificate=false erfordert die Validierung des Serverzertifikats, einschließlich seiner Identität. Microsoft Entra-Authentifizierung bestimmt, wer Ihre Anwendung ist; sie ersetzt die Server-Zertifikatsvalidierung nicht.

Verwenden Sie den vom SQL-Dienst bereitgestellten Endpunkt und pflegen Sie den Zertifikatsvertrauensspeicher des Client-Betriebssystems. Ersetzen Sie den Hostnamen nicht durch eine IP-Adresse, um ein Problem bei der Namensauflösung zu umgehen. Bei einem privaten Endpunkt sollten Sie die Namensauflösung und das Routing korrigieren und dabei den erwarteten Verbindungsnamen des Dienstes beibehalten.

LoginTimeout begrenzt den Verbindungsaufbau. QueryTimeout für SQLSRV und PDO::SQLSRV_ATTR_QUERY_TIMEOUT für PDO_SQLSRV gelten für die Ausführung von Anweisungen. Das Erhöhen eines Abfragetimeouts repariert keinen fehlenden Endpunkt für verwaltete Identitäten oder einen falschen Datenbankbenutzer.

Problembehandlung nach Fehlerphase

SQLSRV gibt false zurück und stellt eine Fehlersammlung über sqlsrv_errors() bereit. Die PDO-Konstruktion löst PDOException aus. Die Beispiele aktivieren auch Ausnahmen für Anweisungsfehler. Erfassen Sie sofort Diagnosen in eingeschränkten Logs und halten Sie SQLSRV-Warnungen von Fehlern getrennt. Geben Sie keine unformatierten Diagnosen, Token oder Verbindungsdetails an einen Browser zurück.

Planen für unterbrochene Verbindungen

Ein Dienst kann eine inaktive Sitzung trennen oder einen Vorgang während Wartung oder Failover unterbrechen. ODBC-Resilienz bei Verbindungsleerlauf und Anwendungswiederholungen lösen unterschiedliche Probleme. Informationen zu Wiederholungsschlüsselwörtern und einem kontrollierten Trennungstest finden Sie unter Resilienz bei Verbindungsleerlauf.

Wiederholen Sie einen Schreibvorgang nicht nur, weil der Client seine Verbindung verloren hat. Der Server hat möglicherweise einen Commit ausgeführt, bevor die Antwort verloren ging. Verwenden Sie eine anwendungsspezifische Wiederholungsrichtlinie und eine Möglichkeit, doppelte Arbeit zu erkennen. Geben Sie Anweisungen und Verbindungshandles frei, wenn die Anforderung oder der Auftrag abgeschlossen ist, einschließlich Fehlerpfaden. Für Lebenszyklus und Pooling-Verhalten siehe Verbindung mit dem Server herstellen.

Verwandte Inhalte

• Herstellen einer Verbindung mit der Microsoft Entra-Authentifizierung
• Verbindungsoptionen
• Wie man von PHP aus auf Azure SQL-Datenbank zugreift