協同編集を伴うSaaS文書にはunitId、ローカルやオフラインでの処理にはSnapshotを選ぶのが基本です。この記事では両経路の違い、変換バックエンドの確認点、実ファイルでの往復検証手順を整理します。
結論：協同保存ならunitId、オフライン処理ならSnapshotです
Univerのインポート・エクスポートは、サーバーに文書を保存して協同編集へつなぐならunitId、ローカルまたはオフラインで処理するならSnapshotを選びます。どちらの経路でも、導入前にファイル変換バックエンドと、実ファイルを使った書き出しまでの動作を確認してください。
この記事は、SaaSにUniver Sheetsを組み込むフロントエンド・全スタック開発者と、文書フローを設計する技術チーム向けです。特に、協同編集を提供しないファイル変換ツールを作る場合は、Snapshotが何を担い、何を担わないのかを確認できます。
まず利用シーンから経路を切り分けます
方式を選ぶ軸は「協同機能を使うか」だけではありません。文書をどこに保存するか、取り込んだファイルを誰がどのように読み込むか、変換バックエンドをどの環境で動かすかを合わせて判断します。
| 利用シーン | 選ぶ経路 | 得られるもの | 事前に確認すること |
|---|---|---|---|
| SaaS上で文書を保存し、協同編集につなぐ | unitId | インポート後に文書を識別して読み込むためのID | サーバー保存、文書アクセス、協同環境での読み込み、再エクスポート |
| ローカルやオフラインで読み込み・加工する | Snapshot | 取り込んだワークブックのデータ | Snapshotの受け渡し、変換バックエンド、出力ファイルの検証 |
| CSV・TSVを扱う | APIと用途に応じて選択 | 表形式データの取り込みまたは書き出し | 対象APIの形式対応、複数シートや書式を保持する必要があるか |
Univerのインポート・エクスポート公式ガイドはunitIdとSnapshotの使い分け、ファイル変換に関わる機能を説明しています。ワークブックとワークシートの構造はSheets APIの説明で確認できます。これらはAPIの機能説明であり、特定の業務ファイルが完全に往復できる保証ではありません。
unitId経路は保存から再出力までつなげます
協同編集が必要なSaaSでは、ファイルを取り込んだ後の文書をサーバー側で扱い、協同環境から再び読み込める構成にします。公式のサーバー導入ドキュメントと協同機能の説明を確認し、unitIdを単なるファイル変換結果ではなく、文書フロー上の識別子として扱ってください。
取り込み後にunitIdを受け取るだけでは、SaaS機能として完成したとはいえません。認証済み利用者がその文書にアクセスできるか、保存した内容を再度読み込めるか、編集後にファイルへ書き戻せるかを一連の流れで検証します。なお、公式クイックスタートの保存方法も確認し、アプリケーション独自の保存処理と混同しないようにします。
Snapshot経路は変換処理とデータ受け渡しを分けます
協同編集を使わず、ファイルを読み込んで加工し、別形式で出力する処理にはSnapshot経路が候補になります。取り込み結果はワークブックデータとして扱い、そのデータを基にエクスポートする設計です。したがって、unitIdを発行して協同文書として運用する必要がないツールでも利用できます。
ただし、Snapshotはファイル変換バックエンドの代替ではありません。Univerのサーバー側インポート・エクスポート構成を参照し、プロジェクトで採用するSDKとサーバーの組み合わせで必要な処理を確認してください。オフラインで使う場合も、入力ファイル、Snapshotの受け渡し、出力ファイルの各段階を個別に追えるログ設計が役立ちます。
CSV・TSVはワークブック全体の往復と分けて扱います
CSVやTSVは表形式の値を受け渡す形式であり、複数シートやワークブック全体の構造、セルの書式や画像をそのまま表す形式ではありません。そのため「CSVを読み書きできる」ことと、「複数シートや数式を含むExcelファイルを保持して往復できる」ことは別の要件です。Univerの対応形式とインポート・エクスポートの説明で、利用するAPIが必要な入力形式と出力形式をそれぞれ扱えるか確認してください。
CSV・TSVを使う場合は、必要な成果物が「表の値」なのか「元のワークブックを保ったファイル」なのかを先に定義します。後者が必要なら、CSV・TSVだけで要件を満たす前提にはしないでください。
実ファイルでインポートから再出力まで検証します
仕様確認の後は、対象SaaSで実際に扱うファイルを使い、次の項目を一連のテストとして記録します。公式の数式機能資料は機能の確認に使えますが、個々のファイルに対する計算結果や見た目は、採用環境での検証が必要です。
- [ ] unitId経路かSnapshot経路かを、保存場所と協同編集の要否から決める。
- [ ] 現行SDKとサーバーの構成を照合し、変換バックエンドが利用可能な状態か確認する。
- [ ] 実際の利用者ファイルを選び、複数シート、数式、画像、書式を含むケースを用意する。
- [ ] インポート前後でシート構成と数式を記録し、数式そのものと計算結果を分けて比較する。
- [ ] 保存またはSnapshotの受け渡し後にエクスポートし、出力ファイルを対象アプリケーションで開く。
- [ ] セルの書式、画像、シート構成、数式の変化を別々に記録し、許容できない差があれば対応形式や設定を再確認する。
- [ ] 失敗時に、入力形式、変換バックエンド、保存処理、出力形式のどこで止まったかを切り分ける。
この手順で確認するのは、一般的な互換性の保証ではなく、利用するファイル、SDK、サーバー構成の組み合わせが業務要件を満たすかどうかです。とくに数式では、式が残ることと期待する値が表示されることを別の合否項目にしてください。
よくある疑問を経路選定に反映します
XLSXを協同編集に使う場合
XLSXを取り込み、文書をサーバーに保存して協同編集へつなぐ場合は、unitId経路を優先して検討します。取り込み時にIDを受け取ることだけでなく、権限に沿った読み込み、編集内容の保存、再エクスポートまでを同じシナリオで確かめます。
Snapshotに協同編集は必要ありません
Snapshotは協同編集を行わないローカル処理やオフライン変換にも適しています。ワークブックデータを処理してファイルに書き出せますが、変換バックエンドの要否は別に確認が必要です。協同機能を使わないという理由だけで、サーバー側の変換設定を省略しないでください。
XLSXの書き出しに変換バックエンドが関わる理由
ファイルの入出力は、ワークブックデータとファイル形式を変換する処理を含みます。フロントエンドの導入だけで書き出しまで完結すると想定せず、公式のサーバー構成と対象APIの対応状況を確認してください。最後は実際のファイルを出力して、開けることと内容を検証します。
複数シートと数式は個別に比較します
複数シートの構成、数式、計算結果、画像、書式を別々の確認項目にします。取り込み前と再出力後のファイルを比較し、差が出た箇所と処理段階を記録してください。ドキュメントに記載された機能だけで、すべての実ファイルの保持を判断することはできません。
開発環境の制約が残る場合は検証方法も見直します
ローカル環境だけで変換を試すと、実行環境が担当者の端末に依存しやすく、共有や再現のためのセットアップも必要です。一般的なサーバー環境では変換サービスとSaaS本体の構成管理が増えるため、開発端末だけで本番相当の動作確認を続けるのも現実的ではありません。ファイル処理そのものはバックエンドで検証し、Mac上での開発・確認環境も一時的に必要な場合に限って分けて用意するのが適切です。
Macを使った確認が必要でも、常時稼働の重い処理や物理接続が必要な用途なら、レンタルより自社環境の運用が向く場合があります。一方、短期間の開発・表示確認用に端末を購入すると、初期調達や管理が残ります。開発端末の一時利用を検討する場合は、日本向けのMac利用プランで条件を確認できます。地域条件が異なるチームではシンガポール向けプランも比較し、Univerの変換バックエンド要件とは切り分けて選定してください。
実ファイルでの検証環境に、nuvcloudの専有Macを
専有のM4搭載Mac miniで、インポート・エクスポート後のファイルを実際に確認できます。
SSHとVNCに対応し、コマンド操作からmacOSのデスクトップ確認まで同じ環境で進められます。