説明
ColdFusion データを JSON (JavaScript Object Notation) 表現に変換します。
戻り値
パラメーター値の JSON 表現を含む文字列
カテゴリ
シンタックス
SerializeJSON(var [, serializeQueryByColumns, useCustomSerializer]) |
関連項目
DeserializeJSON、IsJSON、cfajaxproxy、『ColdFusion アプリケーションの開発』のデータ交換形式の使用、http://www.json.org
履歴
ColdFusion(2016 リリース)アップデート 2:getMetadata を使用した構造体と配列のシリアル化のサポートが追加されました。
ColdFusion 11:この属性が追加されました。 (useCustomSerializer)。
ColdFusion 8: この関数が追加されました。
パラメーター
パラメーター |
説明 |
---|---|
var |
ColdFusion データ値、または ColdFusion データ値を表す変数です。 |
serializeQueryByColumns |
ColdFusion クエリーをシリアル化する方法を指定する boolean 値です。
|
useCustomSerializer | true と false のいずれかを使用し、customSerializer を使用するかどうかを指定します。デフォルト値は true です。シリアル化には必ず、カスタムシリアライザーが使用されます。false に設定した場合には、ColdFusion のデフォルトの動作を使用し、JSON のシリアル化が実 |
使用方法
この関数は、Ajax アプリケーションで使用するための JSON 形式のデータを生成するのに役立ちます。SerializeJSON 関数は、ColdFusion の日付と時間を、JavaScript の Date オブジェクトで簡単に解析できる文字列に変換します。この文字列の形式は次のようになります。
MonthName, DayNumber Year Hours:Minutes:Seconds |
SerializeJSON 関数は、例えば October 3, 2007 at 3:01 PM という ColdFusion の日付と時間のオブジェクトを JSON 文字列「October, 03 2007 15:01:00」に変換します。SerializeJSON 関数が false の場合、serializeQueryByColumns パラメーター(デフォルト)は、次の要素を使用して、ColdFusion クエリーを行指向の JSON オブジェクトに変換します。
要素 |
説明 |
---|---|
COLUMNS |
列名の配列です。 |
DATA |
次のエントリを含む 2 次元配列です。
|
例えば、serializeQueryByColumns パラメーターの値が false に設定された SerializeJSON 関数では、2 つの列 (City と State) と 2 つのデータ行を含む ColdFusion クエリーが次の形式に変換されます。
{"COLUMNS":["CITY","STATE"],"DATA":[["Newton","MA"],["San Jose","CA"]]} |
serializeQueryByColumns パラメーターの値が true に設定された SerializeJSON 関数では、ColdFusion クエリーは、WDDX クエリー表現に相当する列指向の JSON オブジェクトに変換されます。JSON オブジェクトには、次の 3 つの要素があります。
要素 |
説明 |
---|---|
ROWCOUNT |
クエリーの行数. |
COLUMNS |
列名の配列です。 |
DATA |
次のキーと値を含むオブジェクトです。
|
serializeQueryByColumns パラメーターの値が true に設定された SerializeJSON 関数では、2 つの列 (City と State) と 2 つのデータ行を含む ColdFusion クエリーが次の形式に変換されます。
{"ROWCOUNT":2, "COLUMNS":["CITY","STATE"],"DATA":{"City":["Newton","San Jose"],"State":["MA","CA"]}} |
注意:SerializeJSON 関数でバイナリデータを JSON 形式に変換しようとするとエラーが発生します。
SerializeJSON 関数は、他のすべての ColdFusion データ型を、その型に対応する JSON データ型に変換します。構造体は JSON オブジェクトに、配列は JSON 配列に、数値は JSON 数値に、文字列は JSON 文字列に変換されます。
注意:ColdFusion の内部では、構造体のキー名はすべて大文字で表現されます。そのためキー名は、すべて大文字の JSON 表現にシリアル化されます。ColdFusion 構造体の JSON 表現を処理する JavaScript では、CITY や STATE のように、すべて大文字の構造体キー名を使用する必要があります。また、ColdFusion クエリーを JSON 形式で表現する 2 つの配列のキーにも、COLUMNS および DATA というすべて大文字の名前を使用します。
次の例では、2 つの都市の簡単な天気データを提供する JSON 形式のデータフィードを作成します。このデータフィードは、パラメーターとして JSON オブジェクトを取る 1 つの関数呼び出しから構成される JavaScript アプリケーションの形式になっています。このコード例では、次の処理が実行されます。
- 2 行の天気データを含むクエリーオブジェクトを作成します。各行には、都市名、現在の気温、および予報データの構造体の配列があり、それぞれに 1 日の最高気温、最低気温、天気予報データが含まれています。通常、これらのデータはデータソースから提供されます。この例ではコードを簡素化するために、すべての都市と日に対して同じ予報データを使用します。
- クエリーを JSON 形式文字列に変換し、その文字列を JavaScript 関数呼び出しでラップします。
結果を出力に書き込みます。
このページをブラウザで表示すると、使用された JavaScript 関数と JSON パラメーターが表示されます。このページの結果をアプリケーションで使用するには、このファイルと DeserializeJSON 関数の例を ColdFusion の Web ルート配下の適切な場所に置き、DeserializeJSON の例の URL をこのページの URL に置き換えてから、DeserializeJSON の例を実行します。
<!--- Generate a clean feed by suppressing white space and debugging |
ColdFusion 11 では、JSON シリアル化が強化され、以下の新機能がサポートされています。
- 構造体キーの大文字小文字の保持
- データ型の保持
- CF クエリーのキーと値のシリアル化
- カスタムシリアライザー
構造体キーの大文字小文字の保持
現在、ColdFusion では、構造体キーの大文字小文字は保持されません。構造体キーは自動的に大文字に変換されます。
例えば、次のコードについて考えてみます。
<cfscript> |
ColdFusion 10 以前のバージョンでは、このコードによって生成される出力は次のようになります。
{'EMPNAME'='', 'AGE'=''} |
ColdFusion 11 以降のリリースでは、生成される出力は次のようになります。
{'empName'='', 'age'=''} |
アプリケーションレベルで構造体キーの大文字小文字の保持を有効にするには、application.cfc ファイルを変更して、次のように設定します。
this.serialization.preservecaseforstructkey = true |
注意:キーの保持は、アプリケーション、セッションまたはリクエストスコープのキーに対しては機能しません。
デフォルトの動作は true です。以前の動作に切り替えるには、この値を false に設定します。
サーバーレベルで構造体キーの大文字小文字の保持を有効にするには、次のタスクを実行します。
- ColdFusion Administrator ページで、サーバーの設定/設定をクリックします。
- 「シリアル化用の構造体キーで大文字小文字を保持」をクリックします。

