CFHTTP Presentation - June 15 2000

Exploring CFHTTP
Rob Brooks-Bilson
What We'll Cover
 Introduction to CFHTTP
 Retrieving data using CFHTTP
 Generating static HTML pages
 Using the POST method
 Exception handling
 Known issues
Introduction to CFHTTP
What is CFHTTP?
 One of ColdFusion's most powerful tags
 Capable of performing HTTP GET and POST
operations
 Works much the same way as a browser
request
 A variety of attributes allow for a high degree
of flexibility and customization when using the
tag.
 See the CFML Tag Reference in the
ColdFusion documentation for detailed
descriptions of each tag attribute
Why CFHTTP?
 Many uses:
– Gathering content such as stock quotes, news
feeds, etc. from remote sites
– Generating static HTML from dynamic content
– Posting information to remote forms
– Building intelligent agents
– Automating scheduled tasks
– Calling Java servlets on non-jRun servers
General Tag Syntax
<CFHTTP METHOD="get_or_post"
URL="url"
RESOLVEURL="yes/no"
REDIRECT="yes/no"
PORT="port_number"
USERNAME="username"
PASSWORD="password"
NAME="query_name"
COLUMNS="query_columns"
PATH="path"
FILE="filename"
DELIMITER="delimiter"
TEXTQUALIFIER="character"
PROXYSERVER="hostname_or_IP_address"
PROXYPORT="port_number"
TIMEOUT="timeout_period"
USERAGENT="user_agent"
THROWONERROR="yes/no">
</CFHTTP>
New In ColdFusion 4.5.x
 New attributes added:
– USERAGENT (string)
• Optional
• Passes a user agent in the request header
– REDIRECT (Yes/No)
• Optional
• Indicates whether to allow a request to be
redirected
– PROXYPORT (port number)
• Optional
• Automatically appends the proxy port to urls
when RESOLVEURL is set to Yes
New in ColdFusion 4.5.x
 New attributes added (continued):
– THROWONERROR (Yes/No)
• Optional
• Indicates whether to throw a catchable
exception that can be handled with
CFTRY/CFCATCH
 SSL support for Unix
 Additional return variables
– CFHTTP.Header (raw)
– CFHTTP.ResponseHeader (structure)
Retrieving data using CFHTTP
The Basics
 CFHTTP uses the HTTP GET method to
initiate a one-way request for information from
a remote server
 Can retrieve HTML, plain text, XML, or binary
data
 Retrieved data stored in one of two places
– CFHTTP.FileContent for text
– Query object for record sets
– Binary files are automatically saved to the
ColdFusion server
Retrieving Information to a Variable
 The CFHTTP tag can be used to retrieve text
such as HTML and XML from a remote HTTP
server
 Uses HTTP GET method to retrieve the file
via URL
 The retrieved text is stored in a ColdFusion
variable called CFHTTP.FileContent
 The MIME type of the file is stored as
CFHTTP.MIMEType
 Very useful for retrieving syndicated content
(i.e. WDDX packets or other XML)
Retrieving Information to a Variable
<!--- Get the home page of the PACFUG site --->
<CFHTTP METHOD="Get"
URL="http://www.pacfug.org"
RESOLVEURL="Yes">
<!--- output the contents --->
<CENTER>
<H2>Look at what we have here…</H2>
</CENTER>
<CFOUTPUT>
#CFHTTP.FileContent#
</CFOUTPUT>
Retrieving Information to a Variable
Getting HTTP Header Information
 Two variables are returned with a GET
operation that contain information from the
HTTP header:
– CFHTTP.Header contains the raw HTTP
header
– CFHTTP.ResponseHeader is a ColdFusion
structure that contains key/value pairs for each
of the items in the HTTP header
• Keys appearing once are stored as simple
values within the structure
• Keys appearing more than once are stored as
part of an array within the structure
Getting HTTP Header Information
 The CFHTTP.ResponseHeader structure can
