Hci10 Web Services en PDF

PUBLIC
SAP HANA Cloud Integration for data services

Document Version: 1.0.7 - 2014-11-13
Web Services Guide
Table of Contents
1
Web service support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1
Web services technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1
SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2
WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.1.3
XML Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.4
UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2
Creating a client to use web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Supported web service operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
2.1
Connection operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
2.2
2.1.1
ping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.2
logon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.3
logout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Project operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.1
runTask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.2
getTaskStatusByRunID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2.3
getTaskLogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Error reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
PUBLIC
2014 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide

Table of Contents
Web service support
When an external application calls into SAP HANA Cloud Integration through web services, the application acts as
a web service client accessing a web services server.
Web service clients call the published web services, pass in the appropriate parameters, and receive the results.
1.1
Web services technologies
SAP HANA Cloud Integration web services are compliant with JAX-WS and Web Services Interoperability (WS-I)
Basic Profile 1.0, and support several Java web services technologies.
Technology
Description
SOAP
Connection protocol (envelope for XML messages)
WSDL
XML-based language used describe published web services
XML Schema
Format used for the WSDL file
1.1.1
SOAP
SAP HANA Cloud Integration supports the Simple Object Access Protocol (SOAP).
SOAP is an industry standard from the World Wide Web Consortium (WC3.org) used to invoke network resources
using XML over HTTP, HTTPS, and other standard protocols. SAP HANA Cloud Integration supports SOAP over
HTTP and HTTPS protocols.
1.1.2
WSDL
Web Services Description Language (WSDL) is a subset of XML used as a transport mechanism for XML
messages.
The WSDL file generated by the software includes elements (such as services, bindings, ports, and operations)
that support the use of the SOAP protocol. Each element uses a name that the software provides.
This table shows the elements in a WSDL file, and describes how those elements are used in the SAP HANA Cloud
Integration WSDL file.
Element Name
Description
definition
Root element.
service
Used to group a set of related ports or endpoints to which a client applica

tion will connect. The software publishes a single service in the WSDL file.
Web Services Guide

Web service support
PUBLIC
Element Name
Description
port
Defines a specific web service endpoint that a client can access. Each port
has a unique name and a specific address used for binding. The software
defines a single port that contains the operations.
portType
Defines a set of operations that a web service publishes.

A portType is bound to a particular port. The binding specifies the protocol
and data formation for the operations defined by a portType.
operation
Defines a specific function call. The software publishes connection and

project operations.
message
Defines the data to transmit. There is an input (request) message, which

the web service receives from the client, and there is an output (response)
message, which the web service sends back to the client.
type
Defines the data types used in messages sent to and from a web service.
1.1.2.1
Accessing the WSDL file
Access the WSDL file by making web service client calls to it using your HCI URL.
Use the information in the WSDL file provided by SAP HANA Cloud Integration to create an application that can
access tasks.
To view the WSDL file so that you can create your application, open a browser window and navigate to:
http://<hci_url>/DSoD/webservices?wsdl
Example
http://integration.ondemand.com/DSoD/webservices?wsdl
Note that the primary WSDL contains only a readable listing of the available web service operations. A secondary,
imported WSDL defines the XML schema of the services:
http://<hci_url>/DSoD/webservices?wsdl=SoapGateway.wsdl
Example
http://hcids.us1.hana.ondemand.com/DSoD/webservices?wsdl=SoapGateway.wsdl
PUBLIC
Web Services Guide

Web service support
1.1.3
XML Schema
WSDL uses XML Schemas to define input and output message formats.
XML Schema formats are defined in the types element of the WSDL file.
1.1.4
UDDI
UDDI is a method of publishing comments and other reference information about jobs to an external web site.
SAP HANA Cloud Integration does not publish information to a UDDI web site because most web service users
work behind enterprise firewalls.
1.2
Creating a client to use web services
The tools you use to develop your web services client are your choice and the exact steps in using those tools
vary, but these basic steps apply as a simple overview to all development projects for web services clients.
Context
To use a published web service, you must first know the URL of the target WSDL.
The primary SAP HANA Cloud Integration WSDL file is located at:
http://<hci_host>:<port>/DSoD/webservices?wsdl
Procedure
1.
Import the software's WSDL into your development environment to create a web services client application.
The incorporated web services appear in the hierarchy of your development.
2.
Open the web service.

