编录 API 实体使用变更集使用 “详细信息” 属性（旧版）DescribeEntity 用于获取有关您的实体的信息

使用 AWS Marketplace Catalog API

该 AWS Marketplace Catalog API 服务提供了一个API接口， AWS Marketplace 供您的 AWS 组织管理或 AWS 账户. 对于获得批准的卖家，您可以通过编程方式管理您的商品，包括上的自助发布功能。AWS Marketplace 管理门户对于私有市场管理员，您可以通过编程方式管理您的私有市场。

借助 Catalog API 操作，您可以通过编程方式查看和更新现有产品。您可以将产品更新过程 AWS Marketplace Catalog API 与您的产品构建或部署管道集成，从而实现 AWS Marketplace 产品更新过程的自动化。您还可以在目录 API 之上创建自己的应用程序来管理您的商品 AWS Marketplace。您可以管理您 AWS 账户或 AWS 组织中的用户可以通过您的私人市场查看和购买的产品。

该 AWS Marketplace Catalog API 服务提供标准 AWS 的 API 功能。您可以直接使用操作中描述的 REST API 操作，也可以使用 S AWS DK 访问针对您正在使用的编程语言或平台量身定制的 API。有关 AWS 应用程序开发的更多信息，请参阅入门 AWS。有关使用 AWS 软件开发工具包的更多信息，请参阅 AWS 开发工具包。

编录 API 实体

AWS Marketplace 实体是用于不同业务目的（例如产品或报价）的数据容器。实体按类型分类。每种实体类型都封装了与特定业务领域（例如，产品或卖家账户）相关的数据。

为了简化这种范式，在设计实体时，其结构具有一定程度的通用性。因此，引入新的业务领域并不要求您学习全新的结构。

一般结构

任何实体的一般结构是：

带有版本的命名类型
该类型的特定实例的标识符
包含实体属性的一个或多个方面

类型版本控制

每个命名类型都有一个与之关联的类型和版本，例如EntityProduct@1.0。类型（Entity产品）表示内容的分类。版本 (1.0) 代表Entity产品的结构。

该版本为您提供了有关实体结构的详细信息。以下内容描述了何时更改版本：

如果不更改版本，就无法重组现有实体。添加可选的新字段将导致次要版本更新。
任何从根本上改变类型结构的功能都会导致主要版本更新。示例包括：
- 移除字段
- 重命名字段（相同语义使用不同的名称）
- 更改现有字段的语义（例如，更改预期类型）
主要版本更新可以保留先前版本中的一部分方面。
向用户提供新版本的通知和文档。

标识符

每个实体都代表业务领域中独一无二的事物。为了识别唯一的事物，我们使用EntityId与 a 关联的标识符RevisionId，例如 prod-ad8EXAMPLE651 @ 3。在这个例子中，EntityId是prod-ad8EXAMPLE651，RevisionId是3。对实体的每一次成功变更请求都将更新修订版。

以下是有关标识符的重要细节：

每个实体都由其唯一标识EntityId，这是在全球范围内区分一个实体与另一个实体的关键。
实体的每个已发布版本都有RevisionId. 与RevisionId，一起区分一个已发布的EntityId修订版和另一个已发布的修订版。
AWS Marketplace 生成 EntityId s 和 RevisionId s。

您可以使用DescribeEntity操作来查找详细信息以及带有最新信息的标识符revisionId。

RevisionId是请求的可选部分StartChangeSet（请参阅使用变更集）。如果包含RevisionId，则对的请求StartChangeSet将失败，ValidationException如果RevisionId不是实体的最新修订版，则请求将失败。这允许您在应用程序中实现乐观锁定。

注意

当您RevisionId包含不是最新修订版时，ValidationException消息中将包含最新版本RevisionId。

如果省略RevisionId，则会在实体的最新版本上自动执行请求。

警告

两个更改同一个对象的请求可能会导致一个请求覆盖另一个请求的更改，因为第二个请求会重写第一个请求更改的数据。在请求中使用 RevisionId s 可以防止出现此问题，因为它不允许对较早版本的更改覆盖当前修订版。

