エスケープ関数
エスケープ関数を使用すると、クエリ、URL、マークアップドキュメント、CSV行などの特定の形式に値を安全に埋め込めます。
文字列全体ではなく値をエスケープする
各値は挿入する前にエスケープしてください。完成した文字列はエスケープしないでください。完成した文字列をエスケープすると有効な構文が変わる可能性があり、エスケープを省略するとインジェクションを許す可能性があります。
f"SELECT Id FROM Account WHERE Name = '{escape_for_soql(_.name)}'"引用符はクエリ構文の一部です。その間の値だけをエスケープします。
クエリ言語
クエリに直接挿入されたインバウンドデータは、意図しない構文を持ち込む可能性があります。以下の関数は値をエスケープし、クエリエンジンが値をコードではなくデータとして扱うようにします。
escape_for_soql
SalesforceのSOQL文字列リテラル用に値をエスケープします。'と\をエスケープします。 % と _ のワイルドカードはエスケープしません。
escape_for_soql(value)| パラメーター | 説明 |
|---|---|
| value | エスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。 |
SOQL用にアポストロフィをエスケープ
次の例では、SOQL文字列リテラル用にアポストロフィをエスケープします。
Formula
escape_for_soql("O'Brien")出力
O\'Brienescape_for_odata
各シングルクォートを二重にすることで、ODataフィルター文字列リテラル用に値をエスケープします。 ODataでは、バックスラッシュエスケープではなく二重引用符が想定されます。
escape_for_odata(value)| パラメーター | 説明 |
|---|---|
| value | エスケープする値。 |
OData用にアポストロフィをエスケープ
次の例では、ODataフィルター文字列リテラル用にアポストロフィをエスケープします。
Formula
escape_for_odata("O'Brien")出力
O''Brienescape_for_regex
正規表現のメタ文字をエスケープし、パターンが文字列をリテラルとして一致させるようにします。構文文字は前にバックスラッシュが付き、句読点は \xHH エスケープになります。
escape_for_regex(value)| パラメーター | 説明 |
|---|---|
| value | エスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。 |
正規表現のメタ文字をエスケープ
次の例では、文字列内の正規表現メタ文字をエスケープします。
Formula
escape_for_regex('a.b*c')出力
a\.b\*cマークアップ
以下の関数は、HTMLまたはXMLマークアップ用に値をエスケープします。
escape_for_html
HTMLテキストまたは引用符で囲まれた属性値用に値をエスケープします。 &、<、>、"、'、および/をエスケープします。
結果は <script> 要素や <style> 要素の内部、または非引用符付き属性の内部では安全ではありません。イベントハンドラー属性内のJavaScriptについては、まず escape_for_javascript を使用し、その後で escape_for_html を使用します。
escape_for_html(value)| パラメーター | 説明 |
|---|---|
| value | エスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。 |
HTMLマークアップ文字をエスケープ
次の例では、HTML文字列内のマークアップ文字をエスケープします。
Formula
escape_for_html('<b>Tom & Jerry</b>')出力
<b>Tom & Jerry</b>escape_for_xml
XMLテキストまたは属性用に値をエスケープし、XML 1.0で不正なコードポイントを削除します。
これらのコードポイントを削除すると、ソースシステムの制御文字によってパーサーが処理できないXMLが生成されるのを防げます。
escape_for_xml(value)| パラメーター | 説明 |
|---|---|
| value | エスケープする値。 |
XMLマークアップ文字をエスケープ
次の例では、XML文字列内のマークアップ文字をエスケープします。
Formula
escape_for_xml('<tag> & more')出力
<tag> & moreデータ形式
以下の関数は、特定のデータ形式またはコード形式用に値をエスケープします。
escape_for_csv
CSVフィールド用に値をエスケープし、必要に応じてフィールドを引用符で囲み、内部の引用符を二重にすることでRFC 4180に従います。
CSV Formulaインジェクションを防ぐには、'safe_formulas'を渡します。そうしないとスプレッドシートアプリケーションは、タブ、復帰、改行、負の数、=、+、-、@、またはその全角同等文字で始まるフィールドをFormulaとして扱うため、信頼できないソースからの値が、ファイルを誰かが開いたときに実行されてしまうおそれがあります。 'safe_formulas' は、潜在的に危険なフィールドの前にアポストロフィ(')を付加します。
escape_for_csv(value, 'safe_formulas')| パラメーター | 説明 |
|---|---|
| value | エスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。 |
| 'safe_formulas' | 任意。先頭のFormula文字も無効化するには、このパラメーターを渡します。認識されないモードに対しては E225 を送出します。 |
カンマを含むフィールドを引用符で囲む
次の例では、カンマを含むCSVフィールドを引用符で囲みます。
Formula
escape_for_csv('Smith, Josh')出力
"Smith, Josh"先頭のFormula文字を無効化
次の例では、'safe_formulas'を使用して先頭のFormula文字を無効化します。
Formula
escape_for_csv('=1+1', 'safe_formulas')出力
"'=1+1"人が開くものにはSAFE_FORMULASを使用する
人がスプレッドシートアプリケーションでCSVを開く場合は、'safe_formulas'を渡します。スプレッドシートのFormulaを評価しないマシン間処理では、このオプションは不要です。
escape_for_json_string
周囲の引用符を追加せずに、JSON文字列内に埋め込む値をエスケープします。"、\、制御文字のみをエスケープし、/ と非ASCII文字はそのままにします。
JSONテキストを手動で組み立てる場合に使用します。代わりに値全体をシリアライズするには、全体のエスケープを処理するto_jsonを使用します。
escape_for_json_string(value)| パラメーター | 説明 |
|---|---|
| value | エスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。 |
JSON文字列用に引用符をエスケープ
次の例では、JSON文字列内に埋め込むためにダブルクォートをエスケープします。
Formula
escape_for_json_string('He said "hi"')出力
He said \"hi\"escape_for_javascript
値を、引用符自体は追加せずに、シングルクォートまたはダブルクォートで囲まれたJavaScript文字列リテラル内部で使用できるようにエスケープします。
| 文字 | 結果 |
|---|---|
'、"、\、/ | 前にバックスラッシュが付きます |
<、> | \x3C、\x3E になります |
| 改行、CR、タブ、バックスペース、フォームフィード | \n、\r、\t、\b、\f になります |
U+2028、U+2029 | \u2028、\u2029 になります |
| その他の制御文字 | \uXXXX になります |
< と > をエスケープすることで、結果が <script> 要素を閉じてしまうことはありません。バッククォートと ${ はエスケープされないため、結果をテンプレートリテラル内に含めないでください。
escape_for_javascript(value)| パラメーター | 説明 |
|---|---|
| value | 任意のスカラー値。数値、Boolean、時系列値、または null は最初にStringルールでテキストに変換され、null は 'null' になります。 List、Map、または Binary の値に対しては E100 を送出します。 |
JavaScript用にアポストロフィをエスケープ
次の例では、JavaScript文字列リテラル用にアポストロフィをエスケープします。
Formula
escape_for_javascript("O'Brien")出力
O\'BrienURLとクエリ文字列
これら3つの関連関数は、スペースの扱いが異なります。必要なURL形式に一致する関数を選択してください。
| 機能 | スペースの変換先 | 用途 |
|---|---|---|
escape_for_url | %20 | RFC 3986で定義される文字列全体 |
uri_encode_www_form_component | %20 | URLの1つのコンポーネント |
uri_encode_www_form | + | フォームエンコードされたクエリ文字列全体 |
escape_for_url
RFC 3986で定義されるように文字列をパーセントエンコードします。
escape_for_url(value)| パラメーター | 説明 |
|---|---|
| value | エンコードする値。 |
文字列全体をパーセントエンコード
次の例では、RFC 3986で定義されるように文字列全体をパーセントエンコードします。
Formula
escape_for_url('name=Kalani Park&x=1')出力
name%3DKalani%20Park%26x%3D1uri_encode_www_form_component
単一のURIコンポーネントをパーセントエンコードします。予約されていない文字は変更されずに渡されます。
uri_encode_www_form_component(value)| パラメーター | 説明 |
|---|---|
| value | エンコードするコンポーネント。 |
単一のコンポーネントをパーセントエンコード
次の例では、単一のURIコンポーネントをパーセントエンコードします。
Formula
uri_encode_www_form_component('Kalani Park')出力
Kalani%20Parkuri_decode_www_form_component
パーセントエンコードされたURIコンポーネントをデコードします。 + はスペースではなく、そのまま通過します。
uri_decode_www_form_component(value)| パラメーター | 説明 |
|---|---|
| value | デコードするコンポーネント。不正なパーセントエンコーディングに対しては E226 を送出します。 |
パーセントエンコードされたコンポーネントをデコード
次の例では、パーセントエンコードされたURIコンポーネントをデコードします。
Formula
uri_decode_www_form_component('Kalani%20Park')出力
Kalani Parkuri_encode_www_form
Map を、ペアをマップの順序で & で連結した application/x-www-form-urlencoded クエリ文字列としてエンコードします。
キーと値はWHATWGフォームルールを使用します: スペースは + になり、ASCII文字、数字、*、-、.、_ はそのまま通過し、それ以外のすべてのバイトは %XX になります。 String 値はそのまま書き出されます。その他のスカラー値は正規のテキスト形式で書き出されるため、true は true、null は null、日付はISO形式になります。
uri_encode_www_form(map, options)| パラメーター | 説明 |
|---|---|
| map | パラメーターのマップ。 List 値は、各要素ごとに1組のペアを書き出します。空の List に対しては E218 を送出します。 Map、Binary、または入れ子の List の値に対しては E100 を送出します。 |
| options | dialectを指定するオプションのマップ。 'whatwg'(デフォルト)は、各 List 要素についてキーを繰り返します。 'rack' は各要素に対して key[] を書き出し、キーに [ または ] が含まれている場合は E218 を送出します。認識されないオプションキーは E225 をスローします。認識されない dialect 値に対しては E225 を送出します。 |
マップをクエリ文字列としてエンコード
次の例では、マップをフォームエンコードされたクエリ文字列としてエンコードします。
Formula
uri_encode_www_form({status: 'open', q: 'blue widget'})出力
status=open&q=blue+widgeturi_decode_www_form
クエリ文字列をMapにデコードします。この関数は + をスペースにデコードし、空のペアをスキップし、= 記号のないペアを空の値としてデコードし、先頭の ? は最初のキーの一部としてそのまま保持します。
uri_decode_www_form(text, options)| パラメーター | 説明 |
|---|---|
| テキスト | デコードするクエリ文字列。不正なパーセントエンコーディングに対しては E226 を送出します。 |
| options | デコードを制御するオプションのマップ。
E225 が送出されます。 |
クエリ文字列をマップにデコード
次の例では、フォームエンコードされたクエリ文字列をマップにデコードします。
Formula
uri_decode_www_form('status=open&q=blue+widget')出力
{status: "open", q: "blue widget"}ユースケース: フィルターされたAPIリクエストを作成する
インバウンドデータの検索語句には、スペースや句読点が含まれることがあります。文字列を連結する代わりに、パラメーターをマップとしてエンコードして、各値をエスケープし、区切り文字を保持します。
入力
{
"status": "open",
"search": "blue widget & more"
}Formula
f"/api/v2/orders?{uri_encode_www_form({status: _.status, q: _.search})}"出力
"/api/v2/orders?status=open&q=blue+widget+%26+more"uri_encode_www_formは検索語句内の&を%26としてエンコードするため、パラメーター区切り文字と誤認されません。また、2つのパラメーターを実際に区切る&はそのまま残します。
関連情報
- JSON関数: 値全体をシリアライズするには
to_jsonを使用します。 - 文字列関数: 正規表現のマッチングと置換。
- エンコーディング関数: エスケープではなく文字エンコーディング。
- 文字列と書式設定: f-stringに関する詳細情報。
最終更新日: