本文へ移動
Wagby11
マニュアルのグループを選ぶ

WAGBY11 MANUAL / 17

アップロードで登録・更新する

CSV・TSV・XLSXを使って複数行を登録・更新できます。入力する列と処理モードを指定し、ジョブの結果を確認できます。

最終更新日:

ダウンロードとアップロード更新の小目次へ

1. このページで伝える機能

CSV・TSV・XLSXを使って複数行を登録・更新できます。入力する列と処理モードを指定し、ジョブの結果を確認できます。

2. Wagby11で実現できること

2.1 画面での操作

在庫データ登録更新で、取り込む定義とファイル、処理モードを選びます。初期状態は検証のみです。

ファイルと処理モードを選ぶアップロード画面。
ファイルと処理モードを選ぶアップロード画面。

商品コードをキーに、既存行の更新と新しい行の登録を同じファイルで指示する設定です。検証結果を確認した後、反映するモードを選んで送信します。完了後は登録・更新件数と保存データを確認します。

全件一括反映で登録1件・更新1件が正常終了した結果。
全件一括反映で登録1件・更新1件が正常終了した結果。

この例では、S001の在庫数を10から12へ更新し、S003を新規登録しました。一覧には、正常行のみ反映の例で登録したS004も表示しています。保存後の検索一覧で、更新内容と追加された商品を確認できます。

反映後の在庫データ。S001の在庫数12と、新規登録されたS003・S004を確認できます。
反映後の在庫データ。S001の在庫数12と、新規登録されたS003・S004を確認できます。

アップロードの共通上限・待機時間・結果保持期間は、「環境」のアップロードの共通上限と結果保持を設定するを参照してください。

2.2 アップロード定義ごとに処理上限を設定する

対象モデルのfunctions[].uploads[]内で、各取り込みにlimitsを指定します。同じモデルに複数のアップロード定義がある場合も、定義ごとに上限を用意できます。

個別設定在庫取り込みの例
最大ファイル容量5,242,880バイト(5 MiB)
最大データ行数1000行
最大列数20列
収集する最大エラー数100件
処理の制限時間5分

この5項目はすべて必須です。共通上限との小さい方が適用されます。共通10万行・個別1000行の構成で、1000行のファイルは検証でき、1001行は受け付けられません。結果の保持期間・待機時間・同時実行数は共通設定です。

2.3 外部ファイル専用の入力形式を指定する

ダウンロードしたファイルの再取り込みだけでなく、外部システムが作るファイルも登録・更新に使えます。たとえば出力はUTF-8・日付は年/月/日、外部CSVはWindows-31J(CP932)・日付は8桁の年月日という場合、取り込み専用の定義を用意して入力形式を指定します。出力側の設定を変更する必要はありません。

対応するダウンロード定義を指定する方法と、入力形式を独立して決める方法を使い分けます。

方法入力形式の決め方
download_idを指定する対応するダウンロード定義のファイル種別、文字コード・BOM、参照の区切り、値の変換書式を引き継ぎます。項目別の変換書式は同じ英語識別名の列から引き継ぎます。
download_idを省略するinput_formatで受け付けるファイル種別、文字コード・BOM、参照キーの区切り・エスケープ、日付・数値・真偽値やnull・未変更トークンの表現を指定します。

文字コードとBOMは実際のファイルに合わせます。UTF-8またはWindows-31Jを指定でき、UTF-8のBOMを受け付ける場合は明示します。複数の保存形式を受け付ける場合は、次の「複数の文字コードを受け付ける」を参照してください。文字コードを厳密に検査する指定は検査の方針であり、それだけで入力ファイルの文字コードが決まるわけではありません。

外部CSVの見本をAIに示し、列名・順番・文字コード・日付などの表現を伝えます。入力形式を独立させても、列とヘッダの対応、空欄の扱い、権限、検証・反映方式、処理上限は別に設定します。ダウンロード定義を指定している場合も、ヘッダ行数や列名を自動的に一致させるものではありません。

2.4 複数の文字コードを受け付ける

