sp_xml_preparedocument (Transact-SQL)

  • Article

S’applique à :SQL ServerAzure SQL Database

Lit le texte XML fourni en entrée, analyse le texte à l’aide de l’analyseur MSXML (msxmlsql.dll) et fournit le document analysé dans un état prêt à être consommé. Ce document analysé est une représentation arborescente des différents nœuds du document XML : éléments, attributs, textes, commentaires, etc.

sp_xml_preparedocument retourne un handle qui peut être utilisé pour accéder à la représentation interne nouvellement créée du document XML. Ce handle est valide pendant la session ou jusqu’à ce que le handle soit invalidé en exécutant sp_xml_removedocument.

Un document analysé est stocké dans le cache interne de SQL Server. L’analyseur MSXML peut utiliser un huitième de la mémoire totale disponible pour SQL Server. Pour éviter de manquer de mémoire, exécutez sp_xml_removedocument pour libérer la mémoire dès que le document n’est plus nécessaire. Dans de nombreux cas, la méthode node() peut être une meilleure alternative et aider à éviter une utilisation excessive de la mémoire.

Pour une compatibilité descendante, sp_xml_preparedocument réduit les caractères CR (char(13)) et LF (char(10)) dans les attributs, même si ces caractères sont entitisés.

Remarque

L’analyseur XML appelé par sp_xml_preparedocument peut analyser des DTD internes et des déclarations d’entité. Étant donné que des DTD et des déclarations d’entité construits de manière malveillante peuvent être utilisés pour effectuer une attaque par déni de service, nous vous recommandons vivement de ne pas transmettre directement des documents XML à partir de sources sp_xml_preparedocumentnon approuvées.

Pour atténuer les attaques d’extension d’entité récursives, sp_xml_preparedocument limite à 10 000 le nombre d’entités qui peuvent être développées sous une seule entité au niveau supérieur d’un document. Cette limite ne s'applique pas aux entités numériques ou de caractères. Elle permet de stocker des documents contenant de nombreuses références d'entités, mais elle empêche une entité d'être étendue de manière récursive dans une chaîne supérieure à 10 000 extensions.

sp_xml_preparedocument limite le nombre d’éléments qui peuvent être ouverts à la fois à 256.

Conventions de la syntaxe Transact-SQL

Syntaxe

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

Arguments

hdoc

Handle du document nouvellement créé. hdoc est un entier.

[ xmltext ]

Document XML d’origine. L'analyseur MSXML analyse ce document XML. xmltext est un paramètre de texte : char, nchar, varchar, nvarchar, text, ntext ou xml. Lorsque la valeur est NULL (valeur par défaut), une représentation interne d'un document XML vide est créée.

Remarque

sp_xml_preparedocument ne peut traiter que du texte ou du code XML non typé. Si une valeur d'instance à utiliser en entrée est déjà du XML typé, commencez par la convertir en une nouvelle instance XML non typée ou en une chaîne, puis passez cette valeur en entrée. Pour plus d’informations, consultez Comparer du XML typé et du XML non typé.

[ xpath_namespaces ]

Spécifie les déclarations d'espaces de noms utilisées dans les expressions XPath de ligne et de colonne sous OPENXML. xpath_namespaces est un paramètre de texte : char, nchar, varchar, nvarchar, text, ntext ou xml.

La valeur par défaut est <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces fournit les URI d’espace de noms pour les préfixes utilisés dans les expressions XPath dans OPENXML, avec un document XML bien formé. xpath_namespaces déclare le préfixe qui doit être utilisé pour faire référence à l’espace de noms urn:schemas-microsoft-com:xml-metaprop; cela fournit des métadonnées sur les éléments XML analysés. Bien que vous puissiez redéfinir le préfixe d’espace de noms pour l’espace de noms métapropriété à l’aide de cette technique, cet espace de noms n’est pas perdu. Le préfixe mp est toujours valide même urn:schemas-microsoft-com:xml-metaprop si xpath_namespaces ne contient aucune déclaration de ce type.

Valeurs des codes de retour

0 (réussite) ou > 0 (échec).

Autorisations

Nécessite l'appartenance au rôle public .

Exemples

R. Préparer une représentation interne pour un document XML bien formé

L'exemple suivant retourne un descripteur pour la représentation interne nouvellement créée du document XML fourni en entrée. L'appel à sp_xml_preparedocument contient un mappage de préfixes d'espaces de noms par défaut.

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. Préparer une représentation interne pour un document XML bien formé avec un DTD

L'exemple suivant retourne un descripteur pour la représentation interne nouvellement créée du document XML fourni en entrée. La procédure stockée valide le document chargé sur le schéma DTD inclus dans le document. L'appel à sp_xml_preparedocument contient un mappage de préfixes d'espaces de noms par défaut.

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. Spécifier un URI d’espace de noms

L'exemple suivant retourne un descripteur pour la représentation interne nouvellement créée du document XML fourni en entrée. L’appel pour sp_xml_preparedocument conserver le mp préfixe du mappage d’espace de noms métaproperty et ajoute le xyz préfixe de mappage à l’espace de noms 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"/>';

Contenu connexe