Nawiązywanie połączenia z usługą Microsoft Azure SQL Database

Pobieranie sterownika PHP

Sterowniki SQLSRV i PDO_SQLSRV łączą się z następującymi Azure i Fabric celami SQL z w pełni wykwalifikowaną nazwą serwera oraz opcjami połączenia w opcjach połączenia. SQLSRV przyjmuje tablicę opcji; PDO_SQLSRV przyjmuje nazwę źródła danych (DSN), oddzielne argumenty poświadczenia w razie potrzeby oraz atrybuty PDO.

Target Forma nazwy serwera Notes
Azure SQL Database <server>.database.windows.net
Azure SQL Managed Instance Publiczny lub prywatny endpoint Twojej instancji Wymaga połączenia sieciowego przez sieć wirtualną, wirtualną sieć prywatną (VPN) lub publiczny punkt końcowy.
Azure Synapse Analytics (dedicated SQL pool in a workspace) <workspace>.sql.azuresynapse.net Obsługiwane Transact-SQL (T-SQL) instrukcje różnią się od SQL Server. Wspieraną składnię można znaleźć w dokumentacji Synapse SQL.
Baza danych SQL w usłudze Microsoft Fabric Skopiuj serwer i bazę danych z elementów Ustawień>Połączenia w bazie danych Użyj połączenia z bazą danych SQL, a nie z jej endpointem analityki SQL. Wymagane jest uwierzytelnianie Microsoft Entra. Aby uzyskać więcej informacji, zobacz Podłączanie do bazy danych SQL w Fabric.
Magazyn w usłudze Microsoft Fabric Skopiuj SQL parametry połączenia magazynu z portalu Fabric Ustaw Database nazwę magazynu i MultipleActiveResultSets .false Wymagane jest uwierzytelnianie Microsoft Entra. Aby uzyskać więcej informacji, zobacz Połączenie magazynu.

Oba rozszerzenia PHP domyślnie umożliwiają Multiple Active Result Sets (MARS). Warehouse nie obsługuje MARS, więc wyraźnie wyłącz go w tablicy opcji SQLSRV lub PDO_SQLSRV DSN. Baza danych SQL w Fabric i Warehouse to oddzielne produkty; nie zakładaj, że funkcja wspierana przez jeden jest wspierana przez drugi.

Przygotuj endpoint, tożsamość i host PHP

Twój proces PHP potrzebuje dostępu sieciowego do punktu końcowego SQL, obsługiwanego sposobu logowania oraz uprawnień do otwarcia wybranej bazy danych. Sprawdź każde wymagania osobno. Na przykład otwarcie portu firewalla nie daje dostępu do bazy danych.

  1. Zainstaluj rozszerzenie PHP i sterownik Microsoft ODBC na komputerze lub kontenerze, który uruchamia PHP. Zweryfikowaj rozszerzenie w tym procesie, nie tylko w terminalu deweloperskim. Więcej informacji znajdziesz w artykule Ładowanie sterowników.
  2. Skopiuj serwer i bazę danych ze szczegółów połączenia elementu docelowego. Nie uwzględniaj schematu adresu URL HTTPS. Użyj nazwy hosta dostarczonej przez usługę, aby weryfikacja certyfikatu sprawdzała zamierzony punkt końcowy. Publiczny punkt końcowy Azure SQL Managed Instance może zawierać port niedomyślny; zachowaj dostarczony port.
  3. Skonfiguruj dostęp sieciowy usługi dla swojego hosta PHP. Dla prywatnego punktu końcowego potwierdź rozwiązywanie prywatnych nazw i trasę z sieci aplikacji. Publiczna reguła zapory sieciowej nie zapewnia trasy do prywatnego adresu.
  4. Wybierz tożsamość używaną przez proces PHP. W przypadku aplikacji hostowanej w Azure włącz jej zarządzaną tożsamość i zidentyfikuj, czy jest przypisana przez system, czy przez użytkownika. Logowanie programisty do Azure CLI nie jest zarządzaną tożsamością aplikacji.
  5. Administrator bazy danych przyznał dostęp do tej tożsamości do wybranej bazy oraz minimalne uprawnienia wymagane przez aplikację. W przypadku Warehouse sprawdź też dostęp do elementu/obszaru roboczego Fabric. Uprawnienia do zarządzania zasobami w Azure same w sobie nie dają pozwoleń na zapytania do tabel aplikacji.
  6. Ustaw SQL_SERVER i SQL_DATABASE w konfiguracji aplikacji. Nie zapisuj hasła do przykładów z tożsamością zarządzaną.

