README

此仓库不是亚马逊官方PHP库的SP API。

我们反对恐怖主义

2022年2月24日，俄罗斯对乌克兰发动了未经挑衅的战争，并全面入侵。俄罗斯目前正在轰炸和平的乌克兰城市，包括学校和医院，并攻击逃离冲突地区的平民。

2023年10月7日，犹太新年Simchat Torah的全国假日，哈马斯恐怖分子在凌晨对以色列发动袭击，目标是平民。他们释放了暴力，造成至少1,400人死亡，绑架了至少200人，不仅限于以色列人。

为什么选择这个库？

此SDK的主要目标是提供符合亚马逊审计的Amazon SP API SDK。

亚马逊审计可能会发生在必须访问包含PII的API端点的系统中。

目前已有几个适用于PHP的SP API SDK，但其中大部分都带有大量自动生成的代码问题。

硬编码依赖项，如guzzlehttp/guzzle或aws/aws-sdk-php
遗留代码库（7.2）
没有日志记录器
SDK以单个卖家为中心，不适合更大的系统
缺少或缺乏对client_credentials授权类型的支持
没有覆盖所有API
没有扩展

此库的目标是解决上述所有问题。

安装

composer require amazon-php/sp-api-sdk

此库尚未处于稳定阶段，请谨慎使用。

版本

版本已被弃用，因为尝试使亚马逊在Open API规范中使用“标签”进行操作的行为更有意义。这次尝试失败了，为了保持向后兼容的承诺，必须在2.x中引入类名更改。1.0版本将不再更新，请迁移到2.0版本，该版本将与Amazon Models分支3.x保持一致。分支4.x在以下亚马逊API模型中引入了BC breaks

4.x在以下亚马逊API模型中引入了BC breaks

商品列表
报告
供应商
- 直接履行物流
- 直接履行订单
- 直接履行交易

5.x将迁移到2022-04-01版本的目录项API，该版本将替换2020-12-01版本。此外，用于生成关联标识符的uuid被替换为默认使用php内部uniqid()的IdGenerator接口。此更改使我们能够删除一个额外的依赖项。对models/api的模板文件进行了一些小的调整。

6.x在履行入库API以及其他添加和删除方面有所更改。

添加
- 履行入库API v2024-03-20
  - 这是一个重大变更。版本 v2024-03-20 替换了命名空间中的 V0 版本，而 V0 版本的 SDK 现在是 FulfillmentInboundV0SDK，而 V0 模型位于 Model\FulfillmentInboundV0 目录中。
- Amazon 仓储和配送 API v2024-05-09
- 应用程序管理 API v2023-11-30
移除
- 授权 API
- FBA 小型和轻量级 API
  - 您可以使用产品费用 API 和/或相关的 FBA 和推荐费用报告来检索受影响产品的最新费用。

可用的 SDK

SellingPartnerSDK - 所有 SDK 的外观

授权

为了开始使用 SP API，您需要首先注册为开发者并创建应用程序。整个过程在 Amazon 官方指南中有描述。

Amazon 建议在创建应用程序时使用 IAM 角色，但这需要额外的 API 请求来获取访问令牌。使用用户 IAM 更简单，只需确保用户具有以下内联策略即可

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "execute-api:Invoke",
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}

IAM 用户

将刷新令牌更改为访问令牌的示例。

<?php

use AmazonPHP\SellingPartner\OAuth;
use AmazonPHP\SellingPartner\Configuration;
use AmazonPHP\SellingPartner\HttpFactory;
use Buzz\Client\Curl;
use Nyholm\Psr7\Factory\Psr17Factory;
use Psr\Log\NullLogger;

$factory = new Psr17Factory();
$client = new Curl($factory);

$oauth = new OAuth(
    $client,
    $httpFactory = new HttpFactory($factory, $factory),
    $config = Configuration::forIAMUser(
        'lwaClientId',
        'lwaClientIdSecret',
        'awsAccessKey',
        'awsSecretKey'
    ),
    new NullLogger()
);

$accessToken = $oauth->exchangeRefreshToken('seller_oauth_refresh_token');

IAM 角色

<?php

use AmazonPHP\SellingPartner\OAuth;
use AmazonPHP\SellingPartner\Configuration;
use AmazonPHP\SellingPartner\HttpFactory;
use AmazonPHP\SellingPartner\STSClient;
use Buzz\Client\Curl;
use Nyholm\Psr7\Factory\Psr17Factory;
use Psr\Log\NullLogger;

$factory = new Psr17Factory();
$client = new Curl($factory);

