AWS Marketplace
针对 AWS Marketplace 提供商的用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS Marketplace Commerce Analytics Service

使用 AWS Marketplace Commerce Analytics Service,您可以通过 AWS Marketplace 以编程方式访问产品和客户数据。一旦您注册服务,就可以通过 AWS 开发工具包查看自己的使用情况、订阅以及账单报告。


        Commerce Analytics Service Overview

您使用开发工具包工具请求的数据以数据集的形式传输到 AWS 账户。大多数数据集对应的数据与 AWS Marketplace Management Portal 上提供的基于文本的报告相同。您可以请求特定日期的数据集,该数据将传输到所提供的 Amazon S3 存储桶。数据传输通知由 Amazon Simple Notification Service (Amazon SNS) 提供。

条款和条件

这些 AWS Marketplace Commerce Analytics Service 条款和条件(以下简称这些“CAS 条款”)包含与您使用和访问 AWS Marketplace Commerce Analytics Service(“CA 服务”)有关的特定条款和条件,从您单击随这些 CAS 条款显示的“I Accept (我接受)”按钮或复选框之日起生效,或者在更早的时候使用任何 CA 服务时生效。这些 CAS 条款是对您与 Amazon Web Services, Inc.(“AWS”、“我们”或“我们的)之间签订的 AWS Marketplace 卖家条款和条件(“AWS Marketplace 卖家条款”)的补充,因此,我们在此处包含其中的条款。在这些 CAS 条款与 AWS Marketplace 卖家条款发生冲突时,这些 CAS 条款的条款和条件适用,但仅限于发生此类冲突和使用 CA 服务的场合。此处使用但未定义的大写术语具有 AWS Marketplace 卖家条款中规定的含义。

  1. CA 服务和 CAS 数据。 要具备访问 CA 服务的资格,您必须是受现有 AWS Marketplace 卖家条款约束的 AWS Marketplace 卖家。您收到或有权访问的 CA 服务相关的信息和数据(“CAS 数据”)构成了订阅者信息,并受 AWS Marketplace 卖家条款中规定的限制和义务的约束。您可以在保密的基础上使用 CAS 数据改进和精确定位与您的 AWS Marketplace 内容相关的营销和其他促销活动,但前提是您不会 (a) 向任何第三方披露 CAS 数据;(b) 以不符合适用隐私政策或法律的任何方式使用任何 CAS 数据;(c) 联系订阅者以施加影响,以使他们在 AWS Marketplace 外部购买替代产品;(d) 贬低我们、我们的附属公司或者他们或我们的任何相应产品;或 (e) 将 AWS Marketplace 订阅者作为任何种类的沟通的预期接收方。

  2. CA 服务限制和安全性。 您仅通过 CA 服务文档中所述的方法访问(或尝试访问)CA 服务。在使用 CA 服务时,您不会歪曲或掩盖您的身份或您的客户身份。我们保留权利对您使用 CA 服务设置和实施限制 (由我们自行决定),包括但不限于在任何时间段内允许访问 CA 服务的连接、调用和服务器数。您同意并且不会尝试绕过这些限制。如果我们认为您可能违反了这些 CAS 条款或滥用了 CA 服务,我们保留权利限制、暂停或终止您访问 CA 服务的权利。

  3. CA 服务凭证保密性和安全性。 CA 服务凭证(如密码、密钥和客户端 ID)供您在识别您的 API 客户端时使用。应由您全权负责保证您的凭证的机密性,并采取一切合理的措施以避免泄露、传播或未经授权使用此类凭证,至少包括您为保护自己的类似性质的机密信息而采取的措施。CA 服务凭证不得嵌入在开源项目中。应由您全权负责使用您的凭证对 CA 服务进行的任何和所有访问。

  4. 修改。 我们可能会随时在 AWS 网站上发布修订的版本,或者根据 AWS Marketplace 卖家条款向您提供通知以修改这些 CAS 条款。修改的条款将在发布后生效,或者如果我们通过电子邮件通知您,则在电子邮件中指定的日期生效。在对这些 CAS 条款进行的任何修改的生效日期后,一经继续使用或访问 CA 服务,即表示您同意受修改的条款的约束。

  5. 终止。 在由于任何原因终止您的 AWS Marketplace 卖家条款后,这些 CAS 条款以及在此处授予的 CAS 数据使用权利将会终止,可能会通知您,也可能不会。此外,我们可能还会随时由于任何原因或无任何理由停止提供 CA 服务或终止您对 CA 服务的访问。

信息载入指南

