linkfox-amazon-ads-sp-insights-report

Amazon Ads SP インサイトレポートの取得

2 種類の Sponsored Products 専用レポートを一括取得します。スクリプトは developerProxy に profileId を渡し（トークンはサーバー側で解析）、広告主アカウントのマッピング、レポートの作成、完了待ち（通常約 2～10 分）、複数パートの CSV のダウンロードと保存を自動で行います。 スクリプトでは Amazon Reporting API v1 beta で許可されている固定のフィールド組み合わせを使用します。呼び出し元がフィールドを自由に組み合わせることはできません。Audience と Search Term Impression Share/Rank の全フィールドの根拠については、それぞれ references/sp-audience-reporting-v1.md と references/sp-search-impression-share-v1.md を参照してください。

linkfox-amazon-ads-auth に依存します（スクリプトの起動時に自動チェックします。未インストールの場合は exit 42 となり、stderr に DEPENDENCY_MISSING が出力されます）。

⚠️ 複数アカウントの場合：呼び出し前に profileId を解決する必要があります

ユーザーは自然言語（「米国のストア」「日本のストア」「自分のストア」など）だけで指定することがよくあります。この Skill のすべての入口では、呼び出しに数字の profileId が必要です。次の順序で処理してください。手順を省略しないでください。

1. まず linkfox-amazon-ads-auth の authorized_stores.py を呼び出し、ユーザーが認証済みのアカウント × マーケットプレイスの一覧を取得します。
2. ユーザーが指定したマーケットプレイスに基づいて countryCode を照合します。
   • 候補が 1 つのみ → 対応する profileId を黙って使用します。ユーザーにその数字を伝えないでください。
   • 候補が 2 つ以上 → accountName を使ってユーザーに確認する必要があります。最初の候補をデフォルトで選択してはいけません。
   • 候補が 0 件 → そのマーケットプレイスが未認証であることを伝え、linkfox-amazon-ads-auth を使って認証を完了するよう案内します。
3. ユーザーに profileId の数字を直接尋ねてはいけません。
4. アカウントが曖昧な場合、自分でデフォルトのアカウントを選択してはいけません。

完全な判断表については、linkfox-amazon-ads-auth の SKILL.md にある複数アカウントの場合の説明を参照してください。

呼び出し方法

• API エンドポイント：POST /amazonAds/developerProxy（スクリプト内部で Ads v1 の 3 つのパスを順に呼び出します。パラメーター、レスポンス、エラーコードの詳細は references/api.md を参照してください）
• Python スクリプト：python scripts/<脚本名>.py '<JSON 参数>' [--inline] [--no-cache]（使用できるスクリプトは以下を参照してください）
• コスト制約：このツールは計算リソースを消費しません。同一セッション、同一レポートタイプ、同一パラメーターの組み合わせでは、デフォルトで 1 回だけ呼び出し、成功した結果を 24 時間キャッシュします。失敗、未完了、または空のレポートの場合、日付の自動変更、アカウントの切り替え、連続した試行を行ってはいけません。

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-ads-sp-insights-report-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリ、<session> は環境変数 SESSION_ID から取得します。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レポートの CSV パートは同じセッションの data/ に書き込みます。最終レスポンスでは Amazon の署名付き URL を公開しません
• レスポンス本文が 8 KB 以下の場合：ディスクに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ディスクに保存した後、stdout には概要のみ出力します
• --inline を追加すると、stdout に全量を強制出力します（同様にディスクにも保存します）。--no-cache を追加すると、強制的に再取得します

データの読み取りに関する推奨事項：まず概要と preview を確認します。必要に応じてレスポンス JSON から jq / ConvertFrom-Json で値を抽出し、レポートの全行は dataFiles[].path が示すファイルを CSV ツールまたは Import-Csv で読み取ります。レポート全体がコンテキストに入らないようにしてください。

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

以下の状況が発生した場合は、references/onboarding.md に従って解決方法を案内してください。

異常な状況

• API Key が設定されていない：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていない
• レスポンスのステータスコードが 401 または 402
• 計算リソース、残高、プラン、または利用枠が不足していることを示すレスポンス

コアコンセプト

