AWS Marketplace API 참조가 재구성되었습니다. 지원되는 API 작업에 대한 자세한 내용은 AWS Marketplace API 참조를 참조하세요.

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AWS Marketplace 카탈로그 API 사용

AWS Marketplace Catalog API 서비스는 조직에 AWS Marketplace 대해 AWS 또는를 관리할 수 있는 API 인터페이스를 제공합니다 AWS 계정. 승인된 판매자의 경우의 셀프 서비스 게시 기능을 포함하여 제품을 프로그래밍 방식으로 관리할 수 있습니다AWS Marketplace Management Portal. 프라이빗 마켓플레이스 관리자의 경우 프라이빗 마켓플레이스를 프로그래밍 방식으로 관리할 수 있습니다.

카탈로그 API 작업을 사용하면 기존 제품을 프로그래밍 방식으로 보고 업데이트할 수 있습니다. 를 제품 빌드 또는 배포 파이프라인 AWS Marketplace Catalog API 과 통합하여 AWS Marketplace 제품 업데이트 프로세스를 자동화할 수 있습니다. 카탈로그 API를 기반으로 자체 애플리케이션을 생성하여 제품을 관리할 수도 있습니다 AWS Marketplace. AWS 계정 또는 AWS 조직의 사용자가 프라이빗 마켓플레이스를 통해 보고 구매할 수 있는 제품을 관리할 수 있습니다.

AWS Marketplace Catalog API 서비스는 표준 AWS API 기능을 제공합니다. 작업에 설명된 REST API 작업을 직접 사용하거나 AWS SDK를 사용하여 사용 중인 프로그래밍 언어 또는 플랫폼에 맞는 API에 액세스할 https://docs.aws.amazon.com/marketplace-catalog/latest/api-reference/API_Operations.html수 있습니다. AWS 애플리케이션 개발에 대한 자세한 내용은 시작하기를 참조하세요 AWS. AWS SDKs 사용에 대한 자세한 내용은 AWS SDKs.

카탈로그 API 엔터티

AWS Marketplace 엔터티는 제품 또는 제안과 같이 다양한 비즈니스 목적에 맞는 데이터 컨테이너입니다. 개체는 유형별로 분류됩니다. 각 엔터티 유형은 특정 비즈니스 도메인(예: 제품 또는 판매자 계정)과 관련된 데이터를 캡슐화합니다.

이 패러다임을 단순화하기 위해 개체는 구조에서 일정 수준의 공통성을 갖도록 설계되었습니다. 따라서 새 비즈니스 도메인을 도입하더라도 완전히 새로운 구조를 배울 필요가 없습니다.

일반 구조

개체의 일반적인 구조는 다음과 같습니다.

유형 버전 관리

이름이 지정된 모든 유형에는 유형과 버전이 연결되어 있습니다. 예: EntityProduct@1.0. 유형(엔터티 제품)은 콘텐츠의 분류를 나타냅니다. 버전(1.0)은 Entity Product의 구조를 나타냅니다.

버전은 개체의 구조에 대한 세부 정보를 제공합니다. 다음은 버전이 변경되는 시기를 설명합니다.

식별자

각 개체는 비즈니스 도메인 내의 고유한 사물을 나타냅니다. 고유한 사물을 식별하기 위해 prod-ad8EXAMPLE651@3과 RevisionId같은 EntityId와를 연결하는 식별자를 사용합니다. 이 예제에서 EntityId는 prod-ad8EXAMPLE651 이고는 RevisionId입니다3. 엔터티에 대한 모든 성공적인 변경 요청은 개정을 업데이트합니다.

다음은 식별자에 대한 중요한 세부 정보입니다.

DescribeEntity 작업을 사용하여 세부 정보와 가장 최근의 식별자를 찾을 수 있습니다revisionId.

RevisionId는에 대한 요청의 선택적 부분입니다StartChangeSet( 참조변경 세트 작업). 를 포함하면 RevisionId가 엔터티의 최신 개정RevisionId이 아닌 ValidationException 경우에 대한 요청이 StartChangeSet 실패합니다. 이를 통해 애플리케이션에서 낙관적 잠금을 구현할 수 있습니다.

