APIアップロードに冪等性キーを使用

dosyaの冪等性は一括アップロードのPUT /api/upload/fileルートに適用されます。X-Dosya-Idempotency-KeyにUUID v4値を指定して送信してください。マルチパートセッションルートには独自のパート番号による再開の仕組みがあります。

始める前に

• 1つの論理アップロードにつき新しいUUID v4を1つ生成し、結果を検証するまでジョブとともに保持します。
• 再試行時もワークスペース、フォルダー、生のファイル名、Content-Lengthを変更しないでください。これらの値がリクエストのフィンガープリントを構成します。
• 自動再試行を有効にする前に、リクエストボディを再送可能にする必要があります。

手順

1. 3fa85f64-5717-4562-b3fc-2c963f66afa6のようなUUID v4を作成し、ローカルの元ファイルのパスと予定する保存先に紐付けます。
2. 正確なContent-Length、Bearerキー、ボディ、X-Dosya-Idempotency-Keyを指定してPUT /api/upload/file?file_name=report.pdf&folder_id=folder_idを送信します。
3. HTTP 201が返されたら、ファイルの受領情報を保存します。サーバーは完了した冪等性レコードを86,400秒間保持するため、一致する再試行でレスポンスを復旧できます。
4. 結果が不明な通信障害の後は、同一のキーで同一のリクエストを繰り返します。HTTP 200とX-Dosya-Idempotent-Replay: trueは、dosyaが2つ目のファイルを作らず以前の結果を返したことを示します。
5. HTTP 409とRetry-After: 5が返された場合、別の一致するリクエストがまだ処理中です。待ってから再試行してください。放棄された処理の所有権は600秒後に引き継げます。
6. コードidempotency_key_reusedを伴う409の場合は停止します。キーが別のワークスペース、フォルダー、生のファイル名、または宣言した長さと組み合わされています。新しいキーは本当に新しいアップロードの場合にのみ生成してください。

期待される結果

最初に受け付けられたアップロードは201を返します。同一の再送ではステータス200と再送ヘッダーとともに同じ論理結果が返されます。フィンガープリントが一致しない場合は、不確かなデータを作成せず拒否されます。

トラブルシューティング

ボディを再送できない。 最初のリクエスト前に一時ファイルに保存するか、自動再試行を無効にしてください。

再利用コードのない409が返される。 Retry-After: 5に従ってください。元の操作が完了する可能性がある間は新しいキーを作成しないでください。

ファイルのバイトが変わったが長さは変わっていない。 整合性確認にX-Dosya-Sha256を使用し、新しい論理アップロードには新しい冪等性キーを使用してください。

関連ガイド

• APIでアップロード
• REST APIクイックスタート