バイナリ関数
Binaryは、生バイト用のWEL型です。ファイルコンテンツを処理する場合、暗号化関数がダイジェストを返す場合、システムがJSONフィールド内でbase64エンコードされたデータを送信する場合に表示されます。
バイナリ関数は、バイトをJSONで安全なテキスト表現に変換します。また、生バイトを測定およびスライスします。
バイトはテキストではありません
BinaryとStringは異なる型であり、WELはそれらを暗黙的に変換しません。 String()はBinaryを完全に拒否します。
decode_stringを使用して、バイトを読み取り可能なテキストに変換するには、そのバイトの文字エンコーディングを指定します。 encode_base64またはencode_hex_stringを使用して、バイトをJSONフィールドに安全に格納できるテキストに変換します。
Base64
Base64は、生バイトをJSONフィールドまたはURLに埋め込むための標準的な方法です。
encode_base64
バイトまたは ASCII 文字列を base64 文字列としてエンコードします。
encode_base64(binary, mode)| パラメーター | 説明 |
|---|---|
| バイナリ | エンコードするバイトまたは ASCII 文字列。非 ASCII 文字列の場合は E100 を送出します。 |
| mode | 任意。 URLセーフな出力には'url'、パディングを省略するには'no_pad'、その両方には'url_no_pad'。認識されない mode の場合は E225 を送出します。 |
バイトをbase64としてエンコード
次の例では、バイトをbase64文字列としてエンコードします:
Formula
encode_base64(Binary('ABC'))出力
QUJDURL内のトークンにはURLモードを使用
標準のbase64には+と/が含まれ、URLやファイル名で特別な意味を持つ場合があります。 'url'モードでは、それらが-と_に置き換えられます。クエリ文字列またはURLパス内のトークンには、このモードを使用します。
decode_base64
base64文字列をバイトにデコードします。パディングが欠落していても許容します。
decode_base64(text, mode)| パラメーター | 説明 |
|---|---|
| テキスト | デコードするbase64文字列。バイナリ文字列の場合は E100 を送出します。無効な文字または不正なパディングの場合は E226 を送出します。 |
| mode | 任意。 URLセーフな入力には'url'。 |
base64文字列をバイトにデコード
次の例では、base64文字列をバイトにデコードします:
Formula
decode_base64('QUJD')出力
0x"414243"16進数
Hexは各バイトを2文字で表し、サイズと引き換えに人間が読みやすくします。
encode_hex_string
バイトまたは ASCII 文字列を、1 バイト当たり 2 文字の hexadecimal 文字列に変換します。
Hexはbase64より多くの領域を必要としますが、人間が読みやすい表現を提供します。チェックサムとダイジェストでは、一般的にこの形式が使用されます。
encode_hex_string(binary, mode)| パラメーター | 説明 |
|---|---|
| バイナリ | エンコードするバイトまたは ASCII 文字列。非 ASCII 文字列の場合は E100 を送出します。空のバイトは空文字列としてエンコードされます。 |
| mode | 任意。大文字出力には'upper'。認識されない mode の場合は E225 を送出します。 |
バイトをhex文字列としてエンコード
次の例では、バイトを16進数文字列としてエンコードします:
Formula
encode_hex_string(Binary('ABC'))出力
414243decode_hex_string
16進数文字列をバイトに変換します。モードが'strict'でない限り、先頭の0xまたは末尾のhを取り除きます。
decode_hex_string(text, mode)| パラメーター | 説明 |
|---|---|
| テキスト | デコードするhex文字列。文字列の長さが奇数の場合、または hex 以外の文字が含まれる場合は E226 を送出します。空文字列は空のバイナリとしてデコードされます。 |
| mode | 任意。プレフィックスとサフィックスを拒否するには'strict'。認識されない mode の場合は E225 を送出します。 |
hex文字列をバイトにデコード
次の例では、16進数文字列をバイトにデコードします:
Formula
decode_hex_string('414243')出力
0x"414243"Quoted-printable
Quoted-printableは、メール本文などの主にASCIIテキスト向けのMIMEエンコーディングです。
encode_quoted_printable
RFC 2045で定義されているMIME quoted-printableとして、76列のソフト改行を使用してバイトをエンコードします。
メール本文では、コンテンツの大部分がASCIIで、コンパクトさよりも読みやすさが重要な場合にquoted-printableを使用します。
encode_quoted_printable(binary)| パラメーター | 説明 |
|---|---|
| バイナリ | エンコードするバイト。 Binary 以外の入力は E100 を送出します。 |
バイトをquoted-printableとしてエンコード
次の例では、等号を含むバイトをquoted-printableとしてエンコードします:
Formula
encode_quoted_printable(Binary('a=b'))出力
a=3Dbdecode_quoted_printable
MIME quoted-printableテキストをバイトにデコードします。
decode_quoted_printable(text)| パラメーター | 説明 |
|---|---|
| テキスト | デコードするquoted-printable文字列。不正な形式のデータは E226 を送出します。 |
quoted-printable文字列をバイトにデコード
次の例では、quoted-printable文字列をバイトに戻すデコードを行います:
Formula
decode_quoted_printable('a=3Db')出力
0x"613D62"測定とスライス
次の関数は、テキストとして解釈せずに、生バイト範囲を直接測定および抽出します:
byte_length
バイナリまたは ASCII 文字列に含まれるバイト数を返します。
byte_lengthは文字数ではなく、バイト数を返します。 lengthはテキスト内のコードポイントをカウントし、grapheme_lengthは代わりにユーザーが認識する文字(書記素クラスタ)をカウントします。 length と grapheme_length は、ASCII 以外の文字に対しては異なる場合があります。 byte_length は、三つ目のカウントを返す代わりに、非 ASCII テキストに対しては E100 を送出します。
byte_length(binary)| パラメーター | 説明 |
|---|---|
| バイナリ | 計測するバイナリまたは ASCII 文字列。非 ASCII 文字列の場合は E100 を送出します。非 ASCII 文字列をまず Binary にエンコードするには、encode_string を参照してください。 |
文字列のバイト長を測定
次の例では、ASCII文字列のバイト長を測定します:
Formula
byte_length(Binary('ABC'))出力
3byte_slice
オフセットと長さを指定して、バイナリまたは ASCII 文字列から連続したバイト列を抽出します。
byte_slice(binary, offset, length)| パラメーター | 説明 |
|---|---|
| バイナリ | スライスするバイトまたは ASCII 文字列。非 ASCII 文字列の場合は E100 を送出します。 |
| offset | ゼロベースの開始バイト。 offset がバイト列の末尾を越えている場合は E201 を送出します。負の offset の場合は E211 を送出します。 |
| length | 取得するバイト数。負の length の場合は E211 を送出します。 |
バイト範囲を抽出
次の例では、オフセット1から始まる3バイトを抽出します:
Formula
byte_slice(Binary('ABCDEF'), 1, 3)出力
0x"424344"バイトのスライスにより文字が分割される可能性があります
非ASCII文字は、UTF-8で複数のバイトを占有する場合があります。バイトスライスにより、これらの文字の1つが分割され、無効なバイトシーケンスが生成される可能性があります。
データがテキストの場合は、substringまたはgrapheme_substringを使用してテキストとしてスライスします。
ユースケース: ファイルを添付してチェックサムを記録
宛先は、JSONフィールド内のbase64エンコードされたファイルコンテンツと、16進数形式のSHA-256チェックサムを想定しています。バイナリ関数を使用してファイルをエンコードし、チェックサムを計算します:
入力
{
"filename": "note.txt",
"content": "ABC"
}Formula
let bytes = Binary(_.content)
do {
filename: _.filename,
size_bytes: byte_length(bytes),
content_base64: encode_base64(bytes),
sha256: hex_sha256(bytes)
}出力
{
"filename": "note.txt",
"size_bytes": 3,
"content_base64": "QUJD",
"sha256": "b5d4045c3f466fa91fe2cc6abe79232a1a57cdf104f7a26e716e0a1e2789df78"
}let … doはコンテンツを一度だけバイトに変換し、3つの派生フィールドはすべて同じ値を読み取ります。
関連情報
- エンコーディング関数: 名前付き文字エンコーディングを使用してバイトをテキストに変換します。
- 暗号化関数:
Binaryを返すダイジェストとHMAC値を生成します。 - ランダム関数: ソルト用に
random_bytesを生成します。 - データ型:
Binary型の詳細情報。
最終更新日: