AIものさし

Google Sheets APIで文字列が日付・数値・数式に変わるときRAWとUSER_ENTEREDを選ぶ

Google Sheets APIで値を書き込むとき、文字列が日付・数値・数式として解釈されて困ったら、まず使っている書き込みAPIを確認します。

AIものさし編集部

Google Sheets APIで値を書き込むとき、文字列が日付・数値・数式として解釈されて困ったら、まず使っている書き込みAPIを確認します。values系APIでは、文字列をそのまま保存したいならValueInputOptionのRAW、シートの入力欄へ人が打つように解釈させたいならUSER_ENTEREDを選びます。

ただし、どちらかを常に使えば安全という話ではありません。数式を意図して入力する列はUSER_ENTEREDが必要になる場合があり、郵便番号や商品コードのように見た目が数字でも識別子として扱う値は、数値化させない設計が必要です。列ごとの期待型を先に決め、書き込み後に実際の値を読み戻すのが基本です。

目次

先に決めるのはAPI名ではなく列の型

取り込みデータを見てから値の意味を推測するのではなく、列の契約を先に決めます。

表は横にスクロールできます

列の目的例保存したい型書き込み方の基本
識別子00127、A-0081、顧客番号文字列数字に見えても識別子として保持する。values APIなら文字列をRAWで送る
日付として計算する日2026-10-15日付値シートのロケールに応じた解析を使うか、数値の日付表現と表示形式を明示する
人が読める日付文字列受付日: 2026-10-15文字列日付値へ変換せず、そのまま保持する
金額・数量1250、3.5数値数値として送る。通貨・桁区切りはセルの表示形式で指定する
利用者が入力した式=SUM(B2:B9)数式式として解釈させる列に限り、式を入力する。自由入力文字を式として扱わない
コメント・説明文001件、=ではじまる文文字列内容を数式・数値・日付へ変換させない

この表は「すべての値を文字列にする」指示ではありません。日付計算、合計、並べ替えなどを行う列は、文字列ではなく日付値や数値が必要です。逆に、先頭ゼロを含むコードや電話番号を数値にすると、表示や値の意味が変わることがあります。見た目が数字かどうかではなく、後続処理で何をしたいかで型を決めます。

RAWとUSER_ENTEREDの違い

Google Sheets APIのvalues系書き込みには、入力値の解釈方法を指定するValueInputOptionがあります。

  • RAW：値を解析せず、そのまま保存します。文字列として送った値をシートの画面入力と同じルールで日付・数値・数式へ変換しません。

  • USER_ENTERED：Sheetsの画面に入力したときのように値を解析します。文字列が日付、数値、数式などとして解釈される場合があります。具体的な解釈はシートの入力規則やロケールなどの設定に影響されます。

たとえば、values APIへ文字列の00127を送り、USER_ENTEREDを指定すると、識別子として保持したい値が数値として扱われる可能性があります。RAWなら文字列のまま保存できます。一方、文字列の=SUM(B2:B9)をUSER_ENTEREDで送れば数式として扱われ得ます。これは式を設定したい列には便利ですが、外部データの任意文字列に使うと、意図しない数式化を招くことがあります。

RAWは数値や日付の表示形式を決める機能ではありません。RAWで日付文字列を保存すれば、日付計算用の値ではなく文字列になる可能性があります。日付として計算したい列では、ISO形式の文字列が正しく見えるかだけで判断せず、セルの実値が日付値として格納されたかを確認します。必要なら、日付値と表示形式を別々に指定します。

まずvalues系APIとbatchUpdateを見分ける

Sheets APIには似た名前の書き込み経路がありますが、設定方法を混同しないでください。

  1. spreadsheets.values.update、values.append、values.batchUpdateなどのvalues系メソッドは、ValueInputOptionを使って入力値の解析方法を指定します。

  2. spreadsheets.batchUpdateのupdateCellsなどは、セルのuserEnteredValueに型を持つ値を指定します。たとえば、stringValue、numberValue、formulaValueを明示します。この方法にValueInputOptionを付けるのではありません。

  3. 値とセルの数値表示形式は別の情報です。日付シリアル値を日付として表示したい場合などは、値の型とセル形式を両方確認します。

方法を混ぜると、正しいオプションを指定したつもりでも実際のリクエストでは無効だったり、型を明示せず解析に任せたりします。まず実装が呼び出すAPI methodとpayloadをログまたはコードで確認し、使っていない書き込み方法の設定を調べ続けないようにします。

事故を起こしにくい書き込み手順

1. 入力列ごとに期待型を決める

取り込み仕様に、列名・用途・期待型・許容例・変換してはいけない例を記録します。たとえば「郵便番号」は文字列、「請求金額」は数値、「処理日」は日付、「備考」は文字列とします。入力ファイルのセル表示ではなく、システム間で共有する列契約を基準にします。

2. 書き込みAPIと値のJSON型を確認する

values系APIを使う場合、JSONの数値と文字列は別です。文字列の値が必要なら文字列で送ってRAWを選び、数値として使う値は数値型で送ります。すべてを文字列へ連結してからUSER_ENTEREDへ渡す設計は、混在列や先頭ゼロで事故が起きやすくなります。

batchUpdateのupdateCellsを使う場合は、たとえばコードはstringValue、件数はnumberValue、管理者が設定した式はformulaValueのように、セルごとの意味に沿って明示します。利用者から取り込んだ文字列をformulaValueへ置き換えないでください。

3. 小さなテスト行で変換を確認する

本番範囲を更新する前に、使い捨てのテスト用シートまたは隔離した範囲で、少なくとも次の値を試します。