를 생략하면 엔터티의 최신 개정에서 RevisionId요청이 자동으로 수행됩니다.

패싯

패싯은 속성의 논리적 그룹입니다. 엔터티에는 일반적으로 엔터티의 다양한 측면을 나타내는 여러 패싯이 포함됩니다. 패싯 내의 속성에는 다음과 같은 속성이 있습니다.

엔터티 유형

개체 유형은 개체가 나타내는 내용을 정의합니다. 엔터티는 AWS Marketplace 또는 프라이빗 마켓플레이스의 판매자 제품일 수 있습니다. 자세한 내용은 판매자 제품 작업 및 프라이빗 마켓플레이스 작업을 참조하세요.

변경 세트 작업

카탈로그 API를 사용하는 경우 엔터티를 통해 요청이 생성 및 업데이트되고 변경 요청을 사용하여 완료됩니다. 모든 변경에는 변경할 엔터티, 수행할 변경 유형 및 변경 세부 정보가 지정됩니다. 수행할 변경 유형을 라고 합니다ChangeType. 의 모음ChangeType을 라고 합니다ChangeSet.

변경 세트로 작업할 수 있는 네 가지 작업이 있습니다.

일반적인 워크플로는 로 변경을 요청한 다음 StartChangeSet반환된를 사용하여 변경이 완료될 때까지 DescribeChangeSet 작업을 ChangeSetId폴링하는 것입니다.

다음은 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"
}

변경이 완료되면 ListEntities를 사용하여 생성하거나 수정한 엔터티(및 연결된 )를 찾을 수 있습니다EntityID. 그런 다음와 DescribeEntity 함께 EntityID를 사용하여 세부 정보를 가져올 수 있습니다.

콘솔에서 판매자를 위한 변경 요청 작업에 대한 자세한 내용은 AWS Marketplace 판매자 안내서의 변경 요청 생성을 참조하세요.

여러 변경 요청을 동시에 수행

단일 변경 세트 내에서 모든 변경 유형을 번들링하고 함께 실행할 수 있습니다. 카탈로그 API는 최상의 성능을 제공하기 위해 동시에 여러 번 변경하도록 구축되었습니다. 판매자와 채널 파트너는에 여러 번들로 ChangeTypes 번들링된 변경 사항을 호출할 수 있습니다ChangeSet. 동일한의 단일 또는 다른 엔터티에 대해 여러 변경 사항을 호출할 수 있습니다ChangeSet. 카탈로그 API는 변경 사항을 적용해야 하는 순서를 평가하고 이러한 변경을 수행합니다.

그러나 요청이 별도의 변경 세트로 이루어진 경우는 동일한 제품에서 충돌하는 변경 요청을 시작할 수 AWS Marketplace 없습니다. 이러한 경우는 ResourceInUseException 오류를 AWS Marketplace 반환합니다.

변경 요청에 대한 ResourceInUseException 오류가 발생하면 나중에 요청을 다시 시도할 수 있습니다. 진행 중인 요청의 상태에 따라 첫 번째 요청을 취소하여 다시 제출된 두 번째 요청을 더 빨리 완료할 수 있습니다.

하나의 변경 세트에서 여러 변경 유형 호출

카탈로그 API를 사용하여 하나 이상의 서로 다른 엔터티를 대상으로 하는 StartChangeSet 요청 하나에 최대 20개의 변경 사항을 결합하고 연결할 수 있습니다.

일반적인 사용 사례는 SaaSProduct@1.0 초안 제품, Offer@1.0 초안 제안을 생성하고 제품 및 제안의 메타데이터 정보를 작성하는 것입니다. 이 작업은 다음과 같은 네 가지 변경 유형을 하나의 변경 세트에 포함시켜 수행됩니다.

다음은 결합된 변경 세트의 예입니다.

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 속성 작업(레거시)

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';)";

를 에코하면 JSON"${DETAILS_JSON_STRING}"이 제대로 이스케이프된 다음 문자열이 결과가 됩니다. {\"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"
      }
    ]
  }
}