sqlsrv_field_metadata
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 1 | ||
| bit | SQL_BIT (-7) | |||
| char | SQL_CHAR (1) | 0 <n< 8000 1 | ||
| 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 1 | ||
| ntext | SQL_WLONGVARCHAR (-10) | 1 GB | ||
| NUMERIC | SQL_NUMERIC (2) | 1/38 | 0/valor de precisión | |
| 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 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 1 | ||
| varchar | SQL_VARCHAR (12) | 0 <n< 8000 1 | ||
| 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)
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de