分面是属性的逻辑分组。一个实体通常包括几个方面，它们代表实体的不同方面。分面内的属性具有以下属性：

每个属性在其所属容器的范围内都有一个唯一的名称。
属性可以是简单类型（字符串、整数或浮点数）。
属性可以是复杂类型（container/structure 或数组）。

实体类型

实体类型定义了实体所代表的内容。实体可以是卖家产品 AWS Marketplace 或私人市场。有关更多信息，请参阅使用卖家商品和使用私有市场。

使用变更集

使用 Catalog API 时，请求是通过实体创建和更新的，并通过使用变更请求来完成。每项更改都指定要更改的实体、要执行的更改类型以及变更的详细信息。要执行的更改类型称为 a ChangeType。ChangeTypes 的集合称为 a ChangeSet。

有四个操作允许您使用变更集：

StartChangeSet— 请求一组更改。更改将添加到队列中并进行处理。有关更多信息，请参阅使用卖家商品和使用私有市场。
DescribeChangeSet— 获取一组更改的详细信息，包括请求的状态。状态包括：
- PREPARING— 准备好应用更改。
- APPLYING— 正在进行所要求的更改。
- SUCCEEDED— 请求已成功完成。
- CANCELLED— 请求已被用户取消。
- FAILED— 请求未成功完成。更多细节可在答复中找到。
ListChangeSets— 获取当前正在处理的更改集的列表。
CancelChangeSet— 请求取消更改集。只有在PREPARING状态下才能取消更改。

典型的工作流程是使用请求更改StartChangeSet，然后使用返回的ChangeSetId来轮询DescribeChangeSet操作，直到更改完成。

以下是DescribeChangeSet响应的示例。


{
  "ChangeSet":
  [
    {
      "ChangeName": "myChangeName",
      "ChangeType": "UpdateInformation",
      "Details": "{  \"ProductTitle\": \"My Product Title\",  \"ShortDescription\": \"My product short description.\",  \"LongDescription\": \"My product longer description.\",  \"Sku\": \"123example456\",  \"SupportDescription\": \"Need help? Contact our experts at support@example.com\\n\\nYour purchase includes 24x7 support.\",  \"Categories\": [    \"Operating Systems\",    \"Network Infrastructure\",    \"Application Development\"  ]}",
      "DetailsDocument":
      {
        "ProductTitle": "My Product Title",
        "ShortDescription": "My product short description.",
        "LongDescription": "My product longer description.",
        "Sku": "123example456",
        "SupportDescription": "Need help? Contact our experts at support@example.com\n\nYour purchase includes 24x7 support.",
        "Categories":
        [
          "Operating Systems",
          "Network Infrastructure",
          "Application Development"
        ]
      },
      "Entity":
      {
        "Identifier": "example1-abcd-1234-5ef6-7890abcdef12",
        "Type": "AmiProduct@1.0"
      },
      "ErrorDetailList":
      []
    }
  ],
  "ChangeSetArn": "arn:aws:aws-marketplace:[exampleARN]",
  "ChangeSetId": "example123456789012abcdef",
  "ChangeSetName": "myChangeSetName",
  "EndTime": "2023-03-03T00:00:00Z",
  "FailureCode": null,
  "FailureDescription": null,
  "StartTime": "2023-03-02T00:00:00Z",
  "Status": "SUCCEEDED"
}

注意

以编程方式进行轮询或使用变更集时，必须遵守服务限制。有关更多信息，请参阅的服务配额 AWS Marketplace Catalog API。

更改完成后，您可以使用ListEntities查找您创建或修改的实体（及其关联的EntityID）。然后，您可以DescribeEntity与一起使用EntityID来获取有关它的详细信息。

有关在控制台中为卖家处理变更请求的更多信息，请参阅《卖家指南》AWS Marketplace 中的创建变更请求。

同时提出多个变更请求