注意:この設定は CFML ページのコンパイル中に使用されるので、このフラグが(Administrator またはプログラムで)変更されると、変更に関連するすべてのページを再コンパイルする必要があることに注意してください。通常、この処理では、単にファイルが編集(すべてを変更)され、それが再実行されます。ColdFusion Administrator の "信頼できるキャッシュ" が有効な場合、(少なくとも影響を受けたファイル)のテンプレートキャッシュをクリアする必要があります。これらは、ColdFusion Administrator の「キャッシュ機能」ページ内でも実行できます。
データ型の保持
ColdFusion の言語は型なしで、コード生成時に型情報を評価することや保持することはありません。実行時、ColdFusion は予期しない動作を引き起こす可能性がある datatype を確認するために、最大限の推測を実行しようとします。 例えば、ColdFusion では、JSON シリアル化時に、文字列を数値に変換しようとします。この試みが成功した場合、渡されたデータ型は、文字列として扱う必要があるかどうかに関係なく、数値として扱われます。
ColdFusion 11 以降では、クエリーおよび CFC のコード実行時にデータ型が保持されます。
SerializeJSON では、シリアル化時に、データベースで定義されている datatype を考慮します。データベースで列を文字列として定義している場合、その列に挿入された数値はすべて SerializeJSON では文字列として扱われます。
次に例を示します。
<cfquery name="qry_Users" datasource="#DSN#"> |
クエリーのシリアル化
SerializeJSON では、データベースで定義されている列の datatype を優先します。 datatype が列に指定されている限り、同じことが QueryNew() を使用して作成されたメモリ内クエリーに対しても機能します。
CFC プロパティの型の例について考えてみます。
Employee.cfc
Component accessors="true" |
Index.cfm
<cfscript> |
OUTPUT: {"dept":"000","empName":"James","age":26}
以前のバージョンの ColdFusion では、000 は実行時に自動的に数値に変換されます。
クエリーシリアル化用の追加の形式
ColdFusion 10 では、クエリーオブジェクトを JSON 文字列にシリアル化する次の 2 つの方法をサポートしています。
- 行の使用
- 列の使用
ただし、AJAX アプリケーションでこれら 2 つの方法を使用するのは、それほど簡単ではありません。ColdFusion 11 では、クエリーオブジェクトを JSON 文字列にシリアル化する新しい方法が導入されました。
- 構造体の使用
3 つの方法はすべて、アプリケーションレベルで定義でき、型が明示的に定義されていない場合、シリアル化された JSON 関数で使用されます。application.cfc では、次のように定義します。
this.serialization.serializeQueryAs = [row|column|struct] |
AJAX の引数を介して「構造体」にアクセスすることも可能であることに注意してください。そのため、AJAX の URL に構造体を渡して、クエリーオブジェクトを構造体としてシリアル化することができます。
ColdFusion 11 では、現在、クエリーオブジェクトから AJAX フレンドリーな JSON 文字列へのシリアル化をサポートしています。
[ |
現在の SerializeJSON 関数は、機能強化され、「キーと値」形式をサポートしています。
SerializeJSON( Object o, Object serializeQueryByColumns, boolean secure, boolean useCustomSerializer); |
application.cfc で serialzeQueryAs プロパティを使用している場合は、その機能をオーバーライドする必要がなければ、serialzeQueryByColumns プロパティを指定する必要はありません。
カスタムシリアライザー
application.cfc ファイルでは、複合型のシリアル化およびシリアル化解除用の独自のハンドラーを登録できます。シリアライザーが指定されていない場合、ColdFusion は、デフォルトのシリアル化メカニズムを使用します。詳しくは、プラグ可能なシリアライザーおよびデシリアライザーのサポートを参照してください。
構造体のシリアル化
Adobe ColdFusion(2016 リリース)アップデート 2 では、構造体のキーにデータ型情報を指定できます。これは、メタデータと呼ばれています。
<cfscript> example = structnew(); example.firstname = "Yes"; example.lastname = "Man"; // Default serialization converting ctring Yes to true writeoutput(SerializeJSON(example)); </cfscript>
以下の出力では、キー FIRSTNAME の値が true(ブール値)にシリアル化されています。これは、 データ型 の情報がないからです。
{"LASTNAME":"Man","FIRSTNAME":true}
構造体関数 setMetadata を使用して、メタデータを指定します。
メタデータとは、各キーが 構造体の キーであり、各キーの値が JSON でのシリアル化方法についての情報を指定する構造体です。
キーの値には、文字列または構造体を指定できます。
文字列の値
metadata = {firstname: "string"}};
構造体の値
metadata = {firstname: {type: "string"}};
データ型の値は、string、numeric、integer、boolean、date、array および struct です。
<cfscript> example = structnew(); example.firstname = "Yes"; example.lastname = "Man"; // changing the default serialization by specifying the type of "firstname" as string metadata = {firstname: {type:"string"}}; example.setMetadata(metadata); writeoutput(SerializeJSON(example)); </cfscript>
キー FIRSTNAME の値が「Yes」になっており、指定したとおりの出力になります。
{"LASTNAME":"Man","FIRSTNAME":"Yes"}
構造体レベルで型情報を渡す以外に、以下のように Application.cfc にメタデータを定義することもできます。
this.serialization.structmetadata={firstname: {type:"string",name:"fname"},lastname:{name:"lname"}};
上記のように定義した場合、このキーを含む値に、firstname のデータ型を定義する必要がありません。詳しくは、「Application.cfc 変数」を参照してください。
注意:実行時に、構造体レベルで構造体のメタデータが渡されないが、アプリケーションレベルで定義されている場合、アプリケーションレベルのメタデータを使用して構造体がシリアル化されます。ただし、構造体でメタデータを定義した場合は、構造体レベルのメタデータが、Application.cfc で定義した内容よりも優先されます。
構造体を JSON にシリアル化する場合、構造体キーは常に大文字でシリアル化されます。以下のように構造体のキーの正確な名前を指定することで、この動作を変更できます。
<cfscript> example = structnew(); example.firstname = "Yes"; example.lastname = "Man"; writeoutput("<b>After serialization</b>:"); // change the JSON key firstname to fname metadata = {firstname: {type:"string",name:"fname"}}; example.setMetadata(metadata); writeoutput(SerializeJSON(example)); </cfscript>
以下の出力では、キー FIRSTNAME が fname に変更されています。
{"LASTNAME":"Man","fname":"Yes"}
構造体のキーにメタデータが指定されていない場合は、デフォルトのシリアル化が適用されます。
ネストされた構造体でのシリアル化
構造体には、別の構造体をネストすることができます。値が構造体であるキーのメタデータを指定する方法には、2 通りあります。
親構造体に構造体キーのメタデータを設定
構造体に、 値が構造体であるキーのメタデータを 指定します。構造体には、ネストされた構造体に存在するキーのメタデータを含むことができます。そのようなキーのメタデータを構造体として指定しない場合、ネストされた構造体に明示的に設定されたメタデータがあるかどうかがチェックされます。メタデータがある場合、ネストされた構造体のメタデータが、ネストされた構造体のシリアル化に使用されます。
ネストされた構造体にも親構造体にもメタデータがない場合は、ネストされた構造体に ColdFusion のデフォルトのシリアル化が適用されます。
次に例を示します。
<cfscript> employee = structnew(); // define the struct key-value pairs employee.firstname = "Yes"; employee.lastname = "Man"; // define a nested struct for the key address employee.address = {"doorno": "148", "street":"10 Down Street", "country": "UK"}; metadata = {firstname: {type: "string", name: "fname"}, address: {keys: // set the metadata for a key in the nested struct { "doorno": {type: "string", name: "DoorNo"}, "street": "string", "country": "string" }}}; employee.setmetadata(metadata); writeoutput(SerializeJSON(employee)); </cfscript>
出力は次のようになります。
{"LASTNAME":"Man","ADDRESS":{"country":"UK","DoorNo":"148","street":"10 Down Street"}," fname ":"Yes"}
この方法は、例えば employee 構造体に住所が含まれているような場合に便利です。上記の例では、DoorNo キーが 148 と指定されています。しかし、DoorNo キーには、148a や 148-a など、英数字も含まれる場合があります。このような場合、上記の例では、DoorNo キーは文字列としてシリアル化されます。
{"LASTNAME":"Man","ADDRESS":{"country":"UK","DoorNo":"148-a","street":"10 Down Street"}," fname ":"Yes"}
キー DoorNo のメタデータを文字列として設定します。内部構造体のメタデータは、keys というキーに構造体として指定する必要があります。
setMetadata 関数を使用してネストされた構造体のメタデータを設定
親構造体およびネストされた構造体の両方にメタデータを設定した場合、シリアル化では親のメタデータが利用されます。次に例を示します。
<cfscript> employee = structnew(); employee.firstname = "Yes"; employee.lastname = "Man"; employee.address = {"doorno": "148", "street":"10 Downing Street", "country": "UK"}; employee.address.setmetadata({"doorno": {type: "string", name: "DoorNo"},"street": "string","country": "string"}); // changing the default serialization by specifying the type of firstname as string and // changing JSON key firstname to fname metadata = {firstname: {type: "string", name: "fname"}}; employee.setmetadata(metadata); writeoutput(SerializeJSON(employee)); </cfscript>
出力は次のようになります。
{"LASTNAME":"Man","ADDRESS":{"country":"UK","DoorNo":"148","street":"10 Downing Street"}," fname ":"Yes"}
employee 構造体の address キーをシリアル化する場合、employee 構造体にそのメタデータが指定されていないと、address 構造体にメタデータが設定されているかどうかがチェックされます。メタデータが定義されている場合は、そのメタデータを利用してシリアル化が行われます。メタデータが定義されていない場合は、デフォルトのシリアル化が行われます。
構造体内の配列のシリアル化
ColdFusion の構造体には、キーを表す配列を含むことができます。配列には、様々なデータ型の値を含むことができます。
配列内の要素のデータ型が同じ場合、そのデータ型の値を持つキーを設定した構造体としてデータ型を指定します。次に例を示します。
{title: {type:"string",name:"title"}, tags:{items:"string",name:"keywords"}};
以下に、構造体内の配列のシリアル化のコード例を示します。
<cfscript> blogPost = structnew(); blogPost.Title = "Struct Serialization"; blogPost.referenceURL = "http://www.example.com"; // define an array for a struct key. In the array all elements are of type string, except 2016 blogPost.tags = ["struct", "json", "serialization", "2016", "HF2", "metadata"]; // specify all elements as string in the metadata metadata = {title: {type: "string", name: "title"}, tags: {items: "string", name: "keywords"},referenceURL:{name:"url"}}; blogPost.setmetadata(metadata); writeoutput(SerializeJSON(blogPost)); </cfscript>
デフォルトの JSON シリアル化を使用した出力は以下のようになります。
{"TITLE":"Struct Serialization","TAGS":["struct","json","serialization",2016,"HF2","metadata"],"REFERENCEURL":"http://www.example.com"}
TAGS 配列内のすべての値は、数値としてシリアル化される 2016 を除いて文字列としてシリアル化されます。しかし、2016 も文字列としてシリアル化したい場合があります。
上記の例のように TAGS 配列のメタデータを指定すると、出力は以下のようになります。
{"title":"Struct Serialization","keywords":["struct","json","serialization","2016","HF2","metadata"],"url":"http://www.example.com"}
配列に様々なデータ型の値が含まれている場合、キー items に各配列要素のメタデータを指定する値の配列を割り当てます。次に例を示します。
<cfscript> example = structnew(); example.firstname = "Yes"; example.lastname = "Man"; // define an array for a struct key. Elements are of different datatypes example.inputs = ["2500.12", 4.0, "Yes", "False", "339090", {"q1": "Yes"}, ["1","2","3"]]; // set datatypes of first element as numeric, second element as integer, and so on example.setmetadata({firstname: "string", inputs: {items: ["numeric", "integer", "string", "boolean", "string", {q1: "boolean"}, {items: "string"}]}}); writeoutput(serializeJSON(example)); </cfscript>
出力は次のようになります。
{"LASTNAME":"Man","FIRSTNAME":"Yes","INPUTS":[2500.12,4,"Yes",false,"339090",{"q1":true},["1","2","3"]]}
上記の例では、inputs 配列にも要素として構造体および配列が含まれています。このような場合、メタデータは、inputs 配列のメタデータに指定できます。
構造体のキーを無視する
構造体内で、シリアル化する必要がない特定のキーを無視できます。以下のように、キー ignore を指定し、値を true に設定します。
{key:{ignore:true}}
次に例を示します。
<cfscript> employee = structnew(); employee.firstname = "Yes"; employee.lastname = "Man"; employee.salary = "100000"; employee.salarygrade = "D"; // ignore salary and salarygrade keys profileView = {firstname: {type:"string",name:"fname"}, salary: {ignore: true}, salarygrade: {ignore: true}}; employee.setmetadata(profileView); writeoutput(serializeJSON(employee)); </cfscript>
出力は次のようになります。
{"LASTNAME":"Man","fname":"Yes"}
salary および salarygrade キーが無視されますが、他のキーはメタデータに従ってシリアル化されます。
メタデータの取得
getMetadata 関数を使用してメタデータを取得できます。この関数は、構造体において、構造体のタイプ(ソートされているか、ソートされていないか)に加えて、構造体キーのメタデータ情報を提供します。以下に例を示します。
<cfscript> employee = structnew(); employee.firstname = "Yes"; employee.lastname = "Man"; employee.salary = "100000"; employee.salarygrade = "D"; profileView = {firstname: {type:"string",name:"fname"}, salary: {ignore: true}, salarygrade: {ignore: true}}; employee.setmetadata(profileView); writedump(employee.getMetadata()); </cfscript>
このサンプルの出力は次のようになります。

