CFHTTP  
説明

HTTP リクエストを生成し、サーバーからのレスポンスを処理します。

 
カテゴリ

インターネットプロトコルタグ

 
シンタックス
<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"、"no"
   throwOnError = "yes"、"no"
   redirect = "yes"、"no"
   timeout = "timeout_period"
   getasbinary = "yes"、"no"
   multipart = "yes"、"no"
   path = "path"
   file = "filename"
   name = "queryname"
   columns = "query_columns"
   firstrowasheaders = "yes"、"no"
   delimiter = "character"
   textQualifier = "character"
   result = "result_name"
   cfhttpparam タグ [一部のメソッドではオプション]
</cfhttp>
 
関連項目

cfhttpparam、GetHttpRequestData、cfftp、cfldap、cfmail、cfpop、SetEncoding

 
ヒストリ

ColdFusion MX 7: result 属性が追加されました。この属性では、結果を受け取る代替変数を指定することができます。

ColdFusion MX 6.1:

  • HEAD、PUT、DELETE、OPTIONS、および TRACE の各メソッドのサポートが追加されました。
  • multipart、getAsBinary、proxyUser、および proxyPassword の各属性が追加されました。
  • httpparam の動作が変更されました。どのオペレーションでも httpparam タグを含むことができます。
  • cfhttp.errorDetail という戻り変数が追加されました。
  • レスポンスの本文コンテンツのタイプがテキストと見なされるように変更されました。
  • 複数ヘッダの動作が変更されました。同じタイプの複数のヘッダは 1 つの配列で返されます。
  • HTTPS プロキシトンネリングのサポートが追加されました。
  • コードとドキュメントのバグが修正されました。

ColdFusion MX:

  • charset 属性と firstrowasheaders 属性が追加されました。
  • Secure Sockets Layer (SSL) のサポートが変更されました。128 ビットの暗号化をサポートする Sun JSSE ライブラリを使用して、SSL がサポートされるようになりました。

次に示す属性は HTTP トランザクションを制御するためのもので、どの HTTP メソッドでも使用できます。

PUT メソッドでは、次の属性を使用して、httpparam type="formField" で指定されたデータの送信方法を設定します。

次の属性を使用すると、必要なオペレーションの結果を返すために使用する変数の名前を指定することができます。指定した名前が、戻り値にアクセスする際の接頭辞として cfhttp と置き換わります。たとえば、result 属性を myResult に設定した場合は、#myResult.FileContent# として FileContent にアクセスします。

result 属性では、複数のページから同時に呼び出される関数または CFC について、一方の呼び出しの結果が他方の呼び出しの結果を上書きしないようにすることができます。cfhttp の get オペレーションで返される変数の詳細については、「使用方法」の「cfhttp の get オペレーションで返される変数」を参照してください。

次の属性は、HTTP レスポンス本文をファイルに保管するときに使用します。GET、POST、PUT、DELETE、OPTIONS、TRACE の各メソッドでレスポンス本文をファイルに保管することができますが、DELETE メソッドと OPTIONS メソッドではほとんど役に立ちません。

次の属性は、HTTP レスポンス本文を ColdFusion クエリーオブジェクトに変換するときに使用します。これらの属性は GET メソッドと POST メソッドでのみ使用できます。

 
使用方法

cfhttp タグは、HTTP リクエストを作成し、返された結果を処理するための汎用ツールです。このタグを使用すると、ほとんどの標準 HTTP リクエストタイプを生成することができます。リクエストヘッダと本文コンテンツを指定するには、このタグ内で cfhttpparam タグを使用します。

ColdFusion は、cfhttp リクエストに対するレスポンスを受け取ると、そのレスポンス本文をファイルまたは cfhttp.FileContent 文字列変数に保管することができます。本文テキストが結果セットとして構築されている場合は、その本文テキストをクエリーオブジェクトに入れることができます。さらに、返されたすべてのヘッダ値へのアクセス、エラーステータスとリダイレクションの処理方法の指定、リクエストをハングさせないためのタイムアウトの指定もできます。