Przykłady weryfikują połączenie bez tworzenia tabel. Zdanie tego testu nie dowodzi, że tożsamość potrafi odczytać lub zapisać schemat aplikacji. Testuj rzeczywiste operacje osobno pod tą samą tożsamością.

Używaj uwierzytelniania Microsoft Entra bez hasła

Używaj tożsamości zarządzanej, gdy środowisko hostingu udostępnia punkt końcowy zarządzanej tożsamości, a docelowa baza danych SQL przyznaje tej tożsamości uprawnienia dostępu. Poniższe kompletne programy korzystają z zarządzanej tożsamości przypisanej przez system. To nie są przykłady stacji roboczych. Uruchom je na skonfigurowanym hoście Azure, z SQL_SERVER i SQL_DATABASE dostępnymi dla jego procesu PHP.

Oba programy wyłączają MARS, więc to ustawienie połączenia jest również odpowiednie przy wybieraniu opcji Warehouse. Używają jednej aktywnej instrukcji na raz. Aby skonfigurować tożsamość i inne tryby uwierzytelniania, zobacz Nawiązywanie połączenia przy użyciu uwierzytelniania Microsoft Entra.

Ustaw SQL_DATABASE na rzeczywistą nazwę bazy danych. Każdy program tworzy osobną wartość ze znakami ucieczki dla połączenia, podwajając zamykające nawiasy i ujmując nazwę w nawiasy klamrowe. Escaping zapobiega temu, aby znaki specjalne w nazwie bazy danych zmieniały sposób odczytu ustawień połączenia przez sterownik. Programy zachowują oryginalną nazwę, aby sprawdzić wynik DB_NAME().

SQLSRV

Zapisz ten program jako connect-azure-sqlsrv.php i uruchom php connect-azure-sqlsrv.php na skonfigurowanym hoście.

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

Zapisz ten osobny program jako connect-azure-pdo.php, i uruchom php connect-azure-pdo.php na skonfigurowanym hostze. Ustawia PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE, tak że wynik int jest ustawiany na PHP int. Bez niej PDO_SQLSRV domyślnie zwraca tę kolumnę jako ciąg znaków. Kodowanie PDO to atrybut, a nie opcja 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;
}

Jeśli SQL_DATABASE jest appdb, każdy program wypisuje:

Connected to appdb.

ActiveDirectoryMsinie używa Twojego lokalnego logowania do Azure CLI. Do rozwoju lokalnego lub integracji ciągłej (CI) wybierz metodę uwierzytelniania wspieraną przez rozszerzenie PHP i sterownik ODBC. Możesz uzyskać token dostępu Microsoft Entra przez bibliotekę tożsamości i dostarczyć go przez AccessToken. Podczas używania tokena pomiń nazwę użytkownika, hasło i ustawienie Authentication. Ustaw AccessToken w tablicy opcji połączenia SQLSRV lub w PDO_SQLSRV DSN. Trzymaj tokeny z dala od kodu źródłowego i logów. Aby uzyskać więcej informacji, zobacz Connect using Microsoft Entra authentication (Łączenie przy użyciu uwierzytelniania firmy Microsoft Entra).

ActiveDirectoryServicePrincipal używa identyfikatora klienta i sekretu klienta; nie jest to uwierzytelnianie bez hasła. Jeśli go używasz, odczytaj sekret z chronionej konfiguracji aplikacji. Uwierzytelnianie SQL jest alternatywą tylko dla celów, które je obsługują; ani baza danych SQL w Fabric, ani Warehouse nie obsługują uwierzytelniania SQL.

