XML Elements - Headers BeginSession Element (XMLA) EndSession Element (XMLA) ProtocolCapabilities Element (XMLA) Session Element (XMLA)

Transcription

1 Table of Contents XML Elements - Headers BeginSession Element (XMLA) EndSession Element (XMLA) ProtocolCapabilities Element (XMLA) Session Element (XMLA)

2 XML Elements - Headers 1/8/ min to read Edit Online APPLIES TO: SQL Server Analysis Services Azure Analysis Services The XML for Analysis (XMLA) protocol uses XML elements within the SOAP header to manage protocol-level features, such as session support and the negotiation of supported features. In This Section The following topics describe the XMLA header elements implemented by Microsoft SQL Server Analysis Services. METHOD BeginSession Element (XMLA) EndSession Element (XMLA) Session Element (XMLA) ProtocolCapabilities Element (XMLA) Uses a SOAP header in a SOAP request message to start a new session on an instance of Analysis Services. Uses the SOAP header in a SOAP request message to end an existing session on an instance of Analysis Services. Uses the SOAP header in a SOAP request message to identify an existing, explicit session on an instance of Analysis Services. Uses the SOAP header in a SOAP request message to identify protocol capabilities between an instance of Analysis Services and a client application. See Also XML Elements (XMLA) XML Data Types (XMLA) XML Elements (XMLA)

3 BeginSession Element (XMLA) 1/8/ min to read Edit Online APPLIES TO: SQL Server Analysis Services Azure Analysis Services Uses a SOAP header in a SOAP request message to start a new session on an instance of Microsoft SQL Server Analysis Services. Namespace urn:schemas-microsoft-com:xml-analysis Syntax <soap:envelope xmlns:soap=" <soap:header> <BeginSession xmlns="urn:schemas-microsoft-com:xml-analysis" /> </soap:header> <soap:body> </soap:body> </soap:envelope> Element Characteristics CHARACTERISTIC Data type and length Default value Cardinality 0-1: Optional element that can occur once and only once. Element Relationships RELATIONSHIP Parent elements Child elements ELEMENT Remarks The BeginSession header element is part of a SOAP request sent to an Analysis Services instance, and explicitly starts a new session on the instance. The SOAP header returned by the SOAP response contains a Session element that identifies the new session. This new session identifier be stored and sent in subsequent SOAP requests using the Session header element.

4 If the BeginSession header element is not sent, a session is not explicitly started. If a session is not explicitly started, transactions on that session cannot be managed. In other words, you cannot use the following XML for Analysis (XMLA) commands: BeginTransaction, CommitTransaction, and RollbackTransaction. All XMLA methods and commands executed on an implicitly started session are considered to be atomic transactions. See Also EndSession Element (XMLA) Session Element (XMLA) Managing Connections and Sessions (XMLA) Headers (XMLA)

5 EndSession Element (XMLA) 1/8/ min to read Edit Online APPLIES TO: SQL Server Analysis Services Azure Analysis Services Uses the SOAP header in a SOAP request message to end an existing session on an instance of Microsoft SQL Server Analysis Services. Namespace urn:schemas-microsoft-com:xml-analysis Syntax <soap:envelope xmlns:soap=" <soap:header> <EndSession xmlns="urn:schemas-microsoft-com:xml-analysis" SessionId="string" /> </soap:header> <soap:body> </soap:body> </soap:envelope> Element Characteristics CHARACTERISTIC Data type and length Default value Cardinality 0-1: Optional element that can occur once and only once. Element Relationships RELATIONSHIP Parent elements Child elements ELEMENT Attributes ATTRIBUTE

6 ATTRIBUTE SessionId Required String attribute that identifies the session to be ended. Analysis Services uses a globally unique identifier (GUID) to identify a session. Remarks The EndSession header element is part of the SOAP request sent to an existing, explicitly started session on an Analysis Services instance. If the EndSession header element is sent, but contains a session identifier that is no longer valid, a SOAP fault is returned that indicates that the session cannot be found. See Also BeginSession Element (XMLA) Session Element (XMLA) Managing Connections and Sessions (XMLA) Headers (XMLA)