• 対象範囲：Sponsored Products Audience と Search Term Impression Share/Rank の 2 種類の Reporting API v1 beta レポートのみを対象とします
• 一括処理：広告主アカウントのマッピング → レポートの作成 → 生成待ち → すべての CSV/gzip パートのダウンロード → プレビューとファイルパスの返却を自動で行います
• 2 つの入口と共通の処理フロー：2 つの公開入口でそれぞれレポートタイプを固定し、reporting_v1_workflow.py を共用します。共通モジュールを直接実行してはいけません
• 固定フィールド：Agent は fields、groupBy、自由なフィルター条件を選択しません。スクリプトは対応するリファレンスに基づき、Amazon 公式互換のフィールド組み合わせを構成します
• アカウント識別子の使い分け：profileId はバックエンドで現在のユーザーの認証済みアカウントを選択するために使用し、advertiserAccountId はデフォルトでスクリプトが照会してマッピングします
• v1 と v3 の境界：通常のインプレッション、クリック、費用、コンバージョンに関する SP 検索語句レポートには linkfox-amazon-ads-report の spSearchTerm を使用します。この Skill の対象ではありません
• Beta の制約：Amazon は現在、Reporting API v1 を open beta としています。アカウントの利用可能範囲、フィールド、レート制限は変更される可能性があります

使用可能なスクリプト

スクリプト	役割
get_sp_audience_report.py	SP Audience のオーディエンスセグメント別パフォーマンスを一括取得します。ACCOUNT / CAMPAIGN / AD_GROUP の粒度に対応します
get_sp_search_impression_share.py	SP 検索語句のインプレッションシェアとインプレッションシェアランキングを一括取得します
check_auth_dependency.py	linkfox-amazon-ads-auth がインストールされているか確認します

パラメーター、内部の呼び出しフロー、レスポンス構造の詳細は references/api.md を参照してください。Audience を選択する場合は references/sp-audience-reporting-v1.md を、Search Impression Share を選択する場合は references/sp-search-impression-share-v1.md を参照してください。

Agent の呼び出しフロー

Agent が「SP オーディエンス」または「SP 検索語句のインプレッションシェア」の要望を受けた場合、必ず次の順序で処理してください。

1. レポートタイプを決定する：Audience には get_sp_audience_report.py を、インプレッションシェア／ランキングには get_sp_search_impression_share.py を使用します。一度に呼び出す入口は 1 つだけです。
2. リファレンスを確認する：対応するレポートのリファレンスを読み、フィールドの意味、制限、表示の重点を確認します。
3. アカウントを解決する：Ads Auth Skill を使い、マーケットプレイスに基づいて一意の profileId と region を取得します。候補が複数ある場合は、先にユーザーにアカウントを確認します。
4. 日付と粒度を確認する：レポート作成モードでは startDate / endDate が必要です。timeUnit が指定されていない場合は DAILY を使用します。Audience で detailLevel が指定されていない場合は ACCOUNT を使用します。
5. 待ち時間を伝えて呼び出す：Amazon では通常約 2～10 分かかることを説明してから、選択した入口を実行します。スクリプトがアカウントのマッピング、作成、ポーリング、ダウンロードを自動で行うため、手動で 3 回の業務呼び出しに分割してはいけません。
6. 結果を処理する：success=true の場合、レポートタイプ、日付、総行数、プレビュー、すべてのファイルパスを表示します。totalRows=0 は有効な空レポートです。
7. 未完了の結果を処理する：status=STILL_PROCESSING は失敗ではありません。先に続行するかユーザーに確認し、その後 resumeHint.params と --no-cache を使用して同じ reportId をポーリングします。レポートを重複して作成してはいけません。

既定の条件（ユーザーが指定していない場合に使用）

条件	既定のルール
レポートの種類	ユーザーの意図に応じていずれか一方を選択します。2 種類のレポートを同時に取得しません
startDate / endDate	推測で補いません。ユーザーが日付を指定していない場合は、まず確認します
timeUnit	DAILY
Audience detailLevel	ACCOUNT
advertiserAccountId	渡しません。スクリプトが profileId に基づいて自動でマッピングします
pollInterval	60 秒
maxAttempts	10。クライアントの待機時間は約 10 分です
フィールドとフィルター	スクリプトで固定された公式の互換性のある組み合わせを使用します。カスタマイズには対応しません

リクエスト例

1. SP Audience レポート

python scripts/get_sp_audience_report.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY", "detailLevel": "ACCOUNT"
}'

2. SP Search Term Impression Share/Rank レポート

