sqlsrv_field_metadata

下載 PHP 驅動程式

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

語法

  
sqlsrv_field_metadata( resource $stmt)  

參數

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

傳回值

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

Key 描述
名稱 欄位所對應的資料行名稱。
類型 對應至 SQL 類型的數值。
大小 字元類型 (char(n)、varchar(n)、nchar(n)、nvarchar(n)、XML) 之欄位的字元數目。 二進位類型 (binary(n)、varbinary(n)、UDT) 之欄位的位元組數目。 NULL 適用於其他 SQL Server 資料類型。
精確度 變數有效位數 (real、numeric、decimal、datetime2、datetimeoffset 和 time) 之類型的有效位數。 NULL 適用於其他 SQL Server 資料類型。
調整 變數小數位數 (numeric、decimal、datetime2、datetimeoffset 和 time) 之類型的小數位數。 NULL 適用於其他 SQL Server 資料類型。
Nullable 列舉的值,指出資料行可為 Null (SQLSRV_NULLABLE_YES)、資料行不可為 Null (SQLSRV_NULLABLE_NO),或不知道資料行是否可為 Null (SQLSRV_NULLABLE_UNKNOWN)。

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

SQL Server 2008 資料類型 類型 最小/最大的有效位數 最小/最大的小數位數 大小
BIGINT SQL_BIGINT (-5) 8
BINARY SQL_BINARY (-2) 0 <n< 8000 1
bit SQL_BIT (-7)
char SQL_CHAR (1) 0 <n< 8000 1
日期 SQL_TYPE_DATE (91) 10/10 0/0
Datetime SQL_TYPE_TIMESTAMP (93) 23/23 3/3
datetime2 SQL_TYPE_TIMESTAMP (93) 19/27 0/7
datetimeoffset SQL_SS_TIMESTAMPOFFSET (-155) 26/34 0/7
decimal SQL_DECIMAL (3) 1/38 0/有效位數值
FLOAT SQL_FLOAT (6) 4/8
image SQL_LONGVARBINARY (-4) 2 GB
int SQL_INTEGER (4)
money SQL_DECIMAL (3) 19/19 4/4
NCHAR SQL_WCHAR (-8) 0 <n< 4000 1
ntext SQL_WLONGVARCHAR (-10) 1 GB
NUMERIC SQL_NUMERIC (2) 1/38 0/有效位數值
NVARCHAR SQL_WVARCHAR (-9) 0 <n< 4000 1
real SQL_REAL (7) 4/4
smalldatetime SQL_TYPE_TIMESTAMP (93) 16/16 0/0
SMALLINT SQL_SMALLINT (5) 2 個位元組
Smallmoney SQL_DECIMAL (3) 10/10 4/4
sql_variant SQL_SS_VARIANT (-150) 變動
文字 SQL_LONGVARCHAR (-1) 2 GB
time SQL_SS_TIME2 (-154) 8/16 0/7
timestamp SQL_BINARY (-2) 8 個位元組
TINYINT SQL_TINYINT (-6) 1 個位元組
udt SQL_SS_UDT (-151) 變動
UNIQUEIDENTIFIER SQL_GUID (-11) 16
varbinary SQL_VARBINARY (-3) 0 <n< 8000 1
varchar SQL_VARCHAR (12) 0 <n< 8000 1
Xml SQL_SS_XML (-152) 0

(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,可讓使用者使用 sqlsrv_field_metadata 存取 Microsoft SQL Server 2019 中的敏感性資料分類中繼資料,需要 Microsoft ODBC Driver 17.4.2 或更新版本。

根據預設,選項 DataClassificationfalse,但當設定為 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 Driver 17.4.2 或更新版本時新增了分類排名擷取。 當使用者使用 ADD SENSITIVITY CLASSIFICATION 來分類任何資料行時,可能會定義排名。

例如,如果使用者分別指派 NONELOW 至 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

因此,如果使用者在 RANK=NONE 分類 BirthDate 資料行時定義 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)

關於文件中的程式碼範例