在一个变更集中，你可以捆绑所有变更类型，它们可以一起运行。Catalog API 旨在同时进行多项更改，以提供最佳性能。卖家和渠道合作伙伴可以通过将多个ChangeTypes捆绑到一个ChangeSet中来调用变更。您可以在同一个实体或不同实体上调用多个更改ChangeSet。Catalog API 会评估需要按哪个顺序应用更改，然后进行这些更改。

但是，如果请求是作为单独的更改集提出的，则 AWS Marketplace 无法对同一产品发起相互冲突的变更请求。在这些情况下， AWS Marketplace 会返回ResourceInUseException错误。

要修改 AMI 和容器产品，大多数更改都可以在没有错误的情况下进行，但以下情况除外：
- 如果同一ChangeType产品的两个请求相同，则第二个请求会返回错误。
- 如果一个请求是更新版本信息，而另一个请求是限制或添加版本，则第二个请求会返回错误。
- 如果有请求PREPARING，则可以对同一产品提出其他请求。但是，当前的更改APPLYING可能会阻止其他请求，从而返回错误。
对于其他产品类型和私有市场，您一次只能提出一个产品请求。如果在第一个请求进行期间发出了不同的更新相同产品的请求，则第二个请求会返回错误。
如果 AWS Marketplace 卖家运营团队对任何商品的请求处于待处理状态，则对该商品的任何其他请求都会返回错误。

如果您收到更改请求的ResourceInUseException错误，则可以稍后重试该请求。根据正在进行的请求的状态，您还可以取消第一个请求，以便重新提交的第二个请求能够更快地完成。

在一个变更集中调用多种变更类型

您可以使用 Catalog API 在一个针对一个或多个不同实体的StartChangeSet请求中合并和链接最多 20 个更改。

典型的用例是创建产品SaaSProduct@1.0草稿、报价Offer@1.0草稿，并填写产品和报价的元数据信息。这是通过在一个变更集中包含以下四种变更类型来完成的：

SaaSProduct@1.0 上的 CreateProduct

指定 ChangeName 参数。然后，以这种变更类型创建的产品可以被后续变更集中引用在同一个变更集中。

例如 CreateProductChange。
UpdateInformation在同一个变更集中SaaSProduct@1.0创建的

在该Entity.Identifier字段中，您可以使用以下格式的CreateProduct更改名称来引用变更类型创建的产品：

${ChangeName}.Entity.Identifier

例如 $CreateProductChange.Entity.Identifier。
CreateOfferon Offer@1.0 绑定到在同一个变更集中SaaSProduct@1.0创建的

指定 ChangeName 参数。然后，以这种变更类型创建的产品可以被后续变更集中引用在同一个变更集中。例如 CreateOfferChange。

对于CreateOffer变更类型的负载中的ProductId参数，您也可以使用${ChangeName}.Entity.Identifier语法引用在CreateProduct变更类型中创建的 SaaS 产品。

例如 {"ProductId":"$CreateProductChange.Entity.Identifier"}。
UpdateInformation在同一个变更集中Offer@1.0创建的

在该Entity.Identifier字段中，您可以使用以下格式的变更名称来引用CreateOffer变更类型创建的选件：

${ChangeName}.Entity.Identifier

例如 $CreateOfferChange.Entity.Identifier。

以下是组合更改集的示例。


