◀ 3.

Amazon APIのスペース処理|JSONとURLエンコードの違い

▶

JSON内の「harry potter」はスペースのまま、URLクエリでは%20などへ符号化します。旧PA-APIと現行Creators APIの区別に加え、値を変えてしまう二重エンコードを避ける方法を説明します。

JSONの空白とURLクエリ符号化、署名の扱いを分ける図

先に確認: 旧PA-APIと現在のCreators API

2026年10月確認。PA-API 5.0も公式の廃止案内の対象です。このページの旧PA-API例は保守・比較用で、現在の新規導入手順ではありません。旧APIの403をキー再発行や再試行だけで直そうとしないでください。

後継への移行は公式移行ガイドを確認します。旧AWSキーとSigV4ではなく、Creators API用のCredential ID / Secret / VersionとOAuth 2.0を使います。本文の旧フィールド名・旧SDKをそのまま現行APIへ適用しないでください。親のPA-APIの関連資料から各子ページも選択できます。

通信せず確認できるPHPの変換例

次はPHP 8系のローカル変換例です。API要求を完成させるコードではありません。JSONには値をそのまま渡し、URLクエリだけRFC3986形式を選びます。不正なUTF-8等はJSON_THROW_ON_ERRORで例外にします。

<?php

// Local serialization only. This does not authenticate or call an Amazon API.
function keywordRepresentations(string $keyword): array
{
    $json = json_encode(['keywords' => $keyword], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    $query = http_build_query(['q' => $keyword], '', '&', PHP_QUERY_RFC3986);

    return ['json' => $json, 'query' => $query];
}

$example = keywordRepresentations('harry potter + 本');
echo $example['json'], PHP_EOL;
echo $example['query'], PHP_EOL;

出力はJSONのkeywordsが「harry potter + 本」のまま、クエリはq=harry%20potter%20%2B%20%E6%9C%ACです。「+」は空白とは別の文字として保存します。JSONにharry%20potterを入れると検索語そのものを変えます。

json_encode、http_build_query、rawurlencodeの用途を分けて確認してください。JSON_UNESCAPED_UNICODEを省いてUnicodeがエスケープ表記になっても、JSON解析後の文字列が同じなら文字化けではありません。

この記事の要点
  • スペースの扱いはJSON文字列・URLクエリ・署名正規化を分ける。JSON値をURLエンコードしない
  • クエリ文字列のスペースは %20 または + (JSON文字列内のスペースを%20へ置換する意味ではない)
  • PHP: urlencode() / rawurlencode() / http_build_query()
  • JS: encodeURIComponent()
  • AWS V4 署名計算は RFC 3986 準拠の rawurlencode(スペース→%20)が前提
  • JSON ボディの Keywords はそのままスペースで入れて OK。SigV4ではボディハッシュ以外にメソッド・URI・クエリ・ヘッダー等も関係する
  • 現在の導入ではCreators APIの公式SDK配布とOAuth方式を確認。下の旧SDK例は新規導入用ではない

PA-API v5 とスペースの扱い

以下は廃止案内対象の旧PA-API v5を読むための説明です。旧v5ではPOST + JSON ボディでリクエストを送るので、複数語キーワード(例: harry potter)はJSON 文字列の中にそのままスペースで書くのが基本です。

一方で v4 以前は GET + クエリ文字列だったため、スペースは URL エンコードが必要でした。古いコードと新コードが混在する解説が多いので、まずどちらの API かを確認してください。

v5 (旧PA-API) のリクエスト例

次は旧HTTP要求とコメント付き本文をまとめた説明断片で、厳密なJSONや完成した送信要求ではありません。固定日時・省略Authorizationのまま実行せず、現行APIには流用しないでください。

// SearchItems の JSON ボディ
POST /paapi5/searchitems HTTP/1.1
Host: webservices.amazon.co.jp
Content-Type: application/json; charset=utf-8
X-Amz-Date: 20260611T100000Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIA...

{
    "Keywords": "harry potter",          // ← スペースそのまま OK
    "SearchIndex": "All",
    "ItemCount": 10,
    "Resources": ["Images.Primary.Small", "ItemInfo.Title"],
    "PartnerTag": "yourtag-22",
    "PartnerType": "Associates",
    "Marketplace": "www.amazon.co.jp"
}

JSON 文字列の中にあるスペースは何もする必要なし。ASCII の半角スペース (0x20) として送信されます。

署名計算(AWS V4)でのスペース

旧v5のSigV4 Canonical Requestは、HTTPメソッド・URI・正規化クエリ・正規化ヘッダー・署名ヘッダー名・本文ハッシュを組み合わせます。本文ハッシュだけの署名ではありません。JSON内の検索語にはJSONのシリアライズを行い、URIやクエリの符号化と混同しません。パス全体をrawurlencodeすると区切りのスラッシュまで変えるため、一律適用はしないでください。AWSの署名仕様と対象サービスの規則を確認します。

<?php
// RFC 3986 準拠のエンコード
$encoded = rawurlencode('harry potter');
echo $encoded;   // harry%20potter

// urlencode() との違い: urlencode は + を使う(application/x-www-form-urlencoded 用)
echo urlencode('harry potter');     // harry+potter
echo rawurlencode('harry potter');  // harry%20potter

// PA-API v4 のような URL 直書きでは rawurlencode のほうが安全

PHP での実装

cURL で直接呼ぶ

下は廃止API向けの旧コードとして保存する未実行例です。 HTTP失敗・タイムアウト・JSON失敗を扱わず、日付取得も同一時点に統一していません。実資格情報を入れて使う完成例ではありません。PHPの新しい変換例は末尾の通信しないサンプルを確認してください。

<?php
function paapiSearch(string $keywords): array {
    $accessKey = getenv('PAAPI_ACCESS_KEY');
    $secretKey = getenv('PAAPI_SECRET_KEY');
    $partnerTag = 'yourtag-22';
    $host = 'webservices.amazon.co.jp';
    $region = 'us-west-2';
    $service = 'ProductAdvertisingAPI';
    $target = 'com.amazon.paapi5.v1.ProductAdvertisingAPIv1.SearchItems';
    $path = '/paapi5/searchitems';

    $payload = json_encode([
        'Keywords'    => $keywords,            // ★ スペースそのまま
        'SearchIndex' => 'All',
        'ItemCount'   => 10,
        'Resources'   => ['Images.Primary.Small', 'ItemInfo.Title'],
        'PartnerTag'  => $partnerTag,
        'PartnerType' => 'Associates',
        'Marketplace' => 'www.amazon.co.jp',
    ], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

    $amzDate   = gmdate('Ymd\THis\Z');
    $dateStamp = gmdate('Ymd');

    // Canonical Request
    $canonicalHeaders =
        "content-encoding:amz-1.0\n" .
        "content-type:application/json; charset=utf-8\n" .
        "host:{$host}\n" .
        "x-amz-date:{$amzDate}\n" .
        "x-amz-target:{$target}\n";
    $signedHeaders = 'content-encoding;content-type;host;x-amz-date;x-amz-target';
    $payloadHash = hash('sha256', $payload);

    $canonicalRequest =
        "POST\n{$path}\n\n{$canonicalHeaders}\n{$signedHeaders}\n{$payloadHash}";

    // String to Sign
    $credentialScope = "{$dateStamp}/{$region}/{$service}/aws4_request";
    $stringToSign =
        "AWS4-HMAC-SHA256\n{$amzDate}\n{$credentialScope}\n" .
        hash('sha256', $canonicalRequest);

    // Signature
    $kDate    = hash_hmac('sha256', $dateStamp, "AWS4{$secretKey}", true);
    $kRegion  = hash_hmac('sha256', $region,    $kDate,  true);
    $kService = hash_hmac('sha256', $service,   $kRegion, true);
    $kSigning = hash_hmac('sha256', 'aws4_request', $kService, true);
    $signature = hash_hmac('sha256', $stringToSign, $kSigning);

    $authHeader =
        "AWS4-HMAC-SHA256 Credential={$accessKey}/{$credentialScope}, " .
        "SignedHeaders={$signedHeaders}, Signature={$signature}";

    $ch = curl_init("https://{$host}{$path}");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_HTTPHEADER => [
            'Content-Encoding: amz-1.0',
            'Content-Type: application/json; charset=utf-8',
            "Host: {$host}",
            "X-Amz-Date: {$amzDate}",
            "X-Amz-Target: {$target}",
            "Authorization: {$authHeader}",
        ],
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $res = curl_exec($ch);
    return json_decode($res, true);
}

// 使用
$result = paapiSearch('harry potter');           // 半角スペース OK
$result = paapiSearch('鬼滅 の刃');                // 日本語 + スペース OK
print_r($result);

旧PA-API SDKの例(現行の導入には使わない)

次は旧SDK呼出の断片です。配布物・名前空間・動作成功を確認した現行コードではなく、元コードを比較用に保持しています。Creators APIの導入では公式配布と資格情報を確認してください。

// Amazon 公式 SDK (paapi5-php-sdk) をインストール
// composer require ...

use Amazon\ProductAdvertisingAPI\v1\ApiException;
use Amazon\ProductAdvertisingAPI\v1\api\DefaultApi;
use Amazon\ProductAdvertisingAPI\v1\Configuration;
use Amazon\ProductAdvertisingAPI\v1\com\amazon\paapi5\v1\SearchItemsRequest;

$config = new Configuration();
$config->setAccessKey(getenv('PAAPI_ACCESS_KEY'));
$config->setSecretKey(getenv('PAAPI_SECRET_KEY'));
$config->setHost('webservices.amazon.co.jp');
$config->setRegion('us-west-2');

$api = new DefaultApi(new \GuzzleHttp\Client(), $config);

$req = new SearchItemsRequest();
$req->setPartnerTag('yourtag-22');
$req->setPartnerType('Associates');
$req->setKeywords('harry potter');     // ★ スペースそのまま
$req->setSearchIndex('All');
$req->setItemCount(10);

try {
    $res = $api->searchItems($req);
    foreach ($res->getSearchResult()->getItems() as $item) {
        echo $item->getItemInfo()->getTitle()->getDisplayValue() . "\n";
    }
} catch (ApiException $e) {
    echo $e->getMessage();
}

JS / Node.js

下はJSON文字列とURLの組立てだけの例で、認証・fetch送信・レスポンス処理は実装していません。秘密情報をブラウザーへ渡す例ではありません。

// fetch で直接呼ぶ場合
const body = JSON.stringify({
  Keywords: 'harry potter',     // スペースそのまま
  SearchIndex: 'All',
  ItemCount: 10,
  PartnerTag: 'yourtag-22',
  PartnerType: 'Associates',
  Marketplace: 'www.amazon.co.jp'
});

// URL 構築時にスペースを含めるなら
const url = 'https://example.com/search?q=' + encodeURIComponent('harry potter');
// → ?q=harry%20potter

v4 (旧) でのスペース

古い PA-API v4 は GET メソッドでクエリ文字列に乗せる方式だったので、必ず URL エンコードが必要でした。

GET /onca/xml?Operation=ItemSearch&Keywords=harry%20potter&...
                                          ↑ 必須エンコード

PHP: rawurlencode('harry potter')  → harry%20potter
JS:  encodeURIComponent('harry potter')  → harry%20potter

よくあるトラブル

症状原因対処
SignatureDoesNotMatch署名対象とボディが不一致JSON ボディ完全一致を確認
"+" がそのまま検索されるJSONとフォーム形式の符号化を混用JSON値なら空白のまま。URLクエリなら符号化方式を確認し、リテラルの+を区別
日本語が文字化け入力/出力の文字コードや二重変換を確認Unicodeのエスケープ表記自体は文字化けではない。UTF-8とJSON解析後の値を確認
InvalidParameterValue入力値・型・対象APIの制約を確認根拠なく全API共通の1〜250文字とせず、現行操作の仕様を照合
BadRequestContent-Type ミスapplication/json; charset=utf-8

Lambda からの呼出

Lambda等でも、旧PA-APIキーを現在の商品API認証として流用しないでください。現行のCredential SecretをブラウザーやGitへ出さず、利用する秘密情報保管先・ログ・実行ロールの権限を分けて設計します。秘密値の読取権限と外部APIへの認証は別です。

FAQ

Q: + と %20 どちらが正しい?
A: HTTP 仕様としては URL のパスは %20、フォームの application/x-www-form-urlencoded は +。JSON ボディ内ならエンコード不要のスペース。

Q: Keywords に複数語入れると AND 検索?
A: スペースを保持することと検索の論理・完全一致は別です。引用符を付ければ完全フレーズ検索になるとは断定せず、対象操作の仕様と実際の検索結果で確認してください。

Q: スペースを + で入れたら署名エラー
A: ボディ JSON 内の + はリテラルの「+」として送信されます。スペースの代わりにしないでください。

子ページ

子ページはありません

同階層のページ
  1. アカウントの作成とキーの生成
  2. PA-APIの使い方 リクエストの構造とパラメータの指定
  3. リクエストにスペースを含める方法
  4. 署名認証の方法(PHPサンプル ItemSearch)
  5. エラー一覧
  6. レスポンスの構造(ItemSearch)

最近更新/作成されたページ