La référence d'API AWS Marketplace a été restructurée. Pour plus d'informations sur les opérations d'API prises en charge, consultez le manuel AWS Marketplace API Reference.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Travaillez avec le marché privé à l'aide du AWS Marketplace API

Vous pouvez utiliser le AWS Marketplace Catalog API pour gérer un marché privé pour votre entreprise Compte AWS ou celle de votre organisation.

Tous les types de modifications ne peuvent être appelés que depuis le compte de gestion de l'organisation ou par un compte de membre qui est un administrateur délégué pour un marché privé. Si vous êtes actuellement client d'un marché privé sans AWS Organizations intégration d'un marché privé, vous pouvez créer et gérer un marché privé à partir de n'importe quel compte de votre organisation doté de la politique AWSPrivateMarketplaceAdminFullAccess IAM.

Pour plus d'informations sur les marchés privés, consultez la section Sites de vente privés dans le Guide de l'AWS Marketplace acheteur.

Le tableau suivant détaille un ensemble de tâches permettant de gérer les sites de vente privés et les types de modifications applicables à chaque tâche.

Création d'un marché privé

Un marché privé pour un Compte AWS peut être considéré comme une liste de produits que les utilisateurs sont autorisés à acheter sur ce compte, ainsi que l'image de marque du marché. Dans une organisation dotée de plusieurs comptes, vous pouvez utiliser le regroupement issu de AWS Organizations l'unité organisationnelle (UO) pour l'associer à une expérience. Par exemple, vous pouvez avoir un ensemble de produits que tous les comptes de l'organisation sont autorisés à acheter, ou vous pouvez avoir une liste de produits différente pour chaque unité organisationnelle de l'organisation. Vous pouvez également avoir une liste de produits différente pour les comptes individuels de l'organisation. Chaque liste de produits et de marques approuvés est appelée une expérience d'achat.

Dans le AWS Marketplace Catalog API, quatre entités représentent une expérience :

Les étapes pour créer une expérience d'achat sont les suivantes :

Création de l'Experienceentité

Pour créer l'Experienceentité, utilisez l'StartChangeSetaction avec la CreateExperience valeur du ChangeType paramètre pour demander que l'expérience soit créée par AWS Marketplace. Consultez l’exemple de code suivant.

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

Dans cette action, Entity se trouve un modèle pour l'entité que vous souhaitez créer. Il est attribué et EntityId lors de sa création. ChangeSetNameidentifie le changement pour vous aider à le retrouver ultérieurement.

La réponse se présente comme suit.

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

La réponse inclut un ChangeSetId que vous pouvez utiliser pour connaître le statut de votre demande de modification au fur et à mesure de son traitementDescribeChangeSet. Vous pouvez également l'utiliser ListEntities pour rechercher votre Experience entité sans leChangeSetId. Pour plus d’informations sur les jeux de modifications, consultez Travailler avec des ensembles de modifications.

Une Experience entité nouvellement créée n'a pas de politique d'approvisionnement par défaut. Il est également créé avec les paramètres par défaut pour l'image de marque. Pour plus d'informations sur les paramètres de marque, notamment sur la façon de les personnaliser, consultezChanger l'image de marque d'une expérience de marché privée.

Création d'une ProcurementPolicy entité

Vous devez créer une ProcurementPolicy entité. Par défaut, une nouvelle Experience entité est désactivée. Vous pouvez donc créer la politique d'approvisionnement avant de l'activer.

Pour autoriser ou refuser des produits sur votre marché privé, vous devez créer la politique d'approvisionnement. Pour ce faire, vous appelez à nouveauStartChangeSet, mais cette fois avec ChangeType leCreateProcurementPolicy. L'exemple de code suivant crée une politique d'approvisionnement vide.

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

Dans cette action, Entity vous indiquez l'Experienceentité au sein de laquelle vous souhaitez créer la politique d'approvisionnement. Vous devez donc inclure l'identifiant de l'entité que vous avez créée précédemment. Utilisez ListEntities pour rechercher l'Experienceentité. Vous pouvez également renvoyer l'identifiant en l'utilisant DescribeChangeSet avec l'identifiant de l'ensemble de modifications figurant dans l'CreateExperienceaction

Vous pouvez à nouveau utiliser DescribeChangeSet le type de CreateProcurementPolicy modification pour suivre le traitement de votre demande.

Une fois que vous avez créé la politique d'achat, votre place de marché privée s'affiche dans le AWS Management Console. (Vous pouvez vous rendre sur la page Private Marketplace pour le consulter.) Une fois ces étapes terminées, votre place de marché privée sera désactivée, son image de marque par défaut sera définie, sa politique d'approvisionnement sera vide et elle ne sera associée à aucun responsable de votre organisation. Vous pouvez mettre à jour l'image de marque et y ajouter les produits que vous souhaitez, associer l'expérience à un ou plusieurs comptes, puis activer votre place de marché privée.