$sts = new STSClient(
    $client,
    $requestFactory = $factory,
    $streamFactory = $factory
);

$oauth = new OAuth(
    $client,
    $httpFactory = new HttpFactory($requestFactory, $streamFactory),
    $config = Configuration::forIAMRole(
        'lwaClientID',
        'lwaClientIdSecret',
        $sts->assumeRole(
            'awsAccessKey',
            'awsSecretKey',
            'arn:aws:iam::.........'
        )
    ),
    new NullLogger()
);

$accessToken = $oauth->exchangeRefreshToken('seller_oauth_refresh_token');

开发

此库中 99% 的代码是从 Amazon Selling Partner API 模型自动生成的，使用了 OpenAPI Generator 工具。输出随后由 RectorPHP 自动升级到 PHP 7.4 版本，最终编码标准也由 PHP CS Fixer 自动统一。

要求

为了重新生成代码（例如，当 API 定义更改时），执行以下代码

composer generate

示例

<?php

use AmazonPHP\SellingPartner\Marketplace;
use AmazonPHP\SellingPartner\Regions;
use AmazonPHP\SellingPartner\SellingPartnerSDK;
use Buzz\Client\Curl;
use AmazonPHP\SellingPartner\Exception\ApiException;
use AmazonPHP\SellingPartner\Configuration;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Nyholm\Psr7\Factory\Psr17Factory;

require_once __DIR__ . '/vendor/autoload.php';

$factory = new Psr17Factory();
$client = new Curl($factory);

$configuration = Configuration::forIAMUser(
    'lwaClientId',
    'lwaClientIdSecret',
    'awsAccessKey',
    'awsSecretKey'
);

$logger = new Logger('name');
$logger->pushHandler(new StreamHandler(__DIR__ . '/sp-api-php.log', Logger::DEBUG));

$sdk = SellingPartnerSDK::create($client, $factory, $factory, $configuration, $logger);

$accessToken = $sdk->oAuth()->exchangeRefreshToken('seller_oauth_refresh_token');

try {
    $item = $sdk->catalogItem()->getCatalogItem(
        $accessToken,
        Regions::NORTH_AMERICA,
        $asin = 'B07W13KJZC',
        $marketplaceId = [Marketplace::US()->id()]
    );
    dump($item);
} catch (ApiException $exception) {
    dump($exception->getMessage());
}

日志记录

默认日志级别设置为 DEBUG，但可以在配置中将其更改为任何其他级别，以适用于所有 API 中的所有操作，或者仅适用于特定 API 中的特定操作。

$configuration->setDefaultLogLevel(\Psr\Log\LogLevel::INFO);

也可以排除特定 API 或特定操作进行日志记录（例如，包含 PII 或敏感数据的 API）。

$configuration->setLogLevel(CatalogItemSDK::API_NAME, CatalogItemSDK::OPERATION_GETCATALOGITEM, LogLevel::INFO);
$configuration->setSkipLogging(TokensSDK::API_NAME);
$configuration->setSkipLogging(AuthorizationSDK::API_NAME, AuthorizationSDK::OPERATION_GETAUTHORIZATIONCODE);

最后，您还可以在日志记录 HTTP 请求/响应时忽略特定标头。默认情况下，配置设置为忽略以下敏感授权标头

'authorization',
'x-amz-access-token',
'x-amz-security-token',
'proxy-authorization',
'www-authenticate',
'proxy-authenticate',

您也可以添加自己的忽略标头

$configuration->loggingAddSkippedHeader('some-sensitive-key');

扩展

每个 SDK 允许您注册在发送 API 请求前后执行的自定义扩展。

<?php

$configuration->registerExtension(new class implements \AmazonPHP\SellingPartner\Extension {
    public function preRequest(string $api, string $operation, RequestInterface $request): void
    {
        echo "pre: " . $api . "::" . $operation . " " . $request->getUri() . "\n";
    }

    public function postRequest(string $api, string $operation, RequestInterface $request, ResponseInterface $response): void
    {
        echo "post: " . $api . "::" . $operation . " " . $request->getUri() . " "
            . $response->getStatusCode() . " rate limit: " . implode(' ', $response->getHeader('x-amzn-RateLimit-Limit')) . "\n";
    }
});

沙箱

可以使用配置打开沙箱模式

$configuration->setSandbox();

一些 API 端点在功能测试中进行覆盖。要运行使用沙箱模式的测试，您需要创建 .env 文件并填写您的凭据

cp .env.dist .env

然后，您可以通过执行 composer test:functional 命令来运行沙箱测试套件。

amazon-php / sp-api-sdk

维护者

详细信息