sqlsrv_field_metadata

文章
06/02/2023

擷取已備妥陳述式的欄位中繼資料。如需有關準備陳述式的詳細資訊，請參閱 sqlsrv_query 或 sqlsrv_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 ¹
bit	SQL_BIT (-7)
char	SQL_CHAR (1)			0 <n< 8000 ¹
日期	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 ¹
ntext	SQL_WLONGVARCHAR (-10)			1 GB
NUMERIC	SQL_NUMERIC (2)	1/38	0/有效位數值
NVARCHAR	SQL_WVARCHAR (-9)			0 <n< 4000 ¹
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 ¹
varchar	SQL_VARCHAR (12)			0 <n< 8000 ¹
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 或更新版本。

根據預設，選項 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=CRITICAL，而非 RANK=NONE，則分類中繼資料會是：

  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)

關於文件中的程式碼範例

分享方式：

sqlsrv_field_metadata

語法

參數

傳回值

範例

敏感性資料分類中繼資料

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

另請參閱

意見反映

更多資源