A referência da API do AWS Marketplace foi reestruturada. Para obter mais informações sobre as operações de API suportadas, consulte a Referência de API do AWS Marketplace.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Trabalhe com o mercado privado usando oAWS Marketplacesolicitações de

Você pode usar o AWS Marketplace Catalog API para gerenciar um mercado privado para sua Conta da AWS organização.

Todos os tipos de alteração podem ser chamados somente pela conta de gerenciamento da organização ou por uma conta membro que seja um administrador delegado de um mercado privado. Se você é um cliente atual de um mercado privado sem a AWS Organizations integração com o mercado privado, você pode criar e gerenciar um mercado privado a partir de qualquer conta em sua organização que tenha a política AWSPrivateMarketplaceAdminFullAccess do IAM.

Para obter mais informações sobre mercados privados, consulte Mercados privados no Guia do AWS Marketplacecomprador.

A tabela a seguir detalha um conjunto de tarefas para gerenciar mercados privados e os tipos de alteração que se aplicam a cada tarefa.

Criando um mercado privado

Um mercado privado para um Conta da AWS pode ser considerado como uma lista de produtos que os usuários podem adquirir nessa conta e uma marca para o mercado. Em uma organização com várias contas, você pode usar o agrupamento da AWS Organizations chamada unidade organizacional (OU) para associar a uma experiência. Por exemplo, você pode ter um conjunto de produtos que todas as contas da organização podem adquirir, ou você pode ter uma lista diferente de produtos para cada UO na organização. Você também pode ter uma lista diferente de produtos para contas individuais na organização. Cada lista de produtos e marcas aprovados é chamada de experiência de aquisição.

NoAWS Marketplace Catalog API, quatro entidades representam uma experiência:

As etapas para criar uma experiência de aquisição são as seguintes:

Crie a Experience entidade

Para criar a Experience entidade, use a StartChangeSet ação com o CreateExperience valor do ChangeType parâmetro para solicitar que a experiência seja criada porAWS Marketplace. Consulte o seguinte exemplo de código.

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"
}

Nesta ação, Entity é um modelo para a entidade que você deseja criar. Ele é atribuído e EntityId quando é criado. ChangeSetNameidentifica a alteração para ajudá-lo a encontrá-la mais tarde.

A resposta é semelhante à seguinte.

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

A resposta inclui uma ChangeSetId que você pode usar para obter o status da sua solicitação de alteração à medida que ela é processadaDescribeChangeSet. Você também pode usar ListEntities para encontrar sua Experience entidade sem ChangeSetId o. Para obter mais informações sobre conjuntos de alterações, consulte Trabalhando com conjuntos de alterações.

Uma Experience entidade recém-criada não tem uma política de compras por padrão. Ele também é criado com as configurações padrão de identidade visual. Para obter mais informações sobre as configurações de identidade visual, incluindo como personalizá-las, consulteMudando a marca de uma experiência de mercado privado.

Crie uma ProcurementPolicy entidade

Você deve criar uma ProcurementPolicy entidade. Por padrão, uma nova Experience entidade está desativada, para que você possa criar a política de compras antes de ativá-la.

Para permitir e negar produtos em seu mercado privado, você deve criar a política de compras. Para fazer isso, você liga novamenteStartChangeSet, mas desta vez com o ChangeType deCreateProcurementPolicy. O exemplo de código a seguir cria uma política de compras vazia.

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"
      }
    }
  ]
}

O que Entity você fornece nesta ação é a Experience entidade na qual você deseja que a política de compras seja criada, portanto, você deve incluir o identificador da entidade que você criou anteriormente. Use ListEntities para encontrar a Experience entidade. Você também pode retornar o identificador usando DescribeChangeSet com o identificador do conjunto de alterações da CreateExperience ação

Você pode usar DescribeChangeSet novamente o tipo de CreateProcurementPolicy alteração para acompanhar o processamento de sua solicitação.

Depois de criar a política de compras, seu mercado privado é exibido noAWS Management Console. (Você pode acessar a página do Private Marketplace para vê-lo.) Depois de concluir essas etapas, seu mercado privado será desativado, terá uma marca padrão, terá uma política de compras vazia e não será associado a nenhum diretor em sua organização. Você pode atualizar a marca e adicionar os produtos que quiser, associar a experiência a uma ou mais contas e, em seguida, ativar seu mercado privado.

