sp_xml_preparedocument (Transact-SQL)sp_xml_preparedocument (Transact-SQL)

SE APLICA A: síSQL Server síAzure SQL Database noAzure SQL Data Warehouse noAlmacenamiento de datos paralelos APPLIES TO: yesSQL Server yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Lee el texto de XML proporcionado como entrada, analiza el texto con el analizador MSXML (Msxmlsql.dll) y proporciona el documento analizado en un estado apto para su uso.Reads the XML text provided as input, parses the text by using the MSXML parser (Msxmlsql.dll), and provides the parsed document in a state ready for consumption. Este documento analizado es una representación en árbol de varios nodos en el documento XML: elementos, atributos, texto, comentarios, etc.This parsed document is a tree representation of the various nodes in the XML document: elements, attributes, text, comments, and so on.

sp_xml_preparedocument devuelve un identificador que puede utilizarse para tener acceso a la representación interna recién creada del documento XML.sp_xml_preparedocument returns a handle that can be used to access the newly created internal representation of the XML document. Este identificador es válido para la duración de la sesión o hasta que el identificador se invalida ejecutando sp_xml_removedocument.This handle is valid for the duration of the session or until the handle is invalidated by executing sp_xml_removedocument.

Nota

Un documento analizado se guarda en la caché interna de SQL ServerSQL Server.A parsed document is stored in the internal cache of SQL ServerSQL Server. El analizador MSXML usa un octavo de la memoria total disponible para SQL ServerSQL Server.The MSXML parser uses one-eighth the total memory available for SQL ServerSQL Server. Para evitar quedarse sin memoria, ejecute sp_xml_removedocument para liberar la memoria.To avoid running out of memory, run sp_xml_removedocument to free up the memory.

Nota

Para versiones anteriores compatibilidad, sp_xml_preparedocument contrae el CR (char(13)) y LF (char(10)) caracteres en atributos incluso si estos caracteres se crean las entidades.For backwards compatibility, sp_xml_preparedocument collapses the CR (char(13)) and LF (char(10)) characters in attributes even if these characters are entitized.

Nota

El analizador XML invocado por sp_xml_preparedocument puede analizar DTD internas y las declaraciones de entidad.The XML parser invoked by sp_xml_preparedocument can parse internal DTDs and entity declarations. Ya creadas de forma malintencionada DTD y entidades declaraciones pueden usarse para realizar un ataque de denegación de servicio, se recomienda encarecidamente que los usuarios no pasen directamente documentos XML de fuentes no confiables a sp_xml_preparedocument.Because maliciously constructed DTDs and entity declarations can be used to perform a denial of service attack, we strongly recommend that users not directly pass XML documents from untrusted sources to sp_xml_preparedocument.

Para mitigar los ataques de expansión de entidades recursivos, sp_xml_preparedocument limita a 10.000 el número de entidades que pueden expandirse debajo de una sola entidad en el nivel superior de un documento.To mitigate recursive entity expansion attacks, sp_xml_preparedocument limits to 10,000 the number of entities that can be expanded underneath a single entity at the top level of a document. Este límite no se aplica a los caracteres o entidades numéricas.The limit does not apply to character or numeric entities. 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.This limit allows documents with many entity references to be stored, but prevents any one entity from being recursively expanded in a chain longer than 10,000 expansions.

Nota

sp_xml_preparedocument limita el número de elementos que se pueden abrir simultáneamente a 256.sp_xml_preparedocument limits the number of elements that can be open at one time to 256.

Icono de vínculo de tema Convenciones de sintaxis de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxisSyntax

  
sp_xml_preparedocument  
hdoc   
OUTPUT  
[ , xmltext ]  
[ , xpath_namespaces ]   

ArgumentosArguments

hdochdoc
Es el identificador del documento recién creado.Is the handle to the newly created document. hdoc es un entero.hdoc is an integer.

[ xmltext ][ xmltext ]
Es el documento XML original.Is the original XML document. El analizador MSXML analiza este documento XML.The MSXML parser parses this XML document. XmlText es un parámetro de texto: char, nchar, varchar, nvarchar, texto, ntext o xml.xmltext is a text parameter: char, nchar, varchar, nvarchar, text, ntext or xml. El valor predeterminado es NULL, en cuyo caso se crea una representación interna de un documento XML vacío.The default value is NULL, in which case an internal representation of an empty XML document is created.