返されるメタデータには、構造体に設定されたメタデータを含む keys というキーが含まれています。2 つ目のキー ordered は、構造体がソートされているかソートされていないかを返します。
注意:ソートされている構造体では、キー ordered の値は insertion です。
配列のシリアル化
Adobe ColdFusion(2016 リリース)アップデート 2 では、配列のメタデータの設定ができるようになりました。setMetadata 関数を使用して、配列にデータ型を設定できます。
配列のすべての項目が同じデータ型の場合は、データ型の値を文字列として持つ items キーを使用して、構造体として値のデータ型を 指定できます。 。
シリアル化の指定のない例を以下に示します。
<cfscript> tags = ["struct", "json", "serialization", "2016", "HF2", "metadata"]; WriteOutput(serializejSON(tags)); </cfscript>
このサンプルの出力は次のようになります。
["struct"," json ","serialization",2016,"HF2","metadata"]
データ型情報がないので、文字列 2016 は数値に変換されます。以下に、配列に設定されたメタデータの例を示します。
<cfscript> tags = ["struct", "json", "serialization", "2016", "HF2", "metadata"]; tags.setmetadata({items: "string"}); writeoutput(serializejSON(tags)); </cfscript>
出力は次のように表示されます。
["struct"," json ","serialization","2016","HF2","metadata"]
配列に様々なデータ型の値が含まれている場合は、メタデータに配列としてデータ型を指定します。次に例を示します。
myArray=["ColdFusion",2016,"true"];
myArray.setMetadata({items:["string","integer","boolean"]});
次に例を示します。
<cfscript> inputs = ["2500.12", 4.0, "Yes", "False", "339090", {"q1": "Yes"}, ["1","2","3"]]; inputs.setmetadata({items: ["string", "integer", "string", "boolean", "string", {q1: "string"}, {items: "string"}]}); writeoutput(serializeJSON(inputs)); </cfscript>
["2500.12",4,"Yes",false,"339090",{"q1":"Yes"},["1","2","3"]]
配列に構造体または配列が含まれている場合は、それぞれのメタデータを指定できます。内部の配列または構造体のメタデータを指定しない場合、配列または構造体に明示的に定義されたメタデータがないかがチェックされます。メタデータがある場合、ColdFusion では、配列または構造体に明示的に定義されたメタデータが使用されます。
メタデータの取得
getMetadata 関数を使用して、配列のタイプ(同期されているか、同期されていないか)に加えて、配列のメタデータ情報を表示できます。次に例を示します。
<cfscript> inputs = ["2500.12", 4.0, "Yes", "False", "339090", {"q1": "Yes"}, ["1","2","3"]]; inputs.setmetadata({items: ["string", "integer", "string", "boolean", "string", {q1: "string"}, {items: "string"}]}); writedump(inputs.getMetadata()); </cfscript>
このサンプルの出力は次のようになります。

返されるメタデータには、配列に設定されたメタデータが含まれています。items キーには、配列の項目のメタデータが含まれています。type キーには、配列が同期されているか、同期されていないかについての情報が含まれています。
アカウントにログイン