As seções a seguir descrevem o gerenciamento de seu mercado privado com AWS Marketplace Catalog API o.

Mudando a marca de uma experiência de mercado privado

Você pode personalizar a aparência do seu mercado privado para seus usuários. Sem personalização, seu mercado privado terá as configurações de marca padrão, descritas abaixo. Os aspectos da marca que você pode alterar em um mercado privado incluem o seguinte:

Para definir esses valores, você deve primeiro criar uma BrandingSettings entidade com o tipo de CreateBrandingSettings alteração. Em seguida, você pode solicitar uma UpdateBrandingSettings alteração para definir ou alterar a marca. Você só precisa criar um BrandingSettings objeto uma vez. Para criar esse objeto, chame StartChangeSet com o tipo de CreateBrandingSettings alteração, conforme mostrado no exemplo de código a seguir.

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"
      }
    }
  ]
}

Este exemplo modifica a Experience entidade adicionando o BrandingSettings objeto a ela. A revisão do identificador da entidade foi incrementada para2. Para obter mais informações sobre revisões de identificadores, consulte. Identificador

Você modifica as configurações chamando StartChangeSet com o tipo de UpdateBrandingSettings alteração. As configurações fazem parte Configuration do DetailsDocument objeto.

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"
      }
    }
  ]
}

Ativando ou desativando uma experiência de mercado privado

Quando um mercado privado está ativado (e tem uma política de compras), os usuários nas contas associadas só podem comprar produtos aprovados por você. Quando nenhuma experiência de mercado privado está habilitada para uma conta, os usuários podem comprar produtos em todo o AWS Marketplace catálogo.

Para habilitar um mercado privado, use a StartChangeRequest ação com o tipo de UpdateExperience alteração.

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"
      }
    }
  ]
}

Da mesma forma, você pode usar a mesma ação eChangeType, mas alterar a Status entrada DetailsDocument para, Disabled para desativar um mercado privado.

Ativando ou desativando solicitações de usuários

Os usuários da sua organização podem ver o público completoAWS Marketplace, mas só podem assinar os produtos que você permitiu. Por padrão, eles podem solicitar que um produto que não esteja no mercado privado seja adicionado a ele. Essas solicitações aparecem na página do administrador do mercado privado (Private Marketplace), onde você pode decidir se aceita ou nega a solicitação (e se deseja bloquear outras solicitações para o mesmo produto). Você não pode ver nem responder às solicitações usando a API de catálogo.

Você pode ativar ou desativar a capacidade de os usuários criarem solicitações para sua experiência de mercado privado. Use StartChangeSet com o tipo de UpdateProcurementPolicy alteração. A capacidade de fazer solicitações está desativada no exemplo de código a seguir.

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"
      }
    }
  ]
}

Para habilitar o recurso de solicitação de alteração para usuários, use Allow em vez de Deny inPolicyResourceRequests.

Para saber como obter o status atual dessa configuração, consulte a próxima seção,Obter uma lista de produtos em uma experiência de mercado privado.

Obter uma lista de produtos em uma experiência de mercado privado

Os produtos permitidos (e negados) em um mercado privado fazem parte da política de compras da Experience entidade. Para obter os detalhes sobre as políticas de compras em um mercado privado, primeiro você obtém o identificador da política de compras da Experience entidade e, em seguida, liga DescribeEntity com esse identificador.

Para obter o identificador da política de compras, use DescribeEntity na Experience entidade na qual você está interessado, conforme mostrado no comando a seguir.

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

Veja a seguir uma resposta de exemplo.

{
  "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"
}

Você pode usar o retornado EntityId para a política de compras para obter os detalhes, conforme mostrado no comando a seguir.

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

Isso retorna todos os detalhes da política, incluindo produtos permitidos e negados. Veja a seguir uma resposta de exemplo.

{
  "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"
}

Neste exemplo, a política de compras tem dois produtos permitidos e um produto negado. A política permite solicitações de recursos do usuário.

Adicionar ou remover produtos de um mercado privado

Por padrão, um mercado privado não tem nenhum produto aprovado. Use solicitações de alteração para adicionar ou remover um produto. Para adicionar um produto, use o tipo de AllowProductProcurement alteração. Para remover um produto, use o tipo de DenyProductProcurement alteração.

