目錄 API 實體使用變更集使用 Details 屬性（舊版）使用 DescribeEntity 取得實體的相關資訊

使用 AWS Marketplace 目錄 API

AWS Marketplace Catalog API 服務提供 API 界面，可 AWS Marketplace 為您的 AWS 組織或進行管理 AWS 帳戶。對於核准的賣方，您可以透過程式設計方式管理您的產品，包括上的自助發佈功能AWS Marketplace 管理入口網站。對於私有市集管理員，您可以透過程式設計方式管理您的私有市集。

透過目錄 API 動作，您可以透過程式設計方式檢視和更新現有的產品。您可以將 AWS Marketplace Catalog API 與產品建置或部署管道整合，以自動化 AWS Marketplace 產品更新程序。您也可以在目錄 API 上建立自己的應用程式，以管理中的產品 AWS Marketplace。您可以管理 AWS 帳戶或 AWS 組織中的使用者可透過私有市集查看和購買的產品。

AWS Marketplace Catalog API 服務提供標準 AWS API 功能。您可以直接使用動作中所述的 REST API 動作，也可以使用 AWS SDK 來存取專為您正在使用的程式設計語言或平台量身打造的 API。如需 AWS 應用程式開發的詳細資訊，請參閱入門 AWS。如需使用 AWS SDKs的詳細資訊，請參閱 AWS SDKs。

目錄 API 實體

AWS Marketplace 實體是用於不同業務目的的資料容器，例如產品或優惠。實體依類型分類。每個實體類型會封裝與特定商業網域（例如產品或賣方帳戶）相關的資料。

為了簡化此範例，實體的設計在結構中具有某種程度的共通性。因此，引進新的商業網域不需要您學習全新的結構。

一般結構

任何實體的一般結構為：

具有版本的具名類型
類型之特定執行個體的識別符
包含實體屬性的一或多個面向

類型版本控制

每個具名類型都有與其相關聯的類型和版本，例如 EntityProduct@1.0。類型 (實體產品）代表內容的分類。版本 (1.0) 代表實體產品的結構。

版本提供您實體結構的詳細資訊。以下說明變更版本的時間：

如果未變更版本，將無法重組現有的實體。新增選用的新欄位會導致次要版本更新。
從根本上變更類型結構的任何功能都會導致主要版本更新。範例包括：
- 移除欄位
- 重新命名欄位（相同語意的不同名稱）
- 變更現有欄位的語意（例如，變更預期的類型）
主要版本更新可以保留先前版本的面向子集。
使用者會收到新版本的通知和文件。

識別符

每個實體代表商業網域中唯一的物件。為了識別唯一物件，我們使用將 EntityId與建立關聯的識別符RevisionId，例如 prod-ad8EXAMPLE651@3。在此範例中， EntityId是 prod-ad8EXAMPLE651，而 RevisionId是 3。對實體提出的每個成功變更請求都會更新修訂。

以下是有關識別符的重要詳細資訊：

每個實體都由其唯一識別EntityId，這是全域區分一個實體與另一個實體的關鍵。
實體的每個已發佈修訂都有一個 RevisionId。RevisionId與 EntityId一起，區分一個已發佈的修訂。
AWS Marketplace 會產生 EntityId和 RevisionId。

您可以使用 DescribeEntity動作來尋找詳細資訊，以及具有最新的識別符revisionId。

RevisionId 是對請求的選用部分 StartChangeSet（請參閱使用變更集)。如果您包含 RevisionId，則ValidationException如果 RevisionId不是實體的最新修訂版，對的請求StartChangeSet將失敗。這可讓您在應用程式中實作樂觀鎖定。

注意

當您包含不是最新修訂版RevisionId的時，ValidationException訊息會包含最新的 RevisionId。

如果您省略 RevisionId，請求會自動在實體的最新修訂版上執行。

警告

變更相同物件的兩個請求可能會導致一個請求覆寫另一個請求的變更，因為第二個請求會重寫第一個請求變更的資料。在請求中使用 RevisionId可避免此問題，方法是不允許變更先前的修訂版以覆寫目前的修訂版。

面向是屬性的邏輯分組。實體通常包含數個面向，代表實體的不同層面。面向內的屬性具有下列屬性：

每個屬性都有其所屬容器範圍內的唯一名稱。
屬性可以是簡單類型（字串、整數或浮點數）。
屬性可以是複雜類型（容器/結構或陣列）。

實體類型

實體類型會定義實體所代表的內容。實體可以是中的賣方產品或 AWS Marketplace 私有市場。如需詳細資訊，請參閱使用賣方產品和使用私有市場。

使用變更集

使用目錄 API 時，請求會透過實體建立和更新，並使用變更請求完成。每次變更都會指定要變更的實體、要執行的變更類型，以及變更的詳細資訊。要執行的變更類型稱為 ChangeType。的集合ChangeType稱為 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。目錄 API 會評估需要套用變更的順序，並進行這些變更。

不過，如果請求是以個別的變更集提出， AWS Marketplace 就無法在相同的產品上啟動衝突的變更請求。在這些情況下，會 AWS Marketplace 傳回ResourceInUseException錯誤。

對於修改 AMI 和容器產品，大多數變更都可以在沒有錯誤的情況下進行，但以下情況除外：
- 如果ChangeType相同產品的兩個請求相同，第二個請求會傳回錯誤。
- 如果一個請求是更新版本資訊，而另一個請求是限制或新增版本，則第二個請求會傳回錯誤。
- 如果請求是 PREPARING，則可以對相同的產品提出另一個請求。不過，目前所做的變更APPLYING可能會封鎖其他請求，並傳回錯誤。
對於其他產品類型和私有市集，您一次只能對產品提出單一請求。如果在第一個請求進行時提出更新相同產品的不同請求，第二個請求會傳回錯誤。
如果賣方營運團隊有任何待定 AWS Marketplace 產品的請求，則該產品的任何其他請求都會傳回錯誤。

如果您收到變更請求的ResourceInUseException錯誤，您可以稍後重試該請求。根據進行中請求的狀態，您也可以取消第一個請求，以允許重新提交的第二個請求更快完成。

在一個變更集中叫用多個變更類型

您可以使用目錄 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。
CreateOffer 上的與相同變更集中SaaSProduct@1.0建立的 Offer@1.0繫結

指定 ChangeName 參數。然後，在此變更類型中建立的產品可以在後續變更設定的相同變更中參考。例如 CreateOfferChange。

對於CreateOffer變更類型的承載中的 ProductId 參數，您也可以使用語法參考在CreateProduct變更類型中建立的 SaaS ${ChangeName}.Entity.Identifier 產品。

例如 {"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` 屬性（舊版）

注意

本節說明變更請求中的舊版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 轉換為字串

您可以使用輕量型命令列 JSON 處理器 jq 等工具，將 JSON 物件轉換為字串。下列範例顯示使用 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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 API

使用協議 API