开发人员指南概述

亚马逊广告 API 概览

管理广告活动

注意

广告平台将从 2022 年 9 月开始使用多个广告组的广告活动，取代旧版广告活动创建流程。要检索广告平台中创建的广告活动的完整详情，您需要使用新的 POST /sb/v4/campaigns/list 接口以及适用于报告的 "creativeType": "all" 筛选条件。

点击前往： 广告活动 | 广告组 | 广告 | 创意素材 | 报告

广告活动

版本 4 支持广告活动的创建、更新、读取和删除选项。

获取广告活动的列表

使用 POST /sb/v4/campaigns/list 接口来查看有关广告活动的详细信息。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/v4/campaigns/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxx' \
--header 'Accept: application/vnd.sbcampaignresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "includeExtendedDataFields": true,
  "stateFilter": {
    "include": []
  },
  "nameFilter": {
    "include": [],
    "queryTermMatchType": "BROAD_MATCH"
  },
  "campaignIdFilter": {
    "include": [
      "63665260422798"
    ]
  },
  "maxResults": 10
}'

响应示例

{
  "campaigns": [
    {
      "bidding": {
        "bidOptimizationStrategy": "MAXIMIZE_IMMEDIATE_SALES"
      },
      "budget": 100.0,
      "budgetType": "DAILY",
      "campaignId": "63665260422798",
      "extendedData": {
        "creationDate": 1644332919536,
        "lastUpdateDate": 1644332919536,
        "servingStatus": "CAMPAIGN_INCOMPLETE"
      },
      "isMultiAdGroupsEnabled": true,
      "name": "create campaign test",
      "startDate": "2022-02-08",
      "state": "ENABLED"
    }
  ],
  "totalCount": 1
}

更新广告活动

使用 PUT /sb/v4/campaigns 接口更新多个广告组的广告活动。

请求示例

curl --location --request PUT 'https://advertising-api.amazon.com/sb/v4/campaigns' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxx' \
--header 'Accept: application/vnd.sbcampaignresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '[
  {
    "campaignId": 63665260422798,
    "budget": 50
  }
]'

删除广告活动

使用 POST /sb/v4/campaigns/delete 接口来删除多个广告组的广告活动。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/v4/campaigns/delete' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxx' \
--header 'Accept: application/vnd.sbcampaignresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '[
  {
  "campaignIdFilter": {
    "include": [
      "1234567890"
    ]
  }
}

广告组

获取广告组列表

使用POST /sb/v4/adGroups/list 接口列出您希望更新的广告组。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/v4/adGroups/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxxxx' \
--header 'Accept: application/vnd.sbadgroupresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "includeExtendedDataFields": true,
  "campaignIdFilter": {
    "include": []
  },
  "stateFilter": {
    "include": [
      "ENABLED"
    ]
  },
  "maxResults": 10,
  "adGroupIdFilter": {
    "include": [
    "35407526816553"
    ]
  },
  "nameFilter": {
    "queryTermMatchType": "EXACT_MATCH",
    "include": []
  }
}'

响应示例

{
  "adGroups": [
    {
      "adGroupId": "35407526816553",
      "campaignId": "63665260422798",
      "extendedData": {
        "creationDate": 1644334666767,
        "lastUpdateDate": 1644334666767,
        "servingStatus": "CAMPAIGN_INCOMPLETE"
      },
      "name": "create ad group test 2",
      "state": "ENABLED"
    }
  ],
  "totalResults": 1
}

更新广告组

使用 PUT /sb/v4/adGroups 接口更新广告组状态。

请求示例

curl --location --request PUT 'https://advertising-api.amazon.com/sb/v4/adGroups' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--header 'Accept: application/vnd.sbadgroupresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "adGroups": [
    {
      "adGroupId": "35407526816553",
      "state": "PAUSED",
      "name": "New ad group name",
    }
  ]
}'

响应示例

{
  "adGroups": {
    "error": [],
    "success": [
      {
        "adGroup": {
          "adGroupId": "35407526816553",
          "campaignId": "63665260422798",
          "extendedData": {
            "creationDate": 1644334666767,
            "lastUpdateDate": 1644336561287,
            "servingStatus": "CAMPAIGN_INCOMPLETE"
          },
          "name": "New ad group name",
          "state": "PAUSED"
        },
        "adGroupId": "35407526816553",
        "index": 0
      }
    ]
  }
}

删除广告组

使用 POST /sb/v4/adGroups/delete 接口来对接口进行存档。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/v4/adGroups/delete' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxx' \
--header 'Accept: application/vnd.sbadgroupresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "adGroupIdFilter": {
    "include": [
      "35407526816553"
    ]
  }
}'

响应示例