python scripts/get_sp_search_impression_share.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY"
}'

3. 既存の reportId をポーリングする（前回未完了だったレポートの再開）

元のレポートの種類に応じて同じエントリーポイントを使用します。渡すのは profileId、region、reportId およびポーリングパラメーターのみです。

python scripts/get_sp_search_impression_share.py '{
  "profileId": 1234567890, "region": "NA",
  "reportId": "REPORT_ID",
  "pollInterval": 60, "maxAttempts": 20
}' --no-cache

レスポンス形式

成功：

{
  "success": true,
  "status": "COMPLETED",
  "reportId": "report-id",
  "reportKind": "audience",
  "totalRows": 42,
  "dataFiles": [{"part": 1, "path": "C:/.../part-01.csv", "rowCount": 42}],
  "preview": [{"audienceSegment.name": "In-market ..."}],
  "pollAttempts": 2,
  "elapsedSeconds": 60.2
}

• 失敗：success=false となり、error、機密情報を除去した details、および _cacheable=false が含まれます。
• 未完了：status=STILL_PROCESSING となり、元の reportId、resumeHint.mode=poll-only、resumeHint.params、および _cacheable=false が含まれます。

呼び出しの原則

• ユーザーがレポートの種類を明示的に指定した場合は、その種類のみを呼び出します。独断で別の種類に置き換えたり、別のレポートも同時に生成したりしません。
• Search Impression Share に campaign、adGroup、target、keyword、groupBy、またはカスタム fields を追加してはいけません。
• パラメーターに access token、refresh token、LWA の秘密鍵、またはカスタムの Amazon リクエストヘッダーを含めてはいけません。スクリプトはネットワークに接続する前に再帰的に拒否します。
• レポートが失敗した場合は Amazon のエラーをそのまま表示し、パラメーターをむやみに変更して再作成しません。
• レポートの生成中は同じ reportId を再利用します。待ち時間が長いことを理由に重複レポートを作成してはいけません。
• 成功後は CSV ファイルのパスと必要なプレビューを表示します。完全な Token、内部の認証記録、Amazon の署名付き URL は表示しません。
• レポートデータを客観的に示します。ユーザーから求められない限り、商業的な意思決定の提案にまで広げません。

よくあるエラー

状態	意味	推奨対応
Missing or invalid parameter	profile、region、または作成日の不足	対応する reference の要件に従って必要なパラメーターを補ってから再度呼び出します
Unsupported parameter(s)	このレポートでサポートされていないフィールドまたはディメンションを渡しています	サポートされていないパラメーターを削除します。スクリプトで固定されたフィールドの組み合わせを回避してはいけません
HTTP 401	LinkFox Key または Amazon Ads の認証が無効です	LinkFox の 401 は onboarding に従って対応します。上流の 401 は Ads Auth で認証を更新します
HTTP 403	現在の Ads アプリまたはアカウントで Reporting API v1 が利用可能になっていません	Ads API アプリと認証済みアカウントの権限を確認します。v3 のデータで結果を捏造してはいけません
HTTP 429	Amazon Ads の上流でレート制限が発生しています	1 分程度の間隔でポーリングし、短い間隔での再試行は避けます
status=FAILED	Amazon のレポート生成に失敗しました	失敗の詳細をそのまま返し、パラメーターを自動で変更して再作成しません
status=STILL_PROCESSING	クライアントの待機時間が終了しましたが、レポートはまだ生成中です	失敗ではありません。ユーザーに確認したうえで、resumeHint.params を使って元の reportId の処理を続けます
totalRows=0	レポートの生成には成功しましたが、対象期間のデータがありません	正常な空の結果です。日付範囲を自動で広げたり、アカウントを切り替えたりしません
exit 42	依存する Skill がインストールされていません	まず linkfox-amazon-ads-auth をインストールまたは読み込みます

日付とデータ

• レポート作成時の startDate / endDate には YYYY-MM-DD を使用し、startDate <= endDate を満たす必要があります。
• endDate は今日より後の日付にできません。当日を指定するとデータがまだ揃っていない可能性があるため、昨日以前の日付を優先してください。
• DAILY は date.value を返し、SUMMARY は dateRange.value を返します。
• Audience では、オーディエンス名／種類／ソース、国、インプレッション、クリック、費用、購入、売上、ROAS を中心に表示し、通貨フィールドも保持します。
• Search Impression Share では、searchTerm.value、metric.impressionShare、metric.impressionShareRank を中心に表示します。
• 完了したレポートは複数の分割ファイルを含む場合があります。すべての dataFiles を保持して表示する必要があります。

