AWS Marketplace API 參考已重組。如需支援的 API 操作的詳細資訊，請參閱 AWS Marketplace API 參考。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 AWS MarketplaceAPI 處理私有市集

您可以使用 AWS Marketplace Catalog API來管理您 AWS 帳戶或組織的私有市集。

所有變更類型只能從組織的管理帳戶或私有市集的委派管理員成員帳戶呼叫。如果您是目前不AWS Organizations整合私有市集的私有市集客戶，您可以從組織中具有 IAM AWSPrivateMarketplaceAdminFullAccess 政策的任何帳戶建立和管理私有市集。

如需私有市集的詳細資訊，請參閱《 AWS Marketplace買方指南》中的私有市集。

下表詳細說明一組管理私有市集的任務，以及適用於每個任務的變更類型。

建立私有市集

私有市集AWS 帳戶可視為允許使用者在該帳戶中採購的產品清單，並為該市集建立品牌。在具有多個帳戶的組織中，您可以使用來自AWS Organizations稱為組織單位 (OU) 的分組來與 體驗建立關聯。例如，您可以擁有一組允許組織中所有帳戶採購的產品，或者您可以擁有組織中每個 OU 的不同產品清單。您也可以為組織中的個別帳戶擁有不同的產品清單。每個核准的產品和品牌清單稱為採購體驗。

在 中AWS Marketplace Catalog API，四個實體代表一個體驗：

建立採購體驗的步驟如下：

建立Experience實體

若要建立Experience實體，請使用 StartChangeSet動作搭配 ChangeType 參數CreateExperience的值，以請求由 建立體驗AWS Marketplace。請參閱以下程式碼範例。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "CreateExperience",
      "DetailsDocument":
      {
        "Name": "ExamplePrivateMarketplace"
      },
      "Entity":
      {
        "Type": "Experience@1.0"
      }
    }
  ],
  "ChangeSetName": "Create Private Marketplace Example"
}

在此動作中， Entity 是您要建立之實體的範本。它會在建立EntityId時指派 。 會ChangeSetName識別變更，以協助您稍後找到它。

回傳的結果如下所示。

{
   "ChangeSetArn": "arn:...:AWSMarketplace/ChangeSet/abcd1234example5678frjzkz",
   "ChangeSetId": "abcd1234example5678frjzkz"
}

回應包含 ChangeSetId，您可以在使用 處理變更請求時用來取得變更請求的狀態DescribeChangeSet。您也可以使用 ListEntities 來尋找沒有 的Experience實體ChangeSetId。如需變更集的詳細資訊，請參閱使用變更集。

根據預設，新建立的Experience實體沒有採購政策。它也會使用品牌預設設定建立。如需品牌設定的詳細資訊，包括如何自訂設定，請參閱 變更私有市場體驗的品牌。

建立ProcurementPolicy實體

您必須建立ProcurementPolicy實體。預設會停用新的Experience實體，因此您可以在啟用之前建立採購政策。

若要允許和拒絕私有市場中的產品，您必須建立採購政策。若要這樣做，請再次呼叫 StartChangeSet，但這次使用 ChangeType的 CreateProcurementPolicy。下列程式碼範例會建立空的採購政策。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "CreateProcurementPolicy",
      "DetailsDocument":
      {
        "Name": "ExampleProcurementPolicy"
      },
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-1234example@1"
      }
    }
  ]
}

Entity 您在此動作中提供的 是您希望在其中建立採購政策的Experience實體，因此您必須包含先前建立之實體的識別符。使用 ListEntities 尋找Experience實體。您也可以使用 DescribeChangeSet 搭配 CreateExperience動作中的變更集識別符來傳回識別符

您可以在CreateProcurementPolicy變更類型DescribeChangeSet上再次使用 來遵循請求的處理。

建立採購政策後，您的私有市集會顯示在 中AWS Management Console。（您可以前往 Private Marketplace 頁面來查看。) 完成這些步驟後，您的私有市集將會停用、具有預設品牌、具有空白的採購政策，而且不會與您組織中的任何委託人建立關聯。您可以更新品牌並新增任何您想要的產品、將體驗與一或多個帳戶建立關聯，然後啟用您的私有市集。

