cfhttp

Description

Generates an HTTP request and handles the response from the server.

Syntax

<cfhttp 
   url = "server_URL"
   port = "port_number"
   method = "method_name"
   proxyServer = "hostname"
   proxyPort = "port_number"
   proxyUser = "username"
   proxyPassword = "password"
   username = "username"
   password = "password"
   userAgent = "user_agent"
   charset = "character encoding"
   resolveURL = "yes" or "no"
   throwOnError = "yes" or no"
   redirect = "yes" or "no"
   timeout = "timeout_period"
   getasbinary = "yes or no"
   multipart = "yes or no"
   path = "path"
   file = "filename"
   name = "queryname"
   columns = "query_columns"
   firstrowasheaders = "yes" or "no"
   delimiter = "character"
   textQualifier = "character"
   result = "result_name"
   cfhttpparam tags [optional for some methods]
</cfhttp>

History

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.

Attributes

The following attributes control the HTTP transaction and can be used for all HTTP methods:

Attribute	Req/Opt	Default	Description
url	Req	Uses the http protocol	Address of the resource on the server which will handle the request. The URL must include the hostname or IP address. If you do not specify the transaction protocol (http:// or https://), ColdFusion defaults to 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.
port	Opt	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.
method	Opt	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 `cfhttp` `type="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.
proxyServer	Opt		Host name or IP address of a proxy server to which to send the request.
proxyPort	Opt	80	Port number to use on the proxy server.
proxyUser	Opt		User name to provide to the proxy server.
proxyPassword	Opt		Password to provide to the proxy server.
username	Opt		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 Kerebos authentication.
password	Opt		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.
userAgent	Opt	Cold Fusion	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.
charset	Opt	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.
resolveURL	Opt	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	Opt	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.
redirect	Opt	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.
timeout	Opt		Value, in seconds, that is the maximum time the request can take. If the timeout passes without a response, ColdFusion considers the request to have failed. If the client specifies a timeout in the URL search parameter (for example, ?RequestTime=120) ColdFusion uses the lesser of the URL timeout 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 timeout, ColdFusion uses the lesser of the Administrator timeout and the `timeout` attribute value. If the timeout is not set in any of these, ColdFusion waits indefinitely for the `cfhttp` request to process.
getAsBinary	Opt	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. 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.)

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

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.

multipart

Optional

(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 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 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

Attribute	Req/Opt	Default	Description
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.
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.

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.

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
name	Opt		Tells ColdFusion to create a query object with the given name from the returned HTTP response body.
columns	Opt	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.
firstrowas headers	Opt	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".
delimiter	Opt	, [comma]	A character that separates query columns. The response body must use this character to separate the query columns.
textQualifier	Opt	" [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 `""`.

Usage

The 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 timeout 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 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.

To manually import a certificate:

Go 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:\CFusionMX7\runtime\jre\lib\security (or whichever JRE ColdFusion is using).
Run the following command in the same directory (keytool.exe is located in C:\CFusionMX7\runtime\jre\bin):
```
keytool -import -keystore cacerts -alias giveUniqueName -file filename.cer 
```

Variables returned by a cfhttp get operation

The 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. Macromedia recommends that you check this variable for an error condition before checking other variables.
cfhttp.fileContent	Response body; for example, the contents of a 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 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".

Building a query from a delimited text file

The 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.

Notes

For the ColdFusion MX Administrator timeout and the URL timeout to take effect, you must enable the timeout in the ColdFusion MX Administrator, Server Settings page. For more information, see Configuring and Administering ColdFusion MX.
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.

Example

<!--- This example displays the information provided by the Macromedia
Designer & Developer Center XML feed, 
http://www.macromedia.com/desdev/resources/macromedia_resources.xml 
See http://www.macromedia.com/desdev/articles/xml_resource_feed.html
for more information on this feed. --->

<!--- Set the URL address. --->
<cfset urlAddress="http://www.macromedia.com/desdev/resources/macromedia_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>&nbsp;&nbsp;#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>

View comments in LiveDocs