sqlsrv_field_metadata

Artikel
06/02/2023

Ruft Metadaten für die Felder einer vorbereiteten Anweisung ab. Informationen zum Vorbereiten einer Anweisung finden Sie unter sqlsrv_query oder sqlsrv_prepare. Beachten Sie, dass sqlsrv_field_metadata sowohl vor als auch nach der Ausführung jeder Anweisung aufgerufen werden kann.

Syntax

  
sqlsrv_field_metadata( resource $stmt)

Parameter

$stmt: Eine Anweisungsressource für die Feldmetadaten gewünscht werden.

Rückgabewert

Ein Array von Arrays oder false. Das Array besteht aus einem Array für jedes Feld im Resultset. Jedes Teilarray hat Schlüssel, wie in der unten stehenden Tabelle beschrieben. Falls beim Abrufen der Feldmetadaten ein Fehler auftritt, wird false zurückgegeben.

Key	BESCHREIBUNG
Name	Name der Spalte, der das Feld entspricht
Typ	Numerischer Wert, der einem SQL-Typ entspricht
Size	Anzahl der Zeichen für die Felder eines bestimmten Zeichentyps (char(n), varchar(n), nchar(n), nvarchar(n), XML) Anzahl der Bytes für Felder vom Typ „binär“ (binary(n), varbinary(n), UDT). NULL für andere SQL Server-Datentypen.
Genauigkeit	Die Genauigkeit für die Typen mit variabler Genauigkeit (real, numeric, decimal, datetime2, datetimeoffset und time). NULL für andere SQL Server-Datentypen.
Skalieren	Die Skalierung für die Typen mit variabler Skalierung (numeric, decimal, datetime2, datetimeoffset und time). NULL für andere SQL Server-Datentypen.
Nullable	Ein Aufzählungswert, der anzeigt, ob die Spalte NULL-Werte zulässt (SQLSRV_NULLABLE_YES) oder nicht (SQLSRV_NULLABLE_NO), oder ob diese Eigenschaft nicht bekannt ist (SQLSRV_NULLABLE_UNKNOWN).

Die folgende Tabelle enthält mehr Informationen zu den Schlüsseln für jedes Teilarray (weiter Informationen zu diesen Typen finden Sie in der Dokumentation zu SQL Server):

SQL Server 2008-Datentyp	Typ	Min/Max Genauigkeit	Min/Max Skalierung	Size
BIGINT	SQL_BIGINT (-5)			8
BINARY	SQL_BINARY (-2)			0 <n< 8000 ¹
bit	SQL_BIT (-7)
char	SQL_CHAR (1)			0 <n< 8000 ¹
date	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/Genauigkeitswert
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/Genauigkeitswert
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 Bytes
Smallmoney	SQL_DECIMAL (3)	10/10	4/4
sql_variant	SQL_SS_VARIANT (-150)			-Variable
Text	SQL_LONGVARCHAR (-1)			2 GB
time	SQL_SS_TIME2 (-154)	8/16	0/7
timestamp	SQL_BINARY (-2)			8 Bytes
TINYINT	SQL_TINYINT (-6)			1 Byte
udt	SQL_SS_UDT (-151)			-Variable
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) Die Null (0) gibt an, das die Maximalgröße zulässig ist.

Ein Schlüssel der NULL-Werte zulässt, kann entweder „Ja“ oder „Nein“ sein.

Beispiel

Das folgende Beispiel erstellt eine Anweisungsressource, ruft die Feldmetadaten ab und stellt sie dar. Das Beispiel setzt voraus, dass SQL Server und die AdventureWorks-Datenbank auf dem lokalen Computer installiert sind. Wenn das Beispiel über die Befehlszeile ausgeführt wird, werden alle Ausgaben in die Konsole geschrieben.

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

Klassifizierungsmetadaten zu Vertraulichkeitsdaten

Ab Version 5.8.0 ist die neue Option DataClassification verfügbar, damit Benutzer in Microsoft SQL Server 2019 mithilfe von sqlsrv_field_metadata auf die Klassifizierungsmetadaten zu Vertraulichkeitsdaten zugreifen können. Hierfür wird der Microsoft ODBC Driver 17.4.2 oder höher benötigt.

Die Option DataClassification entspricht standardmäßig false. Wenn sie jedoch auf true festgelegt wird, wird das von sqlsrv_field_metadata zurückgegebene Array mit den Klassifizierungsmetadaten zu Vertraulichkeitsdaten aufgefüllt, falls vorhanden.

Hier als Beispiel eine Patiententabelle:

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

Die Spalten „SSN“ und „BirthDate“ können wie unten dargestellt klassifiziert werden:

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')

Rufen Sie sqlsrv_field_metadata wie im folgenden Codeausschnitt gezeigt auf, um auf die Metadaten zuzugreifen:

$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']); 
        }
    }
}

Ausgabe:

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] => 
                )

        )

)

Wenn Sie sqlsrv_query anstelle von sqlsrv_prepare verwenden, können Sie den obigen Codeausschnitt wie folgt anpassen:

$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;
}

Wie in der folgenden JSON-Darstellung veranschaulicht, werden die gezeigten Datenklassifizierungsmetadaten den Spalten zugeordnet:

{"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":""}}]}

Vertraulichkeitsbewertung mithilfe vordefinierter Werte

Ab 5.9.0 können PHP-Treiber bei Verwendung von ODBC-Treibern mit Version 17.4.2 und höher Klassifizierungsbewertungen abrufen. Mithilfe von ADD SENSITIVITY CLASSIFICATION können Benutzer eine Bewertung definieren, um Datenspalten zu klassifizieren.

Wenn ein Benutzer beispielsweise NONE und LOW jeweils BirthDate und SSN zuweist, sieht die JSON-Darstellung folgendermaßen aus:

{"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}

Wie bei der Vertraulichkeitsklassifizierung ersichtlich wird, lauten die numerischen Werte für die Bewertungen wie folgt:

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

Deshalb lauten die Klassifizierungsmetadaten folgendermaßen, wenn der Benutzer RANK=CRITICAL anstelle von RANK=NONE beim Klassifizieren der Spalte BirthDate definiert:

  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)
    }
  }

Unten sehen Sie die aktualisierte JSON-Darstellung:

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

Weitere Informationen

API-Referenz für den SQLSRV-Treiber

Konstanten (Microsoft-Treiber für PHP für SQL Server)

Informationen zu den Codebeispielen in der Dokumentation

Teilen über