HTTP プロトコルは World Wide Web のバックボーンであり、すべての Web トランザクションで使用されます。cfhttp タグはほとんどのリクエストタイプを生成できるので、非常に柔軟に使用することができます。たとえば次のような使い方があります。

  • Web サービスとしては使用できないダイナミックな Web サイトやサービスとやり取りする (SOAP Web サービスへのアクセスには cfinvoke タグを使用)
  • Web サーバー上のイメージなど、HTML ページやその他のファイルのコンテンツを取得し、それを CFML ページ内で使用したり、ファイルに保管したりする
  • url 属性に https プロトコルを指定して、サーバーに安全なリクエストを送信する
  • POST メソッドを使用して、multipart/form-data スタイルのデータを、そのようなデータを処理して結果を返すことのできる任意の URL (CGI 実行可能ファイルや、その他の ColdFusion ページなど) に送信する
  • PUT メソッドを使用して、FTP リクエストを受け付けないサーバーにファイルをアップロードする

このタグの本文には、cfhttpparam タグを含めることができます。また、PUT リクエストと POST リクエストの場合はこのタグは必須です。このタグに cfhttpparam タグを含める場合は、</cfhttp> 終了タグが必要です。

cfhttp タグを含む HTTPS を使用するためには、各 Web サーバーに対する証明書を、ColdFusion が使用する JRE のキーストアに手動でインポートすることが必要になる場合があります。JSSE (Java Secure Sockets Extension) が認識する機関 (Verisign など) によって証明書が署名 (発行) される場合、つまり、署名する機関が既に cacerts にある場合、この手順は必要ありません。ただし、SSL (Secure Sockets Layer) 証明書を自己発行している場合は、この手順が必要になることがあります。

証明書を手動でインポートするには :

  1. SSL サーバー上の当該ページに進みます。
  2. 鍵のアイコンをダブルクリックします。
  3. [詳細] タブをクリックします。
  4. [ファイルにコピー] をクリックします。
  5. base64 オプションを選択してファイルを保存します。
  6. CER ファイルを C:CFusionMX7runtimejrelibsecurity (または JRE ColdFusion が使用する任意の場所) にコピーします。
  7. 同じディレクトリの次のコマンドを実行します (keytool.exe は C:CFusionMXruntimejrebin にあります)。
  8. keytool -import -keystore cacerts -alias giveUniqueName -file filename.cer 
    
 
cfhttp の get オペレーションで返される変数

cfhttp タグは、次の変数を返します。result 属性を設定した場合は、割り当てた名前が接頭辞として cfhttp と置き換わります。その他の情報については、result 属性を参照してください。

名前 説明

cfhttp.charSet

レスポンスの Content-Type ヘッダで指定されたレスポンス文字セット (文字エンコード) です。

cfhttp.errorDetail

HTTP サーバーへの接続が失敗した場合に、失敗の詳細を記録します (例 : "Unknown host: my.co.com")。それ以外の場合は、空の文字列になります。エラー状態について、他の変数を確認する前にこの変数を確認することをお勧めします。

cfhttp.fileContent

レスポンス本文です。たとえば、GET オペレーションによって取得された HTML ページのコンテンツなどです。レスポンスをファイルに保管した場合は空になります。

cfhttp.header

すべてのヘッダ情報を 1 つの文字列に格納した生のレスポンスヘッダです。cfhttp.responseHeader 変数と同じ情報を含みます。

cfhttp.mimeType

レスポンスの Content-Type ヘッダで指定されている MIME タイプです (例 : text/html)。

cfhttp.responseHeader

構造体の形式にされたレスポンスヘッダです。要素キーは、Content-Type や Status_Code などのヘッダ名です。あるヘッダタイプのインスタンスが複数ある場合は、そのタイプの値が配列に格納されます。

よく使用されるテクニックは、#cfhttp.resonseHeader[fieldVariable]# のように、cfhttp.responseHeader 構造体をダイナミック配列としてダイナミックにアクセスすることです。

cfhttp.statusCode

HTTP Explanation ヘッダ値の後に続く HTTP status_code ヘッダ値です (例 : "200 OK")。

cfhttp.text