Les sections suivantes décrivent la gestion de votre place de marché privée avec AWS Marketplace Catalog API.

Changer l'image de marque d'une expérience de marché privée

Vous pouvez personnaliser l'apparence de votre place de marché privée pour vos utilisateurs. Sans personnalisation, votre place de marché privée utilisera les paramètres de marque par défaut, décrits ci-dessous. Les aspects de l'image de marque que vous pouvez modifier sur un marché privé sont les suivants :

Pour définir ces valeurs, vous devez d'abord créer une BrandingSettings entité avec le type de CreateBrandingSettings modification. Vous pouvez ensuite demander une UpdateBrandingSettings modification pour définir ou modifier l'image de marque. Vous ne devez créer un BrandingSettings objet qu'une seule fois. Pour créer cet objet, appelez StartChangeSet avec le type de CreateBrandingSettings modification, comme indiqué dans l'exemple de code suivant.

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

Cet exemple modifie l'Experienceentité en y ajoutant l'BrandingSettingsobjet. La révision de l'identifiant d'entité a été incrémentée à2. Pour plus d'informations sur les révisions des identifiants, consultezIdentifiant.

Vous pouvez modifier les paramètres en appelant StartChangeSet avec le type de UpdateBrandingSettings modification. Les paramètres font partie Configuration de l'DetailsDocumentobjet.

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

Activation ou désactivation d'une expérience de marché privée

Lorsqu'un marché privé est activé (et dispose d'une politique d'approvisionnement), les utilisateurs des comptes associés ne peuvent acheter que des produits que vous avez approuvés. Lorsqu'aucune expérience de marché privée n'est activée pour un compte, les utilisateurs peuvent acheter des produits dans l'ensemble du AWS Marketplace catalogue.

Pour activer un marché privé, utilisez l'StartChangeRequestaction avec le type de UpdateExperience modification.

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

De même, vous pouvez utiliser la même actionChangeType, mais Status en la remplaçant par DetailsDocument Disabled pour désactiver un marché privé.

Activation ou désactivation des demandes des utilisateurs

