sp_xml_preparedocument (Transact-SQL)

  • Articolo

Si applica a: SQL Server Database SQL di Azure

Legge il testo XML fornito come input, analizza il testo usando il parser MSXML (msxmlsql.dll) e fornisce il documento analizzato in uno stato pronto per l'utilizzo. Il documento analizzato corrisponde a una rappresentazione ad albero dei vari nodi (elementi, attributi, testo, commenti e così via) del documento XML.

sp_xml_preparedocument restituisce un handle che può essere utilizzato per accedere alla rappresentazione interna appena creata del documento XML. Questo handle è valido durante la sessione o fino a quando l'handle non viene invalidato eseguendo sp_xml_removedocument.

Un documento analizzato viene archiviato nella cache interna di SQL Server. Il parser MSXML può usare un ottavo della memoria totale disponibile per SQL Server. Per evitare l'esaurimento della memoria, eseguire sp_xml_removedocument per liberare la memoria non appena il documento non è più necessario. In molti casi, il metodo nodes() potrebbe essere un'alternativa migliore e contribuire a evitare un uso eccessivo della memoria.

Per la compatibilità con le versioni precedenti, sp_xml_preparedocument comprime i caratteri CR (char(13)) e LF (char(10)) negli attributi anche se questi caratteri sono entità.

Nota

Il parser XML richiamato da sp_xml_preparedocument può analizzare le dichiarazioni di entità e DTD interne. Poiché i DTD e le dichiarazioni di entità creati in modo dannoso possono essere usati per eseguire un attacco Denial of Service, è consigliabile che gli utenti non passino direttamente documenti XML da origini non attendibili a sp_xml_preparedocument.

Per attenuare gli attacchi di espansione delle entità ricorsive, sp_xml_preparedocument limita a 10.000 il numero di entità che possono essere espanse sotto una singola entità al livello superiore di un documento. Il limite non si applica alle entità di tipo carattere o numerico. e consente di archiviare documenti con numerosi riferimenti a entità impedendo tuttavia l'espansione ricorsiva di qualsiasi entità in una catena di lunghezza superiore a 10.000 espansioni.

sp_xml_preparedocument limita il numero di elementi che possono essere aperti contemporaneamente a 256.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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

Argomenti

hdoc

Handle del documento appena creato. hdoc è un numero intero.

[ xmltext ]

Documento XML originale. Il parser MSXML analizza il documento XML. xmltext è un parametro di testo: char, nchar, varchar, nvarchar, text, ntext o xml. Il valore predefinito è NULL, nel qual caso viene creata una rappresentazione interna di un documento XML vuoto.

Nota

sp_xml_preparedocument può elaborare solo testo o XML non tipizzato. Se un valore istanza da utilizzare come input è già XML tipizzato, eseguire innanzitutto il cast di tale valore in una nuova istanza XML non tipizzata oppure come stringa, quindi passare il valore come input. Per altre informazioni, vedere Confrontare dati XML tipizzati con dati XML non tipizzati.

[ xpath_namespaces ]

Specifica le dichiarazioni degli spazi dei nomi utilizzate nelle espressioni XPath di riga e colonna in OPENXML. xpath_namespaces è un parametro di testo: char, nchar, varchar, nvarchar, text, ntext o xml.

Il valore predefinito è <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces fornisce gli URI dello spazio dei nomi per i prefissi usati nelle espressioni XPath in OPENXML, con un documento XML ben formato. xpath_namespaces dichiara il prefisso che deve essere utilizzato per fare riferimento allo spazio dei nomi urn:schemas-microsoft-com:xml-metaprop. Vengono forniti i metadati sugli elementi XML analizzati. Sebbene sia possibile ridefinire il prefisso dello spazio dei nomi per lo spazio dei nomi metaproperty usando questa tecnica, questo spazio dei nomi non viene perso. Il prefisso mp è ancora valido per urn:schemas-microsoft-com:xml-metaprop anche se xpath_namespaces non contiene alcuna dichiarazione di questo tipo.

Valori del codice restituito

0 (esito positivo) o > 0 (errore).

Autorizzazioni

È richiesta l'appartenenza al ruolo public .

Esempi

R. Preparare una rappresentazione interna per un documento XML ben formato

Nell'esempio seguente viene restituito un handle per la nuova rappresentazione interna del documento XML specificato come input. Nella chiamata a sp_xml_preparedocument viene utilizzato il mapping predefinito per i prefissi degli spazi dei nomi.

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. Preparare una rappresentazione interna per un documento XML ben formato con un DTD

Nell'esempio seguente viene restituito un handle per la nuova rappresentazione interna del documento XML specificato come input. Il documento caricato viene convalidato in base al valore DTD incluso nel documento. Nella chiamata a sp_xml_preparedocument viene utilizzato il mapping predefinito per i prefissi degli spazi dei nomi.

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. Specificare un URI dello spazio dei nomi

Nell'esempio seguente viene restituito un handle per la nuova rappresentazione interna del documento XML specificato come input. La chiamata a sp_xml_preparedocument mantiene il mp prefisso al mapping dello spazio dei nomi della metaproperty e aggiunge il xyz prefisso di mapping allo spazio dei nomi 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"/>';

Contenuto correlato