マルチパートアップロードの初期化¶
POST /api/v1/rum_sourcemap/multipart_upload_init
概要¶
指定した RUM 環境とバージョンの SourceMap ZIP のマルチパートアップロードを初期化します。
呼び出し前の注意点と使用手順¶
現在の 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 などの状態は引き続き確認する必要があります。
まずローカルで完全な ZIP を生成し、その後バイト順に 1 パートあたり 10MiB を超えないファイルに分割します。needCover=false の場合はデフォルトで上書きしません。現在の環境/バージョンに既存レコードがある場合、HTTP 200 で uploadId=""、existsSameFile=true が返されるため、呼び出し元はまず旧バージョンを確認し、その後で needCover=true として再初期化するかどうかを決定してください。空の ID のままアップロードを続けることはできません。上書きは新しい世代を使用し、アップロード/解凍の検証が完了してから公開済みコンテンツを置き換えます。needCover を旧ディレクトリを即座に消去するものとして扱わないでください。
existsOldTask は同じスコープに既存のキャッシュがあることを検出したにすぎず、その旧タスクが引き続き続行可能であること、または今回書き込み可能なセッションを取得したことを証明するものではありません。同時アップロード/復旧/クリーンアップでは引き続き 409 が発生する可能性があります。同時に複数回初期化しないでください。空でない uploadId が返されたら元の値を保存してください。セッションはデフォルトで 1 時間で、パートリクエストでは延長されません。初回アクセス時は履歴ディレクトリ/インデックスを安全に引き継ぎます。古いアップロード/インデックスがまだ完了していない場合は、409 により待機するか管理者に確認を依頼するよう案内します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| appId | string | Y | 現在のワークスペースでアクティブなアプリケーション識別子が必須です。内部 RumCfg UUID ではなく、ワークスペースを跨いで使用できません。 null を許可: False 例: payment_web取得または入力方法: RUM アプリケーション簡易一覧 の content[].appId またはエラーレコードの app_id から取得します。 |
| env | string | 省略可能な文字列。デフォルトは空の環境で、最大 256 文字です。すべての環境を表すものではなく、null は許可されません。 空文字列を許可: True null を許可: False 例: production取得または入力方法: クライアントのリリース環境/エラーレコードの env から取得し、アップロード時と完全に一致させます。 |
|
| needCover | boolean | 省略可能な boolean。デフォルトは false。false の場合、公開済みレコードに遭遇すると確認用に空の uploadId を返します。true の場合は置換世代の準備を許可しますが、引き続き同時実行/所有権/履歴の安全制限を受け、他の環境/バージョンは上書きしません。 null を許可: False 例: false取得または入力方法: まずバージョン一覧を確認し、その環境/バージョンの置換が許可されているかどうかを確認します。 |
|
| version | string | 省略可能な文字列。デフォルトは空のバージョンで、最大 256 文字です。最新/すべてのバージョンを表すものではなく、null は許可されません。 空文字列を許可: True null を許可: False 例: 1.2.3取得または入力方法: クライアントで実際にリリースされたバージョン/エラーレコードの version から取得し、ビルド成果物に対応させます。 |
パラメータ補足説明¶
フローについては SourceMap マルチパートアップロード関連 API の使用説明 を参照し、マルチパートアップロード操作ドキュメント も参照してください。「初期化 → 元の ZIP のすべてのパートをアップロード → パート一覧を確認 → マージ → バージョン状態とファイルツリーを照会」の順に実行します。初期化/マージの成功は、ZIP が検証済みまたは解析可能であることを意味しません。processing/failed/blocked などの状態は引き続き確認する必要があります。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/multipart_upload_init' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"appId":"payment_web","env":"production","version":"1.2.3","needCover":false}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.uploadId | string | 空でない場合のみパートを継続できます。既存バージョンに遭遇し、上書きしない場合は空文字列です。 |
| content.existsOldTask | boolean | 同じスコープに既存タスクのキャッシュがあることを示すヒントであり、セッションの有効性/上書き成功を保証するものではありません。 |
| content.existsSameFile | boolean | 現在既存のバージョンレコードがあることを示すヒントであり、すべてのソースファイルが検証済みであることと同じではありません。 |
| 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",
"existsOldTask": false,
"existsSameFile": false,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
{
"code": 200,
"content": {
"uploadId": "",
"existsOldTask": false,
"existsSameFile": true,
"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 | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の json ファイルの形式エラー | オブジェクトを送信してください。 |
| 404 | ft.NotFoundRumSet | アプリケーションが現在のワークスペースにない、削除済み、または存在しません | 指定された RUM 設定が見つかりません | RUM アプリケーション簡易一覧を更新し、現在のワークスペースの実際の appId を使用してください。 |
| 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 文字であることを確認してください。 |
| 500 | ft.InternalServerError | データベース、Redis、ストレージの読み書き、キュー、または未処理のシステム例外 | 内部エラー | traceId、アプリケーション/env/version/uploadId を保持し、まず一覧/ファイルツリーを確認してください。失敗していてもファイルが公開済み、または処理マークが付いている可能性があるため、むやみに再度上書き/削除しないでください。 |