POST /StartChangeSet HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "ChangeSet": [
    {
      "ChangeType": "CreateProduct",
      "Entity": {
        "Type": "SaaSProduct@1.0"
      },
      "ChangeName": "CreateProductChange",
      "DetailsDocument": {}
    },
    {
      "ChangeType": "UpdateInformation",
      "Entity": {
        "Type": "SaaSProduct@1.0",
        "Identifier": "$CreateProductChange.Entity.Identifier"
      },
      "ChangeName": "UpdateProductInformationChange",
      "DetailsDocument": {
        "ProductTitle": "My Product Title",
        "ShortDescription": "My product short description.",
        "LongDescription": "My product longer description.",
        "Sku": "123example456",
        "LogoUrl": "https://s3.amazonaws.com/presigned-or-public-url-to-logo-stored-in-s3",
        "VideoUrls": [
          "https://example.com"
        ],
        "Highlights": [
          "123example45"
        ],
        "AdditionalResources": "123example456",
        "SupportDescription": "Need help? Contact our experts at support@example.com \n\nYour purchase includes 24x7 support.",        
        "Categories": [
          "Operating Systems",
          "Network Infrastructure",
          "Application Development"
        ],
        "SearchKeywords": [
          "123example45"
        ],
      }
    },
    {
      "ChangeType": "CreateOffer",
      "Entity": {
        "Type": "Offer@1.0"
      },
      "ChangeName": "CreateOfferChange",
      "DetailsDocument": {
        "ProductId": "$CreateProductChange.Entity.Identifier"
      }
    },
    {
      "ChangeType": "UpdateInformation",
      "Entity": {
        "Type": "Offer@1.0",
        "Identifier": "$CreateOfferChange.Entity.Identifier"
      },
      "DetailsDocument": {
        "Name": "Offer created together with SaaSProduct",
        "Description": "Test offer created together with SaaSProduct in the same Catalog API change set"
      }
    }
  ]
}

使用 “`详细信息`” 属性（旧版）

注意

本节介绍变更请求中的旧版Details属性，该属性需要对变更详细信息进行其他格式设置。我们建议使用替代DetailsDocument属性。它不需要额外的格式，也无需更改更改细节。有关该DetailsDocument属性的示例，请参阅使用卖家商品和使用私有市场。

该StartChangeSet操作的Details属性是一个字符串值。它的内容是 JSON 对象。要将 JSON 对象放入字符串属性中，必须通过转义所有 JSON 控制字符并删除换行符将该对象转换为单行字符串。

例如，如果您使用StartChangeSet操作UpdateProcurementPolicy来禁用私有市场中用户的请求，请提出如下请求。


POST /StartChangeSet HTTP/1.1
Content-type: application/json

{
   "Catalog": "AWSMarketplace",
   "ChangeSet": [ 
      { 
         "ChangeType": "UpdateProcurementPolicy",
         "Details": "<string>",
         "Entity": {
            "Type": "Experience@1.0",
            "Identifier" : "exp-1234example@5"
         }
      }
   ]
}

在本例中，用于该Details属性的 JSON 对象如下所示（在转换为字符串之前）。


{
    "Configuration": {
        "PolicyResourceRequests": "Deny"
    }
}

但是该Details属性需要一个字符串，而不是 JSON。将此 JSON 对象转换为单行字符串后，它如下所示。


"{\"Configuration\" : {\"PolicyResourceRequests\" : \"Deny\"}}"

使用此字符串，您可以创建完整的更改集请求，如下所示。


POST /StartChangeSet HTTP/1.1
Content-type: application/json

{
   "Catalog": "AWSMarketplace",
   "ChangeSet": [ 
      { 
         "ChangeType": "UpdateProcurementPolicy",
         "Details": "{\"Configuration\" : {\"PolicyResourceRequests\" : \"Deny\"}}",
         "Entity": {
            "Type": "Experience@1.0",
            "Identifier" : "exp-1234example@5"
         }
      }
   ]
}

通常，此 API 参考中的示例显示已转换为字符串的 JSON 对象。在某些情况下，为了增强理解，还会包括带有新线条的更复杂的样本。

自动将 JSON 转换为字符串

使用诸如 j q（一种轻量级命令行 JSON 处理器）之类的工具，可以自动将 J SON 对象转换为字符串。以下示例演示jq如何使用将 JSON 对象转换为可在Details属性中使用的字符串。


DETAILS_JSON='{
  "ProductTitle": "My Product Title",
  "ShortDescription": "My product short description.",
  "LongDescription": "My product long description."
}';

DETAILS_JSON_STRING="$(echo "${DETAILS_JSON}" | jq 'tostring';)";

