|
cfhttp
DescriptionGenerates
an HTTP request and handles the response from the server.
Syntax<cfhttp
url = "server URL"
charset = "character encoding"
clientCert = "filename"
clientCertPassword = "password"
columns = "query columns"
delimiter = "character"
file = "filename"
firstrowasheaders = "yes|no"
getAsBinary = "auto|yes|no|never"
method = "method name"
multipart = "yes|no"
name = "query name"
password = "password"
path = "path"
port = "port number"
proxyServer = "host name"
proxyPort = "port number"
proxyUser = "username"
proxyPassword = "password"
redirect = "yes|no"
resolveURL = "yes|no"
result = "result name"
textQualifier = "character"
throwOnError = "yes|no"
timeout = "time-out period in seconds"
username = "username"
userAgent = "user agent">
cfhttpparam tags [optional for some methods]
</cfhttp>
Note: You can specify
this tag’s attributes in an attributeCollection attribute
whose value is a structure. Specify the structure name in the attributeCollection attribute
and use the tag’s attribute names as structure keys.
HistoryColdFusion
8: Added the clientCert and clientCertPassword attributes.
ColdFusion
MX 7.01: Added the “never” value of the getAsBinary attribute.
ColdFusion
MX 7: Added the result attribute, which allows
you to specify an alternate variable in which to receive a result.
ColdFusion
MX 6.1:
Added support for the following methods: HEAD,
PUT, DELETE, OPTIONS, TRACE.
Added multipart, getAsBinary, proxyUser,
and proxyPassword attributes.
Changed httpparam behavior: all operations
can have httpparam tags.
Added the cfhttp.errorDetail return variable.
Modified response body content types considered to be text.
Changed behavior for multiple headers: multiple headers of
the same type are returned in an array.
Added support for HTTPS proxy tunneling.
Fixed bugs in code and documentation.
ColdFusion
MX:
Added the charset and firstrowasheaders attributes.
Changed Secure Sockets Layer (SSL) support: ColdFusion uses
the Sun JSSE library, which supports 128-bit encryption, to support
SSL.
AttributesThe
following attributes control the HTTP transaction and can be used
for all HTTP methods:
Attribute
|
Req/Opt
|
Default
|
Description
|
url
|
Required
|
Uses the http
protocol
|
Address of the resource on the server that
handles the request. The URL must include the hostname or IP address.
If
you do not specify the transaction protocol (http:// or https://),
ColdFusion uses the default protocol, http.
If you specify
a port number in this attribute, it overrides any port attribute value.
The cfhttpparam tag URL attribute
appends query string attribute-value pairs to the URL.
|
charset
|
Optional
|
For request: UTF-8
For response: charset specified
by response Content- Type header, or UTF-8 if response
does not specify charset.
|
The character encoding of the request, including
the URL query string and form or file data, and the response. The
following list includes commonly used values:
utf-8
iso-8859-1
windows-1252
us-ascii
shift_jis
iso-2022-jp
euc-jp
euc-kr
big5
euc-cn
utf-16
For more information
character encodings, see www.w3.org/International/O-charset.html.
|
clientCert
|
Optional
|
|
The full path to a PKCS12 format file that
contains the client certificate for the request.
|
clientCertPassword
|
Optional
|
|
Password used to decrypt the client certificate.
|
getAsBinary
|
Optional
|
no
|
no: if ColdFusion
does not recognize the response body type as text, converts it to
a ColdFusion object.
auto: if ColdFusion does not recognize the
response body type as text, converts it to ColdFusion Binary type
data.
yes: always converts the response body content
into ColdFusion Binary type data, even if ColdFusion recognizes
the response body type as text.
never: prevents the automatic conversion
of certain MIME types to the ColdFusion Binary type data; treats
the returned content as text.
ColdFusion recognizes
the response body as text if:
the header does not
specify a content type.
the content type starts with "text".
the content type starts with "message".
the content type is "application/octet-stream".
If
ColdFusion does not recognize the body as text and converts it to
an object, but the body consists of text, the cfoutput tag
can display it. The cfoutput tag cannot display
Binary type data. (To convert binary data to text, use the ToString function.)
|
method
|
Optional
|
GET
|
GET: requests
information from the server. Any data that the server requires to identify
the requested information must be in the URL or in cfhttptype="URL" tags.
POST: sends information to the server for
processing. Requires one or more cfhttpparam tags.
Often used for submitting form-like data.
PUT: requests the server to store the message
body at the specified URL. Use this method to send files to the
server.
DELETE: requests the server to delete the
specified URL.
HEAD: identical to the GET method,
but the server does not send a message body in the response. Use
this method for testing hypertext links for validity and accessibility,
determining the type or modification time of a document, or determining
the type of server.
TRACE: requests that the server echo the
received HTTP headers back to the sender in the response body. Trace
requests cannot have bodies. This method enables the ColdFusion
application to see what is being received at the server, and use
that data for testing or diagnostic information.
OPTIONS: a request for information about
the communication options available for the server or the specified
URL. This method enables the ColdFusion application to determine
the options and requirements associated with a URL, or the capabilities
of a server, without requesting any additional activity by the server.
|
password
|
Optional
|
|
Use to pass a password to the target URL
for Basic Authentication. Combined with username to
form a base64 encoded string that is passed in the Authenticate
header. Does not provide support for Integrated Windows, NTLM, or Kerebos
authentication.
|
port
|
Optional
|
80 for http
443 for https
|
Port number on the server to which to send
the request. A port value in the url attribute
overrides this value.
|
proxyServer
|
Optional
|
|
Host name or IP address of a proxy server
to which to send the request.
|
proxyPort
|
Optional
|
80
|
Port number to use on the proxy server.
|
proxyUser
|
Optional
|
|
User name to provide to the proxy server.
|
proxyPassword
|
Optional
|
|
Password to provide to the proxy server.
|
redirect
|
Optional
|
yes
|
If the response header includes a Location
field AND ColdFusion receives a 300-series (redirection) status
code, specifies whether to redirect execution to the URL specified
in the field:
yes: redirects
execution to the specified page.
no: stops execution and returns the response
information in the cfhttp variable, or throws an
error if the throwOnError attribute is True.
The cfhttp.responseHeader.Location variable
contains the redirection path. ColdFusion follows a maximum of four
redirects on a request. If there are more, ColdFusion functions
as if redirect = "no".
Note: The cflocation tag
generates an HTTP 302 response with the url attribute
as the Location header value.
|
resolveURL
|
Optional
|
no
|
no: does not
resolve URLs in the response body. As a result, any relative URL links
in the response body do not work.
yes: resolves URLs in the response body
to absolute URLs, including the port number, so that links in a
retrieved page remain functional. Applies to these HTML tags:
img
src
a href
form action
applet code
script src
embed src
embed pluginspace
body background
frame src
bgsound src
object data
object classid
object codebase
object usemap
Does not
resolve URLs if the file and path attributes
are used.
|
throwOnError
|
Optional
|
no
|
yes: if the
server returns an error response code, throws an exception that
can be caught using the cftry and cfcatch or
ColdFusion error pages.
no: does not throw an exception if an error
response is returned. In this case, your application can use the cfhttp.StatusCode variable
to determine if there was an error and its cause.
|
timeout
|
Optional
|
|
Value, in seconds, that is the maximum time
the request can take. If the time-out passes without a response,
ColdFusion considers the request to have failed.
If the client
specifies a time-out in the URL search parameter (for example, ?RequestTime=120)
ColdFusion uses the lesser of the URL time-out and the timeout attribute
value; this ensures that the request times out before, or at the same
time as, the page.
If the URL does not specify a time-out,
ColdFusion uses the lesser of the Administrator time-out and the timeout attribute
value.
If the time-out is not set in any of these, ColdFusion
waits indefinitely for the cfhttp request to process.
|
userAgent
|
Optional
|
ColdFusion
|
Text to put in the user agent request header.
Used to identify the request client software. Can make the ColdFusion
application appear to be a browser.
|
username
|
Optional
|
|
Use to pass a user name to the target URL
for Basic Authentication. Combined with password to
form a base64 encoded string that is passed in the Authenticate
header. Does not provide support for Integrated Windows, NTLM, or
Kerberos authentication.
|
The following attribute is used with the
PUT method to determine how to send data specified with httpparam type="formField":
Attribute
|
Req/Opt
|
Default
|
Description
|
multipart
|
Optional
|
no
(Sends as multipart only if request includes
File type data.)
|
Tells ColdFusion to send all data specified
by cfhttpparam type="formField" tags as multipart
form data, with a Content-Type of multipart/form-data. By default,
ColdFusion sends cfhttp requests that contain only formField data
with a Content Type of application/x-www-form-urlencoded. (If the
request also includes File type data, ColdFusion uses the multipart/form-data
content type for all parts.)
If yes, ColdFusion
also sends the request’s charset in each Content-Type description.
All form field data must be encoded in this character encoding,
and ColdFusion does not URLEncode the data. (The field name must
be in ISO-88591-1 or ASCII.) Some http parsers, including the one
used by previous versions of ColdFusion, ignore the multipart form
field character encoding description.
|
The following attribute sets a multipart
header field and is used, for example, for uploading videos on YouTube.
Attribute
|
Req/Opt
|
Default
|
Description
|
multipartType
|
Optional
|
form-data
|
Allows you to set the multipart header field
to related or form-data. By default,
the value is form-data.
|
Example:
<!--- Get Video --->
<cfset videoName = "<vedio path>\hello.wmv">
<cfset videoFileName = "hello.wmv">
<cfoutput>
<!--- Set User Account Data --->
<cfset clientKey = "client key from google"/>
<cfset devKey = "<dev key from google>"/>
<cfset youTubeUploadURL = "http://uploads.gdata.youtube.com/feeds/api/users/default/uploads"/>
<!--- Authenticate with Google / YouTube --->
<cfhttp url="https://www.google.com/accounts/ClientLogin" method="post" result="result" charset="utf-8">
<cfhttpparam type="formfield" name="accountType" value="HOSTED_OR_GOOGLE">
<cfhttpparam type="formfield" name="Email" value="<gmail id>">
<cfhttpparam type="formfield" name="Passwd" value="<password>">
<cfhttpparam type="formfield" name="service" value="youtube">
<cfhttpparam type="formfield" name="source" value="youtubecode">
</cfhttp>
<!--- Create Auth Token --->
<cfset content = result.filecontent>
<cfset authdata = structNew()>
<cfloop index="line" list="#content#" delimiters="#chr(10)#">
<cfset dtype = listFirst(line, "=")>
<cfset value = listRest(line, "=")>
<cfset authdata[dtype] = value></cfloop>
<!--- Create ATOM XML and save to a file to be sent with video --->
<cfsavecontent variable="meta"><cfoutput>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:media="http://search.yahoo.com/mrss/"
xmlns:yt="http://gdata.youtube.com/schemas/2007">
<media:group>
<media:title type="plain">WithOutQuotes</media:title>
<media:description type="plain">Test Description</media:description>
<media:category
scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People
</media:category>
<media:keywords>yourvideo</media:keywords>
</media:group>
</entry>
</cfoutput>
</cfsavecontent>
<cfset tmpfile = expandPath("./meta.xml")/>
<cffile action="write" file="#tmpfile#" output="#trim(meta)#" />
<!--- Upload video --->
<cfhttp url="#youTubeUploadURL#" result="result" method="POST" timeout="450" multipartType="related">
<cfhttpparam type="header" name="Authorization" value="GoogleLogin auth=#authdata.auth#">
<cfhttpparam type="header" name="X-GData-Client" value="#variables.clientkey#">
<cfhttpparam type="header" name="X-GData-Key" value="key=#variables.devkey#">
<cfhttpparam type="header" name="Slug" value="#videoFileName#">
<!---<CFHTTPPARAM type="HEADER" name="Connection" value="Keep-Alive"> --->
<!--- Send 2 files --->
<cfhttpparam type="file" name="API_XML_Request" file="#tmpfile#"
mimetype="application/atom+xml">
<cfhttpparam type="file" name="file" file="#videoName#" mimetype="video/*">
</cfhttp>
<cfdump var="#result#"/>
</cfoutput>
The following attribute allows you
to specify the name of the variable in which you would like the
results of the operation returned. The name you specify replaces cfhttp as
the prefix by which you access the returned variables. For example,
if you set the result attribute to myResult,
you would access FileContent as #myResult.FileContent#.
The result attribute
allows functions or CFCs that are called from multiple pages at
the same time to avoid overwriting the results of one call with
another. For information about the variables returned by a cfhttp get
operation, see the section Variables returned by a cfhttp get operation in
the Usage section.
Attribute
|
Req/Opt
|
Default
|
Description
|
result
|
Optional
|
|
Specifies the name of the variable in which
you want the result returned.
|
The following attributes tell ColdFusion
to put the HTTP response body in a file. You can put the response
body in a file for GET, POST, PUT, DELETE, OPTIONS, and TRACE methods,
but it is generally not useful with the DELETE or OPTIONS method.
Attribute
|
Req/Opt
|
Default
|
Description
|
file
|
Required if path is specified
and not a GET method
|
See Description
|
Name of the file in which to store the response
body.
For a GET operation, the default is the file requested
in the URL, if there is one. For example, if the URL in a GET method
is http:www.myco.com/test.htm, the default file is test.htm.
Do
not specify the path to the directory in this attribute; use the path attribute.
|
path
|
Required if file is specified.
|
|
Tells ColdFusion to save the HTTP response
body in a file. Contains the absolute path to the directory in which
to store the file.
|
Use the following syntax in the path attribute
to specify an in-memory directory for your files. In-memory files
speed processing of transient data.
ram:///filepath
The
filepath can include multiple directories, for example ram:///petStore/images.
Create the directories in the path before you can use them. For
more information on using in-memory files, see Optimizing transient
files in the Developing ColdFusion Applications.
The
following attributes tell ColdFusion to convert the HTTP response
body into a ColdFusion query object. They can be used with the GET
and POST methods only.
Attribute
|
Req/Opt
|
Default
|
Description
|
columns
|
Optional
|
First row of response
contains column names.
|
The column names for the query, separated
by commas, with no spaces. Column names must start with a letter.
The remaining characters can be letters, numbers, or underscore
characters (_).
If there are no column name headers in the
response, specify this attribute to identify the column names.
If
you specify this attribute, and the firstrowasHeader attribute
is True (the default), the column names specified by this attribute
replace the first line of the response. You can use this behavior
to replace the column names retrieved by the request with your own
names.
If a duplicate column heading is encountered in either
this attribute or in the column names from the response, ColdFusion
appends an underscore to the name to make it unique.
If the
number of columns specified by this attribute does not equal the
number of columns in the HTTP response body, ColdFusion generates
an error.
|
delimiter
|
Optional
|
, (comma)
|
A character that separates query columns.
The response body must use this character to separate the query
columns.
|
firstrowasheaders
|
Optional
|
yes
|
Determines how ColdFusion processes the
first row of the query record set:
yes:
processes the first row as column heads. If you specify a columns attribute,
ColdFusion ignores the first row of the file.
no: processes the first row as data. If
you do not specify a columns attribute, ColdFusion
generates column names by appending numbers to the word "column";
for example, "column_1".
|
name
|
Optional
|
|
Tells ColdFusion to create a query object
with the given name from the returned HTTP response body.
|
textQualifier
|
Optional
|
" [double-quotation
mark]
|
A character that, optionally, specifies
the start and end of a text column. This character must surround
any text fields in the response body that contain the delimiter
character as part of the field value.
To include this character
in column text, escape it by using two characters in place of one.
For example, if the qualifier is a double-quotation mark, escape
it as "".
|
UsageThe cfhttp tag
is a general-purpose tool for creating HTTP requests and handling
the returned results. It enables you to generate most standard HTTP request
types. You use embedded cfhttpparam tags to specify
request headers and body content.
When ColdFusion receives
a response to a cfhttp request, it can put the response
body (if any) in a file or the cfhttp.FileContent string
variable. If the body text is structured as a result set, ColdFusion
can put the body text in query object. You can also access the values
of all returned headers and specify how to handle error status and
redirections, and specify a time-out to prevent requests from hanging.
The
HTTP protocol is the backbone of the World Wide Web and is used
for every web transaction. Because the cfhttp tag
can generate most types of requests, it provides significant flexibility.
Possible uses include:
Interacting with dynamic web
sites and services that are not available as web services. (Use
the cfinvoke tag to access SOAP
web services.)
Getting the contents of an HTML page or other file such as
an image on a web server for use in your CFML page or storage in
a file.
Sending a secure request to a server by specifying the https
protocol in the url attribute.
Using the POST method to send a multipart/form-data style
post to any URL that can handle such data and return results, including
CGI executables or even other ColdFusion pages.
Using the PUT method to upload files to a server that does
not accept FTP requests.
This tag can, and for PUT
and POST requests must, have a body that contains cfhttpparam tags.
If this tag has cfhttpparam tags, it must have
a </cfhttp> end tag.
To use HTTPS with
the cfhttp tag, you might need to manually import
the certificate for each web server into the keystore for the JRE
that ColdFusion uses. This procedure should not be necessary if
the certificate is signed (issued) by an authority that the JSSE
(Java Secure Sockets Extension) recognizes (for example, Verisign);
that is, if the signing authority is in the cacerts already. However,
you might need to use the procedure if you are issuing SSL (secure
sockets layer) certificates yourself.
Manually import a certificateGo to a page on the SSL server
in question.
Double-click the lock icon.
Click the Details tab.
Click Copy To File.
Select the base64 option and save the file.
Copy the CER file into C:\ColdFusion9\runtime\jre\lib\security
(or whichever JRE ColdFusion is using).
Run the following command in the same directory (keytool.exe
is located in C:\ColdFusion9\runtime\jre\bin):
keytool -import -keystore cacerts -alias giveUniqueName -file filename.cer
Variables returned by a cfhttp get operationThe cfhttp tag
returns the following variables. If you set the result attribute, the
name you assign replaces cfhttp as the prefix.
For additional information, see the result attribute.
Name
|
Description
|
cfhttp.charSet
|
Response character character set (character
encoding) specified by the response Content-Type header.
|
cfhttp.errorDetail
|
If the connection to the HTTP server fails,
contains details about the failure. For instance: "Unknown host: my.co.com";
otherwise, the empty string. recommends that you check this variable
for an error condition before checking other variables.
|
cfhttp.fileContent
|
Response body; for example, the contents
of an html page retrieved by a GET operation. Empty if you save the
response in a file.
|
cfhttp.header
|
Raw response header containing all header
information in a single string. Contains the same information as the cfhttp.responseHeader variable.
|
cfhttp.mimeType
|
MIME type specified by the response Content-Type
header; for example, text/html.
|
cfhttp.responseHeader
|
The response headers formatted into a structure.
Each element key is the header name, such as Content-Type or Status_Code.
If there is more than one instance of a header type, the type values
are put in an array.
One common technique is to dynamically
access the cfhttp.responseHeader structure as a dynamic array; for
example, #cfhttp.resonseHeader[fieldVariable]#.
|
cfhttp.statusCode
|
The HTTP status_code header value followed
by the HTTP Explanation header value; for example, "200 OK".
|
cfhttp.text
|
Boolean; true if the response
body content type is text. ColdFusion recognizes the response body
as text in the following situations:
if the header
does not specify a content type
if the content type starts with "text"
if the content type starts with "message"
if the content type is "application/octet-stream"
|
Building a query from a delimited text fileThe cfhttp tag
can create a ColdFusion query object form the response body. To
do so, the response body must consist of lines of text, with each
line having fields that are delimited by a character that identifies
the column breaks. The default delimiter is a comma (,). The response
data can also use a text qualifier; the default is a double-quotation
mark ("). If you surround a string field in the text qualifier,
the field can contain the delimiter character. To include the text
qualifier in field text, escape it by using a double character.
The following line shows a two-line request body that is converted
into a query. It has three comma-delimited fields:
Field1,Field2,Field3
"A comma, in text","A quote: ""Oh My!""",Plain text
Run
the following code to show how ColdFusion treats this data:
<cfhttp method="Get"
url="127.0.0.1:8500/tests/escapetest.txt"
name="onerow">
<cfdump var="#onerow#"><br>
Column names
can be specified in three ways:
By default, ColdFusion
uses the first row of the response as the column names.
If you specify a comma-delimited columns attribute,
ColdFusion uses the names specified in the attribute as the column
names. Set firstRowAsHeaders="no" if the first
row of the response contains data. Otherwise, ColdFusion ignores
the first row.
If you do not specify a columns attribute
and set firstrowasheaders="no", ColdFusion generates
column names of the form Column_1, Column2, etc.
The cfhttp tag
checks to ensure that column names in the data returned by the tag
start with a letter and contain only letters, numbers, and underscore characters
(_).
ColdFusion checks for invalid column names. Column names
must start with a letter. The remaining characters can be letters,
numbers, or underscores (_). If a column name is not valid, ColdFusion
generates an error.
NotesFor the ColdFusion Administrator time-out and the URL time-out
to take effect, enable the time-out in the ColdFusion Administrator,
Server Settings page. For more information, see Configuring and Administering ColdFusion.
The cfhttp tag supports Basic Authentication
for all operations.
The cfhttp tag uses SSL to negotiate secure
transactions.
If you put the HTTP response body in a file, ColdFusion does
not put it in the CFHTTP.FileContent variable or generate a query
object. If you do not put the response body in a file, ColdFusion
puts it in the CFHTTP.FileContent variable; if you specify a name attribute
ColdFusion generates a query object.
The cfhttp tag does not support NTLM or
Digest Authentication.
If you are using Microsoft IIS, there is no HTTP header size
limit. To specify an HTTP header size limit, set it in IIS.
Example<!--- This example displays the information provided by
the Designer & Developer Center XML feed,
http://www.adobe.com/devnet/resources/_resources.xml
See http://www.adobe.com/devnet/articles/xml_resource_feed.html
for more information on this feed. --->
<!--- Set the URL address. --->
<cfset urlAddress="http://www.adobe.com/devnet/resources/_resources.xml">
<!--- Use the CFHTTP tag to get the file content represented by urladdress.
Note that />, not an end tag, terminates this tag. --->
<cfhttp url="#urladdress#" method="GET" resolveurl="Yes" throwOnError="Yes"/>
<!--- Parse the XML and output a list of resources. --->
<cfset xmlDoc = XmlParse(CFHTTP.FileContent)>
<!--- Get the array of resource elements, the xmlChildren of the xmlroot. --->
<cfset resources=xmlDoc.xmlroot.xmlChildren>
<cfset numresources=ArrayLen(resources)>
<cfloop index="i" from="1" to="#numresources#">
<cfset item=resources[i]>
<cfoutput>
<strong><a href=#item.url.xmltext#>#item.title.xmltext#</strong></a><br>
<strong>Author</strong> #item.author.xmltext#<br>
<strong>Applies to these products</strong><br>
<cfloop index="i" from="4" to="#arraylen(item.xmlChildren)#">
#item.xmlChildren[i].xmlAttributes.Name#<br>
</cfloop>
<br>
</cfoutput>
</cfloop>
|