SaaS용 제품 수집 API

제품 수집 API는 모든 상업용 Marketplace 제품에서 모든 기존 제출 API를 통합하는 현대화된 API입니다. 시작하는 방법에 대한 자세한 내용은 제품 수집 API를 참조하세요.

이 문서에서는 SaaS 제품 유형에 특별히 API를 사용하는 방법에 대한 지침을 제공합니다.

기존 리소스 구성 검색

기존 리소스를 업데이트하기 전에 먼저 리소스를 검색하여 최신 구성이 있는지 확인해야 합니다. GET 호출을 통해 리소스를 검색하는 방법에는 여러 가지가 있습니다. 단일 API 호출에서 특정 제품 내의 모든 리소스를 검색하려면 다음 섹션인 메서드 1을 참조하세요.

방법 1: 리소스 트리

GET resource-tree/<product-durableID>?$version=<schema-version>

제품의 지속성 ID와 함께 "리소스 트리" 리소스 유형을 사용하여 특정 제품 내의 모든 리소스 구성을 검색할 수 있습니다. 제공하는 스키마 버전은 요청된 제품의 적용 가능한 각 리소스에 대해 지원되는 최대 버전으로 사용됩니다.

메모

제품의 지속성 ID를 모르는 경우 먼저 제품의 외부 ID를 사용하고 GET product?externalID=<product-externalID>&$version=<product-schema-version>실행하여 제품 리소스를 검색할 수 있습니다. 이 요청은 메서드 3에 자세히 설명된 쿼리 문자열 매개 변수를 활용합니다. 응답에는 향후 요청에 사용할 수 있는 제품의 지속성 ID가 포함됩니다.

기본적으로 "resource-tree"를 사용하여 GET 호출을 실행하면 리소스의 초안 버전을 다시 가져옵니다. 그러나 "targetType" 쿼리 매개 변수를 전달하여 원하는 대상을 지정하여 "미리 보기" 또는 "라이브" 데이터를 검색할 수 있습니다. 다음 예제에서 GET 호출은 "12345678-abcd-efgh-1234-12345678901" 제품 아래의 모든 리소스에 대한 미리 보기 환경의 구성을 반환합니다.

샘플 GET 호출:

GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?targetType="preview"&$version=2022-03-01-preview5

샘플 응답:

    {
        "$schema": "https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2",
        "root": "product/12345678-abcd-efgh-1234-12345678901",
        "target": {
        "targetType": "preview"
        },
        "resources": [
        { 
        "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
        "id": "product/12345678-abcd-efgh-1234-12345678901",
        "identity": {
            "externalID": "product_external_id_example"
        },
        "type": "softwareAsAService",
        "alias": "product_example"
        },
        { 
        "$schema": "https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2",
        "id": "commercial-marketplace-setup/12345678-abcd-efgh-1234-12345678901",
        "product": "product/12345678-abcd-efgh-1234-12345678901",
        "sellThroughMicrosoft": true,
        "useMicrosoftLicenseManagementService": false
        },
        {
        "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
        "id": "plan/12345678-abcd-efgh-1234-12345678901/98756328-04e9-55ae-9403-52b6c971a956
        ...
        }, 
            // The response would include all existing resources within this product.
        {
            ...
        }]
    }

리소스 수명 주기 상태

리소스의 수명 주기 상태에 매핑을 수행할 수 있는 다양한 작업이 있습니다. 모든 리소스에 수명 주기 상태가 있는 것은 아니며 모든 수명 주기 상태가 모든 리소스에서 지원되는 것은 아닙니다. 리소스 스키마에서 lifecycleState 속성이 있는지 확인하여 리소스에 수명 주기 상태와 지원되는 값이 있는지 확인합니다. 다음은 SaaS 제품 유형에 대한 리소스 수명 주기 상태를 설정하는 몇 가지 예입니다.

더 이상 사용되지 않는

사용 중단은 상업용 마켓플레이스에서 리소스를 제거합니다. 사용 중단하려면 해당 속성을 지원하는 리소스에서 "lifecycleState" 속성을 "사용되지 않음"으로 설정합니다. 제품 유형에 따라 다양한 수준의 사용 중단이 지원됩니다. 예를 들어 SaaS 제품의 경우 요금제 또는 전체 제품을 더 이상 사용하지 않을 수 있습니다. 계획을 사용 중단할 때 "lifecycleState"를 변경해야 하며, 변경된 내용을 미리 보기로 게시한 후에 최종적으로 라이브 상태로 게시하여 사용 중단이 적용되도록 해야 합니다. 이는 이 설정을 통해 라이브 환경에서 자동으로 사용 중단이 시작되는 제품 수준 사용 중단과 다릅니다. 더 이상 사용되지 않는 리소스를 나중에 복원하려면 "generallyAvailable" 수명 주기 상태를 참조하세요.

계획 사용 중단 샘플 요청:

다음 예제에서는 SaaS 제품의 요금제가 폐지될 예정입니다. 이 변경 내용을 적용하려면 나중에 제출 리소스를 사용하여 게시할 수 있습니다.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

    {
        "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
        "resources": [
        {
        "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
        "id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
        "product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
        "identity": { "externalID": "basic" },
        "alias": "basic plan"
        "lifecycleState": "deprecated"
        }
        ]
    }

제품 사용 중단 샘플 요청:

다음 예제에서는 제품의 실시간 제출이 더이상 사용되지 않도록 설정되었습니다. 이 변경 내용이 적용되면 라이브로 자동으로 게시되어 적용됩니다.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

    {
        "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
        "resources": [
        {
        "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 ",
        "id": "submission/9f8af57f-ab07-461b-8404-50e10e5e80fb/1152921515689848683",
        "product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
        "target": {
            "targetType": "live"
            },
        "lifecycleState": "deprecated"
        }
        ]
    }

일반 공급

일반적으로 사용 가능한 모든 리소스의 기본 수명 주기 상태입니다. 리소스가 사용 중단(폐기)되면 lifecycleState 속성을 일반적으로 사용 가능로 변경하여 복원할 수 있습니다. 중단된 제품을 복원하려면 제품을 미리 보기로 한 번 더 게시한 다음 라이브로 게시해야 합니다.

샘플 요청 복원 계획:

다음 예제에서는 계획을 복원할 예정입니다. 이 변경 내용을 적용하려면 나중에 제출 리소스를 사용하여 라이브로 게시를 완료해야 합니다.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

    {
        "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
        "resources": [
        {
        "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
        "id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
        "product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
        "identity": { "externalID": "basic" },
        "alias": "basic plan"
        "lifecycleState": "generallyAvailable"
        }
        ]
    }

관련 콘텐츠

• SaaS 제품 인제스천 API
• 트랜잭션 가능한 컨테이너를 위한 제품 수집 API