単一チャンクのアップロード¶
POST /api/v1/rum_sourcemap/upload_part
概要¶
SourceMap ZIP の1バイトチャンクをアップロードします。
呼び出し前と使用手順¶
現在の Key には rum.rumCfgManage が必要です。現在の Key が属するワークスペースのみが対象です。appId は RUMアプリケーション簡易一覧 の content[].appId から取得し、SDK/エラーレコードの app_id と一致させます。データベース内部の UUID で代用することはできません。SourceMap はアプリケーション、環境 env、バージョン version によって正確に特定されます。大文字小文字/空白は識別子自体に属するため、収集レコードと完全に一致させる必要があります。env/version の省略または空文字列は空の環境/空のバージョンを表し、すべてに一致するワイルドカードではありません。現在のマネージドライフサイクルでは、それぞれ最大256文字が要求されます。
フローはSourceMap マルチパートアップロード関連API使用説明を参照し、あわせてマルチパートアップロード操作ドキュメントも参照できます。初期化→元のZIPの全チャンクをアップロード→チャンク一覧を確認→マージ→バージョン状態とファイルツリーを照会、の順に実行します。初期化/マージの成功は、ZIP が検証済みまたは解析可能であることを意味しません。processing/failed/blocked などの状態は引き続き確認する必要があります。
multipart/form-data を使用し、通常のフォームフィールドは uploadId/chunkIndex、ファイルフィールドは files です。JSON は送信しません。files は元のZIPの連続したバイト列で、1チャンクあたり最大10MiBです。.zip のファイル名を使用して宣言を満たしますが、サーバー側ではこの時点で各チャンク自体が独立して解凍可能なZIPであることは要求されません。元のZIPの順序に従って番号を付け、0から連続した番号を付けることを推奨します。複数の独立したZIPをチャンクとして扱わないでください。
同一の uploadId + 整数の chunkIndex はそのチャンクを置き換えます。再試行時はまったく同じバイト列のみを送信し、同一番号への同時上書きを避けてください。数値文字列は整数に変換され、00 と 0 は同じインデックスです。先頭のゼロで区別しないでください。マージ公開フェーズに入ると、それ以上チャンクを書き込むことは禁止され、409 になる可能性があります。セッションが期限切れ/置き換え済み/対象世代が書き込み不可の場合は 406 です。成功はそのチャンクが保存されたことだけを証明し、すべてのチャンク、完全なZIP、またはSourceMapの内容が有効であることを証明するものではありません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
フォームパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| chunkIndex | digitsString | Y | クライアントは非負の10進数文字列を使用する必要があります。現在の digitsString 型宣言の認識には互換性のギャップがあり、非数値を強制ブロックしていません。abc/1.2 などは int 変換時に 500 になる可能性があり、負数はマネージドロジックで 406、明示的な空文字列は現在 0 として互換処理されます。これらの異常値の動作に依存しないでください。元のファイル名/UUID をインデックスの代わりに使用することはできません。 空文字列を許可: False null を許可: False 例: 0取得または入力方法: 呼び出し元のチャンク一覧で生成し、0から元のZIPの順序に従って増加させます。 |
| uploadId | string | Y | 必須のアップロードセッションIDです。自身で連結せず、taskId で代用しないでください。同一ワークスペースで管理権限を持つKeyは継続でき、作成したKeyによる分離は行いません。セッションのデフォルトは3600秒で、マルチパートアップロードでは自動更新されません。期限切れ/新しいセッションによる上書きの場合は、確認後に再初期化してください。 null を許可: False 例: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb取得または入力方法: マルチパートアップロードの初期化の成功レスポンス content.uploadId をそのまま保存します。 |
ファイルパラメータ(multipart/form-data)¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| files | file | Y | 必須のファイルを1つ指定し、拡張子は .zip です(空のファイル名を許可する互換宣言があります)。同一チャンクに独立したZIP構造は要求されず、アップロードによってバイト列を変更してはいけません。 空のファイル名を許可: True 許可されるファイル拡張子: ['zip'] 単一ファイルサイズ上限: 10M ファイル数上限: 1 例: part-000.zip取得または入力方法: ローカルの完全なZIPを元のバイト順に分割し、各チャンクが10MiBを超えないようにします。 |
パラメータの補足説明¶
フローはSourceMap マルチパートアップロード関連API使用説明を参照し、あわせてマルチパートアップロード操作ドキュメントも参照できます。初期化→元のZIPの全チャンクをアップロード→チャンク一覧を確認→マージ→バージョン状態とファイルツリーを照会、の順に実行します。初期化/マージの成功は、ZIP が検証済みまたは解析可能であることを意味しません。processing/failed/blocked などの状態は引き続き確認する必要があります。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/upload_part' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-F 'uploadId=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb' \
-F 'chunkIndex=0' \
-F 'files=@./part-000.zip'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.uploadId | string | 現在のセッションID。 |
| content.chunkIndex | integer | 実際に保存された整数のチャンク番号。 |
| content.declaration | object | 現在のワークスペースの共通宣言。 |
| content.reasonCode | string | エラーレスポンスのみ:機械可読な理由。例: active_operation/invalid_scope/registry_missing。 |
| content.action | string | エラーレスポンスのみ:推奨アクション。例: retry_after_operation/verify_ownership/check_scope_and_upload。 |
| content.retryable | boolean | エラーレスポンスのみ:サーバーが推奨する再試行可能フラグ。これのみに基づいて公開済み書き込みを再実行することはできません。 |
| content.uploadCommitted | boolean | 一部の単一ファイルエラー診断のみ:true はその書き込みが公開済みと確認されたことを示します。省略は false を意味せず、未書き込みを確認したことにもなりません。 |
| content.actualBytes | integer | 一部の容量エラーのみ:計上済みバイト数。 |
| content.maxBytes | integer | 容量/読み取り制限のバイト数。 |
| content.workspaceUUID | string | 一部エラーの限定診断:現在のワークスペースUUID。 |
| content.appId | string | 一部エラーの限定診断:公開アプリケーション識別子。 |
| content.rumCfgUUID | string | 一部エラーの限定診断:内部アプリケーション識別子。サポート調査にのみ使用し、リクエストの appId を置き換えません。 |
| content.env | string | 一部エラー診断:環境。 |
| content.version | string | 一部エラー診断:バージョン。 |
| content.bundleUUID | string | 一部エラー診断:今回の世代レコードID。uploadId ではありません。 |
| content.state | string | 一部エラー診断:世代状態。 |
| content.resource | string | 一部占有診断:リソース種別。例: application/bundle。 |
| content.shared | boolean | 一部占有診断:共有アクセスかどうか。 |
| content.waitedSeconds | number | 一部占有診断:待機済み秒数。 |
| content.waitSeconds | number | 一部占有診断:許容待機秒数。 |
| content.waitExhausted | boolean | 一部占有診断:今回の待機が枯渇したか。 |
| content.elapsedSeconds | number | 一部の単一ファイルエラー診断:操作所要秒数。 |
| content.phase | string | 一部エラー診断:失敗フェーズ。 |
| content.phaseElapsedSeconds | number | 一部エラー診断:フェーズ所要秒数。 |
{
"code": 200,
"content": {
"uploadId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"chunkIndex": 0,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
ストレージライフサイクルの互換エラーコードを保持します。409 は通常引き続き ft.InvalidAction であり、ローカライズされた message と content.reasonCode で原因をさらに区別します。message 名 SourceMapOperationBusy などを必然的な errorCode として扱わないでください。読み取り時のパッケージ欠落/処理中/利用不可は通常 404 ft.SourceMapPackageNotFound で、具体的な原因は reasonCode を確認します。retryable=true が明示的に返され、かつ現在の状態が許可する場合にのみバックオフして再試行してください。uploadCommitted=true の場合は、公開済みと確認された書き込みを再実行できません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 404 | ft.NotFoundRumSet | アプリケーションが現在のワークスペースにない、削除済み、または存在しない | 指定されたRUM設定が見つかりません | RUMアプリケーション簡易一覧を更新し、現在のワークスペースの実際の appId を使用してください。 |
| 406 | ft.InvalidUploadId | セッションキャッシュが存在しない/期限切れ/置き換え済み、対象世代の状態/操作IDの不一致、または書き込みフェーズがキャンセル済み。マネージドの負のインデックスも拒否 | 無効な UploadId 値、またはタスクが上書き済み | 元の uploadId とアップロード済みチャンクを確認してください。旧セッションと公開状態を確認したうえで再初期化し、盲目的に上書きしないでください。 |
| 409 | ft.InvalidAction | アップロード/読み取り/クリーンアップの競合、旧ディレクトリの引き継ぎ未完了、所有権/復旧の確認待ち、または環境バージョンがライフサイクルの許可範囲を超えている | reasonCode に応じて具体的なローカライズ済みメッセージを返します。例: SourceMap が他のアップロード、読み取り、またはクリーンアップ操作で使用中 | content.reasonCode/action/retryable を確認します。active_operation/active_upload などは指示に従ってバックオフしてください。owner_recovery_required/ownership_verification_required/legacy_invalid などはまず管理者に検証を依頼し、占有レコードを自分で削除したり強制上書きしたりしないでください。invalid_scope は env/version が最大256文字であることを確認します。 |
| 406 | ft.InvalidFileName | ファイルの相対パス、シンボリックリンク、または過去の公開パスが安全でない | SourceMap ファイルパスが要件を満たしていないか、サポートされないリンクが含まれています。アップロードファイルの相対パスとディレクトリ構造を確認してください。 | パッケージ内の有効な相対パスを使用し、..、バックスラッシュ、絶対パス/シンボリックリンクを含めないでください。reasonCode=invalid_path を確認してください。 |
| 500 | ft.InternalServerError | abc/1.2 などの非数値の chunkIndex が現在の型認識を通過した後に int 変換で失敗した場合、または未処理のファイル/キャッシュ/データベース例外 | 内部エラー | 非負の10進数番号のみを送信してください。ストレージ例外の場合は、まず part_list を確認してそのチャンクが保存されているか照合し、その後同じバイト列で再試行してください。 |