Nota

sp_xml_preparedocument sólo puede procesar texto o XML sin tipo.sp_xml_preparedocument can only process text or untyped XML. 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.If an instance value to be used as input is already typed XML, first cast it to a new untyped XML instance or as a string and then pass that value as input. Para obtener más información, vea Comparar XML con tipo y XML sin tipo.For more information, see Compare Typed XML to Untyped XML.

[ xpath_namespaces ][ xpath_namespaces ]
Especifica las declaraciones de espacio de nombres que se utilizan en las expresiones XPath de fila y columna de OPENXML.Specifies the namespace declarations that are used in row and column XPath expressions in OPENXML. xpath_namespaces es un parámetro de texto: char, nchar, varchar, nvarchar, texto, ntext o xml.xpath_namespaces is a text parameter: char, nchar, varchar, nvarchar, text, ntext or xml.

El valor predeterminado es <xmlns:mp de raíz = "urn: schemas-microsoft-com-metaprop" > .The default value is <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces proporciona el URI de espacio de nombres para los prefijos utilizados en las expresiones de XPath de OPENXML mediante un documento XML bien formado.xpath_namespaces provides the namespace URIs for the prefixes used in the XPath expressions in OPENXML by means of a well-formed XML document. xpath_namespaces declara el prefijo que debe usarse para hacer referencia al espacio de nombres urn: schemas-microsoft-com-metaprop; proporciona metadatos sobre los elementos XML analizados.xpath_namespaces declares the prefix that must be used to refer to the namespace urn:schemas-microsoft-com:xml-metaprop; this provides metadata about the parsed XML elements. Aunque puede redefinir el prefijo del espacio de nombres para el espacio de nombres de metapropiedad mediante esta técnica, este espacio de nombres no se pierde.Although you can redefine the namespace prefix for the metaproperty namespace by using this technique, this namespace is not lost. El prefijo mp sigue siendo válido para urn: schemas-microsoft-com-metaprop aunque xpath_namespaces no contenga esa declaración.The prefix mp is still valid for urn:schemas-microsoft-com:xml-metaprop even if xpath_namespaces contains no such declaration.

Valores de código de retornoReturn Code Values

0 (correcto) o > 0 (error)0 (success) or >0 (failure)

PermisosPermissions

Debe pertenecer al rol public .Requires membership in the public role.

EjemplosExamples

A.A. Preparar una representación interna para un documento XML bien construidoPreparing an internal representation for a well-formed XML document

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada.The following example returns a handle to the newly created internal representation of the XML document that is provided as input. En la llamada a sp_xml_preparedocument se utiliza la asignación predeterminada del prefijo de espacio de nombres.In the call to sp_xml_preparedocument, a default namespace prefix mapping is used.

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.B. Preparar una representación interna de un documento XML bien construido con un DTDPreparing an internal representation for a well-formed XML document with a 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.The following example returns a handle to the newly created internal representation of the XML document that is provided as input. El procedimiento almacenado valida el documento cargado contra el DTD incluido en el documento.The stored procedure validates the document loaded against the DTD included in the document. En la llamada a sp_xml_preparedocument se utiliza la asignación predeterminada del prefijo de espacio de nombres.In the call to sp_xml_preparedocument, a default namespace prefix mapping is used.

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.C. Especificar un URI de espacio de nombresSpecifying a namespace URI

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada.The following example returns a handle to the newly created internal representation of the XML document that is provided as input. La llamada a sp_xml_preparedocument conserva la mp prefijo para la asignación de espacio de nombres de metapropiedad y agrega el xyz prefijo de asignación al espacio de nombres urn:MyNamespace.The call to sp_xml_preparedocument preserves the mp prefix to the metaproperty namespace mapping and adds the xyz mapping prefix to the namespace 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"/>';  

Vea tambiénSee Also


Procedures(Transact-SQL) almacenados de XML XML Stored Procedures(Transact-SQL)
Procedures(Transact-SQL) almacenados del sistema System Stored Procedures(Transact-SQL)
OPENXML(Transact-SQL) OPENXML(Transact-SQL)
sys.dm_exec_xml_handles (Transact-SQL) sys.dm_exec_xml_handles (Transact-SQL)
sp_xml_removedocument (Transact-SQL)sp_xml_removedocument (Transact-SQL)