Each available port for the web service is made visible in the IDE.
3.
Write the code to call any of the jobs or services provided by the ports.
4.
Run the project to execute the code.

Executing the code initiates the web services job, and a connection is made to the SAP HANA Cloud
Integration web services host.
Web Services Guide

Web service support
PUBLIC
Related Information
Accessing the WSDL file [page 4]
PUBLIC
Web Services Guide

Web service support
Supported web service operations
SAP HANA Cloud Integration provides a WSDL file with a single service definition.
It is possible to create multiple service definitions in a WSDL, but many web service implementations do not
support more than one service definition. To avoid that limitation, the software creates only one service.
2.1
Connection operations
The SAP HANA Cloud Integration WSDL defines connection operations that belong to web services.
The software supports the following Connection operations:
Operation
Description
ping
Verifies the connection to SAP HANA Cloud Integration web services.
logon
Verifies secure access and establishes a web services session.
logoff
Terminates an existing web services session.
2.1.1
ping
The ping operation can be used to maintain a user session.
Request message
Table 1: ping elements
Element
Type
Description
SessionID
xs:string
The unique ID of the session that should be used for

the web service operation.
If a session ID is not specified in the request message, the ping operation returns an error message that the
server is available but no ID was specified.
Web Services Guide

PUBLIC
Response message
Table 2: pingResponse elements
Element
Type
Description
Message
xs:string
A message that indicates that a connection has been

established.
For more information about the structure of the ping request and response messages, refer to the SAP HANA
Cloud Integration WSDL.
Related Information
2.1.2
logon
The logon operation provides basic user authentication and returns a valid web services session ID.
Web service logon operations are logged in the SAP HANA Cloud Integration security log.
Request message
Table 3: logonRequest elements
Element
Type
Description
orgName
xs:string
The name of the SAP HANA Cloud Integration organi

zation.
userName
xs:string
The user name.
password
xs:string
The password.
isProduction
xs:boolean
Specifies whether to log in to the production or sand

box repository.
Default value: false
PUBLIC
Web Services Guide

Response message
Table 4: logonResponse elements
Element
Type
Description
SessionID
xs:string
A unique session ID that can be used for subsequent

web services operations.
The session ID is valid only for the specified repository
type. For example, a session ID generated by specify
ing <isProduction>true</isProduction> cannot
be used to execute tasks in the sandbox repository,
even if the user would otherwise have permissions to
do so. You must first log out and then log in again, re
questing a new session ID.
By default, the session will expire and become invalid
after an idle timeout of 30 minutes. The expiration
timer is reset each time a web service operation is
called using the session ID. All session IDs expire after
24 hours.
Additionally, if the user or organization associated with
the session is disabled or deleted, the session will be
expired.
HTTP Basic Authentication

As an alternative to providing the logon details in the SOAP body, the logon operation also supports HTTP Basic
Authentication.
To use HTTP Basic Authentication, do not use the logonRequest element, and instead provide the access details
in the HTTP header.
Table 5: HTTP headers
Header
Possible values
Description
Authorization
Basic
<authorization>
The authentication type and the base64-encoded value

of the username and password pair:
<username>:<password>
orgName
Alphanumeric characters
The name of the SAP HANA Cloud Integration organi

zation.
dsodEnv
PRODUCTION
The type of repository that the web services session

should access.
SANDBOX
SOAPAction
Web Services Guide

function=logon
The SOAP action to perform.
PUBLIC
Note
When using HTTP-based authentication to log on to the SAP HANA Cloud Integration web services from a SAP
Data Services job, you must still include the logonRequest element in the message body because SAP Data
Services does not support an empty mapping. Instead, specify a null value for each element of the
logonRequest message.
For more information about the structure of the logon request and response messages, refer to the SAP HANA
Related Information
2.1.3
logout
The logout operation logs the user out of the system and destroys the specified session.
Web service logout operations are logged in the SAP HANA Cloud Integration security log.
Request message
Table 6: logout elements
Element
Type
Description
SessionID
xs:string
The unique ID of the session that should be logged out

and destroyed.
Response message
Table 7: logoutResponse elements
Element
Type
Description
LogoutMessage
xs:string
A message that indicates that the web services session