下列各節說明使用 管理您的私有市集AWS Marketplace Catalog API。

變更私有市場體驗的品牌

您可以為您的使用者自訂私有市集的外觀。如果沒有自訂，您的私有市集將具有預設品牌設定，如下所述。您可以在私有市場中變更的品牌層面包括：

若要設定這些值，您必須先建立具有CreateBrandingSettings變更類型的BrandingSettings實體。然後，您可以請求UpdateBrandingSettings變更以設定或變更品牌。您只需要建立BrandingSettings物件一次。若要建立此物件，StartChangeSet請使用CreateBrandingSettings變更類型呼叫 ，如下列程式碼範例所示。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "CreateBrandingSettings",
      "DetailsDocument":
      {
        "Name": "ExampleBrandingSettingsName"
      },
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-1234example@2"
      }
    }
  ]
}

此範例透過新增 BrandingSettings 物件來修改Experience實體。實體識別符的修訂已遞增至 2。如需識別碼修訂的詳細資訊，請參閱 識別符。

您可以使用UpdateBrandingSettings變更類型呼叫 StartChangeSet來修改設定。這些設定是 DetailsDocument 物件 Configuration 的一部分。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateBrandingSettings",
      "DetailsDocument":
      {
        "Name": "ExampleBrandingSettingsName",
        "Description": "Example description",
        "Configuration":
        {
          "Title": "ExampleName",
          "Information": "Example description.",
          "ThemeColor": "#0e7f74",
          "LogoUrl": "https://example.com/path/mylogo.png"
        }
      },
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-1234example@3"
      }
    }
  ]
}

啟用或停用私有市場體驗

啟用私有市集時 （且具有採購政策），關聯帳戶中的使用者只能購買您已核准的產品。帳戶未啟用私有市場體驗時，使用者可以跨完整AWS Marketplace目錄購買產品。

若要啟用私有市集，請使用 StartChangeRequest動作搭配 UpdateExperience 變更類型。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "UpdateExperience",
      "DetailsDocument":
      {
        "Status": "Enabled"
      },
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-1234example@4"
      }
    }
  ]
}

同樣地，您可以使用相同的動作 和 ChangeType，但將 StatusDetailsDocument中的 變更為 Disabled以停用私有市集。

啟用或停用使用者請求

組織中的使用者可以檢視完整的公有AWS Marketplace，但他們只能訂閱您允許的產品。根據預設，他們可以請求將不在私有市場中的產品新增到其中。這些請求會顯示在私有市集管理員頁面 (私有市集) 中，您可以在其中決定是否接受或拒絕請求 （以及是否封鎖相同產品的進一步請求）。您無法使用目錄 API 查看或回應請求。

您可以啟用或停用使用者為私有市集體驗建立請求的能力。使用 StartChangeSet搭配 UpdateProcurementPolicy 變更類型。下列程式碼範例中已停用提出請求的功能。

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

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

若要為使用者啟用變更請求功能，請在 Deny中使用 Allow而非 PolicyResourceRequests。

若要了解如何取得此設定的目前狀態，請參閱下一節：取得私有市場體驗中的產品清單。

取得私有市場體驗中的產品清單

私有市場中允許 （和拒絕） 的產品是Experience實體中採購政策的一部分。若要取得私有市場中採購政策的詳細資訊，請先從Experience實體取得採購政策識別符，然後使用DescribeEntity該識別符呼叫 。

若要取得採購政策識別符，請在您感興趣的Experience實體DescribeEntity上使用 ，如下列命令所示。

GET /DescribeEntity?catalog=AWSMarketplace&entityId=exp-example01

以下是回應範例：

{
  "Details": "{\"Name\":\"New Private Marketplace\", \"Status\":\"Enabled\", \"ProcurementPolicies\":[\"procpolicy-123example456\"], \"BrandingSettings\":[\"brandsettings-456example123\"]}",
  "DetailsDocument":
  {
    "Name": "New Private Marketplace",
    "Status": "Enabled",
    "ProcurementPolicies":
    [
      "procpolicy-123example456"
    ],
    "BrandingSettings":
    [
      "brandsettings-456example123"
    ]
  },
  "EntityArn": "arn:<...>:AWSMarketplace/Experience/exp-example-01",
  "EntityIdentifier": "exp-example01@6",
  "EntityType": "Experience@1.0",
  "LastModifiedDate": "2021-01-13T20:31:36Z"
}