be parsed to obtain information about the
requested page
– This technique can be used to read any
cookies set by the remote site.
– This overcomes a limitation in the CFHTTP tag
for versions of ColdFusion prior to 4.5.x
Retrieving the HTTP Header
<!--- retrieve amkor's web site --->
<CFHTTP URL="http://www.amkor.com" METHOD="GET">
<!-- loop over and output all of the values in the http
header --->
<TABLE BORDER="1" CELLSPACING="0" CELLPADDING="5">
<TR><TH>Key</TH><TH>Value</TH></TR>
<CFLOOP COLLECTION=#CFHTTP.ResponseHeader# ITEM="Key">
<CFSET Value = CFHTTP.ResponseHeader[Key]>
<CFIF IsArray(Value)>
<CFLOOP INDEX="i" FROM=1 TO=#ArrayLen(Value)#>
<CFOUTPUT>
<TR><TD>#key#</TD><TD>#value[i]#</TD></TR>
</CFOUTPUT>
</CFLOOP>
<CFELSE>
<CFOUTPUT><TR><TD>#Key#</TD><TD>#value#</TD></TR></CFOUTPUT>
</CFIF>
</CFLOOP>
</TABLE>
Sample HTTP Header
Retrieving and Saving Files
 The CFHTTP tag can be used to retrieve a file
from a remote HTTP server
 Uses HTTP GET method to retrieve the file
via URL
 A copy of the file is saved to the local file
system of the ColdFusion server
 Any type of file may be retrieved
 The MIME type of the downloaded file is
returned as CFHTTP.MIMEType
 Very useful for retrieving file based syndicated
content (i.e. WDDX packets or other XML)
Retrieving and Saving a Binary File
<!--- retrieve a file from a remote server. The FILE
attribute is optional. --->
<CFHTTP METHOD="Get"
URL="http://www.pacfug.org/images/whats_new.gif
FILE="whats_new.gif"
PATH="d:\temp1\">
<!--- output the MIME type of the retrieved file --->
<CFOUTPUT>
MIME Type: #CFHTTP.MIMEType#
</CFOUTPUT>
Creating a Query Object from a
Delimited Text File
 CFHTTP can be used to read the contents of
a delimited text file into a query object
 This allows you to use any delimited text file
that can be accessed via URL as a "pseudo
data source"
 CFHTTP uses the first row of data in the file
as the column headers for the query object
 The returned query object can be manipulated
just like any query object created by
CFQUERY
Creating a Query Object from a
Delimited Text File
<!--- save this file as myfile.txt. Be sure to remove this comment line first --->
Name,Title,Department,Extension
Joe Smith,Lead Salesperson,Sales,5515
Nancy Jones,Liaison,Marketing,5596
Tom White,Mechanical Engineer I,Engineering,5525
Jen Brown,Collection Specialist,Billing,5543
Creating a Query Object from a
Delimited Text File
<CFHTTP URL="http://127.0.0.1/cf/8/MyFile.txt" METHOD="get"
NAME="MyQuery" DELIMITER="," TEXTQUALIFIER=" ">
</CFHTTP>
<TABLE BORDER="0" CELLPADDING="3">
<TR>
<TH BGCOLOR="#8A8A8A">Name</TH>
<TH BGCOLOR="#8A8A8A">Title</TH>
<TH BGCOLOR="#8A8A8A">Department</TH>
<TH BGCOLOR="#8A8A8A">Extension</TH>
</TR>
<CFOUTPUT QUERY="MyQuery">
<TR>
<TD BGCOLOR="##C0C0C0">#Name#</TD>
<TD BGCOLOR="##C0C0C0">#Title#</TD>
<TD BGCOLOR="##C0C0C0">#Department#</TD>
<TD BGCOLOR="##C0C0C0">#Extension#</TD>
</TR>
</CFOUTPUT>
</TABLE>
Creating a Query Object from a
Delimited Text File
Passing Additional Parameters Using
CFHTTP GET
 It is possible to pass URL parameters with the
CFHTTP tag using the GET method
 This allows you to retrieve a page that is
dynamically generated based on URL
variables it receives
 This is useful in cases where you need to
provide information to a remote form that uses
the GET method instead of POST
Passing Additional Parameters Using
CFHTTP GET
<!--- provide URL variables to Yahoo's search interface
because it uses GET instead of POST in its form --->
<CFHTTP METHOD="Get"
URL="http://search.yahoo.com/bin/search?p=Allaire+Cold+Fusio
n"
RESOLVEURL="Yes">
<!--- output the search results --->
<CENTER>
<H2>And the results are in…</H2>
</CENTER>
<CFOUTPUT>
#CFHTTP.FileContent#
</CFOUTPUT>
Passing Additional Parameters
Parsing Data
 Sometimes it is necessary to extract a subset
of data from the results of a CFHTTP call
 You may also need to “massage” data
returned as a query object
 Several functions and custom tags make it
relatively easy:
– CF_SecretAgentOneTwoThree
– Find/REFind
– ReplaceREReplace
– Query manipulation functions
Generating Static HTML Pages
Generating Static HTML Pages
 CFHTTP can be used to create static HTML