ブール値。レスポンス本文のコンテンツタイプがテキストである場合は true になります。ColdFusion は、次の場合にレスポンス本文をテキストとして認識します。

  • ヘッダにコンテンツタイプが指定されていない場合
  • コンテンツタイプが "text" で始まっている場合
  • コンテンツタイプが "message" で始まっている場合
  • コンテンツタイプが "application/octet-stream" である場合

 
区切り形式のテキストファイルからクエリーを構築する方法

cfhttp タグでは、レスポンス本文から ColdFusion クエリーオブジェクトを作成することができます。これを行うには、レスポンス本文が、数行から成るテキストを含んでいて、その各行が列区切り文字によって区切られたいくつかのフィールドを含んでいる必要があります。デフォルトの区切り文字はカンマ (,) です。レスポンス本文では、テキスト修飾子を使用することもできます。デフォルトのテキスト修飾子は二重引用符 (") です。文字列フィールドをテキスト修飾子で囲むと、そのフィールドに区切り文字を含めることができます。フィールドテキスト内にテキスト修飾子を含める場合は、その文字を重ねて指定してエスケープします。次の例は、クエリーに変換される 2 行のリクエスト本文を示しています。各行はカンマで区切られた 3 つのフィールドを含んでいます。

Field1,Field2,Field3
"A comma, in text","A quote:""Oh My!""",Plain text

ColdFusion がこのデータをどのように処理するかを確認するには、次のコードを実行します。

<cfhttp method="Get"
   url="127.0.0.1:8500/tests/escapetest.txt"
   name="onerow">
<cfdump var="#onerow#"><br>

列名は次の 3 とおりの方法で指定できます。

  • デフォルトでは、レスポンスの 1 行めは列名として使用されます。
  • columns 属性にカンマ区切りの値を指定した場合は、その属性で指定した名前が列名として使用されます。レスポンスの 1 行めにデータが含まれている場合は、firstRowAsHeaders="no" を設定します。データが含まれていない場合、1 行めは無視されます。
  • columns 属性を指定せず、firstrowasheaders="no" を設定した場合は、Column_1、Column_2、... というように列名が生成されます。

cfhttp タグは、このタグによって返されるデータ内の列名をチェックして、列名が文字で始まっていること、および文字、数字、アンダースコア文字 (_) だけを含んでいることを確認します。

ColdFusion は無効な列名をチェックします。列名は文字で始める必要があります。2 文字め以降には、文字、数字、アンダースコア (_) を使用できます。列名が無効な場合は、エラーが発生します。

 
メモ :
  • ColdFusion MX Administrator のタイムアウトと URL のタイムアウトを有効にするには、ColdFusion MX Administrator の [サーバーの設定] ページでタイムアウトを有効にする必要があります。詳細については、『ColdFusion MX の設定と管理』 を参照してください。
  • cfhttp タグはすべてのオペレーションで基本認証をサポートします。
  • cfhttp では、SSL を使用してセキュアトランザクション通信が行われます。
  • HTTP レスポンス本文をファイルに保管した場合、それは CFHTTP.FileContent 変数には格納されず、クエリーオブジェクトも生成されません。レスポンス本文をファイルに保管しなかった場合、それは CFHTTP.FileContent 変数に格納されます。このとき、name 属性を指定していればクエリーオブジェクトが生成されます。
  • cfhttp タグは、NTLM 認証やダイジェスト認証をサポートしません。
 
<!--- この例では、Macromedia Designer & Developer Center XML が
提供している情報を示しています
(http://www.macromedia.com/desdev/resources/macromedia_resources.xml)。
詳細については、http://www.macromedia.com/desdev/articles/xml_resource_feed.html 
を参照してください。 --->

<!--- URL アドレスを設定します。 --->
<cfset urlAddress="http://www.macromedia.com/desdev/resources/macromedia_resources.xml">

<!--- CFHTTP タグを使用して、urladdress で示されるファイルの内容を取得します。 
      このタグは、終了タグで終わらずに /> で終わっています。 --->
<cfhttp url="#urladdress#" method="GET" resolveurl="Yes" throwOnError="Yes"/>

<!--- XML を解析して、リソースのリストを出力します。 --->
<cfset xmlDoc = XmlParse(CFHTTP.FileContent)>
<!--- リソース要素の配列 (xmlroot の xmlChildren) を取得します。 --->
<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>作成者</strong>&nbsp;&nbsp;#item.author.xmltext#<br>
        <strong>次の製品に適用</strong><br>
        <cfloop index="i" from="4" to="#arraylen(item.xmlChildren)#">
            #item.xmlChildren[i].xmlAttributes.Name#<br>
        </cfloop>
        <br>
    </cfoutput>
</cfloop>
URL  
  必須
 
Default value: "http プロトコルを使用"

リクエストを処理するサーバー上のリソースのアドレスです。この URL にはホスト名か IP アドレスを含める必要があります。

トランザクションプロトコル (http:// または https://) を指定しなかった場合は、デフォルトで http が使用されます。

この属性でポート番号を指定した場合は、port 属性の値が上書きされます。

cfhttpparam タグの URL 属性を使用すると、クエリー文字列の属性と値のペアがこの URL に追加されます。

PORT  
  オプション
 
Default value: "http の場合は 80、" Default value: "https の場合は 443"

リクエストの送信先となるサーバー上のポート番号です。url 属性のポートの値は、この値よりも優先されます。

METHOD  
  オプション
 
Default value: "GET"
  • GET: サーバーに情報をリクエストします。リクエストされた情報をサーバーが識別するために必要なデータはすべて、URL 内か cfhttp type="URL" タグ内に含まれている必要があります。
  • POST: 処理する情報をサーバーに送信します。1 つ以上の cfhttpparam タグが必要です。フォームに似たデータを送信するときによく使われます。
  • PUT: 指定の URL にメッセージ本文を保管するようサーバーにリクエストします。このメソッドは、サーバーにファイルを送信するときに使われます。
  • DELETE: 指定の URL を削除するようサーバーにリクエストします。
  • HEAD: GET メソッドと同じですが、サーバーはレスポンス内にメッセージ本文を送信しません。このメソッドは、ハイパーテキストリンクの有効性やアクセシビリティのテスト、ドキュメントのタイプや修正時刻の確認、またはサーバーのタイプの判別に使用します。
  • TRACE: 受信した HTTP ヘッダをレスポンス本文に挿入して送信者にエコーバックするようサーバーにリクエストします。トレースリクエストには本文がありません。このメソッドを使用すると、ColdFusion アプリケーションはサーバー側で何を受信したかを調べ、そのデータをテストや診断情報に利用することができます。
  • OPTIONS: サーバーまたは指定の URL で使用できる通信オプションについての情報をリクエストします。このメソッドを使用すると、ColdFusion アプリケーションは、追加のサーバー活動を要求しなくても、URL に関連付けられているオプションや要件、あるいはサーバーの機能を判別することができます。
PROXYSERVER  
  オプション
 

リクエストの送信先となるプロキシサーバーのホスト名または IP アドレスです。

PROXYPORT  
  オプション
 
Default value: "80"

プロキシサーバー上で使用するポート番号です。

PROXYUSER  
  オプション
 

プロキシサーバーに提供するユーザー名です。

PROXYPASSWORD  
  オプション
 

プロキシサーバーに提供するパスワードです。

USERNAME  
  オプション
 

基本認証のターゲット URL にユーザー名を渡すために使用します。password と組み合わせて、認証ヘッダで渡される base64 コード文字列を形成します。統合 Windows 認証、NTLM 認証、または Kerebos 認証には対応しません。

PASSWORD  
  オプション
 

基本認証のターゲット URL にパスワードを渡すために使用します。username と組み合わせて、認証ヘッダで渡される base64 コード文字列を形成します。統合 Windows 認証、NTLM 認証、または Kerebos 認証には対応しません。

USERAGENT  
  オプション
 
Default value: "Cold
Fusion"

ユーザーエージェントリクエストヘッダに配置されるテキストです。リクエストクライアントソフトウェアを識別するために使われます。ColdFusion アプリケーションをブラウザのように見せることができます。

CHARSET  
  オプション
 
Default value: "リクエストの場合 : UTF-8" Default value: "レスポンスの場合 : レスポンスの Content-Type ヘッダに指定された文字セットであり、レスポンスが文字セットを指定していないときは UTF-8"

URL クエリー文字列、フォームまたはファイルデータ、レスポンスなどのリクエストの文字エンコードです。一般的に使用される値を次に示します。

  • utf-8
  • iso-8859-1
  • windows-1252
  • us-ascii
  • shift_jis
  • iso-2022-jp
  • euc-jp
  • euc-kr
  • big5
  • euc-cn
  • utf-16

文字エンコードの詳細については、www.w3.org/International/O-charset.html を参照してください。

RESOLVEURL  
  オプション
 
Default value: "no"
  • no: レスポンス本文の中の URL を変換しません。その結果、レスポンス本文に含まれる相対 URL リンクはすべて機能しなくなります。
  • yes: 取得したページ内でもリンクが機能するように、レスポンス本文中の URL (ポート番号も含む) を絶対 URL に変換します。次の HTML タグに適用されます。
    • - 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

file 属性および path 属性を使用する場合は、URL を変換しません。

THROWONERROR  
  オプション
 
Default value: "no"
  • yes: サーバーがエラーレスポンスコードを返す場合に、cftry と cfcatch (または ColdFusion エラーページ) を使って検出できる例外を返します。
  • no: エラーレスポンスを返す場合に例外を返しません。この場合、アプリケーションは、エラーの有無とその原因を cfhttp.StatusCode 変数から判別することができます。
REDIRECT  
  オプション
 
Default value: "yes"

レスポンスヘッダに Location フィールドが含まれ、ColdFusion が 300 系列 (リダイレクション) のステータスコードを受け取った場合、そのフィールド内で指定された URL に実行をリダイレクトするかどうかを指定します。

  • yes: 指定のページに実行をリダイレクトします。
  • no: 実行を停止し、レスポンス情報を cfhttp 変数に返します。あるいは、throwOnError 属性が true の場合はエラーを返します。

cfhttp.responseHeader.Location 変数にはリダイレクトパスが含まれています。ColdFusion では、1 つのリクエストで最大 4 回までリダイレクトが行われます。これよりも多くなると、redirect ="no" を指定した場合と同じ処理が行われます。

メモ : cflocation タグは、Location ヘッダ値として url 属性を使用する HTTP 302 レスポンスを生成します。

TIMEOUT  
  オプション
 

リクエストの最大待機時間を秒数で指定します。レスポンスがないままタイムアウトになった場合は、そのリクエストが失敗したものと見なされます。

クライアントが URL 検索パラメータ内でタイムアウトを指定した場合は (例 : ?RequestTime=120)、その URL タイムアウトと timeout 属性値のうち、短い方が採用されます。これにより、リクエストが確実にページよりも先に (あるいは同時に) タイムアウトになります。

URL にタイムアウトが指定されていない場合は、Administrator タイムアウトと timeout 属性値のうち、短い方が採用されます。

上記のどの方法でもタイムアウト値が設定されていない場合は、ColdFusion は cfhttp リクエストの処理を無限に待機することになります。

GETASBINARY  
  オプション
 
Default value: "no"
  • no: ColdFusion がレスポンス本文のタイプをテキストとして認識しない場合は、それを ColdFusion オブジェクトに変換します。
  • Auto: ColdFusion がレスポンス本文のタイプをテキストとして認識しない場合は、それを ColdFusion Binary タイプデータに変換します。
  • yes: レスポンス本文のコンテンツを必ず ColdFusion Binary タイプデータに変換します。ColdFusion がレスポンス本文のタイプをテキストとして認識する場合でも同様です。

ColdFusion は、次の場合にレスポンス本文をテキストとして認識します。

  • ヘッダにコンテンツタイプが指定されていない場合
  • コンテンツタイプが "text" で始まっている場合
  • コンテンツタイプが "message" で始まっている場合
  • コンテンツタイプが "application/octet-stream" である場合

ColdFusion がレスポンス本文をテキストとして認識せず、オブジェクトに変換した場合でも、その本文がテキストから構成されている場合は、cfoutput タグを使って表示することができます。cfoutput タグでは Binary タイプデータを表示できません。バイナリデータをテキストに変換するには、ToString 関数を使用します。

MULTIPART  
  オプション
 
Default value: "no" Default value: "(リクエストが File タイプデータを含んでいる場合にのみマルチパートとして送信)"

cfhttpparam type="formField" タグで指定されたすべてのデータを、マルチパートフォームデータ (Content-Type が multipart/form-data) として送信することを ColdFusion に指示します。ColdFusion のデフォルトでは、formField データだけを含む、Content Type が application/x-www-form-urlencoded の cfhttp リクエストが送信されます。ただし、リクエストに File タイプデータも含まれている場合は、すべての部分に multipart/form-data コンテンツタイプが使用されます。

この属性を yes に設定した場合は、Content-Type の説明の中でリクエストの文字セットも送信されます。すべてのフォームフィールドデータをこの文字エンコードでエンコードする必要があります。ColdFusion はこのデータに URLEncode を実行しません。フィールド名は ISO-88591-1 または ASCII である必要があります。一部の http パーサ (以前のバージョンの ColdFusion で使われていたものも含む) は、マルチパートフォームフィールドの文字エンコードの説明を無視します。

NAME  
  オプション
 

返された HTTP レスポンス本文から指定の名前のクエリーオブジェクトを作成するよう ColdFusion に指示します。

COLUMNS  
  オプション
 
Default value: "レスポンスの 1 行めには列名が含まれます。"

このクエリーの列名をカンマで区切って指定します。スペースは使用しません。列名は文字で始める必要があります。2 文字め以降には、文字、数字、アンダースコア文字 (_) を使用できます。

レスポンス内に列名ヘッダがない場合は、列名を識別するためにこの属性を指定します。

この属性を設定したときに、firstrowasHeader 属性が true (デフォルト) だった場合には、この属性で指定した列名によってレスポンスの 1 行めが置き換えられます。この動作を利用して、リクエストによって取得された列名を独自の名前に置き換えることができます。

この属性またはレスポンスからの列名の中で重複する列ヘッダがある場合、その名前にアンダースコアが付加され、固有の名前が作成されます。

この属性で指定した列の数が HTTP レスポンス本文の中の列数と等しくない場合は、エラーが発生します。

FIRSTROWAS
HEADERS
 
  オプション
 
Default value: "yes"

CodFusion で、クエリーのレコードセットの最初の行を処理する方法を決定します。

  • yes: 1 行めを列ヘッダとして扱います。columns 属性を指定した場合は、ファイルの 1 行めが無視されます。
  • no: 1 行めをデータとして扱います。columns 属性を指定しなかった場合は、"column_1" のように、"column" という単語に数字を付加した列名が作成されます。
DELIMITER  
  オプション
 
Default value: ", [カンマ]"

クエリー列を区切る文字です。レスポンス本文はこの文字を使用してクエリー列を区切る必要があります。

TEXTQUALIFIER  
  オプション
 
Default value: "" [二重引用符]"

テキスト列の始まりと終わりを示すオプションの文字です。レスポンス本文中のテキストフィールドがフィールド値の一部に区切り文字を含んでいる場合は、テキストフィールドをこの文字で囲む必要があります。

この文字を列テキストの中に含めるときには、文字を 2 つ指定してエスケープします。たとえば、テキスト修飾子が二重引用符である場合に、この文字をエスケープするには "" と指定します。

PATH  
  file 属性を指定している場合は必須
 

HTTP レスポンス本文をファイルに保管することを ColdFusion に指示します。ファイルの保管先となるディレクトリへの絶対パスを指定します。

FILE  
  path 属性を指定していて、GET メソッドでない場合は必須
 
Default value: "「説明」を参照"

レスポンス本文の保管先となるファイルの名前です。

GET オペレーションでは、URL 内でリクエストされたファイルがデフォルトになります (ファイルが指定されている場合)。たとえば、GET メソッドの URL が http:www.myco.com/test.htm である場合、デフォルトファイルは test.htm です。

この属性ではディレクトリへのパスを指定しないでください。パスは path 属性で指定します。

RESULT  
  オプション
 

結果を返すために使用する変数の名前を指定します。