sp_xml_preparedocument (Transact-SQL)

Artikel
2025-03-11

gäller för:SQL Server Azure SQL Database

Läser XML-texten som tillhandahålls som indata, parsar texten med hjälp av MSXML-parsern (msxmlsql.dll) och tillhandahåller det tolkade dokumentet i ett tillstånd som är redo för förbrukning. Det här tolkade dokumentet är en trädrepresentation av de olika noderna i XML-dokumentet: element, attribut, text, kommentarer och så vidare.

sp_xml_preparedocument returnerar en referens som kan användas för att komma åt den nyligen skapade interna representationen av XML-dokumentet. Det här handtaget är giltigt under sessionen eller tills handtaget har ogiltigförklarats genom att köra sp_xml_removedocument.

Ett tolkat dokument lagras i den interna cachen för SQL Server. MSXML-parsern kan använda en åttondel av det totala tillgängliga minnet för SQL Server. För att undvika att minnet tar slut kör du sp_xml_removedocument för att frigöra minnet så snart dokumentet inte längre krävs. I många fall kan metoden nodes() vara ett bättre alternativ och bidra till att undvika överdriven minnesanvändning.

För bakåtkompatibilitet döljer sp_xml_preparedocument tecknen CR (char(13)) och LF (char(10)) i attribut även om dessa tecken är initierade.

Not

XML-parsern som anropas av sp_xml_preparedocument kan parsa interna DTD:er och entitetsdeklarationer. Eftersom skadliga DTD:er och entitetsdeklarationer kan användas för att utföra en Överbelastningsattack rekommenderar vi starkt att användarna inte direkt skickar XML-dokument från ej betrodda källor till sp_xml_preparedocument.

För att minska rekursiva entitetsexpansionsattacker sp_xml_preparedocument begränsar till 10 000 antalet entiteter som kan expanderas under en enda entitet på den översta nivån i ett dokument. Gränsen gäller inte för tecken eller numeriska entiteter. Den här gränsen tillåter att dokument med många entitetsreferenser lagras, men förhindrar att en entitet expanderas rekursivt i en kedja som är längre än 10 000 expansioner.

sp_xml_preparedocument begränsar antalet element som kan vara öppna samtidigt till 256.

Transact-SQL syntaxkonventioner

Syntax

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

Argument

Viktig

Argument för utökade lagrade procedurer måste anges i den specifika ordning som beskrivs i avsnittet Syntax. Om parametrarna anges i fel ordning visas ett felmeddelande.

hdoc

Handtaget till det nyligen skapade dokumentet. hdoc är ett heltal.

[ xmltext ]

Det ursprungliga XML-dokumentet. MSXML-parsern parsar det här XML-dokumentet. xmltext är en textparameter: char, nchar, varchar, nvarchar, text, ntext eller xml. Standardvärdet är NULL, i vilket fall en intern representation av ett tomt XML-dokument skapas.

Not

sp_xml_preparedocument kan bara bearbeta text eller otypad XML. Om ett instansvärde som ska användas som indata redan är skrivet XML skickar du det först till en ny otypad XML-instans eller som en sträng och skickar sedan det värdet som indata. Mer information finns i Jämför inskriven XML med otypad XML-.

[ xpath_namespaces ]

Anger de namnområdesdeklarationer som används i XPath-uttryck i rad och kolumn i OPENXML. xpath_namespaces är en textparameter: char, nchar, varchar, nvarchar, text, ntext eller xml.

Standardvärdet är <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces tillhandahåller namnområdes-URI:er för prefixen som används i XPath-uttrycken i OPENXML, med ett välformat XML-dokument. xpath_namespaces deklarerar prefixet som måste användas för att referera till namnområdet urn:schemas-microsoft-com:xml-metaprop; Detta ger metadata om de tolkade XML-elementen. Även om du kan omdefiniera namnområdesprefixet för metaproperty-namnområdet med hjälp av den här tekniken går inte det här namnområdet förlorat. Prefixet mp är fortfarande giltigt för urn:schemas-microsoft-com:xml-metaprop även om xpath_namespaces inte innehåller någon sådan deklaration.

Returnera kodvärden

0 (lyckades) eller > 0 (fel).

Behörigheter

Kräver medlemskap i den offentliga rollen.

Exempel

A. Förbereda en intern representation för ett välformat XML-dokument

I följande exempel returneras ett handtag till den nyligen skapade interna representationen av XML-dokumentet som tillhandahålls som indata. I anropet till sp_xml_preparedocumentanvänds en standardmappning av namnområdesprefix.

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. Förbereda en intern representation för ett välformat XML-dokument med en DTD

I följande exempel returneras ett handtag till den nyligen skapade interna representationen av XML-dokumentet som tillhandahålls som indata. Den lagrade proceduren verifierar dokumentet som lästs in mot DTD som ingår i dokumentet. I anropet till sp_xml_preparedocumentanvänds en standardmappning av namnområdesprefix.

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. Ange en namnområdes-URI

I följande exempel returneras ett handtag till den nyligen skapade interna representationen av XML-dokumentet som tillhandahålls som indata. Anropet till sp_xml_preparedocument bevarar mp-prefixet till metaproperty-namnområdesmappningen och lägger till xyz mappningsprefixet i namnområdet 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"/>';

Dela via