エスケープ関数 ​

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

エスケープ関数を使用すると、クエリ、URL、マークアップドキュメント、CSV行などの特定の形式に値を安全に埋め込めます。

文字列全体ではなく値をエスケープする

各値は挿入する前にエスケープしてください。完成した文字列はエスケープしないでください。完成した文字列をエスケープすると有効な構文が変わる可能性があり、エスケープを省略するとインジェクションを許す可能性があります。

wel
f"SELECT Id FROM Account WHERE Name = '{escape_for_soql(_.name)}'"

引用符はクエリ構文の一部です。その間の値だけをエスケープします。

クエリ言語 ​

クエリに直接挿入されたインバウンドデータは、意図しない構文を持ち込む可能性があります。以下の関数は値をエスケープし、クエリエンジンが値をコードではなくデータとして扱うようにします。

escape_for_soql ​

SalesforceのSOQL文字列リテラル用に値をエスケープします。'と\をエスケープします。 % と _ のワイルドカードはエスケープしません。

wel
escape_for_soql(value)
パラメーター説明
valueエスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。
SOQL用にアポストロフィをエスケープ

次の例では、SOQL文字列リテラル用にアポストロフィをエスケープします。

Formula

wel
escape_for_soql("O'Brien")

出力

text
O\'Brien

escape_for_odata ​

各シングルクォートを二重にすることで、ODataフィルター文字列リテラル用に値をエスケープします。 ODataでは、バックスラッシュエスケープではなく二重引用符が想定されます。

wel
escape_for_odata(value)
パラメーター説明
valueエスケープする値。
OData用にアポストロフィをエスケープ

次の例では、ODataフィルター文字列リテラル用にアポストロフィをエスケープします。

Formula

wel
escape_for_odata("O'Brien")

出力

text
O''Brien

escape_for_regex ​

正規表現のメタ文字をエスケープし、パターンが文字列をリテラルとして一致させるようにします。構文文字は前にバックスラッシュが付き、句読点は \xHH エスケープになります。

wel
escape_for_regex(value)
パラメーター説明
valueエスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。
正規表現のメタ文字をエスケープ

次の例では、文字列内の正規表現メタ文字をエスケープします。

Formula

wel
escape_for_regex('a.b*c')

出力

text
a\.b\*c

マークアップ ​

以下の関数は、HTMLまたはXMLマークアップ用に値をエスケープします。

escape_for_html ​

HTMLテキストまたは引用符で囲まれた属性値用に値をエスケープします。 &、<、>、"、'、および/をエスケープします。

結果は <script> 要素や <style> 要素の内部、または非引用符付き属性の内部では安全ではありません。イベントハンドラー属性内のJavaScriptについては、まず escape_for_javascript を使用し、その後で escape_for_html を使用します。

wel
escape_for_html(value)
パラメーター説明
valueエスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。
HTMLマークアップ文字をエスケープ

次の例では、HTML文字列内のマークアップ文字をエスケープします。

Formula

wel
escape_for_html('<b>Tom & Jerry</b>')

出力

text
&lt;b&gt;Tom &amp; Jerry&lt;&#x2F;b&gt;

escape_for_xml ​

XMLテキストまたは属性用に値をエスケープし、XML 1.0で不正なコードポイントを削除します。

これらのコードポイントを削除すると、ソースシステムの制御文字によってパーサーが処理できないXMLが生成されるのを防げます。

wel
escape_for_xml(value)
パラメーター説明
valueエスケープする値。
XMLマークアップ文字をエスケープ

次の例では、XML文字列内のマークアップ文字をエスケープします。

Formula

wel
escape_for_xml('<tag> & more')

出力

text
&lt;tag&gt; &amp; more

データ形式 ​

以下の関数は、特定のデータ形式またはコード形式用に値をエスケープします。

escape_for_csv ​

CSVフィールド用に値をエスケープし、必要に応じてフィールドを引用符で囲み、内部の引用符を二重にすることでRFC 4180に従います。