{
  "adGroups": {
    "error": [],
    "success": [
      {
        "adGroup": {
          "adGroupId": "35407526816553",
          "campaignId": "63665260422798",
          "extendedData": {
            "creationDate": 1644334666767,
            "lastUpdateDate": 1644336599743,
            "servingStatus": "CAMPAIGN_INCOMPLETE"
          },
          "name": "Test campaign",
          "state": "ARCHIVED"
        },
        "adGroupId": "35407526816553",
        "index": 0
      }
    ]
  }
}

广告

获取广告列表

使用 POST /sb/v4/ads/list 接口来获取广告列表。列表接口可返回使用版本 3 和版本 4 创建的广告。

注意

使用版本 3 POST sb/campaigns 接口创建的广告将不包含 adId 或 name。

警告

一些广告主遇到了一个已知的问题，即旧版的创意素材缺少创意素材级别的字段。为确保您收到所有创意素材级别的字段，亚马逊建议您上传最新版本的创意素材。

请求示例：所有广告

curl --location --request POST 'https://advertising-api.amazon.com/sb/v4/ads/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxxxx' \
--header 'Accept: application/vnd.sbadresource.v4+json'

响应示例

在以下响应示例中，第一个返回的广告是作为版本 3 广告活动的一部分创建的，因此它不包含 adId 或广告 name（名称）。第二个广告是作为版本 4 多个广告组的广告活动的一部分创建的，因此它同时包含 adId 和广告 name（名称）。

{
    "ads": [
        {
            "adGroupId": "144346139432941903",
            "campaignId": "144327786111035248",
            "creative": {
                "asins": [
                    "B07R7V6KS8",
                    "B07X2X4D5H",
                    "B003L1717K"
                ],
                "brandLogoAssetID": "amzn1.assetlibrary.asset1.xxxxxxxxxxxx1",
                "brandLogoUrl": "https://m.media-amazon.com/images/S/al-na-184b9306-7f8a/xxxxxxxxxxxxx.png",
                "brandName": "IM Brand",
                "headline": "AA AAA High-Capacity Rechargeable Batteries",
                "type": "PRODUCT_COLLECTION"
            },
            "extendedData": {
                "creationDate": 1635884791000,
                "lastUpdateDate": 1635884791000,
                "servingStatus": "UNKNOWN"
            },
            "landingPage": {
                "pageType": "PRODUCT_LIST",
                "url": "https://development.amazon.com/stores/page/xxxxxxxxxxxxxx"
            },
            "state": "ENABLED"
        },
        {
            "adGroupId": "238010898977121",
            "adId": "7278627757134",
            "campaignId": "177829948461538",
            "creative": {
                "asins": [
                    "B07R7V6KS8"
                ],
                "type": "VIDEO",
                "videoAssetIds": [
                    "amzn1.assetlibrary.asset1.xxxxxxxxxxxxxx"
                ]
            },
            "extendedData": {
                "creationDate": 1665435788770,
                "lastUpdateDate": 1665435791462,
                "servingStatus": "AD_POLICING_PENDING_REVIEW"
            },
            "landingPage": {
                "pageType": "DETAIL_PAGE",
                "url": "https://www.amazon.com/dp/B0000000000"
            },
            "name": "Test video ad",
            "state": "ENABLED"
        }
    ],
    "totalResults": 2
}

请求示例：按 adId 筛选

您可以使用 adId 作为筛选条件以返回特定的广告。

curl --location --request POST 'https://advertising-api.amazon.com/sb/v4/ads/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxxxx' \
--header 'Accept: application/vnd.sbadresource.v4+json' \
--data-raw '
{  
  "maxResults": 10,
  "adIdFilter": {
    "include": [
      "209123071503234", "277277580302345", "158961813536049"
    ]
  }
}'

响应示例

