Web Service Calls from Within PL/SQL

The Bare Necessities

UTL_HTTP

The UTL_HTTP package can be used to access data on the internet over HTTP.

If the package fetches data from a Web site using HTTPS (secure), then it requires Oracle Wallet Manager (OWM) to set up an Oracle wallet.

Necessary Procedures: BEGIN_REQUEST SET_AUTHENTICATION (if password protected) GET_RESPONSE READ_TEXT

HTTPS calls

1. Get certificates for website (you will need the URL, username, and password). *Demonstration

2. Store the certificates in an Oracle Wallet (using OWM).3. Set the Wallet in your procedure using

UTL_HTTP.SET_WALLET(wallet.path, wallet.password);

UTL_HTTP.BEGIN_REQUEST

UTL_HTTP.BEGIN_REQUEST (url IN VARCHAR2, method IN VARCHAR2 DEFAULT 'GET‘); If url has illegal or reserved characters (like spaces) use UTL_URL package If you desire to post to the website, then put ‘POST’ as the method. If you desire to

receive information from the website, then use ‘GET’. Returns request

UTL_HTTP.SET_AUTHENTICATION

UTL_HTTP.SET_AUTHENTICATION(request, username, password); The request is the returned value after BEGIN_REQUEST. Obtain username and password from web service provider.

UTL_HTTP.GET_RESPONSE

UTL_HTTP.GET_RESPONSE(request); Returns response. The request will be ended when this function returns (regardless of

exception) so there is no need for END_REQUEST.

UTL_HTTP.READ_TEXT

UTTL_HTTP.READ_TEXT(response, response_txt, length); Response is the result of GET_RESPONSE. Response_txt is the out variable set as VARCHAR2. Length is the maximum length you desire the response_txt.

Need to query the response_txt?

Your response may be a string of XML or JSON code. So what if you need to store that data in an ORACLE relational database?

XML

ORACLE needs to know that you desire to query XML not a VARCHAR2 string.

 To change your data type to XMLTYPE do: L_xml := XMLTYPE.CREATEXML(l_response_txt);

L_xml is a local variable of XMLTYPE ORACLE also needs to query from a table: To store your data into a table may I suggest a GTT:

CREATE GLOBAL TEMPORARY TABLE xml_gtt OF XMLTYPE; INSERT INTO xml_gtt VALUES (l_xml);

XML (continued…)

You can now query this data in this way (*assuming your xml data is well formed):     SELECT xtab.column1, xtab.column2, xtab.columnN

      FROM xml_gtt x          ,xmltable('/path1/path2/path3' passing              x.sys_nc_rowinfo$ columns                column1    VARCHAR2(100) path 'xmldata1'              ,column2    VARCHAR2(100) path 'xmldata2'              ,columnN    VARCHAR2(20)  path 'xmldataN') xtab;

SYS_NC_ROWINFO$ is the default column name of the gtt. Example…

JSON

Unlike querying XML, ORACLE can query a VARCHAR2 string of well-formed JSON.

To store your data into a table may I suggest a GTT: CREATE GLOBAL TEMPORARY TABLE json_gtt OF VARCHAR2; INSERT INTO json_gtt VALUES (response_txt);

If desired you can put a constraint on your GTT that checks if your JSON data is well-formed: CONSTRAINT ensure_json CHECK (response_txt IS JSON)

JSON (continued…)

You can now query this data in a similar way as the XML data:     SELECT jtab.column1, jtab.column2, jtab.columnN

      FROM json_gtt j          ,json_table(j.sys_nc_rowinfo$, '$.path1.path2.path3'               COLUMNS(                column1    NUMBER path 'jsondata1'              ,column2    VARCHAR2(100) path 'jsondata2'              ,columnN    VARCHAR2(20)  path 'jsondataN‘)) jtab;

SYS_NC_ROWINFO$ is the default column name of the gtt.