Die AWS Marketplace API-Referenz wurde neu strukturiert. Weitere Informationen zu den unterstützten API-Vorgängen finden Sie in der AWS Marketplace API-Referenz.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Verwendung der AWS Marketplace Catalog-API

Der AWS Marketplace Catalog API Dienst bietet eine API-Schnittstelle zur Verwaltung AWS Marketplace für Ihre AWS Organisation oder AWS-Konto. Für zugelassene Verkäufer können Sie Ihre Produkte programmgesteuert verwalten, einschließlich der Self-Service-Veröffentlichungsfunktionen auf der. AWS Marketplace Management Portal Administratoren privater Marketplace-Sites können ihren privaten Marketplace programmgesteuert verwalten.

Mit den Aktionen der Katalog-API können Sie Ihr vorhandenes Produkt programmgesteuert anzeigen und aktualisieren. Sie können Ihren Produktaktualisierungsprozess automatisieren, indem Sie sie in Ihre Entwicklungs- oder AWS Marketplace Bereitstellungs-Pipelines integrieren. AWS Marketplace Catalog API Sie können zusätzlich zur Katalog-API auch Ihre eigenen Anwendungen erstellen, in AWS Marketplace denen Sie Ihre Produkte verwalten können. Sie können die Produkte verwalten, die Benutzer in Ihrem AWS Unternehmen AWS-Konto oder in Ihrer Organisation über Ihren privaten Marktplatz sehen und kaufen können.

Der AWS Marketplace Catalog API Service bietet AWS Standard-API-Funktionen. Sie können die unter Aktionen beschriebenen REST-API-Aktionen direkt verwenden, oder Sie können ein AWS SDK verwenden, um auf eine API zuzugreifen, die auf die von Ihnen verwendete Programmiersprache oder Plattform zugeschnitten ist. Weitere Informationen zur AWS Anwendungsentwicklung finden Sie unter Erste Schritte mit AWS. Weitere Informationen zur Verwendung von AWS SDKs finden Sie unter AWS-SDKs.

API-Entitäten katalogisieren

AWS Marketplace Entitäten sind Datencontainer, die unterschiedlichen Geschäftszwecken dienen, z. B. einem Produkt oder Angebot. Entitäten werden nach Typen kategorisiert. Jeder Entitätstyp kapselt Daten, die sich auf eine bestimmte Geschäftsdomäne beziehen (z. B. ein Produkt oder ein Verkäuferkonto).

Um dieses Paradigma zu vereinfachen, wurden Entitäten so konzipiert, dass ihre Strukturen ein gewisses Maß an Gemeinsamkeit aufweisen. Daher erfordert die Einführung eines neuen Geschäftsbereichs nicht, dass Sie eine völlig neue Struktur erlernen.

Allgemeine Struktur

Die allgemeine Struktur jeder Entität ist:

Geben Sie Versionierung ein

Jedem benannten Typ sind ein Typ und eine Version zugeordnet, zum Beispiel. EntityProduct@1.0 Der Typ (EntityProdukt) steht für die Klassifizierung des Inhalts. Die Version (1.0) steht für die Struktur des Entity Produkts.

Die Version gibt Ihnen Details über die Struktur der Entität. Im Folgenden wird beschrieben, wann eine Version geändert wird:

Kennung

Jede Entität stellt eine einzigartige Sache innerhalb einer Geschäftsdomäne dar. Um das Einzigartige zu identifizieren, verwenden wir einen Bezeichner, der ein EntityId mit einem prod-ad8EXAMPLE651 @ 3 verknüpftRevisionId, zum Beispiel. In diesem Beispiel sind es das EntityId ist prod-ad8EXAMPLE651 und das RevisionId ist3. Bei jeder erfolgreichen Änderungsanforderung an die Entität wird die Revision aktualisiert.

Im Folgenden finden Sie wichtige Informationen zur Kennung:

Sie können die DescribeEntity Aktion verwenden, um die Details und den Identifier mit der neuesten Version zu findenrevisionId.