同じアップロード定義で、UTF-8(BOMあり)とWindows-31J(BOMなし)のCSV・TSVを受け付けられます。ファイルの保存形式に合わせて、受け付ける文字コードとBOMの組み合わせを指定します。ダウンロードの出力形式はそのままに、取り込み側だけで設定できます。

受け付ける形式文字コードBOM
UTF-8のファイルUTF-8あり
Windows-31JのファイルWindows-31J(CP932)なし

この一覧はアップロード定義ごとに指定します。指定しなければ、対応するダウンロード定義、または取り込み専用の入力形式の文字コード・BOM条件を使います。列の対応、日付などの変換書式、権限、処理モードは既存の設定を使い、XLSXにはこの一覧を適用しません。

BOMなしのUTF-8とWindows-31Jを両方指定すると、英数字だけのファイルなどが両方の形式に一致することがあります。複数の形式に一致したファイルは受け付けません。上の例のように、BOMの有無で区別できる組み合わせを使うと運用しやすくなります。

2.5 文字コード・BOMの不一致に対処する

文字コードまたはBOMの不一致を検出すると、アップロード画面に「ファイルの文字コード(UTF-8 / Shift_JIS)またはBOMの有無が設定と一致しません」と、受け付け可能な形式を表示します。例えばUTF-8(BOMあり)だけを受け付ける定義に、BOMなしのUTF-8を送った場合は、BOM条件も確認します。

  1. 画面に表示された、受け付け可能な文字コードとBOM条件を確認します。
  2. ファイルを保存したソフトで保存形式を確認し、受け付け可能な形式で保存し直します。拡張子の変更だけでは文字コードは変わりません。
  3. 保存したファイルを送信し、検証結果を確認してから反映します。

ヘッダーやCSV構文の不一致は、文字コード・BOMの不一致とは区別します。ただし、別の文字コードでも読み取れるバイト列になる場合、文字コードの違いを確実には判定できません。エラーにならない場合も、見本ファイルの日本語の値を検証・反映結果で確認してください。

2.6 移行元の自動採番IDを維持する

既存データを移すときに、元の自動採番IDを保ったまま登録できます。参照先のIDや初期値に使うIDを変えずに取り込めるため、参照されるマスタから順に移行します。アップロード更新画面の「IDの取り込みモード」で、標準と移行用を切り替えます。自動採番主キーを持つモデルでは、同じアップロード定義で両方を選べます。

自動採番主キーの入力標準移行用
IDが空欄自動採番して新規登録エラー。元のIDを指定
IDあり・既存行あり指定IDの行を更新指定IDの行を更新
IDあり・既存行なしエラー指定IDを維持して新規登録
取り込み後の採番通常の自動採番最大IDを超え、現在の採番位置や開始値を下回らない位置へ同期
検証のみ保存・採番なし保存・採番同期なし

例えば、空のテーブルへID1000と1001を移行すると、そのIDのまま登録します。採番同期後の通常登録では1002以降を使います。既に採番位置が先へ進んでいれば、その位置を戻しません。登録・更新の権限や入力・業務上の検証は、移行用でも確認します。

  1. アップロード更新画面を開き、「IDの取り込みモード」で「移行用(元のIDを維持)」を選びます。元のIDと入力形式・列の対応を確認します。移行用では自動採番IDの空欄を受け付けません。
  2. 通常の登録・更新、別のサーバーや処理からの書き込みを停止します。
  3. 「検証のみ」で確認した後、依存するマスタから順に反映します。
  4. 反映結果と採番同期の成功を確認し、ほかのサーバーも再起動してから通常運用を再開します。通常の新規登録で移行済みIDより大きい値が採番されることを確認します。

採番同期に失敗した場合は、登録済みデータが取り消されたとは扱いません。ジョブの反映件数とエラーを確認し、通常の新規登録を再開せず、管理者へ採番位置の確認と再同期を依頼してください。ファイルを再送せず、採番同期だけをやり直すこともできます。正常行のみ反映、キャンセル、時間切れで一部が反映された場合も、確定したデータが対象になります。