您必须配置 AWS 账户和 AWS 服务来使用 AWS Marketplace Commerce Analytics Service。首先,使用正确权限配置 AWS 账户。接下来,配置要将数据传输到的 Amazon S3 存储桶。最后,配置 Amazon SNS 以在传输数据时发送通知。

AWS Marketplace 强烈建议使用 IAM 角色登录到 AWS Marketplace Management Portal,而不是使用您的根账户凭证。请参阅 AWS Marketplace Management Portal 权限 以了解 AWS Marketplace Commerce Analytics Service 权限的特定 AIM 权限。有关详细信息,请参阅创建 IAM 用户。在为访问您的账户的人员创建单独的 IAM 用户时,您可授予每个 IAM 用户一组独特的安全凭证。您还可向每个 IAM 用户授予不同的权限。如有必要,您可随时更改或撤销 IAM 用户的权限。

创建目标 Amazon S3 存储桶

Commerce Analytics Service 将请求的数据传输到您指定的 Amazon S3 存储桶。如果您没有 Amazon S3 存储桶,或者希望为此数据专门创建新 Amazon S3 存储桶,可以查看如何创建 S3 存储桶中的指南。如果您已有 Amazon S3 存储桶可供使用,请继续到下一个步骤。

创建用于响应通知的 Amazon SNS 主题

Commerce Analytics Service 使用 Amazon SNS 传输响应通知。在您的数据集可用或者出错时,该服务发布消息到此主题来通知您。如果您没有为此服务配置 Amazon SNS 主题,请立即配置一个。如需指南,请查看创建主题。如果您已有 Amazon SNS 主题用于此用途,请继续到下一步。

记录您所创建主题的主题 Amazon 资源名称 (ARN),调用服务时需要此信息。

注册到 Commerce Analytics Service 计划

在您使用主题的 ARN 和存储桶的名称配置服务之后,Commerce Analytics Service 会访问 Amazon S3 存储桶和 Amazon SNS 主题。

启用访问

  1. 使用您用于管理 AWS Marketplace 产品的 AWS 账户登录 AWS Marketplace Management Portal

  2. 导航到 Commerce Analytics Service 注册页面

  3. 输入 Amazon S3 存储桶名称和 Amazon SNS 主题 ARN,然后选择 Enroll (注册)

  4. 在权限页面上,选择 Allow (允许)

  5. 在 AWS Marketplace Management Portal 上,记录成功消息中的 Role Name ARN (角色名称 ARN)。您将需要使用它来调用服务。

验证配置

现在,您已完成了配置来使用 AWS Marketplace Commerce Analytics Service,接下来应验证它。