Dies RevisionId ist ein optionaler Teil von Anfragen an StartChangeSet (sieheMit Änderungssätzen arbeiten). Wenn Sie eine angebenRevisionId, schlägt die Anfrage an mit a StartChangeSet fehl, ValidationException sofern RevisionId es sich nicht um die neueste Version der Entität handelt. Auf diese Weise können Sie optimistisches Sperren in Ihrer Anwendung implementieren.

Wenn Sie das weglassenRevisionId, wird die Anforderung automatisch für die neueste Version der Entität ausgeführt.

Facets

Eine Facette ist eine logische Gruppierung von Attributen. Eine Entität umfasst normalerweise mehrere Facetten, die verschiedene Aspekte der Entität repräsentieren. Die Attribute innerhalb einer Facette haben die folgenden Eigenschaften:

Entitätstyp

Der Entitätstyp definiert, wofür die Entität steht. Eine Entität kann ein Verkäufer, ein Produkt auf einem privaten Markt AWS Marketplace oder ein privater Marktplatz sein. Weitere Informationen finden Sie unter Arbeiten mit Verkäuferprodukten und Arbeiten mit einer privaten Marketplace-Site.

Mit Änderungssätzen arbeiten

Bei Verwendung der Katalog-API werden Anfragen über Entitäten erstellt und aktualisiert und mithilfe von Änderungsanforderungen abgeschlossen. Bei jeder Änderung werden die zu ändernde Entität, die Art der durchzuführenden Änderung und Einzelheiten der Änderung angegeben. Die Art der durchzuführenden Änderung wird als a bezeichnetChangeType. Eine Sammlung von ChangeType s wird a genanntChangeSet.

Es gibt vier Aktionen, mit denen Sie mit Änderungssätzen arbeiten können:

Ein typischer Arbeitsablauf besteht darinStartChangeSet, eine Änderung mit anzufordern und die DescribeChangeSet Aktion dann mithilfe der zurückgegebenen Option ChangeSetId abzufragen, bis die Änderung abgeschlossen ist.

Im Folgenden finden Sie ein Beispiel für die DescribeChangeSet Antwort.

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

Nachdem Ihre Änderung abgeschlossen ist, können Sie damit die Entität, ListEntities die Sie erstellt oder geändert haben, (und die zugehörige Entität) suchen. EntityID Sie können dann DescribeEntity mit dem weitere Informationen EntityID dazu abrufen.

Weitere Informationen zur Arbeit mit Änderungsanträgen in der Konsole für Verkäufer finden Sie im AWS Marketplace Verkäuferleitfaden unter Änderungsanträge erstellen.

Gleichzeitiges Stellen mehrerer Änderungsanfragen

In einem einzigen Änderungssatz können Sie alle Änderungstypen bündeln und sie werden zusammen ausgeführt. Die Katalog-API ist so konzipiert, dass mehrere Änderungen gleichzeitig vorgenommen werden können, um die beste Leistung zu erzielen. Verkäufer und Vertriebspartner können Änderungen vornehmen, bei denen mehrere Änderungen ChangeTypes gebündelt sind. ChangeSet Sie können mehrere Änderungen an einzelnen oder verschiedenen Entitäten in derselben Instanz vornehmen. ChangeSet Die Katalog-API bewertet, in welcher Reihenfolge die Änderungen angewendet werden müssen, und nimmt diese Änderungen vor.

Wenn die Anfragen jedoch als separate Änderungssätze gestellt werden, AWS Marketplace können widersprüchliche Änderungsanforderungen für dasselbe Produkt nicht initiiert werden. In diesen Fällen wird ein ResourceInUseException Fehler AWS Marketplace zurückgegeben.

Wenn Sie bei einer ResourceInUseException Änderungsanfrage eine Fehlermeldung erhalten, können Sie die Anfrage später erneut versuchen. Je nach Status der laufenden Anfrage können Sie auch die erste Anfrage stornieren, damit die erneut eingereichte zweite Anfrage früher abgeschlossen werden kann.

Aufrufen mehrerer Änderungstypen in einem Änderungssatz

Sie können die Katalog-API verwenden, um bis zu 20 Änderungen in einer StartChangeSet Anfrage zu kombinieren und zu verketten, die auf eine oder mehrere verschiedene Entitäten abzielen.

