コンテンツにスキップ

単一チャンクのアップロード



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 を確認してそのチャンクが保存されているか照合し、その後同じバイト列で再試行してください。

フィードバック

このページは役に立ちましたか?