如果你回答"${DETAILS_JSON_STRING}"，结果是正确转义了 JSON 的以下字符串：{\"ProductTitle\":\"My Product\",\"ShortDescription\":\"My product short description.\",\"LongDescription\":\"My product long description.\"}

DescribeEntity 用于获取有关您的实体的信息

您可以通过目录 API 以编程方式获取有关现有实体（包括产品和私有市场）的信息。

该ListEntities操作会返回实体列表。然后，您可以使用该DescribeEntity操作来获取有关单个实体的详细信息。例如，这可以直接用于对您销售的产品进行分类。它在更新实体时也很有用，因为你可以在只更新要更新的部分之前获取实体的当前状态。

以下示例显示了ListEntities使用获取容器产品列表，然后使用DescribeEntity来获取有关其中一个特定产品的信息。


POST /ListEntities HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "EntityType": "ContainerProduct"
}

对于实体类型，必须使用不带版本的实体类型。它返回该类型的所有实体（并且不会根据版本进行筛选）。

以下是对该ListEntities操作的响应示例。


{
    "EntitySummaryList": [
        {
            "Name": "Container Product 1",
            "EntityType": "ContainerProduct",
            "EntityId": "example1-abcd-1234-5ef6-7890abcdef12",
            "EntityArn": "arn:aws:aws-marketplace:[exampleARN]",
            "LastModifiedDate": "2021-03-01T00:00:00Z",
            "Visibility": "Public"
        },
        {
            "Name": "Container Product 2",
            "EntityType": "ContainerProduct",
            "EntityId": "example2-abcd-1234-5ef6-7890abcdef12",
            "EntityArn": "arn:aws:aws-marketplace:[exampleARN]",
            "LastModifiedDate": "2021-03-02T00:00:00Z",
            "Visibility": "Public"
        }
    ],
    "NextToken": "exampleabcdef12345..."
}

要获取其中一款产品的详细信息，请使用DescribeEntity操作。以下示例说明如何获取有关上面返回的第一个产品的详细信息。


GET /DescribeEntity?catalog=AWSMarketplace&entityId=example1-abcd-1234-5ef6-7890abcdef12 HTTP/1.1

以下显示了对的回应DescribeEntity。


