Partilhar via

sp_xml_preparedocument (Transact-SQL)

Aplica-se a:SQL ServerBanco de Dados SQL do Azure

Lê o texto XML fornecido como entrada, analisa o texto usando o analisador MSXML (msxmlsql.dll) e fornece o documento analisado em um estado pronto para consumo. Este documento analisado é uma representação em árvore dos vários nós no documento XML: elementos, atributos, texto, comentários e assim por diante.

sp_xml_preparedocument retorna um identificador que pode ser usado para acessar a representação interna recém-criada do documento XML. Esse identificador é válido durante a sessão ou até que o identificador seja invalidado pela execução sp_xml_removedocument.

Um documento analisado é armazenado no cache interno do SQL Server. O analisador MSXML pode usar um oitavo da memória total disponível para o SQL Server. Para evitar ficar sem memória, execute sp_xml_removedocument para liberar a memória assim que o documento não for mais necessário. Em muitos casos, o método nodes() pode ser uma alternativa melhor e ajudar a evitar o uso excessivo de memória.

Para compatibilidade com versões anteriores, sp_xml_preparedocument recolhe os caracteres CR (char(13)) e LF (char(10)) em atributos, mesmo que esses caracteres sejam entitizados.

Observação

O analisador XML invocado por sp_xml_preparedocument pode analisar DTDs internos e declarações de entidade. Como DTDs e declarações de entidade construídas com códigos maliciosos podem ser usados para executar um ataque de negação de serviço, é altamente recomendável que os usuários não passem diretamente documentos XML de fontes não confiáveis para sp_xml_preparedocument.

Para mitigar ataques de expansão de entidade recursiva, sp_xml_preparedocument limita a 10.000 o número de entidades que podem ser expandidas abaixo de uma única entidade no nível superior de um documento. O limite não se aplica a caracteres ou entidades numéricas. Esse limite permite que documentos com muitas referências de entidade sejam armazenados, mas impede que qualquer entidade seja expandida recursivamente em uma cadeia com mais de 10.000 expansões.

sp_xml_preparedocument limita o número de elementos que podem ser abertos ao mesmo tempo a 256.

Transact-SQL convenções de sintaxe

Sintaxe

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

Argumentos

Importante

Os argumentos para procedimentos armazenados estendidos devem ser inseridos na ordem específica, conforme descrito na seção de sintaxe. Se os parâmetros forem inseridos fora de ordem, ocorrerá uma mensagem de erro.

hdoc

O identificador para o documento recém-criado. hdoc é um inteiro.

[ xmltext ]

O documento XML original. O analisador MSXML analisa este documento XML. xmltext é um parâmetro text: char, nchar, varchar, nvarchar, text, ntext ou xml. O valor padrão é NULL, caso em que uma representação interna de um documento XML vazio é criada.

Observação

sp_xml_preparedocument só pode processar texto ou XML sem tipo. Se um valor de instância a ser usado como entrada já estiver digitado XML, primeiro converta-o em uma nova instância XML não tipada ou como uma cadeia de caracteres e, em seguida, passe esse valor como entrada. Para obter mais informações, consulte Comparar XML tipado com XML não tipado.

[ xpath_namespaces ]

Especifica as declarações de namespace que são usadas em expressões XPath de linha e coluna em OPENXML. xpath_namespaces é um parâmetro de texto: char, nchar, varchar, nvarchar, texto, ntext ou xml.

O valor padrão é <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces fornece os URIs de namespace para os prefixos usados nas expressões XPath em OPENXML, com um documento XML bem formado. xpath_namespaces declara o prefixo que deve ser usado para se referir ao namespace urn:schemas-microsoft-com:xml-metaprop; isso fornece metadados sobre os elementos XML analisados. Embora você possa redefinir o prefixo de namespace para o namespace de metapropriedade usando essa técnica, esse namespace não é perdido. O prefixo mp continua a ser válido para urn:schemas-microsoft-com:xml-metaprop mesmo que xpath_namespaces não contenha tal declaração.

Valores de código de retorno

0 (sucesso) ou > 0 (fracasso).

Permissões

Requer a participação na função pública.

Exemplos

Um. Preparar uma representação interna para um documento XML bem formado

O exemplo a seguir retorna um identificador para a representação interna recém-criada do documento XML que é fornecido como entrada. Na chamada para sp_xml_preparedocument, um mapeamento de prefixo de namespace padrão é usado.

DECLARE @hdoc AS INT;
DECLARE @doc AS 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.
EXECUTE sp_xml_preparedocument
    @hdoc OUTPUT,
    @doc;

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

B. Preparar uma representação interna para um documento XML bem formado com um DTD

O exemplo a seguir retorna um identificador para a representação interna recém-criada do documento XML que é fornecido como entrada. O procedimento armazenado valida o documento carregado em relação ao DTD incluído no documento. Na chamada para sp_xml_preparedocument, um mapeamento de prefixo de namespace padrão é usado.

DECLARE @hdoc AS INT;
DECLARE @doc AS 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>';

EXECUTE sp_xml_preparedocument
    @hdoc OUTPUT,
    @doc;

C. Especificar um URI de namespace

O exemplo a seguir retorna um identificador para a representação interna recém-criada do documento XML que é fornecido como entrada. A chamada para sp_xml_preparedocument preserva o prefixo mp para o mapeamento de namespace de metapropriedade e adiciona o prefixo de mapeamento de xyz ao namespace urn:MyNamespace.

DECLARE @hdoc AS INT;
DECLARE @doc AS 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.
EXECUTE sp_xml_preparedocument
    @hdoc OUTPUT,
    @doc, '<ROOT xmlns:xyz="urn:MyNamespace"/>';

Conteúdo relacionado