has been terminated.
For more information about the structure of the logout request and response messages, refer to the SAP HANA
10
PUBLIC
Web Services Guide

Related Information
2.2
Project operations
The SAP HANA Cloud Integration WSDL defines project operations that allow you to execute tasks and retrieve
execution status information.
The software supports the following Project operations:
Operation
Description
runTask
Executes a task and returns a run ID.
getTaskStatusByRunID
Returns the status of the task execution with the specified run ID.
getTaskLogs
Retrieves the trace, monitor, or error log for the task execution with the
specified run ID.
Access restrictions
The roles of the user that created the web services session determines whether the project services have access
to the sandbox or production repository.
Table 8: Repository access for project services
User role
Sandbox
Production
Integration developer
Yes
No
Production operator
No
Yes
Administrator
Yes
Yes
All other roles
No
No
Note
The role-based repository access is additive. That is, if the user is assigned both the Integration developer
and Production operator roles, the project services will be able to access both repositories.
Web Services Guide

PUBLIC
11
SOAP header
All project services may be accessed only by specifying a valid web services session ID obtained from the logon
operation. The session ID must be specified in the SOAP header of the web service request.
Table 9: SOAP header elements
Element
Type
Description
SessionID
xs:string
The unique ID of the session that should be used for

the web service operation.
2.2.1
runTask
The runTask operation executes a task in either the sandbox or production repository.
Request message
Table 10: runTaskRequest elements
Element
Type
Description
taskName
xs:string
The name of the task that should be executed.
agentName
xs:string
The name of the SAP Data Services Agent that should

be used to execute the task.
globalVariables
xs:sequence
Optional. A list of the global variables to pass to the

task, defined as a sequence of xs:string elements.
For example:
<variable name="myVar">Value</variable>
Response message
Table 11: runTaskResponse elements
Element
Type
Description
RunID
xs:string
A unique ID that identifies the specific execution in

stance for the task and can be used to retrieve the exe
cution status or logs.
For more information about the structure of the runTask request and response messages, refer to the SAP
HANA Cloud Integration WSDL.
12
PUBLIC
Web Services Guide

Related Information
2.2.2
getTaskStatusByRunID
The getTaskStatusByRunID operation retreives the status of a task execution with a specified run ID.
To prevent server overload, the getTaskStatusByRunID operation should be called only using a fixed time
overload.
Request message
Table 12: taskStatusRequest elements
Element
Type
Description
runID
xs:int
The unique run ID of the task execution instance.
Response message
Table 13: taskStatusResponse elements
Element
Type
Description
taskStatusRequest
tns:taskStatusReques A copy of the request used to retrieve the task status.

t
JobID
xs:string
The unique JobID of the task.

Even if a task is deleted and a new one with the same
name is then created, the JobID for each remains
unique.
Web Services Guide

PUBLIC
13
Element
Type
Description
statusCode
xs:string
The status of the task execution.

Possible values:
TASK:IMPORTED
TASK:RUNNING
TASK:SUCCESS
TASK:ERROR
TASK:QUEUEING
TASK:TERMINATED
TASK:TERMINATED_FAILED
TASK:UNKNOWN
statusMsg
xs:string
Additional information about the task execution status.
startTime
xs:string
The time the task execution started.
endTime
xs:string
The time the task execution ended.
executionTime
xs:double
The duration of the task execution.
For more information about the structure of the getTaskStatusByRunID request and response messages, refer
to the SAP HANA Cloud Integration WSDL.
Related Information
2.2.3
getTaskLogs
The getTaskLogs operation retrieves the trace, monitor, or error logs for a task execution with a specified run ID.
Request message
Table 14: taskLogsRequest elements
Element
Type
Description
runID
xs:int
The unique run ID of the task execution instance.
14
PUBLIC
Web Services Guide

Element
Type
Description
base64Encode
xs:boolean
Specifies whether any log data returned should be en

coded in base64 format.
Default value: true
traceLog
tns:LogType
Optional. Specifies which page of the trace log to re

trieve, if any.
monitorLog
tns:LogType
Optional. Specifies which page of the monitor log to re

trieve, if any.
errorLog
tns:LogType
Optional. Specifies which page of the error log to re

trieve, if any.
Table 15: tns:LogType elements

