ezerway/amazon-advertising-api-php-sdk
Amazon Advertising API 客户端库
Requires
- php: >=5.3.0
- ext-curl: *
This package is auto-updated.
Last update: 2024-09-13 15:04:11 UTC
README
概述
官方 Amazon Advertising API PHP 客户端库。
此存储库已弃用,将不再接收更新。
要求
PHP >= 7.0.0
cURL >= 7.18
文档
教程
注册沙盒配置文件 - 此教程将展示如何使用 CURL 在沙盒中注册配置文件。
使用 CURL 生成和下载报告 - 在进行此教程之前,您需要先完成在沙盒中注册配置文件。
沙盒自助服务
如果您想测试沙盒中的 API,您需要为想要测试的区域注册一个配置文件。可以通过 registerProfile
API 调用来完成此操作。在调用此之前,请确保在 sandbox
模式下实例化客户端,否则会失败。
以下国家/地区代码可用于测试。
US, CA, UK, DE, FR, ES, IT, IN, CN, JP
$client->registerProfile(array("countryCode" => "IT"));
{
"registerProfileId": "5cf1aca5-4ab8-4489-8c33-013d1f85c586JP",
"status": "IN_PROGRESS",
"statusDetails": "Registration workflow has been started"
}
快速入门
实例化客户端
如果您没有刷新令牌,可以传递
accessToken
。
<?php namespace AmazonAdvertisingApi; require_once "AmazonAdvertisingApi/Client.php"; $config = array( "clientId" => "CLIENT_ID", "clientSecret" => "CLIENT_SECRET", "refreshToken" => "REFRESH_TOKEN", "region" => "na", "sandbox" => false, ); $client = new Client($config);
刷新访问令牌
您可以使用以下方法在访问令牌过期时刷新它。新的访问令牌将在请求响应中。此方法将为您设置它,因此它主要用于参考,如果您需要的话。
$request = $client->doRefreshToken();
获取配置文件列表
$request = $client->listProfiles();
[{
"profileId":1234567890,
"countryCode":"US",
"currencyCode":"USD",
"dailyBudget":10.00,
"timezone":"America/Los_Angeles",
"accountInfo":{
"marketplaceStringId":"ABC123",
"sellerStringId":"DEF456"
}]
设置配置文件 ID
$client->profileId = "1234567890";
一旦设置配置文件 ID,您就可以开始进行 API 调用了。
示例 API 调用
- 配置文件
- 活动
- 广告组
- 可出价关键词
- 否定关键词
- 活动否定关键词
- 产品广告
- 快照
- 报告
- 出价建议
- 关键词建议
getProfile
通过 ID 检索单个配置文件。
$client->getProfile("1234567890");
{
"profileId": 1234567890,
"countryCode": "US",
"currencyCode": "USD",
"dailyBudget": 3.99,
"timezone": "America/Los_Angeles",
"accountInfo": {
"marketplaceStringId": "ABC123",
"sellerStringId": "DEF456"
}
}
updateProfiles
更新一个或多个配置文件。广告商通过其
profileIds
来识别。
$client->updateProfiles( array( array( "profileId" => $client->profileId, "dailyBudget" => 3.99), array( "profileId" => 11223344, "dailyBudget" => 6.00)));
[
{
"code": "SUCCESS",
"profileId": 1234567890
},
{
"code": "NOT_FOUND",
"description": "Profile with id 11223344 was not found for this advertiser.",
"profileId": 0
}
]
listCampaigns
检索满足可选条件的活动列表。
$client->listCampaigns(array("stateFilter" => "enabled"));
[
{
"campaignId": 59836775211065,
"name": "CampaignOne",
"campaignType": "sponsoredProducts",
"targetingType": "manual",
"dailyBudget": 15.0,
"startDate": "20160330",
"state": "enabled"
},
{
"campaignId": 254238342004647,
"name": "CampaignTwo",
"campaignType": "sponsoredProducts",
"targetingType": "manual",
"dailyBudget": 5.0,
"startDate": "20160510",
"state": "enabled"
}
]
getCampaign
通过 ID 检索活动。请注意,此调用返回的最小集合的活动字段,但比
getCampaignEx
更有效率。
$client->getCampaign(1234567890);
{
"campaignId": 1234567890,
"name": "CampaignOne",
"campaignType": "sponsoredProducts",
"targetingType": "manual",
"dailyBudget": 15.0,
"startDate": "20160330",
"state": "enabled"
}
createCampaigns
创建一个或多个推广活动。成功创建的推广活动将被分配唯一的
campaignId
。
$client->createCampaigns( array( array("name" => "My Campaign One", "campaignType" => "sponsoredProducts", "targetingType" => "manual", "state" => "enabled", "dailyBudget" => 5.00, "startDate" => date("Ymd")), array("name" => "My Campaign Two", "campaignType" => "sponsoredProducts", "targetingType" => "manual", "state" => "enabled", "dailyBudget" => 15.00, "startDate" => date("Ymd"))));
[
{
"code": "SUCCESS",
"campaignId": 173284463890123
},
{
"code": "SUCCESS",
"campaignId": 27074907785456
}
]
updateCampaigns
更新一个或多个推广活动。通过它们的
campaignId
来识别推广活动。
$client->updateCampaigns( array( array("campaignId" => 173284463890123, "name" => "Update Campaign One", "state" => "enabled", "dailyBudget" => 10.99), array("campaignId" => 27074907785456, "name" => "Update Campaign Two", "state" => "enabled", "dailyBudget" => 99.99)));
[
{
"code": "SUCCESS",
"campaignId": 173284463890123
},
{
"code": "SUCCESS",
"campaignId": 27074907785456
}
]
archiveCampaign
将推广活动状态设置为已存档。此操作可以通过更新来实现,但包括在此处以示完整。
$client->archiveCampaign(1234567890);
{
"code": "SUCCESS",
"campaignId": 1234567890
}
listAdGroups
检索满足可选条件的广告组列表。
$client->listAdGroups(array("stateFilter" => "enabled"));
[
{
"adGroupId": 262960563101486,
"name": "AdGroup One",
"campaignId": 181483024866689,
"defaultBid": 1.0,
"state": "enabled"
},
{
"adGroupId": 52169162825843,
"name": "AdGroup Two",
"campaignId": 250040549047739,
"defaultBid": 2.0,
"state": "enabled"
}
]
getAdGroup
通过 Id 检索广告组。请注意,此调用返回了广告组的最小字段集,但比
getAdGroupEx
更有效率。
$client->getAdGroup(262960563101486);
{
"adGroupId": 262960563101486,
"name": "AdGroup One",
"campaignId": 181483024866689,
"defaultBid": 1.0,
"state": "enabled"
}
createAdGroups
创建一个或多个广告组。成功创建的广告组将被分配唯一的
adGroupId
。
$client->createAdGroups( array( array( "campaignId" => 250040549047739, "name" => "New AdGroup One", "state" => "enabled", "defaultBid" => 2.0), array( "campaignId" => 59836775211065, "name" => "New AdGroup Two", "state" => "enabled", "defaultBid" => 5.0)));
[
{
"code": "SUCCESS",
"adGroupId": 117483076163518
},
{
"code": "SUCCESS",
"adGroupId": 123431426718271
}
]
updateAdGroups
更新一个或多个广告组。通过它们的
adGroupId
来识别广告组。
$client->updateAdGroups( array( array( "adGroupId" => 117483076163518, "state" => "enabled", "defaultBid" => 20.0), array( "adGroupId" => 123431426718271, "state" => "enabled", "defaultBid" => 15.0)));
[
{
"code": "SUCCESS",
"adGroupId": 117483076163518
},
{
"code": "SUCCESS",
"adGroupId": 123431426718271
}
]
archiveAdGroup
将广告组状态设置为已存档。此操作可以通过更新来实现,但包括在此处以示完整。
$client->archiveAdGroup(117483076163518);
{
"code": "SUCCESS",
"adGroupId": 117483076163518
}
listBiddableKeywords
检索满足可选条件的关键词列表。
$client->listBiddableKeywords(array("stateFilter" => "enabled"));
[
{
"keywordId": 174140697976855,
"adGroupId": 52169162825843,
"campaignId": 250040549047739,
"keywordText": "KeywordOne",
"matchType": "exact",
"state": "enabled"
},
{
"keywordId": 118195812188994,
"adGroupId": 52169162825843,
"campaignId": 250040549047739,
"keywordText": "KeywordTwo",
"matchType": "exact",
"state": "enabled"
}
]
getBiddableKeyword
通过 Id 检索关键词。请注意,此调用返回了关键词的最小字段集,但比 getBiddableKeywordEx 更有效率。
$client->getBiddableKeyword(174140697976855);
{
"keywordId": 174140697976855,
"adGroupId": 52169162825843,
"campaignId": 250040549047739,
"keywordText": "KeywordOne",
"matchType": "exact",
"state": "enabled"
}
createBiddableKeywords
创建一个或多个关键词。成功创建的关键词将被分配唯一的
keywordId
。
$client->createBiddableKeywords( array( array( "campaignId" => 250040549047739, "adGroupId" => 52169162825843, "keywordText" => "AnotherKeyword", "matchType" => "exact", "state" => "enabled"), array( "campaignId" => 250040549047739, "adGroupId" => 52169162825843, "keywordText" => "YetAnotherKeyword", "matchType" => "exact", "state" => "enabled")));
[
{
"code": "SUCCESS",
"keywordId": 112210768353976
},
{
"code": "SUCCESS",
"keywordId": 249490346605943
}
]
updateBiddableKeywords
更新一个或多个关键词。通过它们的
keywordId
来识别关键词。
$client->updateBiddableKeywords( array( array( "keywordId" => 112210768353976, "bid" => 100.0, "state" => "archived"), array( "keywordId" => 249490346605943, "bid" => 50.0, "state" => "archived")));
[
{
"code": "SUCCESS",
"keywordId": 112210768353976
},
{
"code": "SUCCESS",
"keywordId": 249490346605943
}
]
archiveBiddableKeyword
将关键词状态设置为已存档。此操作可以通过更新来实现,但包括在此处以示完整。
$client->archiveBiddableKeyword(112210768353976);
{
"code": "200",
"requestId": "0TR95PJD6Z16FFCZDXD0"
}
listNegativeKeywords
检索满足可选条件的否定关键词列表。
$client->listNegativeKeywords(array("stateFilter" => "enabled"));
[
{
"keywordId": 281218602770639,
"adGroupId": 52169162825843,
"campaignId": 250040549047739,
"keywordText": "KeywordOne",
"matchType": "negativeExact",
"state": "enabled"
},
{
"keywordId": 280875877064090,
"adGroupId": 262960563101486,
"campaignId": 181483024866689,
"keywordText": "KeywordTwo",
"matchType": "negativeExact",
"state": "enabled"
}
]
getNegativeKeyword
通过 Id 检索否定关键词。请注意,此调用返回了关键词的最小字段集,但比
getNegativeKeywordEx
更有效率。
$client->getNegativeKeyword(281218602770639);
{
"keywordId": 281218602770639,
"adGroupId": 52169162825843,
"campaignId": 250040549047739,
"keywordText": "KeywordOne",
"matchType": "negativeExact",
"state": "enabled"
}
createNegativeKeywords
创建一个或多个否定关键词。成功创建的关键词将被分配唯一的 keywordIds。
$client->createNegativeKeywords( array( array( "campaignId" => 250040549047739, "adGroupId" => 52169162825843, "keywordText" => "AnotherKeyword", "matchType" => "negativeExact", "state" => "enabled"), array( "campaignId" => 181483024866689, "adGroupId" => 262960563101486, "keywordText" => "YetAnotherKeyword", "matchType" => "negativeExact", "state" => "enabled")));
[
{
"code": "SUCCESS",
"keywordId": 61857817062026
},
{
"code": "SUCCESS",
"keywordId": 147623067066967
}
]
updateNegativeKeywords
更新一个或多个否定关键词。通过它们的
keywordId
来识别关键词。
$client->updateNegativeKeywords( array( array( "keywordId" => 61857817062026, "state" => "enabled", "bid" => 15.0), array( "keywordId" => 61857817062026, "state" => "enabled", "bid" => 20.0)));
[
{
"code": "SUCCESS",
"keywordId": 61857817062026
},
{
"code": "INVALID_ARGUMENT",
"description": "Entity with id 61857817062026 already specified in this update operation."
}
]
archiveNegativeKeyword
将否定关键词状态设置为已存档。此操作可以通过更新状态来实现,但包括在此处以示完整。
$client->archiveNegativeKeyword(61857817062026);
{
"code": "SUCCESS",
"keywordId": 61857817062026
}
listCampaignNegativeKeywords
检索满足可选条件的否定推广活动关键词列表。
$client->listCampaignNegativeKeywords(array("matchTypeFilter" => "negativeExact"));
[
{
"keywordId": 131747786239884,
"adGroupId": null,
"campaignId": 181483024866689,
"keywordText": "Negative Keyword",
"matchType": "negativeExact",
"state": "enabled"
},
{
"keywordId": 197201372210821,
"adGroupId": null,
"campaignId": 181483024866689,
"keywordText": "My Negative Keyword",
"matchType": "negativeExact",
"state": "enabled"
}
]
getCampaignNegativeKeyword
通过 Id 检索推广活动否定关键词。请注意,此调用返回了关键词的最小字段集,但比
getCampaignNegativeKeywordEx
更有效率。
$client->getCampaignNegativeKeyword(197201372210821);
{
"keywordId": 197201372210821,
"adGroupId": null,
"campaignId": 181483024866689,
"keywordText": "My Negative Keyword",
"matchType": "negativeExact",
"state": "enabled"
}
createCampaignNegativeKeywords
创建一个或多个推广活动否定关键词。成功创建的关键词将被分配唯一的
keywordId
。
$client->createCampaignNegativeKeywords( array( array( "campaignId" => 181483024866689, "keywordText" => "Negative Keyword One", "matchType" => "negativeExact", "state" => "enabled"), array( "campaignId" => 181483024866689, "keywordText" => "Negative Keyword Two", "matchType" => "negativeExact", "state" => "enabled")));
[
{
"code": "SUCCESS",
"keywordId": 196797670902082
},
{
"code": "SUCCESS",
"keywordId": 186203479904657
}
]
updateCampaignNegativeKeywords
更新一个或多个推广活动否定关键词。通过它们的
keywordId
来识别关键词。
目前只能移除推广活动否定关键词。
removeCampaignNegativeKeyword
将推广活动否定关键词状态设置为已删除。此操作可以通过更新状态来实现,但包括在此处以示完整。
$client->removeCampaignNegativeKeyword(186203479904657);
{
"code": "SUCCESS",
"keywordId": 186203479904657
}
listProductAds
检索满足可选条件的商品广告列表。
$client->listProductAds(array("stateFilter" => "enabled"));
[
{
"adId": 247309761200483,
"adGroupId": 262960563101486,
"campaignId": 181483024866689,
"sku": "TEST001",
"state": "enabled"
}
]
getProductAd
通过 Id 检索商品广告。请注意,此调用返回了商品广告的最小字段集,但比
getProductAdEx
更有效率。
$client->getProductAd(247309761200483);
{
"adId": 247309761200483,
"adGroupId": 262960563101486,
"campaignId": 181483024866689,
"sku": "TEST001",
"state": "enabled"
}
createProductAds
创建一个或多个商品广告。成功创建的商品广告将被分配唯一的
adId
。
$client->createProductAds( array( array( "campaignId" => 181483024866689, "adGroupId" => 262960563101486, "sku" => "TEST002", "state" => "enabled"), array( "campaignId" => 181483024866689, "adGroupId" => 262960563101486, "sku" => "TEST003", "state" => "enabled")));
[
{
"code": "SUCCESS",
"adId": 239870616623537
},
{
"code": "SUCCESS",
"adId": 191456410590622
}
]
updateProductAds
更新一个或多个商品广告。通过它们的
adId
来识别商品广告。
$client->updateProductAds( array( array( "adId" => 239870616623537, "state" => "archived"), array( "adId" => 191456410590622, "state" => "archived")));
[
{
"code": "SUCCESS",
"adId": 239870616623537
},
{
"code": "SUCCESS",
"adId": 191456410590622
}
]
archiveProductAd
将商品广告状态设置为已存档。此操作可以通过更新来实现,但包括在此处以示完整。
$client->archiveProductAd(239870616623537);
{
"code": "SUCCESS",
"adId": 239870616623537
}
requestSnapshot
请求单个类型所有实体的快照报告。
$client->requestSnapshot( "campaigns", array("stateFilter" => "enabled,paused,archived", "campaignType" => "sponsoredProducts"));
{
"snapshotId": "amzn1.clicksAPI.v1.p1.573A0477.ec41773a-1659-4013-8eb9-fa18c87ef5df",
"recordType": "campaign",
"status": "IN_PROGRESS"
}
getSnapshot
检索先前请求的报告。
$client->getSnapshot("amzn1.clicksAPI.v1.p1.573A0477.ec41773a-1659-4013-8eb9-fa18c87ef5df");
[
{
"campaignId": 181483024866689,
"name": "Campaign One",
"campaignType": "sponsoredProducts",
"targetingType": "manual",
"dailyBudget": 5.0,
"startDate": "20160330",
"state": "archived"
},
{
"campaignId": 59836775211065,
"name": "Campaign Two",
"campaignType": "sponsoredProducts",
"targetingType": "manual",
"dailyBudget": 10.99,
"startDate": "20160330",
"state": "archived"
},
{
"campaignId": 254238342004647,
"name": "Campaign Three",
"campaignType": "sponsoredProducts",
"targetingType": "manual",
"dailyBudget": 99.99,
"startDate": "20160510",
"state": "enabled"
}
]
requestReport
请求单个类型所有具有性能数据的实体的定制性能报告。
$client->requestReport( "campaigns", array("reportDate" => "20160515", "campaignType" => "sponsoredProducts", "metrics" => "impressions,clicks,cost"));
{
"reportId": "amzn1.clicksAPI.v1.m1.573A0808.32908def-66a1-4ce2-8f12-780dc4ae1d43",
"recordType": "campaign",
"status": "IN_PROGRESS",
"statusDetails": "Report is submitted"
}
getReport
检索先前请求的报告。
$client->getReport("amzn1.clicksAPI.v1.m1.573A0808.32908def-66a1-4ce2-8f12-780dc4ae1d43");
沙盒将返回虚拟数据。
[
{
"cost": 647.75,
"campaignId": 230751293360275,
"clicks": 2591,
"impressions": 58288
},
{
"cost": 619.5,
"campaignId": 52110033002744,
"clicks": 2478,
"impressions": 68408
},
{
"cost": 151.91,
"campaignId": 140739567440917,
"clicks": 633,
"impressions": 17343
},
{
"cost": 143.46,
"campaignId": 79132327246328,
"clicks": 797,
"impressions": 48903
}
]
requestReportV3
请求单个类型所有具有性能数据的实体的定制性能报告。
$client->requestReportV3( json_encode('{ "name":"SP purchased product report 8/13-8/13", "startDate":"2023-08-13", "endDate":"2023-08-13", "configuration":{ "adProduct":"SPONSORED_PRODUCTS", "groupBy":["asin"], "columns":["purchasedAsin","advertisedAsin","adGroupName","campaignName","sales14d","campaignId","adGroupId","keywordId","keywordType","keyword"], "reportTypeId":"spPurchasedProduct", "timeUnit":"SUMMARY", "format":"GZIP_JSON" } }'));
{
"reportId": "4d23db55-3837-4599-8b61-7dc87a6b1ffb",
"recordType": "campaign",
"status": "IN_PROGRESS",
"statusDetails": "Report is submitted"
}
getReportV3
检索先前请求的报告。
$client->getReportV3("4d23db55-3837-4599-8b61-7dc87a6b1ffb");
沙盒将返回虚拟数据。
{
"reportId": "4d23db55-3837-4599-8b61-7dc87a6b1ffb",
"status": "COMPLETED",
"url": "https://offline-report-storage-us-east-1-prod.s3.amazonaws.com"
}
getAdGroupBidRecommendations
请求指定广告组的出价建议。
$client->getAdGroupBidRecommendations(1234509876);
{
"adGroupId": 1234509876,
"suggestedBid": {
"rangeEnd": 2.16,
"rangeStart": 0.67,
"suggested": 1.67
}
}
getKeywordBidRecommendations
请求指定关键词的出价建议。
$client->getKeywordBidRecommendations(85243141758914);
{
"keywordId": 85243141758914,
"adGroupId": 252673310548066,
"suggestedBid": {
"rangeEnd": 3.18,
"rangeStart": 0.35,
"suggested": 2.97
}
}
bulkGetKeywordBidRecommendations
请求最多 100 个关键词的出价建议。
$client->bulkGetKeywordBidRecommendations( 242783265349805, array( array("keyword" => "testKeywordOne", "matchType" => "exact"), array("keyword" => "testKeywordTwo", "matchType" => "exact") ));
{
"adGroupId": 242783265349805,
"recommendations": [
{
"code": "SUCCESS",
"keyword": "testKeywordOne",
"matchType": "exact",
"suggestedBid": {
"rangeEnd": 2.67,
"rangeStart": 0.38,
"suggested": 2.07
}
},
{
"code": "SUCCESS",
"keyword": "testKeywordTwo",
"matchType": "exact",
"suggestedBid": {
"rangeEnd": 3.19,
"rangeStart": 0.79,
"suggested": 3.03
}
}
]
}
getAdGroupKeywordSuggestions
请求指定广告组的关键词建议。
$client->getAdGroupKeywordSuggestions( array("adGroupId" => 1234567890, "maxNumSuggestions" => 2, "adStateFilter" => "enabled"));
{
"adGroupId": 1234567890,
"suggestedKeywords": [
{
"keywordText": "keyword PRODUCT_AD_A 1",
"matchType": "broad"
},
{
"keywordText": "keyword PRODUCT_AD_B 1",
"matchType": "broad"
}
]
}
getAdGroupKeywordSuggestionsEx
请求指定广告组的关键词建议,扩展版本。增加了返回关键词的出价建议的能力。
$client->getAdGroupKeywordSuggestionsEx( array("adGroupId" => 1234567890, "maxNumSuggestions" => 2, "suggestBids" => "yes", "adStateFilter" => "enabled"));
[
{
"adGroupId": 1234567890,
"campaignId": 0987654321,
"keywordText": "keyword TESTASINXX 1",
"matchType": "broad",
"state": "enabled",
"bid": 1.84
},
{
"adGroupId": 1234567890,
"campaignId": 0987654321,
"keywordText": "keyword TESTASINXX 2",
"matchType": "broad",
"state": "enabled",
"bid": 1.07
}
]
getAsinKeywordSuggestions
请求指定 asin 的关键词建议。
$client->getAsinKeywordSuggestions( array("asin" => "B00IJSNPM0", "maxNumSuggestions" => 2));
[
{
"keywordText": "keyword B00IJSNPM0 1",
"matchType": "broad"
},
{
"keywordText": "keyword B00IJSNPM0 2",
"matchType": "broad"
}
]
bulkGetAsinKeywordSuggestions
请求对asin列表的建议关键词。
$client->bulkGetAsinKeywordSuggestions( array("asins" => array( "B00IJSNPM0", "B00IJSO1NM"), "maxNumSuggestions" => 2));
[
{
"keywordText": "keyword B00IJSNPM0 1",
"matchType": "broad"
},
{
"keywordText": "keyword B00IJSO1NM 1",
"matchType": "broad"
}
]