linkfox-amazon-store-uploads

Amazon ストア Uploads（ファイルアップロード）

このスキルは Amazon にアップロード先を申請してファイルをアップロードするためのもので、linkfox-amazon-store-auth と同じシリーズです。店舗の選択には linkfox-amazon-store-auth（sellerId+region）を使用します。POST /spApi/developerProxy に sellerId+region を渡して createUploadDestinationForResource を呼び出し、最後に upload_to_destination.py で返された URL に PUT を実行します（ゲートウェイ経由ではありません）。

これは Uploads API であり、Orders の注文インターフェースではありません。注文については linkfox-amazon-store-orders を、Feed の一括ファイルについては linkfox-amazon-store-feeds を参照してください。

呼び出し方法

• API エンドポイント：POST /spApi/developerProxy（操作はリクエスト本文で区別します。パラメーター／レスポンス／エラーコードの詳細は references/api.md を参照してください）
• Python スクリプト：python scripts/<脚本名>.py '<JSON 参数>' [--inline]（利用可能なスクリプトは上記のスクリプト一覧を参照してください）
• コスト制約：このツールは計算リソースを消費します。失敗や空の結果が返された場合、自動的にキーワードを変えたり、ページをめくったり、連続して試したりしてはいけません。検索を続ける必要がある場合は、追加のコストが発生することを先にユーザーへ説明してください。

出力ポリシー（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-uploads-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリにあたります。<session> は環境変数 SESSION_ID から取得し、ユーザーのタスクごとに自動的にまとめられます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken など一般的な件数、最も大きいリストフィールドの長さと先頭 3 件のサンプル）
• --inline を追加すると、stdout にすべて出力します（同様にファイルにも保存します）

データの読み取りに関する推奨事項：まず要約を確認して十分か判断してください。具体的なフィールドが必要な場合は、保存された JSON ファイルから jq または ConvertFrom-Json を使って必要な情報だけを抽出し、JSON 全体をコンテキストに取り込まないようにしてください。

認証と計算リソースの問題を解決する

次のような異常が発生した場合は、references/onboarding.md に従って問題を解決してください。

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• レスポンスのステータスコードが 401 または 402
• レスポンスに計算リソースまたは残高不足の案内が含まれる：メッセージに「计算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值」が含まれる場合、または同様の内容がある場合。

公式リファレンス

createUploadDestinationForResource · アップロード先の作成

---

前提条件

1. linkfox-amazon-store-auth が必要です。
2. resource は、後続の API ドキュメントと一致している必要があります（例：A+：aplus/2020-11-01/contentDocuments、Messaging は対応する messages リソースパス）。
3. contentMD5 は、アップロード対象ファイルの内容の Base64 MD5 ダイジェストです。filePath／content を渡す場合、スクリプトが自動で計算できます。

---

ワークフロー

create_upload_destination_for_resource  →  uploadDestination { uploadDestinationId, url, headers }
upload_to_destination (PUT url + headers)  →  在 A+/Messaging 等 API 中引用 uploadDestinationId

---

スクリプト

スクリプト	説明
create_upload_destination_for_resource.py	POST uploads/2020-11-01/uploadDestinations/{resource}
upload_to_destination.py	返された url に PUT します（headers 付き）
_spapi_uploads_common.py	内部共通モジュール

---

例

export LINKFOXAGENT_API_KEY="<your-key>"

# 1) 创建上传目的地（自动根据 filePath 计算 contentMD5）
python scripts/create_upload_destination_for_resource.py '{
  "sellerId":"A1...",
  "region":"NA",
  "resource":"aplus/2020-11-01/contentDocuments",
  "marketplaceId":"ATVPDKIKX0DER",
  "filePath":"/path/to/banner.jpg",
  "contentType":"image/jpeg"
}'

# 2) 上传文件（将上一步 stdout 中的 uploadDestination 传入）
python scripts/upload_to_destination.py '{
  "uploadDestination": { "url": "...", "headers": { } },
  "filePath": "/path/to/banner.jpg"
}'

---

表示ルール

1. 目的地の作成に成功すると、通常は HTTP 201 が返されます。まず developerProxy を確認し、次に uploadDestination を確認してください。
2. resource には、エンコードされていない後続リソースのパスを渡します。先頭の / は付けても付けなくてもかまいません。path の生成時には内部の / が保持されます（greedy path）。事前に %2F にエンコードしてはいけません。
3. ゲートウェイでは uploads/2020-11-01/ プレフィックスを許可する必要があります。

Amazon SP-API インターフェースの保護と再試行のガイドライン

同じ店舗で Amazon SP-API から 400、403、404、または 429 が連続して返された場合、ゲートウェイは 450、453、454、または 459 を返し、短時間のクールダウンに入ります。これらのカスタムステータスコードは Amazon 本来のステータスではなく、アカウント停止を意味するものでもありません。継続的な異常や高頻度の呼び出しによって店舗のリスクが拡大するのを防ぐためのものです。

ステータスと message	範囲	発生条件とクールダウン	対応
450：400，请求异常，请优化您的参数	店舗+インターフェース	60 秒以内に 3 回を超える：5 分間、10 分以内に 4 回を超える：20 分間	同じパラメーターでの再試行を停止し、必須フィールド、marketplace、ID、日付、リクエスト本文を確認してください
453：403，店铺未授权，请先授权	店舗の全インターフェース	60 秒以内に 2 回を超える：5 分間、10 分以内に 4 回を超える：30 分間	その店舗への呼び出しを停止し、認証、権限、店舗の帰属、リージョンを確認してください
454：404，资源不存在，请优化您的参数	店舗+インターフェース	60 秒以内に 3 回を超える：5 分間、10 分以内に 4 回を超える：30 分間	リソース ID、対象の店舗／サイト、リソースの状態、インターフェースのパスを確認してください
459：429限流中，请降低频率	店舗+インターフェース	初回：15 秒間、2 分以内に 2 回を超える：30 秒間、3 分以内に 4 回を超える：2 分間	同時実行数、ページング、ポーリングの頻度を下げ、段階的にバックオフしてください

• 自動または並列での再試行は直ちに停止してください。スクリプトを変えたり、タスクを繰り返し作成したりして保護を回避してはいけません。まず retryAfter、blockedUntil に従い、これらがない場合は表に記載された時間を目安にしてください。
• 450／453／454 の場合は、クールダウン後に慎重に最大 1 回だけ再試行する前に、パラメーター、認証、またはリソース識別子を修正する必要があります。再度発生した場合は呼び出しを停止してください。453 の発生中は、その店舗のすべての SP-API 呼び出しを停止してください。
• 既存の reportId、feedId などのタスク ID を保持してください。書き込み操作の結果が不明な場合は、再実行せずに先にステータスを照会してください。
• 店舗保護についてユーザーに先に説明し、原因、対応、待ち時間を伝えてください。次のように回答できます。「Amazon ストアの安全を保護するため、Amazon SP-API から{原因}が連続して返されたことを検知し、現在、短時間の保護状態に入っています。先に{対応内容}を行い、{待ち時間}後に再試行してください。これはアカウント停止を意味するものではなく、プランや計算リソースの制限でもありません。」「LinkFox のレート制限」や「サーバーが混み合っています」とだけ伝えてはいけません。

計算リソースの消費ルール

計算リソースを消費しません。

フィードバック： skillName：linkfox-amazon-store-uploads。

---

その他の越境 EC スキル：LinkFox Skills