要素
最終更新日 :
2023年11月27日
説明
ColdFusion データを JSON（JavaScript Object Notation）表現に変換します。
戻り値
パラメーター値の JSON 表現を含んだ文字列
ColdFusion 2018 リリースより前のリリースでは、文字列のシリアル化を処理する際に、ColdFusion は文字列がブール値（「yes」、「no」、「true」、「false」）か数値（「100」、「0.125」など）のどちらであるかを調べ、それぞれ JSON ブール値または JSON 数値に変換します。 2018年以降、ColdFusion はこのチェックを行わず、どちらも有効な文字列として扱い、JSON 文字列（二重引用符で囲んだ値）に変換します。
詳しくは、Charlie Arehart 氏のブログを参照してください。
カテゴリ
シンタックス
SerializeJSON(data[, queryFormat[, useSecureJSONPrefix[, useCustomSerializer]]])
関連項目
DeserializeJSON、 IsJSON 、 cfajaxproxy 、『ColdFusion アプリケーションの開発』のデータ交換形式の使用、http://www.json.org
履歴
ColdFusion（2018 リリース）：名前付きパラメーターが導入されました。
ColdFusion（2016 リリース）アップデート 2：getMetadata を使用した構造体と配列のシリアル化のサポートが追加されました。
ColdFusion 11：useSecureJSONPrefix および useCustomSerializer という新しいパラメーターが追加されました。
ColdFusion 8：この関数が追加されました。
パラメーター
パラメーター |
説明 |
|---|---|
data |
ColdFusion データ値または ColdFusion データ値を表す変数。 |
queryFormat |
ColdFusion クエリをシリアル化する方法を指定するブール値か、「row」、「column」、「struct」のいずれかの値を取る文字列です。 |
useSecureJSONPrefix |
デフォルト値は false です。ColdFusion Administrator で「シリアル化 JSON への接頭辞付加」オプションが有効になっている場合は、デフォルトで、安全な JSON 接頭辞が JSON の先頭に挿入されます。 |
| useCustomSerializer | true と false のいずれかを使用し、customSerializer を使用するかどうかを指定します。デフォルト値は true です。常に、カスタム シリアライザーが シリアル化に使用されます。false の場合、JSON シリアル化はデフォルトの ColdFusion 動作を使用して実行されます。 |
使用方法
この関数は、Ajax アプリケーションで使用するための JSON 形式のデータを生成するのに役立ちます。SerializeJSON 関数は、ColdFusion の日付と時刻を、JavaScript の Date オブジェクトで簡単に解析できる文字列に変換します。この文字列の形式は次のようになります。
MonthName, DayNumber Year Hours:Minutes:Seconds
SerializeJSON 関数は、例えば、2007年10月3日午後 3:01 を表す 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 パラメーターの値が false に設定された 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 というすべて大文字の名前を使用します。
構造体のシリアル化
ColdFusion では、構造体キーの大文字と小文字の区別は保持されません。構造体キーは自動的に大文字に変換されます。
例えば、次のコード スニペットでは、出力のキーが既定で大文字に変換されます。
<cfscript>
data = {empName="James", age="26"};
serializedStr = serializeJSON(data);
writeoutput(serializedStr);
</cfscript>
出力
{"EMPNAME":"James","AGE":"26"}
アプリケーションレベルでキーの大文字と小文字の区別を保持する必要がある場合は、application.cfc で次のように設定を変更します。
this.serialization.preservecaseforstructkey = true
application.cfc に次の設定が含まれるようになりました。
component
{
this.name='serializeJSON'
this.serialization.preservecaseforstructkey = true
}
この状態でスニペットを再実行すると、次の出力が表示されます。
{"empName":"James","age":"26"}
サーバーレベルで大文字と小文字の区別の保持を有効にする
サーバーレベルで構造体キーの大文字と小文字の区別の保持を有効にするには、次の操作を行います。
- ColdFusion Administrator ページで、サーバーの設定／設定を選択します。
- 「シリアル化用の構造体キーで大文字小文字を保持」を選択します。
なお、この設定は CFML ページのコンパイル中に使用されるので、このフラグが（Administrator またはプログラムで）変更されると、変更に関連するすべてのページを再コンパイルする必要があります。通常、この処理では、単にファイルが編集（すべてを変更）され、それが再実行されます。ColdFusion Administrator の「信頼できるキャッシュ」が有効な場合、（少なくとも影響を受けたファイル）のテンプレートキャッシュをクリアする必要があります。これらは、ColdFusion Administrator のキャッシュ機能ページ内でも実行できます。
クエリのシリアル化
serializeJSON 関数では、ColdFusion クエリを、次の要素を含んだ行指向の JSON オブジェクトに変換します。
| 要素 | 説明 |
| COLUMNS | 列名の配列です。 |
DATA
|
次のエントリを含む 2 次元配列です。
|
例えば、serializeQueryByColumns パラメーターの値が false に設定された SerializeJSON 関数では、2 つの列（City と State）と 2 つのデータ行を含んだ ColdFusion クエリが次の形式に変換されます。
{"COLUMNS":["CITY","STATE"],"DATA":[["Newton","MA"],["San Jose","CA"]]}
例 1
この例のコードスニペットは、queryFormat を行として使用しています。このスニペットの出力では、クエリのデータが行の配列として配置されます。
<cfscript>
myquery=QueryNew([
{"Id":101,"Name":"John Adams","Paid":FALSE},
{"Id":102,"Name":"Samuel Jackson","Paid":TRUE},
{"Id":103,"Name":"Jack Michaels","Paid":TRUE},
{"Id":104,"Name":"Tony Stark","Paid":FALSE}
])
//writeDump(myquery)
serializedQuery=serializeJSON(data=myquery,queryformat="row")
writeOutput(serializedQuery)
</cfscript>
出力
{"COLUMNS":["PAID","ID","NAME"],"DATA":[[false,101,"John Adams"],[true,102,"Samuel Jackson"],[true,103,"Jack Michaels"],[false,104,"Tony Stark"]]}
例 2
この例のコードスニペットは、queryFormat を列として使用しています。このスニペットの出力では、行に関連付けられた配列の形式でデータが生成されます。
<cfscript>
myquery=QueryNew([
{"Id":101,"Name":"John Adams","Paid":FALSE},
{"Id":102,"Name":"Samuel Jackson","Paid":TRUE},
{"Id":103,"Name":"Jack Michaels","Paid":TRUE},
{"Id":104,"Name":"Tony Stark","Paid":FALSE}
])
//writeDump(myquery)
serializedQuery=serializeJSON(data=myquery,queryformat="column")
writeOutput(serializedQuery)
</cfscript>
出力
{"ROWCOUNT":4,"COLUMNS":["PAID","ID","NAME"],"DATA":{"PAID":[false,true,true,false],"ID":[101,102,103,104],"NAME":["John Adams","Samuel Jackson","Jack Michaels","Tony Stark"]}}
例 3
この例のコードスニペットは、queryFormat を構造体として使用しています。このスニペットの出力では、データが構造体の配列になっています。
<cfscript>
myquery=QueryNew([
{"Id":101,"Name":"John Adams","Paid":FALSE},
{"Id":102,"Name":"Samuel Jackson","Paid":TRUE},
{"Id":103,"Name":"Jack Michaels","Paid":TRUE},
{"Id":104,"Name":"Tony Stark","Paid":FALSE}
])
//writeDump(myquery)
serializedQuery=serializeJSON(data=myquery,queryformat="struct")
writeOutput(serializedQuery)
</cfscript>
出力
[{"PAID":false,"ID":101,"NAME":"John Adams"},{"PAID":true,"ID":102,"NAME":"Samuel Jackson"},{"PAID":true,"ID":103,"NAME":"Jack Michaels"},{"PAID":false,"ID":104,"NAME":"Tony Stark"}]
日時のシリアル化
SerializeJSON 関数は、ColdFusion の日付時刻オブジェクトを変換して、JavaScript の Date オブジェクトで簡単に解析できる文字列を返します。この文字列の形式は次のようになります。
MonthName, DayNumber Year Hours:Minutes:Seconds
例えば、SerializeJSON 関数では、2023年10月3日午後 3:01 を表す ColdFusion の日時オブジェクトが、"October, 03 2023 15:01:00" という JSON 文字列に変換されます。
例
<cfscript>
currentdate = now()
datetimeobj = arrayNew(1)
datetimeobj[1] = currentdate
datetimeobj[2] = "8/11/2006"
datetimeobj[3] = CreateDate(2006,8,11)
datetimeobj[4] = CreateDateTime(2006,8,11,15,30,30)
datetimeobj[5] = CreateODBCDate(datetimeobj[4])
datetimeobj[5] = CreateODBCDateTime(datetimeobj[4])
// ループ処理で表を生成
writeOutput('<table border="1">');
writeOutput('<tr><th>入力した日時値</th><th>JSON 表現</th></tr>');
for (i=1;i<=arrayLen(datetimeobj);i++){
jsonstring = serializeJSON(datetimeobj[i])
writeOutput('<tr>')
writeOutput('<td>#datetimeobj[i]#</td>')
writeOutput('<td>#jsonstring#</td>')
writeOutput('</tr>')
}
// HTML テーブルタグを終了
writeOutput('</table>')
</cfscript>
出力
null のシリアル化
null は最新のプログラミング言語の重要な構文要素で、他の技術スタックやプログラミング言語との言語の相互運用性を向上させます。
ColdFusion の 2018 リリース以前は、外部サービスから返された null は空の文字列に変換されていました。したがって、ColdFusion アプリケーションで null のコードを記述したり、null 値に基づいて判断する場合、これを実現する固有の方法はありませんでした。
null 値を導入するには、空の値を代入するか、JavaCast を使用して強制的に null 値に型変換する必要がありました。
以前は、次のようなコードを使用していました。
<cfscript>
response={}
response.result="Success"
response.error="Error"
//writeDump(response)
response.error=javacast("null","")
serializedResponse = serializeJSON(response)
writeOutput(serializedResponse)
</cfscript>
出力
{"error":null,"result":"Success"}
ColdFusion の 2018 リリースでは、Application.cfc に this.enableNullSupport = true という設定が導入されました。このオプションを有効にすると、null 値を変数または構造体キーに代入できます。
例
Application.cfc
component
{
this.name='serializeJSON';
this.serialization.preservecaseforstructkey = true
this.enableNullSupport = true
}
File.cfm
<cfscript>
response={}
response.result="Success"
response.error="Error"
//writeDump(response)
//response.error=javacast("null","")
response.error=null
serializedResponse = serializeJSON(response)
writeOutput(serializedResponse)
</cfscript>
出力
{"error":null,"result":"Success"}
データ型の保持
ColdFusion の言語は型なしで、コード生成時に型情報を評価することや保持することはありません。実行時、ColdFusion は予期しない動作を引き起こす可能性がある datatype を確認するために、最大限の推測を実行しようとします。 例えば、ColdFusion では、JSON シリアル化時に、文字列を数値に変換しようとします。この試みが成功した場合、渡されたデータ型は、文字列として扱う必要があるかどうかに関係なく、数値として扱われます。
ColdFusion 11 以降では、クエリおよび CFC のコード実行時にデータ型が保持されます。
SerializeJSON では、シリアル化時に、データベースで定義されている datatype を考慮します。データベースで列を文字列として定義している場合、その列に挿入された数値はすべて SerializeJSON では文字列として扱われます。
次に例を示します。
<cfquery name="qry_Users" datasource="#DSN#"> select * from users </cfquery> <cfoutput>#SerializeJSON(qry_Users)#</cfoutput><br>
クエリのシリアル化
SerializeJSON では、データベースで定義されている列の datatype を優先します。datatype が列に指定されている限り、同じことが QueryNew() を使用して作成されたメモリ内クエリに対しても機能します。
CFC プロパティの型の例について考えてみます。
Employee.cfc
Component accessors="true"
{
property string empName;
property numeric age;
property string dept;
}
Index.cfm
<cfscript>
emp = new Employee({empName="James", age=26, dept="000"});
writeOutput(SerializeJSON(emp));
</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 に構造体を渡して、クエリオブジェクトを構造体としてシリアル化することができます。
URL を介して CFC を呼び出す場合は、queryformat=struct を指定する必要があります。
ColdFusion 11 では、現在、クエリオブジェクトから AJAX フレンドリーな JSON 文字列へのシリアル化をサポートしています。
[
{"colour":"red","id":1},
{"colour":"green","id":2},
{"colour":"blue","id":3}
]
現在の SerializeJSON 関数は機能強化され、「キーと値」の形式をサポートしています。
SerializeJSON( Object o, Object serializeQueryByColumns, boolean secure, boolean useCustomSerializer);
application.cfc で serialzeQueryAs プロパティを使用している場合は、その機能をオーバーライドする必要がなければ、serialzeQueryByColumns プロパティを指定する必要はありません。
カスタムシリアライザー
application.cfc ファイルでは、複合型のシリアル化およびシリアル化解除用の独自のハンドラーを登録できます。シリアライザーが指定されていない場合、ColdFusion は、デフォルトのシリアル化メカニズムを使用します。プラグ可能なシリアライザーおよびデシリアライザーのサポートを参照してください。
構造体のシリアル化
Adobe ColdFusion（2016 リリース）アップデート 2 では、構造体のキーにデータ型情報を指定できます。これは、メタデータと呼ばれています。
メタデータの設定を開始する前に、メタデータで使用される属性について十分に理解しておきます。次の表にメタデータ属性を示します。
|
属性 |
説明 |
|
type |
構造体キーの データ型 。 |
|
name |
構造体内のキーをシリアル化する際に、キー名を JSON キーとして使用するのではなく、ここで指定された名前が使用されます。 |
|
keys |
ネストされた構造体のメタデータ情報を含んだ構造体。 |
|
items |
配列の要素または構造体内の配列をシリアル化するためのメタデータを設定する場合のデータ型の配列。 |
|
ignore |
"true" の場合、 構造体 で指定されたキーを無視します。 デフォルト は "false" です。 |
<cfscript>
example = structnew();
example.firstname = "Yes";
example.lastname = "Man";
// デフォルトのシリアル化で文字列 Yes を 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";
// firstname の型を 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>:");
// JSON キー firstname を 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();
// 構造体のキーと値のペアを定義
employee.firstname = "Yes";
employee.lastname = "Man";
// address キー用のネストされた構造体を定義
employee.address = {"doorno": "148", "street":"10 Down Street", "country": "UK"};
metadata = {firstname: {type: "string", name: "fname"}, address: {keys:
// ネストされた構造体にキーのメタデータを設定
{
"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"});
// firstname の型を string として指定することでデフォルトのシリアル化を変更し、
// JSON キー firstname を 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";
// 構造体キーの配列を定義。配列内の 2016 を除くすべての要素が string 型
blogPost.tags = ["struct", "json", "serialization", "2016", "HF2", "metadata"];
// メタデータですべての要素を string として指定
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";
// 構造体キーの配列を定義。要素は様々なデータ型
example.inputs = ["2500.12", 4.0, "Yes", "False", "339090", {"q1": "Yes"}, ["1","2","3"]];
// 最初の要素のデータ型を numeric、2番目の要素のデータ型を integer などと設定
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";
// salary および salarygrade キーを無視
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 関数を使用して、配列にメタデータを設定できます。
配列のすべての項目が同じデータ型の場合は、データ型の値を string とする 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 キーには、配列が同期されているか、同期されていないかについての情報が含まれています。
