sqlsrv_field_metadata
Recupera metadados para os campos de uma instrução preparada. Para obter informações sobre como preparar uma instrução, consulte sqlsrv_query ou sqlsrv_prepare. Observe que sqlsrv_field_metadata pode ser chamado em qualquer instrução preparada, antes ou após a execução.
Sintaxe
sqlsrv_field_metadata( resource $stmt)
Parâmetros
$stmt: um recurso de instrução para o qual os metadados de campo são pesquisados.
Valor de retorno
Uma matriz de matrizes ou false. A matriz consiste em uma matriz para cada campo no conjunto de resultados. Cada submatriz tem chaves, conforme descrito na tabela a seguir. Se ocorrer um erro na recuperação de metadados do campo, será retornado false .
| Chave | Descrição |
|---|---|
| Nome | Nome da coluna correspondente ao campo. |
| Type | Valor numérico que corresponde a um tipo SQL. |
| Tamanho | Número de caracteres de campos do tipo character (char(n), varchar(n), nchar(n), nvarchar(n), XML). Número de bytes para campos do tipo binary (binary(n), varbinary(n), UDT). NULL para outros tipos de dados do SQL Server. |
| Precisão | A precisão dos tipos de precisão variável (real, numeric, decimal, datetime2, datetimeoffset e time). NULL para outros tipos de dados do SQL Server. |
| Escala | A escala dos tipos de escala variável (numeric, decimal, datetime2, datetimeoffset e time). NULL para outros tipos de dados do SQL Server. |
| Nullable | Um valor enumerado que indica se a coluna é anulável (SQLSRV_NULLABLE_YES), não anulável (SQLSRV_NULLABLE_NO) ou se não se sabe se a coluna é anulável (SQLSRV_NULLABLE_UNKNOWN). |
A tabela a seguir fornece mais informações sobre as chaves para cada submatriz (consulte a documentação do SQL Server para obter mais informações sobre esses tipos):
| Tipos de dados do SQL Server 2008 | Type | Precisão mínima/máxima | Escala mínima/máxima | Tamanho |
|---|---|---|---|---|
| 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 | ||
| Data | 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 da precisão | |
| 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/valor da precisão | |
| 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) | variável | ||
| 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) | variável | ||
| 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) Zero (0) indica que o tamanho máximo é permitido.
A chave Nullable pode ser yes ou no.
Exemplo
O exemplo a seguir cria um recurso de instrução. Em seguida, recupera e exibe os metadados de campo. O exemplo supõe que o SQL Server e o banco de dados AdventureWorks estejam instalados no computador local. Toda a saída será gravada no console quando o exemplo for executado da linha de comando.
<?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);
?>
Metadados de classificação de dados de confidencialidade
Uma nova opção DataClassification foi introduzida na versão 5.8.0 para os usuários acessarem os metadados de classificação de dados de confidencialidade no Microsoft SQL Server 2019 usando o sqlsrv_field_metadata, que requer o Microsoft ODBC Driver 17.4.2 ou posterior.
Por padrão, a opção DataClassification é false, porém, quando definido como true, a matriz mencionada anteriormente como sqlsrv_field_metadata será preenchida com os metadados de classificação de dados de confidencialidade, se existirem.
Pegue a tabela de Pacientes, por exemplo:
CREATE TABLE Patients
[PatientId] int identity,
[SSN] char(11),
[FirstName] nvarchar(50),
[LastName] nvarchar(50),
[BirthDate] date)
Podemos classificar as colunas SSN e BirthDate, como mostrado abaixo:
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 acessar os metadados, invoque sqlsrv_field_metadata, como mostrado no trecho abaixo:
$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']);
}
}
}
A saída 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] =>
)
)
)
Se estiver usando sqlsrv_query em vez de sqlsrv_prepare, o trecho acima poderá ser modificado, desta forma:
$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 você pode ver na representação JSON abaixo, os metadados de classificação de dados são exibidos se associados às colunas:
{"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":""}}]}
Classificação de Confidencialidade usando um conjunto de valores predefinido
Da versão 5.9.0 em diante, os drivers PHP adicionarão uma recuperação da ordem de classificação ao usar o driver ODBC 17.4.2 ou posterior. O usuário poderá definir a classificação ao usar a opção ADICIONAR CLASSIFICAÇÃO DE CONFIDENCIALIDADE para classificar colunas de dados.
Por exemplo, caso o usuário atribua NONE e LOW a BirthDate e SSN, respectivamente, a representação JSON será mostrada da seguinte maneira:
{"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}
Conforme mostrado na classificação de confidencialidade, os valores numéricos das classificações são:
0 for NONE
10 for LOW
20 for MEDIUM
30 for HIGH
40 for CRITICAL
Portanto, em vez de RANK=NONE, caso o usuário defina RANK=CRITICAL ao classificar a coluna BirthDate, os metadados de classificação serão:
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 representação JSON atualizada será mostrada abaixo:
{"0":{"Label":{"name":"Confidential Personal Data","id":""},"Information Type":{"name":"Birthdays","id":""},"rank":40},"rank":40}
Consulte Também
Referência da API do driver SQLSRV