sqlsrv_field_metadata

Artículo
06/02/2023

Recupera los metadatos de los campos de una instrucción preparada. Para obtener información acerca de cómo preparar una instrucción, consulte sqlsrv_query o sqlsrv_prepare. Tenga en cuenta que se puede llamar a sqlsrv_field_metadata en cualquier instrucción preparada, ya sea antes o después de la ejecución.

Sintaxis

  
sqlsrv_field_metadata( resource $stmt)

Parámetros

$stmt: un recurso de instrucción para el que se buscan metadatos de campo.

Valor devuelto

Una matriz de matrices o el valor False. La matriz consta de una matriz por cada campo del conjunto de resultados. Cada submatriz contiene las claves que se describen en la siguiente tabla. Si se produce un error en el proceso de recuperación de los metadatos de los campos, se devuelve el valor False .

Clave	Descripción
NOMBRE	Nombre de la columna a la que corresponde el campo.
Tipo	Valor numérico que corresponde a un tipo SQL.
Tamaño	Número de caracteres de los campos de tipo de carácter: char(n), varchar(n), nchar(n), nvarchar(n) y XML. Número de bytes de los campos de tipo binario: binary(n), varbinary(n) y UDT. En otros tipos de datos de SQL Server, se devuelveNULL .
Precisión	La precisión de los tipos de precisión de variables: real, numeric, decimal, datetime2, datetimeoffset y time. En otros tipos de datos de SQL Server, se devuelveNULL .
Escala	La escala de los tipos de escala de variables: numeric, decimal, datetime2, datetimeoffset y time. En otros tipos de datos de SQL Server, se devuelveNULL .
Nullable	Un valor enumerado que indica si la columna acepta valores Null (SQLSRV_NULLABLE_YES), no los acepta (SQLSRV_NULLABLE_NO) o no se sabe si los acepta (SQLSRV_NULLABLE_UNKNOWN).

En la tabla siguiente se proporciona más información sobre las claves de cada submatriz (consulte la documentación de SQL Server para obtener más información sobre estos tipos):

Tipo de datos de SQL Server 2008	Tipo	Precisión mín./máx.	Escala mín./máx.	Tamaño
bigint	SQL_BIGINT (-5)			8
binary	SQL_BINARY (-2)			0 <n< 8000 ¹
bit	SQL_BIT (-7)
char	SQL_CHAR (1)			0 <n< 8000 ¹
Fecha	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/valor de precisión
FLOAT	SQL_FLOAT (6)	4/8
imagen	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/valor de precisión
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
texto	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) Un valor de cero (0) indica que se permite el tamaño máximo.

La clave que acepta valores Null puede ser yes o no.

Ejemplo

En el ejemplo siguiente se crea un recurso de instrucción y, luego, se recuperan y muestran los metadatos de los campos. En el ejemplo se da por hecho que SQL Server y la base de datos AdventureWorks están instalados en el equipo local. Los resultados se agregan a la consola cuando se ejecuta el ejemplo en la línea de comandos.

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

Metadatos de clasificación de datos confidenciales

En la versión 5.8.0, se incluye una nueva opción DataClassification para que los usuarios tengan acceso a los metadatos de clasificación de datos confidenciales en Microsoft SQL Server 2019 con sqlsrv_field_metadata, que requiere Microsoft ODBC Driver 17.4.2 o versiones posteriores.

De forma predeterminada, la opción DataClassification es false, pero cuando se establece en true, la matriz devuelta por sqlsrv_field_metadata se rellenará con los metadatos de la clasificación de datos confidenciales, si existe.

Tome como ejemplo una tabla Patients (Pacientes):

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

Podemos clasificar las columnas SSN y BirthDate como se muestra a continuación:

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

Para acceder a los metadatos, invoque sqlsrv_field_metadata como se muestra en el fragmento de código siguiente:

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

El resultado será:

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

        )

)

Si usa sqlsrv_query en lugar de sqlsrv_prepare, el fragmento de código anterior se puede modificar, como se indica a continuación:

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

Como puede ver en la representación JSON siguiente, se muestran los metadatos de clasificación de datos si están asociados a las columnas:

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

Rango de confidencialidad con un conjunto predefinido de valores

A partir de la versión 5.9.0, los controladores de PHP incluyen la recuperación de rangos de clasificación al usar el controlador ODBC 17.4.2 o versiones posteriores. El usuario puede definir un rango al usar la instrucción ADD SENSITIVITY CLASSIFICATION para clasificar cualquier columna de datos.

Por ejemplo, si el usuario asigna NONE y LOW a BirthDate y SSN respectivamente, la representación JSON se muestra de la siguiente manera:

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

Tal y como se muestra en la clasificación de confidencialidad, los valores numéricos de los rangos son:

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

Por lo tanto, si en lugar de RANK=NONE, el usuario define RANK=CRITICAL al clasificar la columna BirthDate, los metadatos de clasificación serán los siguientes:

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

A continuación se muestra la representación JSON actualizada:

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

Consulte también

Referencia de API del controlador SQLSRV

Constantes (controladores de Microsoft para PHP para SQL Server)

Sobre los ejemplos de código de la documentación

Compartir vía