pages from dynamic content
 Sources of dynamic content are NOT limited
to your ColdFusion server nor are they limited
to ColdFusion generated pages
 Why generate static pages?
– Performance
• Static pages load faster
• Reduce access time on pages that require long
queries to generate
– Make your pages more visible to search
engines
Generating Static HTML Pages
<!--- use CFHTTP to get the content from a remote site --->
<CFHTTP METHOD="Get"
URL="http://www.myserver.com/mydynamictemplate.cfm"
RESOLVEURL="Yes">
<!--- create the static file using the CFFILE tag --->
<CFFILE ACTION="Write"
FILE="c:\inetsrv\wwwroot\myfile.htm"
OUTPUT="#CFHTTP.FileContent#">
Using The POST Method
The Basics
 CFHTTP uses the HTTP POST method to
post information to a remote server
 This is usually the same operation that occurs
when a web browser submits an HTML form
 The CFHTTPPARAM tag is used to specify
the type of information to post
– Form fields
– URL variables
– CGI variables
– Cookies
– Files
More Basics
 The CFHTTPPARAM tag is nested with the
CFHTTP tag
 More than one CFHTTPPARAM tag may be
used
 If the template being posted to generates any
output, it is returned in CFHTTP.FileContent
Posting Information
<!--- Post various data types to a remote Perl script --->
<CFHTTP METHOD="POST"
URL="http://www.foo.com/cgi-bin/formaccept.pl"
RESOLVEURL="Yes">
<CFHTTPPARAM TYPE="FormField" NAME="UserID"
VALUE="jblow">
<CFHTTPPARAM TYPE="URL" NAME="ID"
VALUE="12345">
<CFHTTPPARAM TYPE="Cookie" NAME="UserID"
VALUE="jblow">
<CFHTTPPARAM TYPE="CGI" NAME="HTTP_REFERER"
VALUE="http://www.foo.com/cgi-bin/form.htm">
<CFHTTPPARAM TYPE="File"
NAME="MyFile"
FILE="c:\cf\test.txt">
</CFHTTP>
<CFOUTPUT>#CFHTTP.FileContent#</CFOUTPUT>
Exception Handling
Exception Handling
 Setting THROWONERROR="Yes" allows
ColdFusion to throw a catchable exception in
the event of a problem with the CFHTTP tag
– Exceptions can be handled using
CFTRY/CFCATCH
 Setting THROWONERROR="No" (the default)
causes ColdFusion to write status information
about the transaction to CFHTTP.StatusCode
– There are 37 possible status codes
Exception Handling
<CFTRY>
<H2>Using CFHTTP to grab <I>http://www.pacfug.org/test.htm</I></H2>
<CFHTTP METHOD="Get"
URL="http://www.pacfug.org/test.htm"
THROWONERROR="Yes">
<CFCATCH TYPE="Any">
<H3>Looks like we had an error:</H3>
<CFOUTPUT>
Error Type: <I>#CFCATCH.Type#</I><BR>
Error Message: <I>#CFCATCH.Message#</I>
</CFOUTPUT>
<CFABORT>
</CFCATCH>
</CFTRY>
<CFOUTPUT>
#CFHTTP.FileContent#
</CFOUTPUT>
Exception Handling
Known Issues
Known Issues
 Allaire's documentation on the
THROWONERROR attribute of the CFHTTP
tag (in CF 4.5.x) is incorrect
– The CFHTTP.StatusCode is returned when
THROWONERROR="No", not when it is set to
Yes
 Column headers and delimited text fields
– Been an "issue" since CFHTTPs inception
– Work-around is to include column headers or a
bogus line of data for the first row in the file
Known Issues
 Authentication
– Basic (plain text) authentication is supported
on the Windows platform by using the
Usernamer/Password attributes of the
CFHTTP tag
– Basic authentication does not work on MS IIS
servers when NT Challenge/Response
Authentication is enabled
Known Issues
"Error Occurred While Processing Request"
error in Windows 95
– Results from an out of date dll file
– Download the updated Windows Socket 2
from:
http://www.microsoft.com/windows95/downloa
ds/contents/wuadmintools/s_wunetworkingtool
s/w95sockets2/default.asp
Known Issues
 “Connection Failure” in CF 4.5.x
– Try adding a valid browser for the
USERAGENT attribute as many remote
servers check for a valid browser type before
returning any content
– This is often a firewall/proxy server issue
• Look at the PORT, PROXYSERVER and
PROXYPORT attributes
• Try specifying the IP address for the
PROXYSERVER attribute if using the host
name fails
Questions?