{
  "EntityType": "ContainerProduct@1.0",
  "EntityIdentifier": "example1-abcd-1234-5ef6-7890abcdef12@9",
  "EntityArn": "arn:aws:aws-marketplace:[exampleARN]",
  "LastModifiedDate": "2021-03-02T20:19:14Z",
  "Details": "{\"Versions\":[{\"Id\":\"example2-0000-aaaa-5ef6-7890abcdef12\",\"ReleaseNotes\":\"My release notes\",\"UpgradeInstructions\":\"N/A\",\"VersionTitle\":\"1.0\",\"CreationDate\":\"2021-03-02T00:00:00.000Z\",\"Sources\":[{\"Type\":\"DockerImages\",\"Id\":\"example3-1111-bbbb-5ef6-7890abcdef12\",\"Images\":[\"111122223333.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1:some-tag\"],\"Compatibility\":{\"Platform\":\"Linux\"}}],\"DeliveryOptions\":[{\"Id\":\"example4-2222-cccc-2222-cccccccccccc\",\"Type\":\"ElasticContainerRegistry\",\"SourceId\":\"example3-1111-bbbb-5ef6-7890abcdef12\",\"Title\":\"New delivery option 1\",\"ShortDescription\":\"Delivery option 1\",\"isRecommended\":false,\"Compatibility\":{\"AWSServices\":[\"ECS\",\"EKS\"]},\"Instructions\":{\"Usage\":\"test\"},\"Recommendations\":{\"AdditionalArtifacts\":[]},\"Visibility\":\"Limited\"}]}],\"Description\":{\"Highlights\":[\"Some highlight\"],\"LongDescription\":\"Description of my product\",\"ProductCode\":\"123456789012abcdef1234567\",\"Manufacturer\":null,\"Visibility\":\"Limited\",\"AssociatedProducts\":null,\"Sku\":null,\"SearchKeywords\":[\"some keyword\"],\"ProductTitle\":\"Container Product 1\",\"ShortDescription\":\"Description of my product\",\"Categories\":[\"Operating Systems\"]},\"PromotionalResources\":{\"LogoUrl\":\"https://awsmp-logos.s3.amazonaws.com/PLACEHOLDER_Logo_for_Containers_products.png\",\"AdditionalResources\":[],\"Videos\":[]},\"SupportInformation\":{\"Description\":\"Description of support information.\",\"Resources\":[]},\"RegionAvailability\":{\"Regions\":[\"ap-south-1\",\"eu-west-3\",\"eu-north-1\",\"eu-west-2\",\"eu-west-1\",\"ap-northeast-2\",\"ap-northeast-1\",\"me-south-1\",\"ca-central-1\",\"sa-east-1\",\"ap-east-1\",\"ap-southeast-1\",\"ap-southeast-2\",\"eu-central-1\",\"us-east-1\",\"us-east-2\",\"us-west-1\",\"us-west-2\"],\"FutureRegionSupport\":null},\"Repositories\":[{\"Url\":\"111122223333.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1\",\"Type\":\"ECR\"}]}",
  "DetailsDocument":
  {
    "Versions":
    [
      {
        "Id": "example2-0000-aaaa-5ef6-7890abcdef12",
        "ReleaseNotes": "My release notes",
        "UpgradeInstructions": "N/A",
        "VersionTitle": "1.0",
        "CreationDate": "2021-03-02T00:00:00.000Z",
        "Sources":
        [
          {
            "Type": "DockerImages",
            "Id": "example3-1111-bbbb-5ef6-7890abcdef12",
            "Images":
            [
              "111122223333.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1:some-tag"
            ],
            "Compatibility":
            {
              "Platform": "Linux"
            }
          }
        ],
        "DeliveryOptions":
        [
          {
            "Id": "example4-2222-cccc-2222-cccccccccccc",
            "Type": "ElasticContainerRegistry",
            "SourceId": "example3-1111-bbbb-5ef6-7890abcdef12",
            "Title": "New delivery option 1",
            "ShortDescription": "Delivery option 1",
            "isRecommended": false,
            "Compatibility":
            {
              "AWSServices":
              [
                "ECS",
                "EKS"
              ]
            },
            "Instructions":
            {
              "Usage": "test"
            },
            "Recommendations":
            {
              "AdditionalArtifacts":
              []
            },
            "Visibility": "Limited"
          }
        ]
      }
    ],
    "Description":
    {
      "Highlights":
      [
        "Some highlight"
      ],
      "LongDescription": "Description of my product",
      "ProductCode": "123456789012abcdef1234567",
      "Manufacturer": null,
      "Visibility": "Limited",
      "AssociatedProducts": null,
      "Sku": null,
      "SearchKeywords":
      [
        "some keyword"
      ],
      "ProductTitle": "Container Product 1",
      "ShortDescription": "Description of my product",
      "Categories":
      [
        "Operating Systems"
      ]
    },
    "PromotionalResources":
    {
      "LogoUrl": "https://awsmp-logos.s3.amazonaws.com/PLACEHOLDER_Logo_for_Containers_products.png",
      "AdditionalResources":
      [],
      "Videos":
      []
    },
    "SupportInformation":
    {
      "Description": "Description of support information.",
      "Resources":
      []
    },
    "RegionAvailability":
    {
      "Regions":
      [
        "ap-south-1",
        "eu-west-3",
        "eu-north-1",
        "eu-west-2",
        "eu-west-1",
        "ap-northeast-2",
        "ap-northeast-1",
        "me-south-1",
        "ca-central-1",
        "sa-east-1",
        "ap-east-1",
        "ap-southeast-1",
        "ap-southeast-2",
        "eu-central-1",
        "us-east-1",
        "us-east-2",
        "us-west-1",
        "us-west-2"
      ],
      "FutureRegionSupport": null
    },
    "Repositories":
    [
      {
        "Url": "111122223333.dkr.ecr.us-east-1.amazonaws.com/some-seller-prefix/my-repo-1",
        "Type": "ECR"
      }
    ]
  }
}

注意

该DetailsDocument属性以 JSON 对象的形式包含实体详细信息。旧Details属性包含与字符串相同的 JSON 对象。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

使用 API

使用协议 API