CSV Formulaインジェクションを防ぐには、'safe_formulas'を渡します。そうしないとスプレッドシートアプリケーションは、タブ、復帰、改行、負の数、=、+、-、@、またはその全角同等文字で始まるフィールドをFormulaとして扱うため、信頼できないソースからの値が、ファイルを誰かが開いたときに実行されてしまうおそれがあります。 'safe_formulas' は、潜在的に危険なフィールドの前にアポストロフィ(')を付加します。

wel
escape_for_csv(value, 'safe_formulas')
パラメーター説明
valueエスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。
'safe_formulas'任意。先頭のFormula文字も無効化するには、このパラメーターを渡します。認識されないモードに対しては E225 を送出します。
カンマを含むフィールドを引用符で囲む

次の例では、カンマを含むCSVフィールドを引用符で囲みます。

Formula

wel
escape_for_csv('Smith, Josh')

出力

wel
"Smith, Josh"
先頭のFormula文字を無効化

次の例では、'safe_formulas'を使用して先頭のFormula文字を無効化します。

Formula

wel
escape_for_csv('=1+1', 'safe_formulas')

出力

wel
"'=1+1"

人が開くものにはSAFE_FORMULASを使用する

人がスプレッドシートアプリケーションでCSVを開く場合は、'safe_formulas'を渡します。スプレッドシートのFormulaを評価しないマシン間処理では、このオプションは不要です。

escape_for_json_string ​

周囲の引用符を追加せずに、JSON文字列内に埋め込む値をエスケープします。"、\、制御文字のみをエスケープし、/ と非ASCII文字はそのままにします。

JSONテキストを手動で組み立てる場合に使用します。代わりに値全体をシリアライズするには、全体のエスケープを処理するto_jsonを使用します。

wel
escape_for_json_string(value)
パラメーター説明
valueエスケープする値。 List、Map、または Binary の値に対しては E100 を送出します。
JSON文字列用に引用符をエスケープ

次の例では、JSON文字列内に埋め込むためにダブルクォートをエスケープします。

Formula

wel
escape_for_json_string('He said "hi"')

出力

text
He said \"hi\"

escape_for_javascript ​

値を、引用符自体は追加せずに、シングルクォートまたはダブルクォートで囲まれたJavaScript文字列リテラル内部で使用できるようにエスケープします。

文字結果
'、"、\、/前にバックスラッシュが付きます
<、>\x3C、\x3E になります
改行、CR、タブ、バックスペース、フォームフィード\n、\r、\t、\b、\f になります
U+2028、U+2029\u2028、\u2029 になります
その他の制御文字\uXXXX になります

< と > をエスケープすることで、結果が <script> 要素を閉じてしまうことはありません。バッククォートと ${ はエスケープされないため、結果をテンプレートリテラル内に含めないでください。

wel
escape_for_javascript(value)
パラメーター説明
value任意のスカラー値。数値、Boolean、時系列値、または null は最初にStringルールでテキストに変換され、null は 'null' になります。 List、Map、または Binary の値に対しては E100 を送出します。
JavaScript用にアポストロフィをエスケープ

次の例では、JavaScript文字列リテラル用にアポストロフィをエスケープします。

Formula

wel
escape_for_javascript("O'Brien")

出力

text
O\'Brien

URLとクエリ文字列 ​

これら3つの関連関数は、スペースの扱いが異なります。必要なURL形式に一致する関数を選択してください。

機能スペースの変換先用途
escape_for_url%20RFC 3986で定義される文字列全体
uri_encode_www_form_component%20URLの1つのコンポーネント
uri_encode_www_form+フォームエンコードされたクエリ文字列全体

escape_for_url ​

RFC 3986で定義されるように文字列をパーセントエンコードします。

wel
escape_for_url(value)
パラメーター説明
valueエンコードする値。
文字列全体をパーセントエンコード

次の例では、RFC 3986で定義されるように文字列全体をパーセントエンコードします。

Formula

wel
escape_for_url('name=Kalani Park&x=1')

出力

text
name%3DKalani%20Park%26x%3D1

uri_encode_www_form_component ​

単一のURIコンポーネントをパーセントエンコードします。予約されていない文字は変更されずに渡されます。

wel
uri_encode_www_form_component(value)
パラメーター説明
valueエンコードするコンポーネント。
単一のコンポーネントをパーセントエンコード

次の例では、単一のURIコンポーネントをパーセントエンコードします。

Formula

wel
uri_encode_www_form_component('Kalani Park')

出力

text
Kalani%20Park

uri_decode_www_form_component ​

パーセントエンコードされたURIコンポーネントをデコードします。 + はスペースではなく、そのまま通過します。

wel
uri_decode_www_form_component(value)
パラメーター説明
valueデコードするコンポーネント。不正なパーセントエンコーディングに対しては E226 を送出します。
パーセントエンコードされたコンポーネントをデコード

次の例では、パーセントエンコードされたURIコンポーネントをデコードします。

Formula

wel
uri_decode_www_form_component('Kalani%20Park')

出力

text
Kalani Park

uri_encode_www_form ​

Map を、ペアをマップの順序で & で連結した application/x-www-form-urlencoded クエリ文字列としてエンコードします。

キーと値はWHATWGフォームルールを使用します: スペースは + になり、ASCII文字、数字、*、-、.、_ はそのまま通過し、それ以外のすべてのバイトは %XX になります。 String 値はそのまま書き出されます。その他のスカラー値は正規のテキスト形式で書き出されるため、true は true、null は null、日付はISO形式になります。

wel
uri_encode_www_form(map, options)
パラメーター説明
mapパラメーターのマップ。 List 値は、各要素ごとに1組のペアを書き出します。空の List に対しては E218 を送出します。 Map、Binary、または入れ子の List の値に対しては E100 を送出します。
optionsdialectを指定するオプションのマップ。 'whatwg'(デフォルト)は、各 List 要素についてキーを繰り返します。 'rack' は各要素に対して key[] を書き出し、キーに [ または ] が含まれている場合は E218 を送出します。認識されないオプションキーは E225 をスローします。認識されない dialect 値に対しては E225 を送出します。
マップをクエリ文字列としてエンコード

次の例では、マップをフォームエンコードされたクエリ文字列としてエンコードします。

Formula

wel
uri_encode_www_form({status: 'open', q: 'blue widget'})

出力

text
status=open&q=blue+widget

uri_decode_www_form ​

クエリ文字列をMapにデコードします。この関数は + をスペースにデコードし、空のペアをスキップし、= 記号のないペアを空の値としてデコードし、先頭の ? は最初のキーの一部としてそのまま保持します。

wel
uri_decode_www_form(text, options)
パラメーター説明
テキストデコードするクエリ文字列。不正なパーセントエンコーディングに対しては E226 を送出します。
optionsデコードを制御するオプションのマップ。
  • collect_duplicates: 繰り返しキーをリストに収集します。 collect_duplicates がない重複キーは E223 を送出します。
  • dialect: 'rack'はkey[]配列を読み取ります。 'whatwg' はキーを不透明なものとして扱います。無効な dialect 値は E225 を送出します。
未認識のオプションキーの場合は E225 が送出されます。
クエリ文字列をマップにデコード

次の例では、フォームエンコードされたクエリ文字列をマップにデコードします。

Formula

wel
uri_decode_www_form('status=open&q=blue+widget')

出力

wel
{status: "open", q: "blue widget"}

ユースケース: フィルターされたAPIリクエストを作成する ​

インバウンドデータの検索語句には、スペースや句読点が含まれることがあります。文字列を連結する代わりに、パラメーターをマップとしてエンコードして、各値をエスケープし、区切り文字を保持します。

入力

json
{
  "status": "open",
  "search": "blue widget & more"
}

Formula

wel
f"/api/v2/orders?{uri_encode_www_form({status: _.status, q: _.search})}"

出力

json
"/api/v2/orders?status=open&q=blue+widget+%26+more"

uri_encode_www_formは検索語句内の&を%26としてエンコードするため、パラメーター区切り文字と誤認されません。また、2つのパラメーターを実際に区切る&はそのまま残します。

最終更新日: