sqlsrv_field_metadata

下載 PHP 驅動程式

擷取已備妥陳述式的欄位中繼資料。 如需有關準備陳述式的詳細資訊，請參閱 sqlsrv_query 或 sqlsrv_prepare。 請注意，在執行前或執行後，均可在任何已備妥的陳述式上呼叫 sqlsrv_field_metadata。

語法

  
sqlsrv_field_metadata( resource $stmt)  

參數

$stmt：為其尋找欄位中繼資料的陳述式資源。

傳回值

陣列的 array ，或為 false。 此陣列包含結果集內各欄位的一個陣列。 每個子陣列都有如下表中所述的索引鍵。 如果擷取欄位中繼資料發生錯誤，則會傳回 false 。

下表提供有關每個子陣列的索引鍵的詳細資訊 (如需這些類型的詳細資訊，請參閱 SQL Server 文件)：

(1) 零 (0) 表示允許大小上限。

可為 Null 的索引鍵可為是或否。

範例

下列範例會建立陳述式資源，然後擷取並顯示欄位中繼資料。 此範例假設本機電腦上已安裝 SQL Server 和 AdventureWorks 資料庫。 從命令列執行範例時，所有輸出都會寫入至主控台。

<?php
/* Connect to the local server using Windows Authentication and
specify the AdventureWorks database as the database in use. */
$serverName = "(local)";
$connectionInfo = array("Database"=>"AdventureWorks");
$conn = sqlsrv_connect($serverName, $connectionInfo);
if ($conn === false) {
    echo "Could not connect.\n";
    die( print_r( sqlsrv_errors(), true));
}

/* Prepare the statement. */
$tsql = "SELECT ReviewerName, Comments FROM Production.ProductReview";
$stmt = sqlsrv_prepare( $conn, $tsql);
  
/* Get and display field metadata. */
foreach( sqlsrv_field_metadata( $stmt) as $fieldMetadata) {
    foreach( $fieldMetadata as $name => $value) {
        echo "$name: $value\n";
    }  
    echo "\n";
}  
  
/* Note: sqlsrv_field_metadata can be called on any statement
resource, pre- or post-execution. */
  
/* Free statement and connection resources. */
sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>

敏感性資料分類中繼資料

5.8.0 版中引進新選項 DataClassification，可讓使用者使用 存取 Microsoft SQL Server 2019 中的sqlsrv_field_metadata，需要 Microsoft ODBC Driver 17.4.2 或更新版本。

根據預設，選項 DataClassification 是 false，但當設定為 true 時，sqlsrv_field_metadata 所傳回的陣列將會填入敏感性資料分類中繼資料 (如果存在)。

以患者資料表為例：

CREATE TABLE Patients 
      [PatientId] int identity,
      [SSN] char(11),
      [FirstName] nvarchar(50),
      [LastName] nvarchar(50),
      [BirthDate] date)

我們可以將 SSN 和 BirthDate 資料行分類，如下所示：

ADD SENSITIVITY CLASSIFICATION TO [Patients].SSN WITH (LABEL = 'Highly Confidential - secure privacy', INFORMATION_TYPE = 'Credentials')
ADD SENSITIVITY CLASSIFICATION TO [Patients].BirthDate WITH (LABEL = 'Confidential Personal Data', INFORMATION_TYPE = 'Birthdays')

若要存取中繼資料，請叫用 sqlsrv_field_metadata，如下面的程式碼片段所示：

$tableName = 'Patients';
$tsql = "SELECT * FROM $tableName";
$stmt = sqlsrv_prepare($conn, $tsql, array(), array('DataClassification' => true));
if (sqlsrv_execute($stmt)) {
    $fieldmeta = sqlsrv_field_metadata($stmt);

    foreach ($fieldmeta as $f) {
        if (count($f['Data Classification']) > 0) {
            echo $f['Name'] . ": \n";
            print_r($f['Data Classification']); 
        }
    }
}

輸出將是：