Ein typischer Anwendungsfall ist die Erstellung eines SaaSProduct@1.0 Produktentwurfs und eines Offer@1.0 Angebotsentwurfs sowie das Ausfüllen der Metadateninformationen des Produkts und des Angebots. Dies wird erreicht, indem die folgenden vier Änderungstypen in einem Änderungssatz zusammengefasst werden:

Das Folgende ist ein Beispiel für einen kombinierten Änderungssatz.

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

Arbeiten mit dem Details-Attribut (Legacy)

Das Details Attribut der StartChangeSet Operation ist ein Zeichenfolgenwert. Sein Inhalt sind JSON-Objekte. Um ein JSON-Objekt in ein Zeichenkettenattribut einzufügen, müssen Sie das Objekt in eine einzeilige Zeichenfolge konvertieren, indem Sie alle JSON-Steuerzeichen maskieren und Zeilenumbrüche entfernen.

Wenn Sie beispielsweise den StartChangeSet Vorgang mit verwenden, UpdateProcurementPolicy um Anfragen von Benutzern auf Ihrem privaten Marktplatz zu deaktivieren, stellen Sie eine Anfrage wie die folgende.

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

In diesem Fall sieht das JSON-Objekt, das Sie für das Details Attribut verwenden, wie folgt aus (vor der Konvertierung in eine Zeichenfolge).

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

Für das Details Attribut ist jedoch eine Zeichenfolge erforderlich, kein JSON. Nach der Konvertierung dieses JSON-Objekts in eine einzeilige Zeichenfolge sieht es wie folgt aus.

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

Mit dieser Zeichenfolge können Sie die vollständige Änderungsansatzanforderung wie folgt erstellen.

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

Im Allgemeinen zeigen Beispiele in dieser API-Referenz, dass das JSON-Objekt bereits in eine Zeichenfolge konvertiert wurde. In einigen Fällen sind kompliziertere Beispiele mit neuen Zeilen enthalten, um das Verständnis zu verbessern.

Automatisieren Sie die Konvertierung von JSON in eine Zeichenfolge

Die Konvertierung eines JSON-Objekts in eine Zeichenfolge kann mithilfe von Tools wie jq, einem einfachen Befehlszeilen-JSON-Prozessor, automatisiert werden. Das folgende Beispiel zeigt die Verwendung jq zur Konvertierung eines JSON-Objekts in eine Zeichenfolge, die im Attribut verwendet werden kann. 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';)";

Wenn Sie echo verwenden"${DETAILS_JSON_STRING}", ist das Ergebnis die folgende Zeichenfolge, bei der JSON korrekt maskiert wurde: {\"ProductTitle\":\"My Product\",\"ShortDescription\":\"My product short description.\",\"LongDescription\":\"My product long description.\"}

Wird verwendet DescribeEntity , um Informationen über Ihre Entitäten zu erhalten

Über die Katalog-API können Sie programmgesteuert Informationen zu Ihren bestehenden Entitäten, einschließlich Produkten und privaten Marktplätzen, abrufen.

Die ListEntities Aktion gibt eine Liste von Entitäten zurück. Anschließend können Sie die DescribeEntity Aktion verwenden, um Details zu einer einzelnen Entität abzurufen. Dies kann direkt nützlich sein, um beispielsweise die von Ihnen verkauften Produkte zu katalogisieren. Dies kann auch beim Aktualisieren von Entitäten nützlich sein, da Sie den aktuellen Status der Entität abrufen können, bevor Sie nur die Teile aktualisieren, die Sie aktualisieren möchten.

Das folgende Beispiel zeigtListEntities, wie Sie eine Liste von Containerprodukten abrufen und anschließend Informationen DescribeEntity zu einem der spezifischen Produkte abrufen können.

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

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

Für den Entitätstyp müssen Sie den Entitätstyp ohne die Version verwenden. Es gibt alle Entitäten dieses Typs zurück (und filtert nicht nach Version).

Hier ist ein Beispiel für die Reaktion auf die ListEntities Aktion.

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

Verwenden Sie die DescribeEntity Aktion, um die Details zu einem dieser Produkte abzurufen. Das folgende Beispiel zeigt, wie Sie Details zum ersten oben zurückgegebenen Produkt abrufen können.

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

Das Folgende zeigt die Antwort aufDescribeEntity.

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