cfhttp

Description

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

Category

Internet protocol tags

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>

See also

cfhttpparam, GetHttpRequestData, cfftp, cfldap, cfmail, cfpop

History

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

Attributes

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

The following attribute is used with the PUT method to determine how to send data specified with httpparam type="formField":

The following attribute sets a multipart header field and is used, for example, for uploading videos on YouTube.

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.

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.

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.

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

1. Go to a page on the SSL server in question.

2. Double-click the lock icon.

3. Click the Details tab.

4. Click Copy To File.

5. Select the base64 option and save the file.

6. Copy the CER file into C:\ColdFusion9\runtime\jre\lib\security (or whichever JRE ColdFusion is using).

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

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