「データ管理」のインポートはZIP形式です。CSV・TSV・XLSXは、このアップロード更新で取り込みます。

3. AIへの指示例

最小限の指示例

在庫ファイルを使って、複数の商品をまとめて登録・更新したいです。

AIは入力ファイルの列と形式、対象キー、検証・反映の流れを類推して補います。受け付ける形式と、まず検証してから反映したい意図を伝えます。

より詳細な指示例

全項目ダウンロードと同じ形式を取り込む「在庫データ登録更新」を作ってください。商品コードをキー、残りの列を更新可能とします。検証のみを既定にし、全件反映・正常行だけ反映も選べるようにしてください。メニューからアップロード画面を開けるようにします。
既存のモデル・データ・権限を保持し、Wagby11のguide・referenceを確認してください。メニューと一般利用者向け操作マニュアルを更新し、生成・ビルド後に画面・出力ファイル・保存結果を確認してください。

個別上限の最小限の指示例

在庫データの取り込みは、1ファイル1000行までにしてください。

AIは対象の取り込み定義、共通上限、容量・列数・エラー数・時間の値を既存の設計から類推します。どのモデルのどの取り込みかを伝えます。この短い指示だけで、次の詳細例と同じ上限一式になるとは限りません。

個別上限のより詳細な指示例

TransferStockのアップロード定義full(在庫データ登録更新)のlimitsを、最大5 MiB、1000データ行、20列、エラー収集100件、処理5分としてください。5項目をすべて指定してください。
既存の共通設定、列・入力形式・権限・処理モードを保持し、共通上限と個別上限の小さい方が適用されることを確認してください。共通の行数上限が1000以上であることも確認してください。
定義を検証・生成・ビルドして起動し、1000行をVALIDATE_ONLYで検証、1001行を拒否することを確認してください。検証用データを業務データへ反映しないでください。結果保持・待機・同時数の共通設定は変更しないでください。

外部ファイル用の最小限の指示例

外部システムの在庫CSVを取り込めるようにしてください。既存のダウンロード形式と異なるので、添付した見本に合わせてください。

AIは見本と既存モデルから列の対応、主キー、日付などの入力書式を類推します。文字コードや空欄の意味など、見本だけでは判別できない条件も伝えます。最小限の指示だけで次の詳細例と同じ仕様になるとは限りません。

外部ファイル用のより詳細な指示例

在庫へ「外部在庫CSV取り込み」を追加してください。既存のダウンロード形式は変更せず、download_idを省略してinput_formatを定義します。
入力はWindows-31J(CP932)、BOMなし、ヘッダ1行のCSVだけを受け付けます。列は商品コード・適用日・在庫数の順で、商品コードをキー、残りを更新対象にします。日付は20261031のような8桁の年月日、数値は桁区切りなしとします。
nullは\N、更新時に現在値を残す指定は\KEEP、エスケープはバックスラッシュとし、通常の空欄はnullへ変換しません。参照を使う場合の複合キー区切りは$SEP$とします。
ロケールは日本語、タイムゾーンはAsia/Tokyo、書式は厳密に検査します。input_format.value_codecの入力・出力書式は一致させてください。検証のみを既定とし、メニューから開けるようにします。
Wagby11のguide・referenceを確認し、権限・ファイル検証・処理上限などの必須設定も用意してください。既存データを保持し、生成・ビルド後に見本ファイルの検証結果と反映結果を確認してください。

複数の文字コードを受け付ける最小限の指示例

在庫のCSV取り込みで、UTF-8(BOMあり)とWindows-31J(BOMなし)の両方を受け付けてください。

AIは対象モデルと既存の取り込み定義から編集箇所を類推します。対象の定義名や、CSV・TSVのどちらを使うかも伝えると明確になります。短い指示だけで、次の詳細例の確認項目まですべて補われるとは限りません。

複数の文字コードを受け付けるより詳細な指示例

