JSONオブジェクトをクエリ文字列に変換

API、フロントエンドのルーター、分析パイプラインは、フィルタやフォーム項目を単純なJSONマップとして保持しつつ、アドレスバーや外向きHTTPクライアント向けに正しく符号化されたクエリ文字列を必要とすることがよくあります。この機能は平坦なJSONオブジェクトを1つ受け取り、各スカラー値をテキストに変換し、すべてのキーと値をパーセント符号化して、付与しやすいクエリ文字列と順序付きペア、正規化された文字列マップを返します。ネストしたオブジェクトと配列は invalid_input で拒否されるため、呼び出し側が有効なURLに見える半構造のゴミを送出しません。

平坦なオブジェクトから符号化クエリ文字列へ

結果は生の特殊文字から余分な区切りを発明しないクエリ文字列です。ネストしたオブジェクトと配列は意図的に非対応です。空のオブジェクトは空のクエリ文字列と疑問符プレフィックスだけの形を生成し、ダミーキーを発明せずパラメータなしを主張するテストに役立ちます。キー数と直列化後の総長の上限は、無料ブラウザ経路で病的なマップがメモリを使い果たすのを防ぎます。URLクエリ文字列は、名前イコール値のフィールドをアンパサンドでつないだ列であり、パスの後に疑問符が付くこともあります。信頼できる情報源がすでにJSONオブジェクトである場合——たとえばフィルタ状態、フォームモデル、設定マップ——ブラウザとサーバが期待するワイヤ形式へそのマップを移す決定的な手段が必要です。この機能はオブジェクト自身のキーを挿入順に走査し、各スカラー値を安定した文字列へ変換し（真偽値は true または false、有限数は通常の十進表記、null は空の値）、各キーと各値に encodeURIComponent を適用して空白を percent-twenty、アンパサンドを percent-twenty-six にし、Unicode が転送を生き延びるようにします。クエリパラメータは平坦なキー値ペアであり、ネスト構造を1本の不透明な文字列に直列化すると、リクエストがクライアントを離れる前に直したい誤りが隠れてしまいます。経路は文字列とオブジェクトの純粋な作業で、ネットワークも乱数シードも壁時計もなく、同一入力は常に同一のJSONを生みます。成功時のAPI料金は公開されている基準 $0.002 の1件あたりであり、検証失敗は前払い残高を消費しません。

入力契約、応答形、エラーの扱い

値は文字列、数値、真偽値、null をプロパティとする平坦なオブジェクトでなければなりません。非有限数（NaN と Infinity）はクエリ文字列に標準の可搬な形がないため拒否されます。例: name が Ada Lovelace、city が London、active が true、score が四十二なら、空白と予約文字がパーセント符号化された4パラメータの文字列になります。必須フィールド object（別名 json、data、params、map、fields）を持つJSON本体をPOSTしてください。object をそのようなマップに解析されるJSONテキストとして渡すこともできます。最上位の配列、null、スカラー、ネストしたオブジェクトや配列の値は invalid_input と、該当時に悪いキーを名指しする明確な英語メッセージで失敗します。成功時の応答には query（先頭の疑問符なしの符号化文字列）、query_with_prefix（先頭に疑問符を付けた同じ文字列、キーがない場合は疑問符のみ）、count（パラメータ数）、pairs（スカラー変換後・符号化前の key と value の文字列の順序付き配列）、object（その強制後の値の last-wins 文字列マップ）が含まれます。典型的な失敗: filter のようなキーの下にネストしたフィルタをオブジェクトとして送り、黙って壊れたURLではなく invalid_input を受け取る。成功時のAPI料金は公開基準 $0.002 の1件あたりで、検証失敗は課金されません。

JSONからクエリへの変換が生きる場面

外向きリクエストを記録したり設定マップから署名付きURLを組み立てるバックエンドは、サポートチケットとアクセスログがクライアントが実際に送った内容と一致するよう、ブラウザと同じパーセント符号化規則を必要とします。JSONマップを持つ人は符号化を望み、parse モードの選択肢は望みません。実装が純粋な parse のティア A であるため、成功した呼び出しはモデルトークンも外向きネットワークもなく公開基準価格 $0.002 です。