> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/api-integration/file-library-resumable-upload.md).

# ファイルライブラリの再開可能アップロード API

分割アップロードセッションでファイルをファイルライブラリに書き込み、サーバーのオフセットで転送を再開し、SHA-256 で完全性を検証し、完了とキャンセルを処理します。

連携側で大きなファイルをアップロードする場合や、ネットワーク切断後に転送を再開する場合は、ファイルライブラリのアップロードセッションを利用できます。このフローは **1 byte から 500 MiB（524,288,000 bytes）** までのファイルを受け付けます。通常の直接アップロードとバージョンの直接アップロードの上限は引き続き 10 MiB のままで、本ページの 500 MiB の上限は適用されません。

たとえば、ドキュメント連携サービスが大きな研修資料をファイルライブラリに保存する場合を考えます。サービスはまずファイル全体の SHA-256 を計算し、セッションを作成してチャンクごとに送信します。途中で切断された場合はサーバーから進捗を読み戻し、返されたオフセットから再開して、最後にサーバーへ検証とファイルの完了を依頼します。

## 前提条件とパス <a href="#prerequisites-and-path" id="prerequisites-and-path"></a>

`Authorization: Api-Key <API キー>` で認証してください。キーの取得方法は[クイックスタート](https://docs.maiagent.ai/tech/ja/api-integration/quickstart.md)を参照してください。

組織でファイルライブラリが有効になっていること、呼び出し元が認証済みメンバーでファイルライブラリの権限を持ち、対象スペースへ書き込めることが必要です。対象はフォルダーである必要があり、スペースのルートへ直接アップロードすることはできません。外部ソース同期フォルダーとそのサブフォルダーは読み取り専用の対象であり、アップロードできません。

本ページでは次のパスを基準とし、以下では `{base}` と表記します。

```
/api/v1/file-library/folders/{folderId}/upload-sessions/
```

## セッションの作成または再取得 <a href="#create-session" id="create-session"></a>

`{base}` に JSON で `POST` を送信します。

| フィールド             | 必須  | 説明                                                         |
| ----------------- | --- | ---------------------------------------------------------- |
| `clientId`        | はい  | クライアントが生成する UUID。同じアップロードを再開する際は同じ値を使用します                  |
| `filename`        | はい  | ファイル名。ディレクトリパスを含めることはできず、拡張子はファイルライブラリで許可されている形式である必要があります |
| `sha256`          | はい  | ファイル全体の SHA-256。64 文字の小文字 16 進数                            |
| `size`            | はい  | ファイル全体のバイト数。空のファイルは受け付けません                                 |
| `contentType`     | いいえ | MIME タイプ。デフォルトは空文字列です                                      |
| `collisionPolicy` | いいえ | `ask`（デフォルト）、`keep_both`、`replace`                         |
| `replaceFileId`   | いいえ | `replace` を使用する際に置き換えるファイル                                 |

許可される拡張子は `pdf`、`doc`、`docx`、`ppt`、`pptx`、`xls`、`xlsx`、`csv`、`txt`、`md`、`json`、`html`、`png`、`jpg`、`jpeg`、`gif`、`webp`、`mp3`、`wav`、`m4a`、`mp4`、`dxf` で、大文字・小文字は区別されません。拡張子がない場合や未対応の形式は拒否されます。

同じユーザー、同じフォルダー、同じ `clientId` の場合は既存のセッションが返されます。`filename`、`sha256`、`size`、`contentType` が元の値と異なる場合は拒否されます。作成も再取得も `201` を返します。

レスポンスには `id`、`folderId`、`filename`、`sha256`、`size`、`offset`、`chunkSize`、`completed`、`completedFileId` が含まれます。`offset` は次に送信すべきチャンクのバイトオフセットで、`chunkSize` は 2 MiB（2,097,152 bytes）です。

## 送信と再開 <a href="#send-and-resume" id="send-and-resume"></a>

1. `{base}{sessionId}/` に `multipart/form-data` で `PATCH` を送信し、非負整数の `offset` とバイナリのファイルフィールド `chunk` を指定します。
2. 各チャンクは 0 より大きく `chunkSize` 以下である必要があります。`chunkSize` より短くてよいのは最後のチャンクだけです。順番に送信してください。オフセットはサーバーの現在の `offset` と一致する必要があり、合計は宣言した `size` を超えてはいけません。
3. 成功するたびに `200` のセッションが返されます。返された `offset` で次のチャンクを決定します。直前のチャンクが届いたか不明な場合は、先に `{base}{sessionId}/` へ `GET` を送信して進捗を読み戻してください。

すでに受信済みのチャンクは再送できますが、オフセットは記録済みのチャンク境界上にあり、オフセット、サイズ、内容の SHA-256 がすべて元のチャンクと一致している必要があります。条件を満たす場合のみ既存の進捗が返されます。並列や順不同でのアップロードはしないでください。

各チャンクのハッシュはサーバーが計算するため、PATCH でチャンクのハッシュを別途送る必要はありません。セッションは作成から 24 時間有効で、存在しない場合、本人のものでない場合、または期限切れの場合は `404` を返します。

## 完了とキャンセル <a href="#complete-and-cancel" id="complete-and-cancel"></a>

すべてのバイトを送信し終えたら、`{base}{sessionId}/complete/` に `POST` を送信します。同名ファイルの処理が不要な場合は、空の JSON オブジェクト `{}` を使用できます。サーバーは各チャンクのオフセット、サイズ、SHA-256 を再確認し、続いてファイル全体の SHA-256 と照合します。検証に通った場合のみ完了し、成功すると `201` とファイルオブジェクトを返します。

完了時にも同名の競合、容量、バージョンが再確認されるため、すべてのチャンクを送信し終えてもファイルが完了したとは限りません。

* `ask` は同名ファイルがある場合に `409 duplicate_name` を返し、`existingFileId` と `currentVersionNumber` が付きます。
* `keep_both` はファイル名に数字の接尾辞を付けます。
* `replace` には `replaceFileId` の指定が必要です。完了時には `expectedVersionNumber` も指定し、他の人が直前に更新したバージョンを上書きしないようにします。完了リクエストでは `collisionPolicy: "replace"` と `replaceFileId` を再度指定する必要があり、`expectedVersionNumber` には直近に読み取った値、または `409` レスポンスの `currentVersionNumber` を指定します。バージョンが存在する場合は正の整数、まだバージョンがない場合は明示的に JSON の `null` を指定してください。省略したり、バージョン番号を推測したりしてはいけません。

{% hint style="warning" %}
セッション作成時の同名ポリシーはセッションに保存されません。`keep_both` または `replace` を選択した場合は、完了リクエストでもそのポリシーと必要なフィールドを再度送信する必要があります。指定しない場合は再び `ask` が使用されます。
{% endhint %}

完了済みのセッションに再度 complete を送信すると、最初に完了したファイルが返され、2 つ目のファイルは作成されません。元のファイルが削除されている場合や現在表示できない場合は `404` を返します。

未完了のセッションをキャンセルするには、`{base}{sessionId}/` に `DELETE` を送信します。成功すると `204` を返します。完了後はキャンセルできません。完了済みのファイルを扱う場合は、ファイル管理のフローを使用してください。

{% hint style="info" %}
このフローはファイルライブラリへの書き込みであり、会話の添付ファイルのアップロードではありません。会話内の Agent にファイルを渡す場合は、[会話添付ファイルのアップロードとダウンロード](https://docs.maiagent.ai/tech/ja/api-integration/endpoint-behaviors/conversation-attachments.md)を参照してください。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/ja/api-integration/file-library-resumable-upload.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