Element
Type
Description
getLog
xs:boolean
Specifies whether to retrieve log data for this log type.
pageNum
xs:int
Specifies the page of the log to return.

Default value: 1
If the page number is not specified or is larger than the
maximum number of pages in the log, the first page is
returned.
Response message
Table 16: taskLogsResponse elements
Element
Type
Description
traceLog
tns:LogContent
The content for the requested page of the trace log.
monitorLog
tns:LogContent
The content for the requested page of the monitor log.
errorLog
tns:LogContent
The content for the requested page of the error log.
Table 17: tns:LogContent elements

Element
Type
Description
maxPage
xs:int
The total number of pages in the log.
pageNum
xs:int
The page number of the requested log page.
isJobRunning
xs:boolean
Specifies whether the task is still running.
messageLines
xs:string
A line of content from the requested page of the log.
For more information about the structure of the getTaskLogs request and response messages, refer to the SAP
HANA Cloud Integration WSDL.
Web Services Guide

PUBLIC
15
Related Information
16
PUBLIC
Web Services Guide

Error reporting
In addition to the output message for each web services operation, the SAP HANA Cloud Integration returns a
fault message when an error occurs.
Fault message
Table 18: WebFaultException elements
Element
Type
Description
faultCode
xs:string
The type of fault that occurred.

Possible values:
faultString
Web Services Guide

Error reporting
xs:string
Connection:Authentication
Services:Authorization
Services:Server
A description of the fault that has occurred.
PUBLIC
17
Important Disclaimers and Legal Information

Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.
Accessibility
The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a
binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does
not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.
Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales
person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not
exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.
Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages
caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency
(see: http://help.sap.com/disclaimer).
18
PUBLIC
Web Services Guide

Web Services Guide

PUBLIC
19
www.sap.com/contactsap
No part of this publication may be reproduced or transmitted in any

form or for any purpose without the express permission of SAP SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only
warranties for SAP or SAP affiliate company products and services
are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein
should be construed as constituting an additional warranty.
SAP and other SAP products and services mentioned herein as well
as their respective logos are trademarks or registered trademarks
of SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the
trademarks of their respective companies.
Please see http://www.sap.com/corporate-en/legal/copyright/
index.epx for additional trademark information and notices.

Hci10 Web Services en PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Hci10 Web Services en PDF

Hochgeladen von

Copyright:

Verfügbare Formate

PUBLIC

SAP HANA Cloud Integration for data services

Web Services Guide

Web service support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Web services technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Creating a client to use web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Supported web service operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Web Services Guide

Web service support

Web services technologies

Connection protocol (envelope for XML messages)

XML-based language used describe published web services

Format used for the WSDL file

Used to group a set of related ports or endpoints to which a client applica

Web Services Guide

Defines a set of operations that a web service publishes.

Defines a specific function call. The software publishes connection and

Defines the data to transmit. There is an input (request) message, which

Accessing the WSDL file

Web Services Guide

Creating a client to use web services

Open the web service.

Run the project to execute the code.

Web Services Guide

Web Services Guide

Supported web service operations

Verifies the connection to SAP HANA Cloud Integration web services.

Verifies secure access and establishes a web services session.

Terminates an existing web services session.

The ping operation can be used to maintain a user session.

The unique ID of the session that should be used for

Web Services Guide

A message that indicates that a connection has been

The name of the SAP HANA Cloud Integration organi

The user name.

Specifies whether to log in to the production or sand

Web Services Guide

A unique session ID that can be used for subsequent

HTTP Basic Authentication

The authentication type and the base64-encoded value

The name of the SAP HANA Cloud Integration organi

The type of repository that the web services session

Web Services Guide

The SOAP action to perform.

The unique ID of the session that should be logged out

A message that indicates that the web services session

Web Services Guide

Executes a task and returns a run ID.

All other roles

Web Services Guide

The unique ID of the session that should be used for

The name of the task that should be executed.

The name of the SAP Data Services Agent that should

Optional. A list of the global variables to pass to the

A unique ID that identifies the specific execution in

Web Services Guide

The unique run ID of the task execution instance.

tns:taskStatusReques A copy of the request used to retrieve the task status.

The unique JobID of the task.

Web Services Guide

The status of the task execution.

Additional information about the task execution status.

The time the task execution started.