SSN: 
Array
(
    [0] => Array
        (
            [Label] => Array
                (
                    [name] => Highly Confidential - secure privacy
                    [id] => 
                )

            [Information Type] => Array
                (
                    [name] => Credentials
                    [id] => 
                )

        )

)
BirthDate: 
Array
(
    [0] => Array
        (
            [Label] => Array
                (
                    [name] => Confidential Personal Data
                    [id] => 
                )

            [Information Type] => Array
                (
                    [name] => Birthdays
                    [id] => 
                )

        )

)

如果使用 sqlsrv_query 而不是 sqlsrv_prepare，可以修改上述程式碼片段，像這樣：

$tableName = 'Patients';
$tsql = "SELECT * FROM $tableName";
$stmt = sqlsrv_query($conn, $tsql, array(), array('DataClassification' => true));
$fieldmeta = sqlsrv_field_metadata($stmt);

foreach ($fieldmeta as $f) {
    $jstr = json_encode($f);
    echo $jstr . PHP_EOL;
}

如您在下面的 JSON 標記法中所見，如果資料分類中繼資料與資料行相關聯，就會加以顯示：

{"Name":"PatientId","Type":4,"Size":null,"Precision":10,"Scale":null,"Nullable":0,"Data Classification":[]}
{"Name":"SSN","Type":1,"Size":11,"Precision":null,"Scale":null,"Nullable":1,"Data Classification":[{"Label":{"name":"Highly Confidential - secure privacy","id":""},"Information Type":{"name":"Credentials","id":""}}]}
{"Name":"FirstName","Type":-9,"Size":50,"Precision":null,"Scale":null,"Nullable":1,"Data Classification":[]}
{"Name":"LastName","Type":-9,"Size":50,"Precision":null,"Scale":null,"Nullable":1,"Data Classification":[]}
{"Name":"BirthDate","Type":91,"Size":null,"Precision":10,"Scale":0,"Nullable":1,"Data Classification":[{"Label":{"name":"Confidential Personal Data","id":""},"Information Type":{"name":"Birthdays","id":""}}]}

使用預先定義的一組值進行敏感度排名

從 5.9.0 開始，PHP 驅動程式在使用 ODBC 驅動程式 17.4.2 或更新版本時新增了分類排名擷取。 使用者在使用 ADD SENSITIVITY CLASSIFICATION 分類任何資料欄位時，可以定義排名。

例如，如果使用者分別指派和 NONE 至 LOW BirthDate 和 SSN，JSON 標記法的顯示如下：

{"0":{"Label":{"name":"Confidential Personal Data","id":""},"Information Type":{"name":"Birthdays","id":""},"rank":0},"rank":0}
{"0":{"Label":{"name":"Highly Confidential - secure privacy","id":""},"Information Type":{"name":"Credentials","id":""},"rank":10},"rank":10}

如敏感度分類所示，排名的數值為：

0 for NONE
10 for LOW
20 for MEDIUM
30 for HIGH
40 for CRITICAL

因此，如果使用者在分類 BirthDate 資料行時定義 RANK=NONE，而非 RANK=CRITICAL，則分類中繼資料會是：

  array(7) {
    ["Name"]=>
    string(9) "BirthDate"
    ["Type"]=>
    int(91)
    ["Size"]=>
    NULL
    ["Precision"]=>
    int(10)
    ["Scale"]=>
    int(0)
    ["Nullable"]=>
    int(1)
    ["Data Classification"]=>
    array(2) {
      [0]=>
      array(3) {
        ["Label"]=>
        array(2) {
          ["name"]=>
          string(26) "Confidential Personal Data"
          ["id"]=>
          string(0) ""
        }
        ["Information Type"]=>
        array(2) {
          ["name"]=>
          string(9) "Birthdays"
          ["id"]=>
          string(0) ""
        }
        ["rank"]=>
        int(40)
      }
      ["rank"]=>
      int(40)
    }
  }

更新的 JSON 標記法如下所示：

{"0":{"Label":{"name":"Confidential Personal Data","id":""},"Information Type":{"name":"Birthdays","id":""},"rank":40},"rank":40}

相關內容

• SQLSRV 驅動程式 API 參考
• 常數 (Microsoft Drivers for PHP for SQL Server)
• 關於文件中的程式碼範例