测试配置

  1. 下载、安装和配置 AWS 命令行界面 (AWS CLI)。

  2. 使用 AWS CLI 执行此命令:

    aws marketplacecommerceanalytics generate-data-set \ --data-set-type "customer_subscriber_hourly_monthly_subscriptions" \ --data-set-publication-date "{TODAY'S-DATE}" \ --role-name-arn "{YOUR-ROLE-NAME-ARN}" \ --destination-s3-bucket-name "{YOUR-S3-BUCKET}" \ --destination-s3-prefix "test-prefix" \ --sns-topic-arn "{YOUR-SNS-TOPIC-ARN}"
  • 对于 --data-set-publication-date,使用 ISO-8601 格式 ({TODAY'S DATE}) 的当前日期替换 YYYY-MM-DDT00:00:00Z,其中 YYYY 是四位数的年份,MM 是两位数的月份,DD 是两位数的天。

  • 对于 --role-name-arn,使用您在第 5 步:注册到 Commerce Analytics Service 计划的注册过程中收到的角色 ARN 替换 {YOUR-ROLE-NAME-ARN}

  • 对于 --destination-s3-bucket-name,使用您在第 2 步:创建目标 Amazon S3 存储桶中创建的 Amazon S3 存储桶替换 {YOUR-S3-BUCKET}

  • 对于 –sns-topic-arn,使用您在第 3 步:创建 Amazon SNS 主题中创建的 Amazon SNS 主题替换 {YOUR-SNS-TOPIC-ARN}

如果您从服务收到包含 dataSetRequestId 的响应,则您已成功完成信息载入过程。成功的响应类似于以下内容:

{ "dataSetRequestId": "646dd4ed-6806-11e5-a6d8-fd5dbcaa74ab" }

技术实施指南

AWS Marketplace Commerce Analytics Service 通过 AWS 开发工具包提供。本指南演示如何使用 AWS CLIAWS SDK for Java 与服务交互。

使用 AWS CLI 发出请求

首先,请下载 AWS CLI。以下 AWS CLI 示例针对 2017 年 10 月 1 日每小时/每月订阅数据集发出请求。此数据集将使用前缀 demo-prefix 发布到 demo-bucket Amazon S3 存储桶,而通知消息将传输到 demo-topic Amazon SNS 主题。

aws marketplacecommerceanalytics generate-data-set \ --data-set-type "customer_subscriber_hourly_monthly_subscriptions" \ --data-set-publication-date "2017-10-01T00:00:00Z" \ --role-name-arn "arn:aws:iam::123412341234:role/MarketplaceCommerceAnalyticsRole" \ --destination-s3-bucket-name "demo-bucket" \ --destination-s3-prefix "demo-prefix" \ --sns-topic-arn "arn:aws:sns:us-west-2:123412341234:demo-topic"

此请求返回对每个请求唯一的标识符。您可以使用此标识符将请求与发布到 Amazon SNS 主题的通知关联。以下是此标识符的示例。

{ "dataSetRequestId": "646dd4ed-6806-11e5-a6d8-fd5dbcaa74ab" }

使用 AWS SDK for Java 发出请求

要开始,请下载 AWS Java 开发工具包。以下 AWS SDK for Java 示例针对 2015 年 10 月 1 日每小时/每月订阅数据集发出请求。此数据集将使用前缀 demo-prefix 发布到 demo-bucket Amazon S3 存储桶,而通知消息将传输到 demo-topic Amazon SNS 主题。

/* * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. * A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either * express or implied. See the License for the specific language governing * permissions and limitations under the License. */ import java.text.DateFormat; import java.text.ParseException; import java.text.SimpleDateFormat; import java.util.Date; import java.util.TimeZone; import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Region; import com.amazonaws.regions.Regions; import com.amazonaws.services.marketplacecommerceanalytics.AWSMarketplaceCommerceAnalyticsClient; import com.amazonaws.services.marketplacecommerceanalytics.model.GenerateDataSetRequest; import com.amazonaws.services.marketplacecommerceanalytics.model.GenerateDataSetResult; /** * This sample demonstrates how to make basic requests to the AWS Marketplace Commerce * Analytics service using the AWS SDK for Java. * <p> * <b>Prerequisites:</b> Follow the on-boarding guide: {URL OR SOMETHING} * <p> * Fill in your AWS access credentials in the provided credentials file * template, and be sure to move the file to the default location * (~/.aws/credentials) where the sample code will load the credentials from. * <p> * <b>WARNING:</b> To avoid accidental leakage of your credentials, DO NOT keep * the credentials file in your source directory. * <p> * http://aws.amazon.com/security-credentials */ public class MarketplaceCommerceAnalyticsSample { public static void main(String[] args) throws ParseException { /* * The ProfileCredentialsProvider will return your [default] * credential profile by reading from the credentials file located at * (~/.aws/credentials). */ AWSCredentials credentials = null; try { credentials = new ProfileCredentialsProvider().getCredentials(); } catch (Exception e) { throw new AmazonClientException("Cannot load the credentials from the credential profiles " + "file. Please make sure that your credentials file is at the correct " + "location (~/.aws/credentials), and is in valid format.", e); } AWSMarketplaceCommerceAnalyticsClient client = new AWSMarketplaceCommerceAnalyticsClient(credentials); Region usEast1 = Region.getRegion(Regions.US_EAST_1); client.setRegion(usEast1); System.out.println("==============================================================="); System.out.println("Getting Started with AWS Marketplace Commerce Analytics Service"); System.out.println("===============================================================\n"); // Create a data set request with the desired parameters GenerateDataSetRequest request = new GenerateDataSetRequest(); request.setDataSetType("customer_subscriber_hourly_monthly_subscriptions"); request.setDataSetPublicationDate(convertIso8601StringToDateUtc("2014-06-09T00:00:00Z")); request.setRoleNameArn("arn:aws:iam::864545609859:role/MarketplaceCommerceAnalyticsRole"); request.setDestinationS3BucketName("awsmp-goldmine-seller"); request.setDestinationS3Prefix("java-sdk-test"); request.setSnsTopicArn("arn:aws:sns:us-west-2:864545609859:awsmp-goldmine-seller-topic"); System.out.println( String.format("Creating a request for data set %s for publication date %s.", request.getDataSetType(), request.getDataSetPublicationDate())); try { // Make the request to the service GenerateDataSetResult result = client.generateDataSet(request); // The Data Set Request ID is a unique identifier that you can use to correlate the // request with responses on your Amazon SNS topic System.out.println("Request successful, unique ID: " + result.getDataSetRequestId()); } catch (AmazonServiceException ase) { System.out.println("Caught an AmazonServiceException, which means your request made it " + "to the AWS Marketplace Commerce Analytics service, but was rejected with an " + "error response for some reason."); System.out.println("Error Message: " + ase.getMessage()); System.out.println("HTTP Status Code: " + ase.getStatusCode()); System.out.println("AWS Error Code: " + ase.getErrorCode()); System.out.println("Error Type: " + ase.getErrorType()); System.out.println("Request ID: " + ase.getRequestId()); } catch (AmazonClientException ace) { System.out.println("Caught an AmazonClientException, which means the client encountered " + "a serious internal problem while trying to communicate with the AWS Marketplace" + "Commerce Analytics service, such as not being able to access the " + "network."); System.out.println("Error Message: " + ace.getMessage()); } } private static Date convertIso8601StringToDateUtc(String dateIso8601) throws ParseException { TimeZone utcTimeZone = TimeZone.getTimeZone("UTC"); DateFormat utcDateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssX"); utcDateFormat.setTimeZone(utcTimeZone); return utcDateFormat.parse(dateIso8601); } }

您应该预期看与此示例类似的结果。

=============================================================== Getting Started with AWS Marketplace Commerce Analytics Service =============================================================== Creating a request for data set customer_subscriber_hourly_monthly_subscriptions for publication date Sun Jun 08 17:00:00 PDT 2014. Request successful, unique ID: c59aff81-6875-11e5-a6d8-fd5dbcaa74ab

技术文档

该服务公开了一个方法 GenerateDataSet,您可以使用该方法请求将数据集发布到 Amazon S3 存储桶。下表中列出了 GenerateDataSet 的参数。

数据集参数

字段 描述
数据集类型 此数据集将作为请求的结果返回。
数据集发布日期

发布数据集的日期。

对于每日数据集,请提供在所需日期具有天级别粒度的日期。

对于每月数据集,请提供在所需月具有月级别粒度的日期。忽略天值。

角色名称 ARN 角色的 ARN,该角色附加了用于向服务提供对您资源的访问权限的权限策略。
目标 Amazon S3 存储桶名称 目标 Amazon S3 存储桶的名称(易于识别的名称,而非 ARN)。您的数据集将发布到此位置。
目标 Amazon S3 前缀

(可选)已发布数据集所需的 Amazon S3 前缀,类似于标准文件系统中的目录路径。

例如,如果给定存储桶名称 mybucket 以及前缀 myprefix/mydatasets,则输出文件将发布到 s3://mybucket/myprefix/mydatasets/outputfile

如果前缀目录结构不存在,则会自动创建。

如果没有提供前缀,数据集将发布到 Amazon S3 存储桶根。

SNS 主题 ARN

在发布数据集或者出现错误时,需要通知的 Amazon SNS 主题的 ARN。

响应

AWS Marketplace Commerce Analytics 服务返回两个响应。第一个是立即返回的同步响应,第二个是使用 Amazon SNS 返回的异步响应。同步响应类似于此示例。

数据集参数

字段 描述
数据集请求 ID 表示对服务的特定请求的唯一标识符。此标识符可用于将请求与 Amazon SNS 主题上的通知关联。

异步响应是 JSON 格式的文档,发布到 Amazon SNS 主题,与此示例类似。

数据集参数

字段 描述
数据集 S3 位置 已传输数据集的存储桶名称和密钥。
数据集元数据 S3 位置 已传输数据集元数据文件的存储桶名称和密钥。
数据集请求 ID 表示对服务的特定请求的唯一标识符。此标识符可用于将请求与 Amazon SNS 主题上的通知关联。
成功 如果操作成功,则为 True;否则为 False。
Message (可选)如果出现错误(例如“Success”是“false”),此消息将包含有关故障的信息。

示例 JSON 格式的异步响应

{     "dataSetS3Location":{    "bucketName":"demo-bucket",  "key":"demo-prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.csv" }, "dataSetMetaDataS3Location":{   "bucketName":"demo-bucket",   "key":"demo-prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.meta.json" }, "dataSetRequestId":"f65b7244-6862-11e5-80e2-c5127e17c023", "success":true }

输出

成功请求之后,请求的数据集将以 .csv 文件的格式传输到您的 Amazon S3 存储桶。JSON 格式的元数据文件将发布到与数据集文件相同的位置。元数据文件提供有关数据集和原始请求参数的有用信息。元数据文件与数据集文件具有相同名称,但以扩展名 .meta.json 结尾。下表列出了 .csv 文件中的元数据字段。

元数据字段

字段 描述
数据集请求 ID 表示对服务的特定请求的唯一标识符。此标识符可用于将请求与 Amazon SNS 主题上的通知关联。
数据集覆盖范围 定义数据覆盖范围的开始日期/时间和结束日期/时间。这些日期采用 ISO 8601 格式。
数据集请求参数 针对 GenerateDataSet 方法的原始请求参数。
数据集 S3 位置 已传输数据集的存储桶名称和密钥。
数据集元数据 S3 位置 已传输数据集元数据文件的存储桶名称和密钥。

这是 JSON 格式的元数据内容示例。

{ "dataSetRequestId": "43d7137b-8a94-4042-a09d-c41e87f371c1", "dataSetCoverageRange": { "startDateTime": "2014-06-08T00:00:00.000Z", "endDateTime": "2014-06-08T23:59:59.000Z" }, "dataSetRequestParameters": { "sellerAccountId": "123412341234", "dataSetType": "customer_subscriber_hourly_monthly_subscriptions", "dataSetPublicationDate": "2014-06-09T00:00:00.000Z", "roleNameArn": "arn:aws:iam::123412341234:role/MarketplaceCommerceAnalyticsRole", "destinationS3BucketName": "demo-bucket", "destinationS3Prefix": "demo_prefix/customer_subscriber_hourly_monthly_subscriptions", "snsTopicArn": "arn:aws:sns:us-west-2:123412341234:demo-topic" }, "dataSetS3Location": { "bucketName": "demo-bucket", "key": "demo_prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.csv" }, "dataSetMetaDataS3Location": { "bucketName": "demo-bucket", "key": "demo_prefix/customer_subscriber_hourly_monthly_subscriptions_2014-06-09.meta.json" } }

有关可用数据集的完整列表(包括可用日期),请参阅 AWS 开发工具包文档

故障排除

由于白名单问题,我无法访问服务。

如果您尚未注册为 AWS Marketplace 上的卖家,请访问 AWS Marketplace Management Portal 进行注册。如果您已注册为 AWS Marketplace 上的卖家,请联系 AWS Marketplace 卖家运营团队。

我无法请求过去某个日期的数据集,即使开发工具包文档说明此日期应该可用。

即使过去特定日期的数据集列出为可用,但我们只有自您加入 AWS Marketplace 日期之后的数据。如果您仍认为这是一个错误,请联系 AWS Marketplace 卖家运营团队。

在调用服务时,我收到了错误消息“无法连接到终端节点 URL:https://marketplacecommerceanalytics.eu-central-1.amazonaws.com/”

目前,AWS Marketplace Commerce Analytics Service 仅在美国东部(弗吉尼亚北部)地区可用。您必须将对 Commerce Analytics Service 的所有调用针对 us-east-1 终端节点。

如果您使用 AWS CLI,请将 --region 标记添加到各个调用,并将区域指定为 us-east-1,如以下示例中所示。

aws marketplacecommerceanalytics generate-data-set \ --data-set-type "customer_subscriber_hourly_monthly_subscriptions" \ --data-set-publication-date "2016-04-21T00:00:00Z" \ --role-name-arn "arn:aws:iam::138136086619:role/MarketplaceCommerceAnalyticsRole" \ --destination-s3-bucket-name "marketplace-analytics-service" \ --destination-s3-prefix "test-prefix" \ --sns-topic-arn "arn:aws:sns:eu-central-1:138136086619:Marketplace_Analytics_Service_Notice" \ --region us-east-1

我希望使用与完成信息载入过程时选择的不同 Amazon S3 存储桶或 Amazon SNS 主题。

注册到 AWS Marketplace Commerce Analytics Service 时,您指定了 Amazon S3 存储桶和 Amazon SNS 主题。信息载入过程会配置您的 IAM 权限,仅允许服务访问这些特定资源,因此,如果您希望使用其他资源,就需要更改您的策略文档。要修改 IAM 策略,请执行以下操作:

  1. 登录 AWS 管理控制台 并通过以下网址打开 IAM 控制台 https://console.amazonaws.cn/iam/

  2. 在 IAM 控制台的左侧,选择 Roles (角色)

  3. 选择 MarketplaceCommerceAnalyticsRole

  4. 如果尚未展开 Inline Roles (内联角色) 部分,请展开该部分。

  5. 找到名称以 oneClick_MarketplaceCommerceAnalyticsRole 开头的策略并选择 Edit Policy (编辑策略)

  6. 在策略文档中,找到指定与所要修改服务相关的操作的部分。例如,要更改 Amazon S3 存储桶,您应找到包含以 s3: 开头的操作的部分,更改相应的 Resource (资源) 选择以指定新的 Amazon S3 存储桶。

有关 IAM 策略的更多信息,请参阅以下指南:https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html

此处未列出我的问题。

联系 AWS Marketplace 卖家运营团队。