sp_xml_preparedocument (Transact-SQL)

適用対象: SQL Server Azure SQL データベース

入力として指定された XML テキストを読み取り、MSXML パーサー (msxmlsql.dll) を使用してテキストを解析し、解析されたドキュメントを使用できる状態で提供します。 この解析されたドキュメントは、XML ドキュメント内のさまざまなノード (要素、属性、テキスト、コメントなど) のツリー表現です。

sp_xml_preparedocument は、XML ドキュメントの新しく作成された内部表現にアクセスするために使用できるハンドルを返します。 このハンドルは、セッション中、または sp_xml_removedocumentを実行してハンドルが無効になるまで有効です。

解析されたドキュメントは、SQL Server の内部キャッシュに格納されます。 MSXML パーサーは、SQL Server で使用可能な合計メモリの 8 分の 1 を使用できます。 メモリ不足を回避するには、 sp_xml_removedocument を実行して、ドキュメントが不要になったらすぐにメモリを解放します。 多くの場合、nodes() メソッドの方が適切な代替方法であり、メモリの過剰な使用を回避するのに役立ちます。

下位互換性のために、 sp_xml_preparedocument は、これらの文字がエンティティ化されている場合でも、属性の CR (char(13)) 文字と LF (char(10)) 文字を折りたたみます。

Note

sp_xml_preparedocumentによって呼び出される XML パーサーは、内部 DTD とエンティティ宣言を解析できます。 悪意を持って構築された DTD とエンティティ宣言を使用してサービス拒否攻撃を実行できるため、ユーザーが信頼されていないソースから直接 XML ドキュメントを sp_xml_preparedocumentに渡さないことを強くお勧めします。

再帰エンティティ拡張攻撃を軽減するために、ドキュメントの最上位レベルにある 1 つのエンティティの下に展開できるエンティティの数を 10,000 個に制限 sp_xml_preparedocument 。 この制限は、文字エンティティまたは数値エンティティには適用されません。 この制限により、多数のエンティティ参照を持つドキュメントを格納できますが、1 つのエンティティが 10,000 個を超える拡張チェーンで再帰的に展開されるのを防ぐことができます。

sp_xml_preparedocument は、一度に開くことができる要素の数を 256 に制限します。

Transact-SQL 構文表記規則

構文

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

引数

hdoc

新しく作成されたドキュメントのハンドル。 hdoc は整数です。

[ xmltext ]

元の XML ドキュメント。 MSXML パーサーは、この XML ドキュメントを解析します。 xmltext はテキスト パラメーターです: char、 nchar、 varchar、 nvarchar、 text、 ntext または xml。 既定値は NULLです。この場合、空の XML ドキュメントの内部表現が作成されます。

Note

sp_xml_preparedocument では、テキストまたは型指定されていない XML のみを処理できます。 入力値として使用するインスタンス値が既に型指定された XML である場合は、まずその値を、型指定されない新しい XML インスタンスまたは文字列にキャストし、その後入力値として渡します。 詳細については、「型指定された XML と型指定されていない XML の比較」を参照してください。

[ xpath_namespaces ]

OPENXML の行および列 XPath 式で使用される名前空間宣言を指定します。 xpath_namespaces は、テキスト パラメーターです: char、 nchar、 varchar、 nvarchar、 text、 ntext または xml。

既定値は <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop"> です。 xpath_namespaces は、OPENXML の XPath 式で使用されるプレフィックスの名前空間 URI と、整形式の XML ドキュメントを提供します。 xpath_namespaces は、名前空間 urn:schemas-microsoft-com:xml-metapropを参照するために使用する必要があるプレフィックスを宣言します。これにより、解析された XML 要素に関するメタデータが提供されます。 この手法を使用してメタプロパティ名前空間の名前空間プレフィックスを再定義できますが、この名前空間は失われません。 プレフィックス mpは、xpath_namespacesにそのような宣言が含まれている場合でも、urn:schemas-microsoft-com:xml-metapropに対して引き続き有効です。

リターン コードの値

0 (成功) または > 0 (失敗)。

アクセス許可

ロール public のメンバーシップが必要です。

例

A. 整形式 XML ドキュメントの内部表現を準備する

次の例では、入力として提供される XML ドキュメントの新しく作成された内部表現へのハンドルを返します。 sp_xml_preparedocument の呼び出しでは、既定の名前空間プレフィックス マッピングを使用します。

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. DTD を使用して整形式 XML ドキュメントの内部表現を準備する

次の例では、入力として提供される XML ドキュメントの新しく作成された内部表現へのハンドルを返します。 ストアド プロシージャは、ドキュメントに含まれる DTD に対して読み込まれたドキュメントを検証します。 sp_xml_preparedocument の呼び出しでは、既定の名前空間プレフィックス マッピングを使用します。

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: 名前空間 URI を指定する

次の例では、入力として提供される XML ドキュメントの新しく作成された内部表現へのハンドルを返します。 sp_xml_preparedocumentの呼び出しでは、メタプロパティ名前空間マッピングにmp プレフィックスが保持され、xyz マッピング プレフィックスが名前空間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"/>';

関連するコンテンツ

• XML ストアド プロシージャ (Transact-SQL)
• システム ストアド プロシージャ (Transact-SQL)
• OPENXML (Transact-SQL)
• sys.dm_exec_xml_handles (Transact-SQL)
• sp_xml_removedocument (Transact-SQL)
• nodes() メソッド (xml データ型)