Les utilisateurs de votre organisation peuvent consulter l'intégralité du public AWS Marketplace, mais ils ne peuvent s'abonner qu'aux produits que vous avez autorisés. Par défaut, ils peuvent demander qu'un produit qui ne figure pas sur le marché privé y soit ajouté. Ces demandes apparaissent sur la page d'administration du marché privé (Private Marketplace), où vous pouvez décider d'accepter ou de refuser la demande (et de bloquer d'autres demandes pour le même produit). Vous ne pouvez pas voir les demandes ni y répondre à l'aide de l'API Catalog.

Vous pouvez activer ou désactiver la possibilité pour les utilisateurs de créer des demandes pour votre expérience de marché privée. À utiliser StartChangeSet avec le type de UpdateProcurementPolicy modification. La possibilité de faire des demandes est désactivée dans l'exemple de code suivant.

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

Pour activer la fonctionnalité de demande de modification pour les utilisateurs, utilisez Allow plutôt que Deny inPolicyResourceRequests.

Pour savoir comment obtenir l'état actuel de ce paramètre, consultez la section suivante,Obtenir une liste de produits dans le cadre d'une expérience de marché privée.

Obtenir une liste de produits dans le cadre d'une expérience de marché privée

Les produits autorisés (et refusés) sur un marché privé font partie de la politique d'approvisionnement de l'Experienceentité. Pour obtenir des informations détaillées sur les politiques d'approvisionnement d'un marché privé, vous devez d'abord obtenir l'identifiant de la politique d'approvisionnement auprès de l'Experienceentité, puis vous appelez DescribeEntity avec cet identifiant.

Pour obtenir l'identifiant de la politique d'approvisionnement, utilisez DescribeEntity l'Experienceentité qui vous intéresse, comme indiqué dans la commande suivante.

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

Voici un exemple de réponse.

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

Vous pouvez utiliser le retour EntityId pour la politique d'achat pour obtenir les détails, comme indiqué dans la commande suivante.

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

Cela renvoie tous les détails de la politique, y compris les produits autorisés et refusés. Voici un exemple de réponse.

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

Dans cet exemple, la politique d'approvisionnement prévoit deux produits autorisés et un produit refusé. La politique autorise les demandes de ressources des utilisateurs.

Ajouter ou supprimer des produits sur un marché privé

Par défaut, un marché privé ne contient aucun produit approuvé. Utilisez les demandes de modification pour ajouter ou supprimer un produit. Pour ajouter un produit, utilisez le type de AllowProductProcurement modification. Pour supprimer un produit, utilisez le type de DenyProductProcurement modification.

L'exemple de code suivant montre le type de AllowProductProcurement modification avec l'StartChangeSetaction d'ajouter un produit sur un marché privé.

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

Vous ajoutez le produit à l'Experienceentité pour un marché privé en utilisantAllowProductProcurement. La syntaxe permettant de retirer un produit d'un marché privé est identique, à l'exception du fait que vous utilisez le à la DenyProductProcurement ChangeType place deAllowProductProcurement. Les produits sont ajoutés à la liste d'autorisation (ou de refus) de l'ProcurementPolicyentité contenue dans votre Experience entité.

Trouver des produits

En obtenant les détails de votre politique d'approvisionnement, vous pouvez trouver les identifiants des produits déjà présents sur un marché privé. Cependant, il AWS Marketplace Catalog API ne permet pas de trouver les identifiants de produits pour d'autres produits. Il existe deux méthodes pour obtenir des identifiants de produit à utiliser avec le service Catalog API :

Travailler avec des places de marché privées pour AWS Organizations

Que vous travailliez avec une place de marché privée pour votre compte ou pour votre organisation, vous utilisez la même API. Cependant, il existe des différences lorsque vous travaillez au sein de votre organisation :

Pour répertorier Experience les objets de votre propre compte, appelez ListEntities comme indiqué dans l'exemple de code suivant.

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

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

Toutefois, pour répertorier les entités qui ont été partagées avec vous, vous devez ajouter un FilterList avec un Scope deSharedWithMe, comme indiqué dans l'exemple de code suivant. Par conséquent, vous effectuez des AWS Marketplace recherches en dehors de votre propre compte pour trouver les entités partagées avec vous.

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

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

Dans ce cas, seules les entités extérieures à votre compte (celles de votre organisation) sont renvoyées.

De même, pour appelerListChangeSets, vous devez définir la portée, comme indiqué dans l'exemple de code suivant.

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

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

Cela renvoie des ensembles de modifications qui s'appliquent à un marché privé partagé pour votre organisation.

Associer des principes à des expériences

Une expérience de marché privé doit être associée à un ou plusieurs principes afin d'avoir un impact sur votre organisation. Pour un single Compte AWS, vous devez associer le compte à l'expérience pour utiliser le marché privé. Au sein d'une organisation, plusieurs expériences peuvent s'appliquer à différents principes.

Pour associer un principal à une expérience, utilisez le type de AssociateAudience modification avec l'StartChangeSetaction, comme illustré dans l'exemple de code suivant.

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

L'audience est la liste des principaux associés auExperience. Un directeur est une Compte AWS unité organisationnelle ou une organisation définie par son identifiant. Principalsest une liste, de sorte que vous pouvez inclure plusieurs principes à associer à l'expérience. Après le premier appel, les appels suivants au type de AssociateAudience modification ajouteront des principes à l'association pour l'expérience.

Vous pouvez également supprimer des comptes d'une expérience. Pour ce faire, utilisez le type de DisassociateAudience modification, comme indiqué dans l'exemple de code suivant.

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

Archivage et réactivation d'une expérience de marché privée

Vous pouvez supprimer une expérience de marché privée en l'archivant. Les expériences archivées ne peuvent pas être mises à jour ni utilisées pour gérer les comptes de votre organisation. Si des audiences sont associées à une expérience archivée, vous pouvez les associer à une autre expérience. Si vous décidez d'utiliser l'expérience ultérieurement, vous pouvez toujours la réactiver. Les administrateurs du compte de gestion ou d'un compte membre qui est un administrateur délégué pour le marché privé sont autorisés à archiver et à réactiver les expériences. Si vous êtes actuellement client d'une place de marché privée sans AWS Organizations intégration d'une place de marché privée, les administrateurs du compte qui a créé l'expérience sont autorisés à archiver et à réactiver les expériences.

Pour archiver une expérience, utilisez le type de RestrictExperience modification avec l'StartChangeSetaction, comme illustré dans l'exemple de code suivant.

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

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

Pour réactiver une expérience, utilisez le type de ReviveExperience modification avec l'StartChangeSetaction, comme illustré dans l'exemple de code suivant.

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

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

Erreurs dans l'API du marché privé

Les erreurs suivantes sont spécifiques aux actions du marché privé dans l'API AWS Marketplace Catalog.

Types d'entités définis par le marché privé

Le tableau suivant répertorie les types d'entités du marché privé, leur objectif et les actions pour lesquels chacune peut être spécifiée. Chaque type d'entité peut être utilisé pour spécifier une ressource Amazon Resource Name (ARN) qui peut être utilisée dans la politique Gestion des identités et des accès AWS (IAM). Pour plus de détails sur les formats ARN, consultezEntités de l'API du catalogue.