sp_xml_preparedocument (Transact-SQL)

Se aplica a:SQL ServerAzure SQL Database

Lee el texto XML proporcionado como entrada, analiza el texto mediante el analizador MSXML (msxmlsql.dll) y proporciona el documento analizado en un estado listo para su consumo. Este documento analizado es una representación en árbol de varios nodos en el documento XML: elementos, atributos, texto, comentarios, etc.

sp_xml_preparedocument devuelve un identificador que se puede usar para tener acceso a la representación interna recién creada del documento XML. Este identificador es válido durante la sesión o hasta que el identificador se invalida ejecutando sp_xml_removedocument.

Un documento analizado se almacena en la memoria caché interna de SQL Server. El analizador MSXML puede usar una octava parte de la memoria total disponible para SQL Server. Para evitar quedarse sin memoria, ejecute sp_xml_removedocument para liberar la memoria en cuanto el documento ya no sea necesario. En muchos casos, el método nodes() podría ser una alternativa mejor y ayudar a evitar un uso excesivo de memoria.

Para la compatibilidad con versiones anteriores, sp_xml_preparedocument contrae los caracteres CR (char(13)) y LF (char(10)) en los atributos, incluso si estos caracteres están entitizados.

Nota:

El analizador XML invocado por sp_xml_preparedocument puede analizar dtD internos y declaraciones de entidad. Dado que se pueden usar DTD y declaraciones de entidad construidos de forma malintencionada para realizar un ataque por denegación de servicio, se recomienda encarecidamente que los usuarios no pasen directamente documentos XML de orígenes que no son de confianza a sp_xml_preparedocument.

Para mitigar los ataques de expansión de entidades recursivas, sp_xml_preparedocument limita a 10 000 el número de entidades que se pueden expandir debajo de una sola entidad en el nivel superior de un documento. Este límite no se aplica a los caracteres o entidades numéricas. Este límite permite almacenar documentos con muchas entidades, pero evita que cualquier entidad se expanda de forma recursiva en una cadena con más de 10.000 expansiones.

sp_xml_preparedocument limita el número de elementos que se pueden abrir al mismo tiempo a 256.

Convenciones de sintaxis de Transact-SQL

Sintaxis

sp_xml_preparedocument hdoc OUTPUT
    [ , xmltext ]
    [ , xpath_namespaces ]
[ ; ]

Argumentos

hdoc

Identificador del documento recién creado. hdoc es un entero.

[ xmltext ]

Documento XML original. El analizador MSXML analiza este documento XML. xmltext es un parámetro de texto: char, nchar, varchar, nvarchar, text, ntext o xml. El valor predeterminado es NULL, en cuyo caso se crea una representación interna de un documento XML vacío.

Nota:

sp_xml_preparedocument solo puede procesar texto o XML sin tipo. Si el valor de instancia que se va a utilizar como entrada ya es XML con tipo, primero conviértalo a una nueva instancia XML sin tipo o a una cadena y, a continuación, pase ese valor como entrada. Para obtener más información, vea Comparar XML con tipo y XML sin tipo.

[ xpath_namespaces ]

Especifica las declaraciones de espacio de nombres que se utilizan en las expresiones XPath de fila y columna de OPENXML. xpath_namespaces es un parámetro de texto: char, nchar, varchar, nvarchar, text, ntext o xml.

El valor predeterminado es <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces proporciona los URI de espacio de nombres para los prefijos usados en las expresiones XPath de OPENXML, con un documento XML bien formado. xpath_namespaces declara el prefijo que se debe usar para hacer referencia al espacio de nombres urn:schemas-microsoft-com:xml-metaprop; esto proporciona metadatos sobre los elementos XML analizados. Aunque puede redefinir el prefijo de espacio de nombres para el espacio de nombres de metapropiedad mediante esta técnica, este espacio de nombres no se pierde. El prefijo mp sigue siendo válido para urn:schemas-microsoft-com:xml-metaprop aunque xpath_namespaces no contenga dicha declaración.

Valores de código de retorno

0 (correcto) o > 0 (erróneo).

Permisos

Debe pertenecer al rol public .

Ejemplos

A Preparación de una representación interna para un documento XML bien formado

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada. En la llamada a sp_xml_preparedocument se utiliza la asignación predeterminada del prefijo de espacio de nombres.

DECLARE @hdoc INT;
DECLARE @doc VARCHAR(1000);

SET @doc = '
<ROOT>
<Customer CustomerID="VINET" ContactName="Paul Henriot">
   <Order CustomerID="VINET" EmployeeID="5" OrderDate="1996-07-04T00:00:00">
      <OrderDetail OrderID="10248" ProductID="11" Quantity="12"/>
      <OrderDetail OrderID="10248" ProductID="42" Quantity="10"/>
   </Order>
</Customer>
<Customer CustomerID="LILAS" ContactName="Carlos Gonzlez">
   <Order CustomerID="LILAS" EmployeeID="3" OrderDate="1996-08-16T00:00:00">
      <OrderDetail OrderID="10283" ProductID="72" Quantity="3"/>
   </Order>
</Customer>
</ROOT>';

--Create an internal representation of the XML document.
EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc;

-- Remove the internal representation.
EXEC sp_xml_removedocument @hdoc;

B. Preparación de una representación interna para un documento XML bien formado con un DTD

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada. El procedimiento almacenado valida el documento cargado contra el DTD incluido en el documento. En la llamada a sp_xml_preparedocument se utiliza la asignación predeterminada del prefijo de espacio de nombres.

DECLARE @hdoc int;
DECLARE @doc varchar(2000);
SET @doc = '
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE root
[<!ELEMENT root (Customers)*>
<!ELEMENT Customers EMPTY>
<!ATTLIST Customers CustomerID CDATA #IMPLIED ContactName CDATA #IMPLIED>]>
<root>
<Customers CustomerID="ALFKI" ContactName="Maria Anders"/>
</root>';

EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc;

C. Especificar un URI de espacio de nombres

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada. La llamada a sp_xml_preparedocument conserva el mp prefijo a la asignación del espacio de nombres de metapropiedad y agrega el xyz prefijo de asignación al espacio de nombres urn:MyNamespace.

DECLARE @hdoc int;
DECLARE @doc varchar(1000);
SET @doc ='
<ROOT>
<Customer CustomerID="VINET" ContactName="Paul Henriot">
   <Order CustomerID="VINET" EmployeeID="5"
           OrderDate="1996-07-04T00:00:00">
      <OrderDetail OrderID="10248" ProductID="11" Quantity="12"/>
      <OrderDetail OrderID="10248" ProductID="42" Quantity="10"/>
   </Order>
</Customer>
<Customer CustomerID="LILAS" ContactName="Carlos Gonzlez">
   <Order CustomerID="LILAS" EmployeeID="3"
           OrderDate="1996-08-16T00:00:00">
      <OrderDetail OrderID="10283" ProductID="72" Quantity="3"/>
   </Order>
</Customer>
</ROOT>'
--Create an internal representation of the XML document.
EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc, '<ROOT xmlns:xyz="urn:MyNamespace"/>';