{
    "ads": [
        {
            "adGroupId": "281221120502625",
            "adId": "209123071503234",
            "campaignId": "10391599853578",
            "creative": {
                "asins": [
                    "B00MCW8MGI",
                    "B07BWBQ66J",
                    "B07F6FSDHS"
                ],
                "brandLogoAssetID": "amzn1.assetlibrary.asset1.fcf9b0ad0ac4cfedcd647b53b0f9c14f:version_v1",
                "brandName": "test brand name",
                "headline": "SB v2 product collection ad",
                "type": "PRODUCT_COLLECTION"
            },
            "extendedData": {
                "creationDate": 0,
                "lastUpdateDate": 0
            },
            "landingPage": {
                "pageType": "PRODUCT_LIST",
                "url": "https://development.amazon.com/stores/page/C3769F1F-3A90-4357-8678-258CF10FB46A"
            },
            "name": "test product collection ad",
            "state": "ENABLED"
        },
        {
            "adGroupId": "73487879298399",
            "adId": "277277580302345",
            "campaignId": "10391599853578",
            "creative": {
                "asins": [
                    "B00DLDH1N2"
                ],
                "type": "VIDEO",
                "videoAssetIds": [
                    "amzn1.assetlibrary.asset1.f976557494bbce76a848044e2cf32890:version_v1"
                ]
            },
            "extendedData": {
                "creationDate": 0,
                "lastUpdateDate": 0
            },
            "landingPage": {
                "pageType": "DETAIL_PAGE",
                "url": "https://www.amazon.com/dp/B00DLDH1N2"
            },
            "name": "test video ad",
            "state": "ENABLED"
        },
        {
            "adGroupId": "281221120502625",
            "adId": "158961813536049",
            "campaignId": "10391599853578",
            "creative": {
                "brandLogoAssetID": "amzn1.assetlibrary.asset1.1db463836cdc85be5e5ad73c3b73557c:version_v1",
                "brandName": "Test",
                "headline": "Create new buildings with Lego",
                "subpages": [
                    {
                        "asin": "B005K5GQ9O",
                        "pageTitle": "cool lego buildings with permissions",
                        "url": "https://development.amazon.com/stores/page/DE343B73-427D-4600-B645-338AFA3D36AE"
                    },
                    {
                        "asin": "B00EQ7LZSY",
                        "pageTitle": "lego cars",
                        "url": "https://development.amazon.com/stores/page/EA9BE582-5996-45B6-BD7E-C2BBCEA5668D"
                    },
                    {
                        "asin": "B08F2S3QW5",
                        "pageTitle": "fantasy legos",
                        "url": "https://development.amazon.com/stores/page/B03C3B80-78DA-4978-AECC-3E7A5CE2CDA2"
                    }
                ],
                "type": "STORE_SPOTLIGHT"
            },
            "extendedData": {
                "creationDate": 0,
                "lastUpdateDate": 0
            },
            "landingPage": {
                "pageType": "STORE",
                "url": "https://development.amazon.com/stores/page/B63FC824-E7AF-4B24-B898-83B4B46B3F15"
            },
            "name": "test store spotlight ad",
            "state": "ENABLED"
        }
    ],
    "totalResults": 3
}

更新广告

使用 PUT /sb/v4/ads 接口来更新广告的状态或名称。

请求示例

curl --location --request PUT 'https://advertising-api.amazon.com/sb/v4/ads' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxx' \
--header 'Accept: application/vnd.sbadresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "ads": [
    {
      "adId": "277277580302345",
      "name": "New ad name",
      "state": "PAUSED"
    }
  ]
}

'

响应示例

{
    "ads": {
        "error": [],
        "success": [
            {
                "ad": {
                    "adGroupId": "73487879298399",
                    "adId": "277277580302345",
                    "campaignId": "10391599853578",
                    "creative": {
                        "asins": [
                            "B00DLDH1N2"
                        ],
                        "type": "VIDEO",
                        "videoAssetIds": [
                            "amzn1.assetlibrary.asset1.f976557494bbce76a848044e2cf32890:version_v1"
                        ]
                    },
                    "extendedData": {
                        "creationDate": 0,
                        "lastUpdateDate": 0
                    },
                    "landingPage": {
                        "pageType": "DETAIL_PAGE",
                        "url": "https://www.amazon.com/dp/B00DLDH1N2"
                    },
                    "name": "New ad name",
                    "state": "PAUSED"
                },
                "adId": "277277580302345",
                "index": 0
            }
        ]
    }
}

删除广告

使用 POST /sb/v4/ads/delete 接口来删除广告。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/v4/ads/delete' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxx' \
--header 'Accept: application/vnd.sbadresource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "adIdFilter": {
    "include": [
      "158961813536049"
    ]
  }
}

'

响应示例