您可以使用採購政策傳回EntityId的 來取得詳細資訊，如下列命令所示。

GET /DescribeEntity?catalog=AWSMarketplace&entityId=procpolicy-123example456

這會傳回政策的完整詳細資訊，包括允許和拒絕的產品。以下是回應範例：

{
  "Details": "{\"Name\":\"ExampleProcurementPolicy\", \"Statements\":[{\"Effect\":\"Allow\",\"Resources\":[{\"Type\":\"Product\",\"Ids\":[\"example1-1234-abcd-5678-90abcdef1234\"]},{\"Type\":\"Product\",\"Ids\":[\"example2-2345-bcde-6789-01bcdea2345\"]}]},{\"Effect\":\"Deny\",\"Resources\":[{\"Type\":\"Product\",\"Ids\":[\"example3-3456-cdef-7890-12defabc5678\"]}]}],\"Configuration\":{\"PolicyResourceRequests\":\"Allow\"}}",
  "DetailsDocument":
  {
    "Name": "ExampleProcurementPolicy",
    "Statements":
    [
      {
        "Effect": "Allow",
        "Resources":
        [
          {
            "Type": "Product",
            "Ids":
            [
              "example1-1234-abcd-5678-90abcdef1234"
            ]
          },
          {
            "Type": "Product",
            "Ids":
            [
              "example2-2345-bcde-6789-01bcdea2345"
            ]
          }
        ]
      },
      {
        "Effect": "Deny",
        "Resources":
        [
          {
            "Type": "Product",
            "Ids":
            [
              "example3-3456-cdef-7890-12defabc5678"
            ]
          }
        ]
      }
    ],
    "Configuration":
    {
      "PolicyResourceRequests": "Allow"
    }
  },
  "EntityArn": "arn:<...>AWSMarketplace/ProcurementPolicy/procpolicy-123example456",
  "EntityIdentifier": "procpolicy-123example456@4",
  "EntityType": "ProcurementPolicy@1.0",
  "LastModifiedDate": "2020-10-01T12:00:00Z"
}

在此範例中，採購政策有兩個允許的產品和一個遭拒的產品。政策允許使用者資源請求。

從私有市集新增或移除產品

根據預設，私有市集中沒有任何核准的產品。使用變更請求來新增或移除產品。若要新增產品，請使用 AllowProductProcurement 變更類型。若要移除產品，請使用 DenyProductProcurement 變更類型。

下列程式碼範例顯示AllowProductProcurement變更類型，其中包含將產品新增至私有市集StartChangeSet的動作。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "AllowProductProcurement",
      "DetailsDocument":
      {
        "Products":
        [
          {
            "Ids":
            [
              "example-1234-abcd-5678-90abcded1234"
            ],
            "Notes": "Useful product"
          }
        ]
      },
      "Entity":
      {
        "Identifier": "exp-1234example@6",
        "Type": "Experience@1.0"
      }
    }
  ]
}

您可以使用 將產品新增至私有市集的Experience實體AllowProductProcurement。從私有市集移除產品的語法完全相同，但您使用 DenyProductProcurementChangeType而非 的例外AllowProductProcurement。產品會新增至Experience您的ProcurementPolicy實體所包含實體的允許 （或拒絕） 清單。

尋找產品

透過取得採購政策的詳細資訊，您可以找到已在私有市場中產品的產品 IDs。不過， AWS Marketplace Catalog API不提供尋找其他產品的產品 IDs的方法。有兩種方式可以取得產品 IDs以搭配 Catalog API 服務使用：

使用 的私有市集AWS Organizations

無論您是為帳戶或組織使用私有市集，您都使用相同的 API。不過，在組織內工作時會有差異：

若要列出您自己的帳戶中的Experience物件，請呼叫 ListEntities，如下列程式碼範例所示。

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

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

