CFHTTP | |||||||||||||||||||
Description | |||||||||||||||||||
Generates an HTTP request and handles the response from the server. | |||||||||||||||||||
Category | |||||||||||||||||||
Forms tags, Internet Protocol tags | |||||||||||||||||||
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" > cfhttpparam tags [optional for some methods] </cfhttp> |
|||||||||||||||||||
See also | |||||||||||||||||||
cfhttpparam, GetHttpRequestData, cfftp, cfldap, cfmail, cfpop, SetEncoding | |||||||||||||||||||
History | |||||||||||||||||||
ColdFusion MX 6.1:
|
|||||||||||||||||||
ColdFusion MX:
|
|||||||||||||||||||
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 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 DELETE or OPTIONS. | |||||||||||||||||||
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 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:
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. |
|||||||||||||||||||
Variables returned by a cfhttp get operation
The cfhttp tag returns the following variables:
|
|||||||||||||||||||
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:
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 underscores (_). 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
|
|||||||||||||||||||
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> #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> |
URL | |
Req | |
Default value: "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 cfhttppparam tag URL attribute appends query string attribute-value pairs to the URL. |
PORT | |
Opt | |
Default value: "80 for http"
Default value: "413 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 | |
Default value: "GET"
|
PROXYSERVER | |
Opt | |
Host name or IP address of a proxy server to which to send the request. |
PROXYPORT | |
Opt | |
Default value: "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 | |
A username. May be required by server. |
PASSWORD | |
Opt | |
A password. May be required by server |
USERAGENT | |
Opt | |
Default value: "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. |
CHARSET | |
Opt | |
Default value: "For request: UTF-8"
Default value: "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:
For more information character encodings, see:www.w3.org/International/O-charset.html. |
RESOLVEURL | |
Opt | |
Default value: "No"
|
THROWONERROR | |
Opt | |
Default value: "No"
|
REDIRECT | |
Opt | |
Default value: "Yes"
If the response header includes a Location field, determines whether to redirect execution to the URL specified in the field.
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". |
TIMEOUT | |
Opt | |
Value, in seconds of 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 | |
Default value: "No"
ColdFusion recognizes the response body as text if:
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.) |
MULTIPART | |
Optional | |
Default value: "No"
Default value: "(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. |
NAME | |
Opt | |
Tells ColdFusion to create a query object with the given name from the returned HTTP response body. |
COLUMNS | |
Opt | |
Default value: "First row of response contains column names."
The column names for the query, separated by commas. Column names must start with a letter. The remaining characters can be letters, numbers, or underscores (_). 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. |
FIRSTROWASHEADERS | |
Opt | |
Default value: "Yes"
Determines how ColdFusion processes the first row of the query record set.
|
DELIMITER | |
Opt | |
Default value: ", [comma]"
A character that separates query columns. The response body must use this character to separate the query columns. |
TEXTQUALIFIER | |
Opt | |
Default value: "" [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 "". |
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 | |
Default value: "See Description"
Name of file in which to store the response body. For a GET operation, defaults to 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. |