在庫データ登録更新の既存アップロード定義fullで、UTF-8(BOMあり)とWindows-31J(CP932、BOMなし)のCSVを受け付けてください。Wagby11のguide・referenceを確認し、取り込み側で受け付ける文字コードとBOMの組み合わせを設定してください。
ダウンロードの出力形式、入力する列、日付などの変換書式、権限、処理モード、処理上限は維持してください。
定義を検証・生成・ビルドして起動し、日本語の値を含む両形式のファイルを検証のみで確認してください。BOMや文字コードが設定と一致しない場合は、画面に受け付け可能な形式が案内されることも確認してください。

元のIDを維持する最小限の指示例

移行元のIDを変えずに、在庫データをCSVから取り込めるようにしてください。

AIは対象モデルの主キーや参照関係から、利用するアップロード定義と取り込み順を類推します。対象の定義名、文字コード、既存IDがある場合の更新可否も伝えると、実行範囲が明確になります。短い指示だけで、次の詳細例と同じ確認手順になるとは限りません。

元のIDを維持するより詳細な指示例

autoid主キーを持つ在庫モデルのアップロード更新で、画面の「IDの取り込みモード」を「移行用(元のIDを維持)」にして取り込む手順を用意してください。元のIDを必須とし、同じIDの行があれば更新、なければそのIDで新規登録します。画面を開いたときの初期値は標準にしてください。
ファイルの文字コードとBOM、列の対応を見本で確認し、既存の権限・検証・計算・処理上限を維持します。最初は検証のみで確認します。
移行中は通常の登録・更新と別プロセスからの書き込みを停止し、参照先のマスタから順に取り込みます。反映後は採番同期の成功を確認してください。ほかのサーバーも再起動してから通常の新規登録を確認し、移行済みIDと重複しないことを確認します。
同期に失敗した場合は反映済み件数を報告し、通常登録を再開せず、採番同期だけの再実行方法を案内してください。

4. 編集されるAppSchemaの例

以下は関連する定義の抜粋です。

uploads:
  - id: full
    name: 在庫データ登録更新
    download_id: full
    client_type: interactive
    operation: UPSERT
    permissions: { roles: [G_ADMIN] }
    processing_modes:
      allowed: [ALL_OR_NOTHING, VALID_ROWS, VALIDATE_ONLY]
      default: VALIDATE_ONLY
    columns:
      - { name_en: productCode, upload: key }
      - { name_en: productName, upload: writable }
      - { name_en: effectiveDate, upload: writable }
      - { name_en: quantity, upload: writable }
      - { name_en: unitPrice, upload: writable }
      - { name_en: active, upload: writable }
      - { name_en: notes, upload: writable }

抜粋のほか、冪等性・ファイル検証・文字コード検査・上限などの設定も必要です。download_idは対応する出力の値表現を継承します。アップロード画面はメニューへの追加も必要です。

取り込みごとの上限を追加する

対象モデルのfunctions[].uploads[]の既存要素へ追加する抜粋です。ほかの必須設定や列定義は維持します。

functions:
  - description: 在庫データ検索
    uploads:
      - id: full
        # 入力形式・権限・列など、ほかの設定は省略
        limits:
          max_file_size_bytes: 5242880
          max_rows: 1000
          max_columns: 20
          max_errors: 100
          max_processing_time: PT5M

共通上限だけを指定してlimitsを省略する構成にはできません。

ダウンロードから独立した入力形式

外部在庫CSV向けの入力形式と列定義の抜粋です。単独で生成できる定義ではありません。権限・冪等性・処理モード・ファイル検証・テキスト検証・複数参照の処理方針・上限などの必須設定は別途必要です。