不過，若要列出已與您共用的實體，您必須使用 FilterList Scope的 新增 SharedWithMe，如下列程式碼範例所示。因此， AWS Marketplace會在您自己的帳戶之外搜尋，以尋找與您共用的實體。

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

{"Catalog":"AWSMarketplace", 
"EntityType":"Experience",
 "FilterList": 
  [{
     "Name": "Scope",
     "ValueList":
      ["SharedWithMe"]
      }]}

在這種情況下，只會傳回您帳戶之外的實體 （您組織的實體）。

同樣地，若要呼叫 ListChangeSets，您必須設定範圍，如下列程式碼範例所示。

POST /ListChangeSets HTTP/1.1
Content-Type: application/json

{"Catalog":"AWSMarketplace", 
 "FilterList": 
  [{
     "Name": "Scope",
     "ValueList":
      ["SharedWithMe"]
      }]}

這會傳回適用於組織共用私有市集的變更集。

將主體與體驗建立關聯

私有市場體驗必須有一或多個與之相關聯的委託人，才能對組織產生任何影響。對於單一 AWS 帳戶，您必須將帳戶與體驗建立關聯，才能使用私有市集。在組織中，您可以有多個經驗適用於不同的委託人。

若要將委託人與 體驗建立關聯，請使用 AssociateAudience 變更類型與 StartChangeSet動作，如下列程式碼範例所示。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-example01@1"
      },
      "ChangeType": "AssociateAudience",
      "DetailsDocument":
      {
        "Name": "AudienceName",
        "Description": "Audience example.",
        "Principals":
        [
          "012345678901",
          "ou-abcd-01234567",
          "o-0123456789"
        ]
      }
    }
  ],
  "ChangeSetName": "Set Audience for experience 01"
}

對象是與 相關聯的委託人清單Experience。委託人是 AWS 帳戶、組織單位，或由其 ID 定義的組織。 Principals是清單，因此您可以包含多個要與體驗建立關聯的委託人。第一次呼叫後，對AssociateAudience變更類型的後續呼叫會將主體新增至 關聯，以獲得體驗。

您也可以從 體驗中移除帳戶。使用DisassociateAudience變更類型來執行此操作，如下列程式碼範例所示。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-example01@02"
      },
      "ChangeType": "DisassociateAudience",
      "DetailsDocument":
      {
        "Principals":
        [
          "012345678901",
          "ou-abcd-01234567",
          "o-0123456789"
        ]
      }
    }
  ],
  "ChangeSetName": "Disassociate audience example"
}

封存和重新啟用私有市場體驗

您可以透過封存來移除私有市場體驗。封存的體驗無法更新或用於管理組織中的帳戶。如果您有與封存體驗相關聯的對象，您可以將他們與不同的體驗建立關聯。如果您決定稍後使用體驗，您可以隨時重新啟用。來自管理帳戶的管理員或身為私有市集委派管理員的成員帳戶，具有封存和重新啟用體驗的許可。如果您是目前不AWS Organizations整合私有市集的私有市集客戶，則來自建立體驗之帳戶的管理員具有封存和重新啟用體驗的許可。

若要封存體驗，請將RestrictExperience變更類型與 StartChangeSet動作搭配使用，如下列程式碼範例所示。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "RestrictExperience",
      "DetailsDocument":
      {},
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-1234example"
      }
    }
  ]
}

若要重新啟用體驗，請將ReviveExperience變更類型與 StartChangeSet動作搭配使用，如下列程式碼範例所示。

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

{
  "Catalog": "AWSMarketplace",
  "ChangeSet":
  [
    {
      "ChangeType": "ReviveExperience",
      "DetailsDocument":
      {},
      "Entity":
      {
        "Type": "Experience@1.0",
        "Identifier": "exp-1234example"
      }
    }
  ]
}

私有市集 API 中的錯誤

下列錯誤專屬於目錄 API AWS Marketplace中的私有市集動作。

私有市集定義的實體類型

下表列出可指定每個 的私有市集實體類型、用途和動作。每個實體類型都可用來指定可在 (IAM) 政策中使用的資源 Amazon Resource Name AWS Identity and Access Management(ARN)。如需 ARN 格式的詳細資訊，請參閱 目錄 API 實體。