7 ProtocolCapabilities Element (XMLA) 1/8/ min to read Edit Online APPLIES TO: SQL Server Analysis Services Azure Analysis Services Uses the SOAP header in a SOAP request message to identify protocol capabilities between an instance of Microsoft SQL Server Analysis Services and a client application. Namespace Syntax <soap:envelope xmlns:soap=" <soap:header> <ProtocolCapabilities xmlns=" <Capability></Capability> </ProtocolCapabilities> </soap:header> <soap:body> </soap:body> </soap:envelope> Element Characteristics CHARACTERISTIC Data type and length Default value Cardinality 0-1: Optional element that can occur once and only once. Element Relationships RELATIONSHIP Parent elements Child elements ELEMENT Capability Remarks The ProtocolCapabilities element enables client applications to negotiate protocol capabilities, such as binary XML or compression support, with an Analysis Services instance at any time. Protocol negotiation involves the following steps: 1. The client application identifies its protocol capability by sending a SOAP request that includes the

8 ProtocolCapabilities element as part of the SOAP header. 2. The Analysis Services instance receives and processes the SOAP request. 3. If the Analysis Services instance has the same protocol capability as that requested, the instance sends a SOAP response that includes the same ProtocolCapabilities element sent in the SOAP request, and the protocol has been successfully negotiated. Otherwise, the protocol capabilities are not successfully negotiated, and the instance returns a SOAP fault. After successfully negotiating protocol capabilities, how long the client application and the Analysis Services instance use a particular protocol depends upon whether the session is explicit or implicit: An explicit session is one that is created using the BeginSession header element. For an explicit session, the negotiated protocol is used until either the client application sends a new ProtocolCapabilities element or the session ends. An implicit session is one that is created by an Analysis Services instance and not explicitly specified by the client application when submitting a SOAP request. For an implicit session, the negotiated protocol is used only until the SOAP request is completed. Protocol capabilities do not have to be explicitly negotiated. That is, a client application does not have to include a ProtocolCapabilities element as part of the SOAP request. If a SOAP request does not include a ProtocolCapabilities element, the Analysis Services instance responds using the same format as the SOAP request. See Also Managing Connections and Sessions (XMLA) Headers (XMLA)

9 Session Element (XMLA) 1/8/ min to read Edit Online APPLIES TO: SQL Server Analysis Services Azure Analysis Services Uses the SOAP header in a SOAP request message to identify an existing, explicit session on an instance of Microsoft SQL Server Analysis Services. Namespace urn:schemas-microsoft-com:xml-analysis Syntax <soap:envelope xmlns:soap=" <soap:header> <Session xmlns="urn:schemas-microsoft-com:xml-analysis" SessionId="string" /> </soap:header> <soap:body> </soap:body> </soap:envelope> Element Characteristics CHARACTERISTIC Data type and length Default value Cardinality 0-1: Optional element that can occur once and only once. Element Relationships RELATIONSHIP Parent elements Child elements ELEMENT Attributes ATTRIBUTE

10 ATTRIBUTE SessionId Required String attribute that identifies the session to be used. Analysis Services uses a globally unique identifier (GUID) to identify a session. Remarks The Session header element identifies an existing, explicitly started session on the Analysis Services instance. The Session element is part of the SOAP header in the following types of messages: A SOAP response that contains a BeginSession SOAP header element. A SOAP request to identify the session on which to run the Discover or Execute method. A session identifier does not guarantee that a session remains valid. The session specified in the Session element can expire. For example, a session can expire if the session times out or the connection associated with the session is disconnected. If the session expires and is no longer valid, Analysis Services ends the session and rolls back any transaction currently in process. Any SOAP message sent with a session identifier that is no longer valid fails with a SOAP fault indicating that the specified session cannot be found. If a Session element is not sent as part of a SOAP request, the Analysis Services instance implicitly begins a session for the duration of the Discover or Execute method call, and then ends that session once the method call has completed. See Also EndSession Element (XMLA) Managing Connections and Sessions (XMLA) Headers (XMLA)