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:
ColdFusion MX:
次に示す属性は 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 タグはほとんどのリクエストタイプを生成できるので、非常に柔軟に使用することができます。たとえば次のような使い方があります。
このタグの本文には、cfhttpparam タグを含めることができます。また、PUT リクエストと POST リクエストの場合はこのタグは必須です。このタグに cfhttpparam タグを含める場合は、</cfhttp> 終了タグが必要です。 cfhttp タグを含む HTTPS を使用するためには、各 Web サーバーに対する証明書を、ColdFusion が使用する JRE のキーストアに手動でインポートすることが必要になる場合があります。JSSE (Java Secure Sockets Extension) が認識する機関 (Verisign など) によって証明書が署名 (発行) される場合、つまり、署名する機関が既に cacerts にある場合、この手順は必要ありません。ただし、SSL (Secure Sockets Layer) 証明書を自己発行している場合は、この手順が必要になることがあります。 証明書を手動でインポートするには :
keytool -import -keystore cacerts -alias giveUniqueName -file filename.cer |
|||||||||||||||||||
cfhttp の get オペレーションで返される変数
cfhttp タグは、次の変数を返します。result 属性を設定した場合は、割り当てた名前が接頭辞として cfhttp と置き換わります。その他の情報については、result 属性を参照してください。
|
|||||||||||||||||||
区切り形式のテキストファイルからクエリーを構築する方法
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 とおりの方法で指定できます。
cfhttp タグは、このタグによって返されるデータ内の列名をチェックして、列名が文字で始まっていること、および文字、数字、アンダースコア文字 (_) だけを含んでいることを確認します。 ColdFusion は無効な列名をチェックします。列名は文字で始める必要があります。2 文字め以降には、文字、数字、アンダースコア (_) を使用できます。列名が無効な場合は、エラーが発生します。 |
|||||||||||||||||||
メモ :
|
|||||||||||||||||||
例<!--- この例では、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> #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"
|
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 クエリー文字列、フォームまたはファイルデータ、レスポンスなどのリクエストの文字エンコードです。一般的に使用される値を次に示します。
文字エンコードの詳細については、www.w3.org/International/O-charset.html を参照してください。 |
RESOLVEURL | |
オプション | |
Default value: "no"
file 属性および path 属性を使用する場合は、URL を変換しません。 |
THROWONERROR | |
オプション | |
Default value: "no"
|
REDIRECT | |
オプション | |
Default value: "yes"
レスポンスヘッダに Location フィールドが含まれ、ColdFusion が 300 系列 (リダイレクション) のステータスコードを受け取った場合、そのフィールド内で指定された URL に実行をリダイレクトするかどうかを指定します。
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"
ColdFusion は、次の場合にレスポンス本文をテキストとして認識します。
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 で、クエリーのレコードセットの最初の行を処理する方法を決定します。
|
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 | |
オプション | |
結果を返すために使用する変数の名前を指定します。 |