Dostosuj uwierzytelnianie do swojego środowiska

Używaj jednego mechanizmu uwierzytelniania dla każdego połączenia. Nie zostawiaj starej nazwy użytkownika, hasła ani ustawienia Authentication przy przełączaniu się na AccessToken.

Environment Configuration Odpowiedzialność
Azure host z systemowo przypisaną tożsamością zarządzaną Ustaw opcję Authentication na ActiveDirectoryMsi. Nie podawaj nazwy użytkownika ani hasła. ODBC pobiera token z punktu końcowego tożsamości hosta.
Azure host z zarządzaną tożsamością przypisaną przez użytkownika Ustaw opcję Authentication na ActiveDirectoryMsi. Podaj identyfikator (ID) tożsamości za pomocą opcji SQLSRV UID lub argumentu nazwy użytkownika w PDO. Nie podawaj hasła. Wymagany identyfikator zależy od usługi hostingowej. App Service i Container Instances używają identyfikatora klienta; sprawdź wskazówki dotyczące tożsamości ODBC dla innych hostów.
Stacja robocza lub CI z zewnętrznym dostawcą tokenów Uzyskaj token dla usługi SQL, a następnie ustaw AccessToken. Pomiń nazwę użytkownika, hasło i ustawienie Authentication. Twoja aplikacja lub biblioteka tożsamości pobiera i odświeża token. Żadne z tych rozszerzeń PHP nie korzysta automatycznie z logowania do Azure CLI.
Zasada usługi z klientem sekretem Ustaw opcję Authentication na ActiveDirectoryServicePrincipal. Dla SQLSRV ustaw UID na identyfikator klienta i PWD na sekret. W przypadku PDO należy przekazać identyfikator klienta i sekret jako argumenty konstruktora: nazwę użytkownika i hasło. Chroń i odnów sekret. Ta metoda nie jest bezhasłowa.
Logowanie SQL na obiekcie docelowym, który to obsługuje SQLSRV używa UID/PWD; PDO używa argumentów konstruktora: drugiego i trzeciego. Obiekt docelowy weryfikuje dane uwierzytelniające SQL. Ta opcja nie dotyczy żadnego z produktów Fabric.

Poproś o token dla usługi SQL, a nie dla zarządzania zasobami Azure. Parametr audience tokena identyfikuje usługę, która go akceptuje. W przypadku publicznej chmury Azure zażądaj zakresu https://database.windows.net/.default przy użyciu biblioteki tożsamości. Potwierdź odpowiedni zasób dla innej chmury. Przekaż token do rozszerzenia PHP jako ciąg znaków; nie konwertuj go ręcznie na strukturę tokenu dostępu ODBC.

Token może wygasnąć, gdy proces roboczy nadal działa. Uzyskaj ważny token przed otwarciem kolejnego połączenia i odświeżaj tokeny w długotrwale działających procesach roboczych. Nigdy nie loguj DSN zawierającego token dostępu. Więcej informacji o uwierzytelnianiu ODBC można znaleźć w artykule Używanie Microsoft Entra ID ze sterownikiem ODBC.

Trzymaj szyfrowanie i sprawdzanie tożsamości oddzielnie

Encrypt=true żąda zaszyfrowanego połączenia. TrustServerCertificate=false wymaga weryfikacji certyfikatu serwera, w tym jego tożsamości. Uwierzytelnianie Microsoft Entra ustala, kim jest twoja aplikacja; nie zastępuje walidacji certyfikatu serwera.

Korzystaj z punktu końcowego dostarczanego przez usługę SQL i utrzymuj magazyn zaufanych certyfikatów systemu operacyjnego klienta. Nie zastępuj nazwy hosta adresem IP, aby obejść problem z rozpoznawaniem nazw. Dla prywatnego punktu końcowego popraw rozwiązywanie nazw i routing, zachowując oczekiwaną nazwę połączenia usługi.