uploads:
  - id: external_stock
    name: 外部在庫CSV取り込み
    # download_idは指定しない
    client_type: interactive
    operation: UPSERT
    header: { rows: 1, required: true, exact: true, allow_reorder: false }
    empty_as_null: false
    input_format:
      file_types: { allowed: [csv] }
      text: { charset: Windows-31J, utf8_bom: false }
      reference: { composite_key_separator: '$SEP$', escape: backslash }
      value_codec:
        locale: ja-JP
        timezone: Asia/Tokyo
        tokens: { null: '\N', unchanged: '\KEEP', escape: backslash }
        output:
          text:
            date: uuuuMMdd
            datetime: uuuuMMdd HH:mm:ss
            decimal: plain
            boolean: { true_value: 'true', false_value: 'false' }
        input:
          text:
            date: uuuuMMdd
            datetime: uuuuMMdd HH:mm:ss
            decimal: plain
            boolean: { true_value: 'true', false_value: 'false' }
            parsing: strict
    columns:
      - { name_en: productCode, upload: key }
      - { name_en: effectiveDate, upload: writable }
      - { name_en: quantity, upload: writable }

現在の定義の検証仕様では、アップロード専用でもvalue_codecのoutput.textとinput.textを同じ書式で指定します。対象列に日時や真偽値がなくても、これらの書式を含めます。ここでのoutput.textは入力形式の定義の一部であり、ダウンロード機能を追加する指定ではありません。

アップロード直下のtext.charset: strictとtext.bom: strictは検証方針です。上の例では、実際の文字コードとBOMをinput_format.textで指定します。複数の組み合わせを受け付ける場合は、次のtext.accepted_encodingsを使います。入力形式の指定を省略しても、必須設定全体が自動的に補完されるわけではありません。

受け付ける文字コードとBOMを複数指定する

既存のuploads[]の要素に設定するtextの抜粋です。アップロード直下のtext.accepted_encodingsへ追加します。input_format.textやダウンロード側のtextには追加しません。列・権限・処理上限など、ほかの設定は維持します。

text:
  charset: strict
  bom: strict
  syntax: strict
  quote_style: flexible
  line_separators: [CRLF, LF]
  accepted_encodings:
    - charset: UTF-8
      utf8_bom: true
    - charset: Windows-31J
      utf8_bom: false

download_idの有無にかかわらず指定できます。一覧を指定すると、CSV・TSVの文字コードとBOM条件を一覧の組み合わせに置き換えます。未指定または空配列の場合は従来の条件を引き継ぎます。従来のTSVのBOM条件は「なし」です。

charsetはUTF-8またはWindows-31J、utf8_bomの省略時はfalseです。trueはUTF-8のみ指定でき、同じ組み合わせの重複は指定できません。text.charset: strictとtext.bom: strictは、引き続き厳密に検査する方針を表します。

IDの取り込みモードの初期値を設定する

自動採番主キーを持つモデルでは、追加設定なしで画面から標準・移行用を選べます。画面を開いたときの初期値を変えたい場合だけ、既存のアップロード定義へ次の設定を追加します。列・入力形式・権限・処理モード・上限などの必須設定は省略した抜粋です。

uploads:
  - id: full
    name: 在庫データ登録更新
    operation: UPSERT
    identity_mode: migration

identity_modeはstandard(省略時)またはmigrationです。この例では初期値が移行用になりますが、送信前に標準へ戻せます。migrationは自動採番主キーを持つモデルに指定します。Designerの「IDの取り込みモードの初期値」でも設定できます。自動採番主キーのないモデルでは標準のみを使用します。

REST APIで送信するときは、multipartのidentityModeにSTANDARDまたはMIGRATIONを指定します。省略時はアップロード定義の初期値を使います。ジョブ照会は受付時に保存したidentityModeを返します。

採番同期だけを再実行するAPIはPOST /api/entities/{entityId}/uploads/{uploadId}/synchronize-identityです。自動採番主キーを持つモデルのアップロード定義に対して、アップロードの実行権限とモデルの登録権限が必要です。成功時は204を返します。データの再取り込みや更新は行いません。

5. 参考資料

guide:アップロードで登録・更新する
designer/docs/appschema/markdown/guide/09-data-transfer/08-upload-update-overview.md
reference:ファイルアップロード一括更新
designer/docs/appschema/markdown/reference/12-file-upload.md