JMJ CLOUD
  • Home
  • Projects
  • Blog
  • About Us
  • Contact Us

Our Blog

Accessing CGI Information from ORDS Handlers

9/1/2016

1 Comment

 

Background

OWA_UTIL is a database package that provides access to PL/SQL Common Gateway Interface (CGI) variables. Oracle REST Data Services (ORDS) 2.0 introduced a full OWA environment allowing us to tap into the information provided by OWA_UTIL.

So, why is this useful to me? OWA_UTIL holds a significant amount of information about the environment in which your ORDS PL/SQL handler is being called. This includes information such as the character set, host name, port, web service name and even information about the caller of the service such as the user agent.

In this post I will take you through an example of how to tap into the CGI information available to you in OWA_UTIL. Before we get started, however, you should know that the OWA environment is only available for ORDS POST, PUT and DELETE services. The OWA environment is not set for Collection or Query GET handler types.

What CGI Variables are Available?

By far the quickest (and best) way to see what CGI variables are available to ORDS is to use 'owa_util.print_cgi_env'. This will print out all of the CGI variables in the current session. At this point you may ask how do I see this from my ORDS web service? Well it is easier than you may think.

First of all, let's create a basic ORDS module, resource template and GET handler to use for our CGI tinkering. The slide show below, illustrates my example service:
Note: The GET handler Source Type is PL/SQL. Now that we have a get handler, all we need to do it add a PL/SQL block with a call to  owa_util.print_cgi_env:

    
All that is left to do is call the web service, I am going to illustrate this using CURL:
curl -X GET -H "Accept: application/json" -H "Cache-Control: no-cache" "https://example.com:443/ords/ordstest/master/owablog"

After running the CURL command, you should see a list of the CGI variables, I have a link below to a file with the full response but wanted to illustrate some some of the more interesting ones:
  • accept = application/json
  • APEX_LISTENER_VERSION = 3.0.5.124.10.54
  • REQUEST_METHOD = GET
  • PATH_INFO = /owablog
  • SCRIPT_NAME = /ords/ordstest/master
  • REMOTE_USER = ORDSTEST
  • REQUEST_CHARSET = AL32UTF8
  • REQUEST_IANA_CHARSET = UTF-8
  • REQUEST_PROTOCOL = https
  • REQUEST_SCHEME = https
  • SERVER_NAME = example.com
  • SERVER_PORT = 443

Having this information available opens up some interesting possibilities:
  1. You can develop a generic logging API to log web service calls. A combination of PATH_INFO, SCRIPT_NAME and REQUEST_METHOD can be used to identify the service and log all your web service calls to to a log table.
  2.  The caller of the service (in this case our CURL command) indicated they wanted a JSON response. Having access to this HTTP header value is key in us being able to honor this response. Of course, in this case we could have added a parameter to our handler to get this HTTP header value from a bind variable.
  3. If you have some code that is ORDS version specific, it may be handy to know the version of ORDS which is running.
full_response_listing_all_cgi_variables.txt
File Size: 1 kb
File Type: txt
Download File

Referencing Individual Values

Now that we know what information we have access to, how do we access it without having to parse the results of 'print_cgi_env'?

The short answer is to use 'owa_util.get_cgi_env'. You simply pass the name of the variable you want and it will return the value. Let's change the Handler for our GET service so that it responds with the URL used to call the web service.

    
If we run the CURL command again:
curl -X GET -H "Cache-Control: no-cache" "https://example.com:443/ords/ordstest/master/owablog"
We should get the following:
You called me with: https://example.com:443/ords/ordstest/master/owablog

Conclusion

In this post, we have seen why having access to the CGI information for a web service call can be useful and how you can get access to that information from within an ORDS session.
1 Comment
Stan
4/25/2019 04:50:54 am

We can also loop over CGI variables like this:

apex_json.open_object;
FOR i IN 1..owa.num_cgi_vars LOOP
apex_json.write( owa.cgi_var_name(i), owa.cgi_var_val(i) );
END LOOP;
apex_json.close_object;

Useful if we want to audit all of them.

Reply

Your comment will be posted after it is approved.


Leave a Reply.

    RSS Feed

    Popular Posts

    - APEX Dog Food
    - Cloud ERP & APEX Mashup
    - Modernizing EBS with APEX
    - Easy APEX_WEB_SERVICE
    - Running APEX in RDS
    - ORDS What & Why?

    Categories

    All
    APEX
    AWS
    Fusion Cloud ERP
    INTEGRATION
    OCI
    ORDS
    PaaS
    RAD
    REST
    SOAP

    Archives

    January 2021
    October 2020
    September 2020
    June 2020
    May 2020
    April 2020
    February 2020
    January 2020
    October 2019
    September 2019
    August 2019
    July 2019
    June 2019
    April 2019
    March 2019
    February 2019
    January 2019
    December 2018
    November 2018
    October 2018
    September 2018
    August 2018
    July 2018
    June 2018
    May 2018
    April 2018
    March 2018
    February 2018
    January 2018
    September 2017
    August 2017
    July 2017
    June 2017
    February 2017
    January 2017
    December 2016
    November 2016
    October 2016
    September 2016
    August 2016
    July 2016

Company

About
Contact
Blog
  • Home
  • Projects
  • Blog
  • About Us
  • Contact Us