{
    "ads": {
        "error": [],
        "success": [
            {
                "ad": {
                    "adGroupId": "281221120502625",
                    "adId": "158961813536049",
                    "campaignId": "10391599853578",
                    "creative": {
                        "brandLogoAssetID": "amzn1.assetlibrary.asset1.1db463836cdc85be5e5ad73c3b73557c:version_v1",
                        "brandName": "Test",
                        "headline": "Create new buildings with Lego",
                        "subpages": [
                            {
                                "asin": "B005K5GQ9O",
                                "pageTitle": "cool lego buildings with permissions",
                                "url": "https://development.amazon.com/stores/page/DE343B73-427D-4600-B645-338AFA3D36AE"
                            },
                            {
                                "asin": "B00EQ7LZSY",
                                "pageTitle": "lego cars",
                                "url": "https://development.amazon.com/stores/page/EA9BE582-5996-45B6-BD7E-C2BBCEA5668D"
                            },
                            {
                                "asin": "B08F2S3QW5",
                                "pageTitle": "fantasy legos",
                                "url": "https://development.amazon.com/stores/page/B03C3B80-78DA-4978-AECC-3E7A5CE2CDA2"
                            }
                        ],
                        "type": "STORE_SPOTLIGHT"
                    },
                    "extendedData": {
                        "creationDate": 0,
                        "lastUpdateDate": 0
                    },
                    "landingPage": {
                        "pageType": "STORE",
                        "url": "https://development.amazon.com/stores/page/B63FC824-E7AF-4B24-B898-83B4B46B3F15"
                    },
                    "name": "test store spotlight ad",
                    "state": "ARCHIVED"
                },
                "adId": "158961813536049",
                "index": 0
            }
        ]
    }
}

创意素材

获取创意素材列表

获取符合给定资源标识符和筛选条件的所有品牌推广创意素材的数组。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/ads/creatives/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer xxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxxxxx' \
--header 'Accept: application/vnd.sbAdCreativeResource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "adId":"6972682587490",
    "maxResults":1
}'

响应示例

{
    "creatives": [{
        "adId": "1234567890",
        "creationTime": 1656026684.349,
        "creativeProperties": {
            "asins": [
                "B0000000001"
            ],
            "brandLogoAssetId": "amzn1.assetlibrary.asset1.abcdefghijklmn:version_v1",
            "brandLogoCrop": {
                "height": 400,
                "left": 0,
                "top": 0,
                "width": 400
            },
            "brandLogoUrl": "https://m.media-amazon.com/images/S/al-na-some0-image.jpeg",
            "brandName": "Test Brand",
            "headline": "Test Headline",
            "landingPage": {
                "type": "STORE",
                "value": "https://www.amazon.com/stores/page/1111111-222222-AAAA-BBBB-333333333333"
            },
          "videoAssetIds": ["amzn1.assetlibrary.asset1.abcdefghijklmn:version_v1"]
        },
        "creativeStatus": "PENDING_FOR_MODERATION",
        "creativeType": "BRAND_VIDEO",
        "creativeVersion": "2"
    }],
    "totalResults": 1
}

更新视频创意素材

通过提供新的视频创意素材内容，为给定的品牌推广视频广告创建现有视频创意素材的新版本。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/ads/creatives/video' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--header 'Accept: application/vnd.sbAdCreativeResource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "adId": "6972682587490",
  "creative": {
    "videoAssetIds": [
      "amzn1.assetlibrary.asset1.abcdefghijklmn:version_v1"
    ]
  }
}'

响应示例

{
    "adId": "1234567890",
    "creativeVersion": "2"
}

更新品牌视频创意素材

通过提供新的视频创意素材内容，为给定的品牌推广的品牌视频广告创建现有视频创意素材的新版本。

请求示例

curl --location --request POST 'https://advertising-api.amazon.com/sb/ads/creatives/brandVideo' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxxx' \
--header 'Authorization: Bearer Atza| xxxxxxxxxxxx' \
--header 'Accept: application/vnd.sbAdCreativeResource.v4+json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "adId": "1234567890",
  "creative": {
    "asins": [
      "B000000001"
    ],
    "brandName": "Test Brand Name",
    "videoAssetIds": [
      "amzn1.assetlibrary.asset1.abcdefghijklmn:version_v1"
    ],
    "brandLogoAssetId": "amzn1.assetlibrary.asset1.abcdefghijklmn:version_v1",
    "headline": "Test Headline"
  }
}'

响应示例

{
    "adId": "1234567890",
    "creativeVersion": "2"
}

报告

使用版本 2 报告接口： POST /v2/hsa/{reportType}/report。

请求体示例

{
    "reportDate": "20220101",
    "creativeType": "all",
    "metrics": "clicks,campaignName,campaignId,adGroupName,adGroupId,adId,impressions,cost,dpv14d,attributedDetailPageViewsClicks14d,attributedOrdersNewToBrand14d,attributedOrdersNewToBrandPercentage14d,attributedOrderRateNewToBrand14d,attributedSalesNewToBrand14d,attributedSalesNewToBrandPercentage14d,attributedUnitsOrderedNewToBrand14d,attributedUnitsOrderedNewToBrandPercentage14d"
}

响应示例

{
    "reportId": "amzn1.clicksAPI.v1.p1.620D5F4E.ba672e9e-0ceb-4982-8bb3-318d90b9a526",
    "recordType": "ad",
    "status": "IN_PROGRESS",
    "statusDetails": "Report is being generated."
}
Amazon Advertising logo