| Oracle® Application Express Application Builder User's Guide Release 3.2 E11947-03 |
|
|
PDF · Mobi · ePub |
| Oracle® Application Express Application Builder User's Guide Release 3.2 E11947-03 |
|
|
PDF · Mobi · ePub |
Web services enable applications to interact with one another over the Web in a platform-neutral, language independent environment. In a typical Web services scenario, a business application sends a request to a service at a given URL by using the protocol over HTTP. The service receives the request, processes it, and returns a response. You can incorporate calls with external Web services in applications developed in Application Builder.
Web services are based on Simple Object Access Protocol (SOAP). SOAP is a World Wide Web Consortium (W3C) standard protocol for sending and receiving requests and responses across the Internet. SOAP messages can be sent back and forth between a service provider and a service user in SOAP envelopes.
SOAP offers two primary advantages:
SOAP is based on XML, and therefore easy to use.
SOAP messages are not blocked by firewalls because this protocol uses simple transport protocols, such as HTTP.
Tip:
If you are running Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services in order to use Web services. See "Enabling Network Services in Oracle Database 11g"Topics in this section include:
Note:
The SOAP 1.1 specification is a W3C note. (The W3C XML Protocol Working Group has been formed to create a standard that will supersede SOAP.)For information about Simple Object Access Protocol (SOAP) 1.1 see:
http://www.w3.org/TR/SOAP/
To utilize Web services in Oracle Application Express, you create a Web service reference using a wizard. Web service references can be based either on a Web Services Description Language (WSDL) document or created manually by supplying information about the service.
When you create a Web service reference based on a WSDL, the wizard analyzes the WSDL and collects all the necessary information to create a valid SOAP message, including:
The URL used to post the SOAP request over HTTP(S)
A Universal Resource Identifier (URI) identifying the SOAP HTTP request
Operations of the Web Service
Input parameters for each operation
Output parameters for each operation
When you create a Web service reference manually, you supply the necessary information to create a valid SOAP request, including:
The URL used to post the SOAP request over HTTP(S)
A Universal Resource Identifier (URI) identifying the SOAP HTTP request
The SOAP envelope for the request, including any item substitutions
Optionally the name of a collection to store the response from the Web service
You manage Web service references on the Web Service References page.
To access the Web Service References page:
On the Workspace home page, click the Application Builder icon.
Select an application.
Application Builder appears.
Click Shared Components.
The Shared Components page appears.
Under Logic, click Web Service References.
The Web Service References page appears.
If your environment requires a proxy server to access the Internet, you must specify a proxy server address on the Application Attributes page before you can create a Web service reference.
To specify a proxy address for an application:
On the Workspace home page, click the Application Builder icon.
Select an application.
Application home page appears.
Click Shared Components.
Under Application, click Definition.
Under Name, enter the proxy server in the Proxy Server field.
Click Apply Changes.
Secure Sockets Layer (SSL) is an industry standard protocol that uses RSA public key cryptography with symmetric key cryptography to provide authentication, encryption, and data integrity.
If the Web service that you need to interact with is SSL-enabled (that is, https displays in the URL to the Web service), you must create a wallet. A wallet is a password-protected container that stores authentication and signing credentials (including private keys, certificates, and trusted certificates) needed by SSL.
See Also:
"Configuring Wallet Information" in Oracle Application Express Administration GuideWhen you create a Web service reference based on a WSDL, you must decide how to locate the WSDL. You can locate a WSDL in two ways:
By searching a Universal Description, Discovery and Integration (UDDI) registry
by entering the URL to the WSDL document
A UDDI registry is a directory where businesses register their Web services.
Topics in this section include:
Creating a Web Service Reference by Searching a UDDI Registry
Creating a Web Service Reference by Specifying a WSDL Document
To create a Web service by searching a UDDI registry:
Navigate to the Web Service References page. See "Accessing the Web Service References Page".
Click Create.
When prompted to search a UDDI registry to find a WSDL, click Yes.
For UDDI Location you can either:
Enter a URL endpoint to a UDDI registry.
Click the List icon and select a UDDI registry.
For Search, specify the following:
Search Type - Specify whether to search for a business name or a service name. You cannot search for both.
Name - Enter the business name or service name to search for. Use the percent (%) symbol as a wildcard character.
Optionally indicate if the search should be case-sensitive or an exact match.
Click Search.
When the search results appear, make a selection and click Next.
A summary page appears describing the selected Web service.
Review your selection and click Next to continue.
The URL to the WSDL document displays in the WSDL Location field.
Click Finish.
The Web service reference is added to the Web Service References Repository.
To create a Web service by specifying a URL to a specific WSDL document:
Navigate to the Web Service References page. See "Accessing the Web Service References Page".
Click Create.
When prompted to search a UDDI registry to find a WSDL, click No.
In WSDL Location, enter the URL to the WSDL document.
Click Finish.
The Web service reference is added to the Web Service References Repository.
To create a Web service reference manually:
Navigate to the Web Service References page. See "Accessing the Web Service References Page".
Click Create.
When prompted to search a UDDI registry to find a WSDL, click No.
From the Tasks list, click Create Web Service Reference Manually.
The Create/Edit Web Service page appears.
In Name, enter a name to identify the reference.
Under Service Description:
URL - Enter the URL endpoint of the Web service.
Action - Enter the action of the Web service (optional).
Proxy - Enter a proxy if you want to override the application proxy for this service.
Basic Authentication - Choose whether the Web service requires authentication. Select Yes or No.
For SOAP Envelop, enter the SOAP envelope for this request.
For Store Response in Collection, enter the name of a collection to store the response (optional).
Click Create.
The Web service reference is added to the Web Service References Repository.
Web service references are stored in the Web Service Reference Repository.
To access the Web Service References Repository:
On the Workspace home page, click the Application Builder icon.
Select an application.
Application Builder appears.
Click Shared Components.
The Shared Components page appears.
Under Logic, click Web Service References.
The Web Service Reference page appears.
Use the Navigation bar at the top of the page to search for Web service references or change the page display. Available options include:
Web Service Reference - Enter a case insensitive query for the reference name and click Go. To view all Web service references, leave the field blank and click Go.
View - Select a display mode and click Go. Available options include:
Icons (the default) displays each Web service reference as a large icon. To edit a Web service reference, click the appropriate icon.
Details displays each Web service reference as a line in a report.
Select Details from the View list and click Go.
In Details view you can:
Edit a reference by clicking the reference name.
Test a reference by clicking the Run icon.
View details about a reference by clicking the View icon. Note that this option is not available for manually created Web service references.
After you have created a Web service reference, you can test it on the Test Web Service Reference page.
To test a Web service reference:
Navigate to the Web Service References page. See "Accessing the Web Service References Page".
From View, select Details.
Click the Run icon adjacent to the Web Service reference name.
The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.
From Operation, select an operation (that is, the method to be executed).
Under Input Parameters, enter the appropriate value.
Click Test.
The message request and response appear at the bottom of the page.
After you have created a Web service reference, you can test it on the Test Web Service Reference page.
To test a Web service reference:
Navigate to the Web Service References page. See "Accessing the Web Service References Page".
From View, select Details.
Click the Run icon adjacent to the Web Service reference name.
The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.
If required, enter the username and password under Basic Authentication.
In SOAP Envelope text area, optionally edit the SOAP request envelope.
Click Test.
The message request and response appear at the bottom of the page.
The Create Form and Report on Web Service Wizard creates an input form, a submit button, and a report for displaying results. You can execute this wizard directly after creating the Web service reference from a WSDL, or by adding a page.
Use this wizard when you expect a nonscalar result from the Web service. The Amazon Web service is a good example. This Web service returns many results based on the search criteria entered in an input form.
To create a form and report after creating a Web Service Reference:
Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".
After the Web service reference has been added, select Create Form and Report on Web Service.
For Choose Service and Operation:
Web Service Reference - Select the Web service reference.
Operation - Select the method to be executed.
For Page and Region Attributes, review the displayed attributes. If the page you specify does not exist, the wizard creates the page for you.
For Input Items:
Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
If necessary, edit the item label.
If applicable, specify the Item Names and Item Labels for basic authentication. Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
For Window Service Results:
Temporary Result Set Name - Enter a name for the collection that stores the Web service result.
Result Tree to Report On - Select the portion of the resulting XML document that contains the information you want to include in the report.
For Result Parameters to Display, select the parameters to be included in the report.
Click Finish.
If you have an existing Web service reference, you can create an input form and report by adding a new page.
To create a form and report by adding a new page:
Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".
Create a new page. See "Managing Pages in an Application".
In the Create Page Wizard:
Select Form.
Select Form and Report on Web Service.
For Choose Service and Operation:
Web Service Reference - Select the Web service reference.
Operation - Select the method to be executed.
For Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.
For Input Items:
Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
If necessary, edit the item label.
If applicable, specify the Item Names and Item Labels for basic authentication. Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
Follow the on-screen instructions.
Click Finish.
The Create Form on Web Service Wizard creates a form and a submit button. You can execute this wizard after creating the Web service reference from a WSDL, or from the Page Definition.
Use this wizard when you expect a scalar result from the Web service. A Web service that looks up a stock price is a good example because the input is a stock symbol and the output is the scalar value price.
To create a form after creating a Web Service Reference:
Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".
After the Web service references has been added, select Create Form on Web Service.
For Choose Service and Operation:
Web Service Reference - Select the Web service reference.
Operation - Select the method to be executed.
For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.
For Items for Input Parameters:
Identify which items to add. To include an item, select Yes in the Create column. Otherwise, select No.
If necessary, edit the item label.
For Items for Output Parameters:
Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.
If necessary, edit the item label.
If applicable, specify the Item Names and Item Labels for basic authentication.
Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
Click Finish.
If you have an existing Web service reference created from a WSDL, you can create form by adding a new page.
To create a form by adding a new page:
Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".
Create a new page. See "Managing Pages in an Application".
In the Create Page Wizard:
Select Form.
Select Form on Web Service.
For Web Service Reference and Operation, select the Web service reference and operation (that is, the method to be executed).
For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.
For Items for Input Parameters:
Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.
If applicable, specify the Item Names and Item Labels for basic authentication.
Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
For Items for Output Parameters:
Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.
If necessary, edit the item label.
Click Finish.
You can also implement a Web service as a process on the page. Running the process submits the request to the service provider. You can then display the request results in report.
To invoke a Web service as a process:
Create a page. See "Managing Pages in an Application".
In the Create Page Wizard:
Select Blank Page.
When prompted to use tabs, select No.
Navigate to the Page Definition. See "Accessing a Page Definition".
Under Page Rendering, Processes, click the Create icon.
From the process category, select Web Services.
Specify a process name, sequence, and processing point.
Select the Web service reference.
If the Web reference was created from a WSDL, perform the following additional steps.
Select the Web service reference and operation (that is, the method to be executed).
Define the process. You can store the results in a collection or in items on the page by selecting options under Web Service Output Parameters.
To store the results in a collection:
For Store Result in, select Collection.
Enter a name for the collection in the value field.
To store the results in items on the page:
For Store Result in, select Items.
Enter the appropriate items value in the fields provided.
Click Create Process.
To create a report in which to display Web Service request results:
Navigate to the Page Definition. See "Accessing a Page Definition".
Under Regions, click the Create icon.
The Create Region Wizard appears.
For the region type, select Report.
For the report implementation, select Report on collection containing Web service result.On Identify Region Attributes, enter a region title and optionally edit the region attributes.
Choose whether the Web reference was created manually or from a WSDL.
If the Web service reference was created from a WSDL:
For Web Service Reference and Operation, select a Web service reference and an operation (that is, the method to be executed).
For Result Tree to Report On, select the portion of the resulting XML document that contains the information you want to include in the report.
For Result Parameters:
In Temporary Result Set Name, enter a name for the collection that stores the Web service result.
Select and deselect the appropriate parameters.
If the Web service reference was created manually:
Select the Web service reference.
Choose the SOAP style.
Choose the message format.
Enter the XPath expression to the node to report on.
Enter the namespace for the SOAP response envelope and click Next.
Enter the name of the collection where the response message is stored.
Enter the names of the parameters that you want to be included in the report.
Click Create SQL Report.
After you create a process of type Web service on a Web service reference created from a WSDL, you can map input parameters to a static value (for example to pass a key) by editing the Web service process.
To edit a Web service process:
Create a Web service process. See "Invoking a Web Service as a Process".
Navigate to the Page Definition containing the Web service process.
Select the process name.
The Edit Page Process page appears.
To map an input parameter to a static value:
Scroll down to Web Service Input Parameters.
Enter a value in the Value field, adjacent to the appropriate parameter name.
Click Apply Changes.
The Web Services History displays changes to Web service references for the current application by application ID, Web service references name, developer, and date.
To view a history of Web service reference changes:
On the Workspace home page, click the Application Builder icon.
Select an application.
Application Builder appears.
Click Shared Components.
The Shared Components page appears.
Under Logic, click Web Service References.
Click History.
Note:
The History button only appears on the Web Service Reference page after you have created a Web service reference.
|
 Copyright © 2003, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