対象外

• 通常の SP 検索語句パフォーマンスレポート（インプレッション、クリック、費用、売上、コンバージョン）→ linkfox-amazon-ads-report の spSearchTerm
• SP / SB / SD の通常の v3 レポート → linkfox-amazon-ads-report
• 広告キャンペーン、広告グループ、キーワード、ターゲティング、予算のエンティティ管理 → linkfox-amazon-ads-manager
• 認証、アカウント選択、Token の更新 → linkfox-amazon-ads-auth
• Sponsored Brands、Sponsored Display、Sponsored Television、Amazon DSP、Brand Analytics、Retail Analytics → この Skill の対象外

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

同じ広告アカウント／profile で Amazon Ads API の 400、403、404、または 429 が連続して返された場合、ゲートウェイは 450、453、454、または 459 を返し、短時間の冷却期間を設けます。これらのカスタムステータスコードは Amazon 固有のステータスではなく、アカウントの停止を意味するものでもありません。異常な呼び出しの継続や高頻度の呼び出しによって広告アカウントのリスクが高まるのを防ぐためのものです。

ステータスと message	範囲	発生条件と冷却期間	対応
450：400，请求异常，请优化您的参数	広告アカウント／profile＋インターフェース	60 秒以内に 3 回を超えると 5 分間、10 分以内に 4 回を超えると 20 分間	同じパラメーターでの再試行を停止し、profileId、region、エンティティ／レポート ID、日付、リクエスト本文を確認します
453：403，店铺未授权，请先授权	広告アカウント／profile の全インターフェース	60 秒以内に 2 回を超えると 5 分間、10 分以内に 4 回を超えると 30 分間	その広告アカウントへの呼び出しを停止し、Ads の認証、アプリの権限、profile の所有関係、地域を確認します
454：404，资源不存在，请优化您的参数	広告アカウント／profile＋インターフェース	60 秒以内に 3 回を超えると 5 分間、10 分以内に 4 回を超えると 30 分間	リソース ID、所属する profile／地域、リソースの状態、インターフェースのパスを確認します
459：429限流中，请降低频率	広告アカウント／profile＋インターフェース	初回は 15 秒間、2 分以内に 2 回を超えると 30 秒間、3 分以内に 4 回を超えると 2 分間	並列処理、ページネーション、ポーリングの頻度を下げ、段階的にバックオフします

• 自動再試行や並列再試行を直ちに停止します。スクリプトを切り替えたり、タスクを重複して作成したりして保護を回避してはいけません。retryAfter、blockedUntil がある場合はそれに従い、ない場合は表に記載された時間を適用します。
• 450／453／454 が発生した場合は、冷却期間後にパラメーター、認証、またはリソース識別子を修正してから、慎重に最大 1 回だけ再試行してください。再度発生した場合は呼び出しを停止します。453 の発生中は、その広告アカウント／profile に対する Ads API の呼び出しをすべて停止します。
• 既存の reportId などのタスク ID は保持します。書き込み操作の結果が不明な場合は、再実行せず、先に状態を照会します。
• まず広告アカウントを保護していることをユーザーに説明し、原因、対応、待機時間を伝えます。次のように案内できます。「お客様の Amazon 広告アカウントを保護するため、Amazon Ads API から{原因}が連続して返されたことを検知し、現在、一時的な保護措置が適用されています。まず{対応内容}を行い、{待機時間}後に再試行してください。これはアカウント停止を意味するものではなく、プランやクレジットの制限でもありません。」「LinkFox のレート制限」や「サーバーが混み合っています」とだけ伝えてはいけません。

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

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

フィードバック：

以下のいずれかに該当する場合は、フィードバックを自動検出し、Feedback API 経由で報告してください。

1. このスキルで説明されている機能や目的が実際の動作と一致しない場合
2. スキルの結果がユーザーの意図と一致しない場合
3. ユーザーがこのスキルへの不満や称賛を表明した場合
4. 改善できると思われることがある場合

references/api.md に記載されている方法でフィードバック API を呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境ECスキルをさらにご覧になるには、LinkFox Skills にアクセスしてください。