Drive 内の対象ファイルのアップロード URL を取得します。
Drive は現在 Beta 機能です。API 定義、レスポンス構造、動作は変更される可能性があります。ドキュメントの更新を確認し、本番環境で使用する前に互換性を検証してください。
POST /api/v1/forward/drives/upload-url
リクエストヘッダー
| Header | 必須 | 説明 |
|---|---|---|
| Authorization | はい | Bearer <PAT or SAT> |
| Content-Type | はい | application/json |
| Idempotency-Key | いいえ | 同じリクエストのリトライでは元の値を再利用します。冪等リトライを参照してください。 |
クエリパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| identity_id | string | はい | 現在の認証範囲内の Identity ID。必ず 1 回だけ指定します。Identity レベルの SAT は、紐付けられた Identity のみを選択できます。 |
リクエストボディのパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| path | string | はい | 対象ファイルの相対パス。ルートは指定できません。同じパスへのアップロードは既存の内容を上書きします。 |
| content_type | string | いいえ | ファイルの MIME タイプ。前後の空白除去後で最大 255 バイト、有効なメディアタイプで、制御文字を含まないこと。省略または空の場合、アップロードの Content-Type を制限しません。 |
パスのルール
projects/reportsなど、有効な UTF-8 の相対パスを使用します。/projects/reportsやC:/projects/reportsなどの絶対パスは使用できません。- ディレクトリは
/で区切ります。先頭・末尾・連続する/、バックスラッシュ、.および..のパス要素は使用できません。 - 先頭・末尾の空白、制御文字、
%（projects%2Freportsのようなエスケープ済み文字列を含む）は使用できません。
リクエスト例
レスポンス例
HTTP 200 OK
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
| url | string | 署名付き URL。 |
| method | string | 常に PUT。 |
| headers | object | 署名付き URL の使用時に必要なヘッダー。不要な場合は {}。 |
| expires_at | string | RFC 3339 形式の有効期限。発行後 15 分間有効です。 |
冪等リトライ
この API は任意で Idempotency-Key を受け付けます。リトライ時は認証範囲、Identity、キー、リクエストボディの元の内容を同一にしてください。再送レスポンスには Idempotency-Replayed: true が含まれます。署名付き URL を更新するにはヘッダーを省略するか新しい値を使用します。再送では有効期限は延長されません。
エラー
| HTTP | Code | 発生条件 |
|---|---|---|
| 400 | invalid_drive_path | 対象ファイルのパスまたは Identity 識別子の形式が無効です。 |
| 400 | invalid_content_type | MIME タイプが無効、255 バイト超過、または制御文字を含んでいます。 |
| 400 | — | リクエストボディが有効な JSON でない、フィールドの型が誤っている、または不明なフィールドを含んでいます。 |
| 400 | invalid_identity_id | identity_id が未指定、空、または複数回指定されています。 |
| 401 | — | 認証情報が未指定または無効です。Service Account Key は事前に SAT と交換してください。 |
| 403 | identity_mismatch | Identity レベルの SAT で別の Identity を選択しています。 |
| 404 | identity_not_found | 現在の認証範囲内に Identity が見つかりません。 |
| 409 | idempotency_key_reused | 同じキーが異なるリクエストボディに使用されています。 |
| 409 | idempotency_key_in_progress | 同じキーのリクエストを処理中です。リトライ間隔は Retry-After を参照してください。 |
| 413 | — | リクエストボディがサービスの制限を超えています。 |
| 500 | — | 内部サーバーエラー。 |
| 503 | drive_unavailable | Drive のストレージ、署名、または依存機能が一時的に利用できません。 |
| 503 | idempotency_unavailable | 冪等性ストレージが一時的に利用できません。 |
HTTP エラーレスポンス
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
| type | string | 常に error。 |
| request_id | string | リクエスト追跡 ID。利用可能な場合に返されます。 |
| error.type | string | エラーの分類。例：invalid_request_error、authentication_error、permission_error、not_found_error、conflict_error、api_error。 |
| error.code | string | 業務エラーコード。一部の共通エラーでは返されません。 |
| error.message | string | エラーの説明。 |
error オブジェクトのみが返され、リクエスト追跡 ID は error.request_id に格納されます。署名付き URL のストレージサービスエラーは別のレスポンス形式を使用します。
入口での認証エラーは、異なるレスポンス構造になる場合があります。