LoginTimeout ogranicza nawiązywanie połączenia. QueryTimeout dla SQLSRV i PDO::SQLSRV_ATTR_QUERY_TIMEOUT dla PDO_SQLSRV dotyczą wykonywania instrukcji. Podniesienie limitu zapytania nie naprawi brakującego endpointu z tożsamością zarządzaną ani błędnego użytkownika bazy danych.

Rozwiązywanie problemów według etapu awarii

Etap niepowodzenia Co należy sprawdzić?
PHP nie może załadować rozszerzenia Potwierdź wersję środowiska uruchomieniowego, architekturę, kompilację rozszerzenia, instalację ODBC oraz element php.ini używany przez proces aplikacji.
Przekroczono limit czasu połączenia protokołu TCP Zweryfikuj skopiowany punkt końcowy i port, rozwiązywanie nazw, reguły zapory, routing sieci wirtualnej oraz konfigurację prywatnego punktu końcowego z hosta PHP.
Walidacja certyfikatu nie powiodła się Sprawdź nazwę endpointu, łańcuch certyfikatów i magazyn zaufania klienta. Zachowaj włączoną walidację certyfikatów.
Zarządzana tożsamość nie może pozyskać tokena Potwierdź, że tożsamość jest włączona na tym hostie oraz że jej punkt końcowy jest dostępny. Nie testuj ActiveDirectoryMsi na zwykłym laptopie i nie oczekuj, że logowanie do Azure CLI to spełni.
Uwierzytelnianie tokenowe nie udaje się Sprawdź zamierzoną usługę tokena, jego wygaśnięcie, dzierżawę oraz tożsamość. Potwierdź dostęp do bazy danych dla tego konta. Usuń wszelkie nazwy użytkownika, hasła i Authentication ustawienia.
Logowanie się udało, ale wybrana baza danych nie może się otworzyć Potwierdź nazwę bazy danych oraz to, że jej administrator utworzył lub przyznał dostęp do docelowej tożsamości.
Połączenie jest nawiązywane, ale zapytanie aplikacji kończy się niepowodzeniem Sprawdź uprawnienia obiektów oraz obsługiwane funkcje T-SQL w ciele. Test połączenia nie uzyskuje dostępu do schematu aplikacji.
Warehouse odrzuca ustawienia połączenia Ustaw MultipleActiveResultSets na false w tablicy opcji SQLSRV lub w ciągu PDO DSN i użyj uwierzytelniania Microsoft Entra.

SQLSRV zwraca false i ujawnia kolekcję błędów przez sqlsrv_errors(). Konstrukcja PDO wyrzuca PDOException; przykłady umożliwiają również wyjątki dla błędów instrukcji. Natychmiast rejestruj diagnostykę w zastrzeżonych logach i odróżniaj ostrzeżenia SQLSRV od błędów. Nie zwracaj surowych danych diagnostycznych, tokenów ani szczegółów połączenia do przeglądarki.

Planowanie na wypadek przerwanych połączeń

Usługa może przerwać sesję bezczynnościową lub przerwać operację podczas konserwacji lub przełączania awaryjnego. Odporność na bezczynne połączenie ODBC oraz próby aplikacji rozwiązują różne problemy. Aby uzyskać ponownie próby słów kluczowych i kontrolowany test rozłączenia, zobacz Odporność połączenia bezczynnego.

Nie ponawiaj operacji zapisu tylko dlatego, że klient stracił połączenie. Serwer mógł się zobowiązać zanim odpowiedź została utracona. Użyj polityki powtórek specyficznej dla aplikacji oraz metody wykrywania duplikatów pracy. Instrukcje release i uchwyty połączenia po zakończeniu żądania lub zadania, w tym ścieżki błędów. Aby poznać cykl życia i zachowanie pulacji, zobacz Łączenie z serwerem.

Treści powiązane

  • Ostatnia aktualizacja o