O exemplo de código a seguir mostra o tipo de AllowProductProcurement alteração com a StartChangeSet ação de adicionar um produto a um mercado privado.

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"
      }
    }
  ]
}

Você adiciona o produto à Experience entidade para um mercado privado usandoAllowProductProcurement. A sintaxe para remover um produto de um mercado privado é idêntica, com a exceção de que você usa o DenyProductProcurement ChangeType em vez deAllowProductProcurement. Os produtos são adicionados à lista de permitir (ou negar) da ProcurementPolicy entidade contida em sua Experience entidade.

Encontrar produtos

Ao obter os detalhes da sua política de compras, você pode encontrar os IDs dos produtos que já estão em um mercado privado. No entanto, o AWS Marketplace Catalog API não fornece uma maneira de encontrar as IDs de produtos de outros produtos. Há duas maneiras de obter IDs de produtos para usar com o serviço da API de catálogo:

Trabalhando com mercados privados paraAWS Organizations

Se você está trabalhando com um mercado privado para sua conta ou sua organização, você usa a mesma API. No entanto, existem diferenças ao trabalhar em sua organização:

Para listar Experience objetos em sua própria conta, chame ListEntities conforme mostrado no exemplo de código a seguir.

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

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

No entanto, para listar as entidades que foram compartilhadas com você, você deve adicionar um FilterList com um Scope deSharedWithMe, conforme mostrado no exemplo de código a seguir. Como resultado, AWS Marketplace pesquisa fora da sua própria conta para encontrar entidades que são compartilhadas com você.

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

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

Nesse caso, somente entidades fora da sua conta (aquelas da sua organização) são retornadas.

Da mesma forma, para chamarListChangeSets, você deve definir o escopo, conforme mostrado no exemplo de código a seguir.

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

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

Isso retorna conjuntos de alterações que se aplicam a um mercado privado compartilhado para sua organização.

Associando diretores a experiências

Uma experiência de mercado privado deve ter um ou mais princípios associados a ela para ter algum efeito em sua organização. Por exemploConta da AWS, você deve associar a conta à experiência para usar o mercado privado. Em uma organização, você pode ter várias experiências aplicadas a diferentes princípios.

Para associar um diretor a uma experiência, use o tipo de AssociateAudience alteração com a StartChangeSet ação, conforme mostrado no exemplo de código a seguir.

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"
}

O público é a lista de diretores associados aoExperience. Um diretor é uma Conta da AWS unidade organizacional ou organização definida por seu ID. Principalsé uma lista, para que você possa incluir vários princípios a serem associados à experiência. Após a primeira chamada, as chamadas subsequentes para o tipo de AssociateAudience alteração adicionarão diretores à associação para a experiência.

Você também pode remover contas de uma experiência. Use o tipo de DisassociateAudience alteração para fazer isso, conforme mostrado no exemplo de código a seguir.

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"
}

Arquivamento e reativação de uma experiência de mercado privado

Você pode remover uma experiência de mercado privado arquivando-a. As experiências arquivadas não podem ser atualizadas nem usadas para controlar contas na sua organização. Se você tiver audiências associadas a uma experiência arquivada, poderá associá-las a uma experiência diferente. Se você decidir usar a experiência mais tarde, poderá reativá-la quando quiser. Os administradores da conta de gerenciamento ou de uma conta membro que seja um administrador delegado do mercado privado têm permissões para arquivar e reativar experiências. Se você é um cliente atual de um mercado privado sem a AWS Organizations integração com o mercado privado, os administradores da conta que criou a experiência têm permissões para arquivar e reativar experiências.

Para arquivar uma experiência, use o tipo de RestrictExperience alteração com a StartChangeSet ação, conforme mostrado no exemplo de código a seguir.

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

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

Para reativar uma experiência, use o tipo de ReviveExperience alteração com a StartChangeSet ação, conforme mostrado no exemplo de código a seguir.

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

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

Erros na API do mercado privado

Os erros a seguir são específicos das ações do mercado privado na API de AWS Marketplace catálogo.

Tipos de entidade definidos pelo mercado privado

A tabela a seguir lista os tipos, objetivos e ações de entidades do mercado privado nas quais cada uma pode ser especificada. Cada tipo de entidade pode ser usado para especificar um recurso Amazon Resource Name (ARN) que pode ser usado na política AWS Identity and Access Management (IAM). Para obter mais detalhes sobre os formatos ARN, consulte. Entidades da API de catálogo