表は横にスクロールできます

テスト入力期待する結果読み戻しで見ること
00127文字列userEnteredValueがstringValueで、先頭ゼロが残る
2026-10-15要件に応じ文字列または日付期待型とeffectiveValue、表示形式が一致する
03/04/2026国や設定により曖昧になり得る日付として使うなら年月日を一意に指定できる契約にする
=1+2説明文なら文字列、式列なら数式意図しないeffectiveValueやformulaValueが生じていない
1,250.50数値または文字列ロケール・小数点・桁区切りで値が変わっていない

テスト値が画面上で期待どおりに見えるだけでは十分ではありません。識別子の先頭ゼロは表示形式で一時的に補えることがありますし、数式は結果の数字だけだと入力文字列と区別できないことがあります。可能ならuserEnteredValue、effectiveValue、formattedValue、数値形式を読み戻し、どの層で変換されたか見ます。

4. 変換された列だけでなく、後続処理を確認する

日付が日付値になったことで、CSV再出力時にタイムゾーンや日付書式が変わることがあります。識別子を文字列へ保った場合、数値比較や合計ができなくなります。数値の桁区切りは表示だけに影響する場合と、入力時の解析そのものに影響する場合があります。

そのため、書き込みテストでは「値が保存されたか」に加えて、並べ替え、フィルタ、数式参照、CSV再出力など実際の利用工程を小さく試します。セルの見た目だけでは、後続処理に必要な型かどうか判断できません。

5. 本番範囲へ反映する前に差分を保存する

既存行を更新する場合、対象範囲・件数・元の値を記録し、差分を確認できる状態にします。最初は少数の代表行で反映し、readback後に件数を広げます。想定外の型変換を検出した場合は、続行せず、対象範囲と戻し方を確認します。データを大量に上書きした後で修正方法を考えるのは遅いため、復元用の入力元と変換前データを保持します。

目的別の選択例

顧客コードを取り込む

入力値00127を顧客コードとして保存し、表示・検索・突合にも先頭ゼロを必要とするなら、文字列として保持します。values系APIなら、JSON文字列をRAWで書く方法が基本です。数値127をセルへ書いてから表示形式で5桁に整えると、画面上は00127でも、実値は数値127です。他システムと突合する列では、この違いが問題になることがあります。

ユーザー入力を日付として認識させる

人が入力した「2026-10-15」をSheetsの入力欄と同じように日付として処理させたい場合は、USER_ENTEREDが候補になります。ただし、入力書式が複数ある、月日順が曖昧、シートごとにロケールが違う、といった場合は予測可能な結果になりません。入力形式を固定するか、アプリ側で解析・検証して日付値を作り、書き込み後の実値と表示形式を確認します。

数式を設定する

アプリケーションが管理する式を特定の列へ設定するときは、式であることを明示的に区別します。values系APIでUSER_ENTEREDを使う場合でも、式を書き込む列を限定し、利用者由来のコメントやCSVセルと混ぜません。updateCellsならformulaValueで式として指定し、stringValueで説明文として保存する値と分けられます。数式列を上書きする処理では、式を消していないか、参照範囲が正しいかも読み戻して検査します。

数字と文字が混ざる列

注文番号のように「12345」と「A-12345」が混ざる列は、集計用の数値列と識別用の文字列列に分けられないか検討します。一つの列に複数の意味を持たせると、ソート・集計・比較が難しくなります。列を分けられない場合は、その列の保存型を文字列に固定し、数値計算が必要な値を別項目にします。

よくある誤解

「RAWならセルの表示も元データと同じになる」とは限りません。RAWはvalues APIが値を解析するかどうかの指定で、文字色・日付表示・小数点桁数などを設定するものではありません。表示はセルのnumber format等にも左右されます。

「USER_ENTEREDなら正確な日付になる」とも限りません。画面入力と同様の解析に任せるため、曖昧な文字列や設定差に影響されます。入力値を正規化し、期待する日付形式を固定してから使います。

「数式っぽい文字列は全部式にする」は避けます。外部から来る文字列に先頭の等号が含まれても、それが利用者の文章なら、数式として実行させる理由はありません。式を許可する列と任意テキスト列を分離し、許可する式の出所を限定します。

実装前のチェックリスト

  • 書き込みに使うAPI methodを確認した。

  • 列ごとに文字列・数値・日付・数式の期待型を決めた。

  • values系APIならRAW / USER_ENTEREDを明示した。

  • updateCellsならstringValue / numberValue / formulaValueを意味に合わせて使った。

  • 先頭ゼロ、日付、曖昧な日付、数式文字列、ロケール依存の数値でテストした。

  • userEnteredValueとeffectiveValue、必要な表示形式を読み戻した。

  • 数式、並べ替え、CSV出力など後続処理を代表ケースで確認した。

  • 既存データのバックアップ、対象範囲、復元方法を用意した。

  • 小さな範囲で成功してから、本番データの更新件数を広げた。

結局、RAWとUSER_ENTEREDの選択だけでデータ整合性は決まりません。まず列の用途を決め、使っているAPIに合った型指定を行い、代表データを読み戻して確かめます。識別子は文字列、計算対象は数値や日付、管理された数式は式として、それぞれ意図した型を維持できた場合にだけ全件を書き込みます。

Sources

確認日：2026-10-15。Google Sheets APIの公式資料でRAW / USER_ENTEREDの挙動、値の読み書き、セルに型を明示する方法を確認しました。この記事では取り込み処理を実測したとは主張せず、公式仕様から導く検証手順として説明します。