共用方式為

適用於 SaaS 的產品擷取 API

  • 發行項

產品擷取 API 是現代化 API，可統一所有商業市集產品的所有現有提交 API。 如需如何開始使用的詳細資訊，請參閱產品擷取 API。

本文提供如何特別針對 SaaS 供應專案類型使用 API 的指引。

擷取現有的資源組態

更新現有資源之前，請務必先擷取它們，以確保您有最新的設定。 有數種方式可透過 GET 呼叫擷取資源。 請參閱下一節方法 1，以在單一 API 呼叫中擷取特定產品中的所有資源。

方法 1：資源樹狀結構

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

您可以使用「資源樹狀結構」資源類型，以及產品的耐久標識符，擷取特定產品內的所有資源組態。 您提供的架構版本將作為所要求產品每個適用資源的最大支援版本。

注意

如果您不知道產品的耐久標識符，您可以改為使用產品的外部標識碼並執行 GET product?externalID=<product-externalID>&$version=<product-schema-version>來擷取產品資源。 此要求會利用方法 3 中詳述的查詢字串參數。 回應會包含產品的耐久標識符，您可以用於未來的要求。

根據預設，當您使用 「resource-tree」 執行 GET 呼叫時，您會取回資源的草稿版本。 不過，藉由傳遞 「targetType」 查詢參數，您可以指定所需的目標來擷取 「preview」 或 「live」 資料。 在下列範例中，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” 屬性設定為 “deprecated”。 根據產品類型，支援各種層級的淘汰。 例如，針對 SaaS 產品，您可以取代方案或整個產品。 當淘汰計劃時，必須變更 「lifecycleState」，然後必須發佈變更，才能讓取代生效。 這與產品層級淘汰不同，在此設定時，這會在實時環境中自動啟動淘汰。 若要稍後還原已被取代的資源，請參閱「一般Available」生命周期狀態。

規劃取代範例要求：

在下列範例中，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"
        }
        ]
    }

正式推出

一般而言，Available 是所有資源的默認生命周期狀態。 一旦資源已被取代，您就可以將 lifecycleState 屬性變更回 generallyAvailable 來還原它。 若要還原已被取代的產品，您必須再次發佈產品以預覽，然後上線。

規劃還原範例要求：

在下列範例中，計劃是要還原。 若要套用這項變更，您稍後必須一路發佈，才能使用提交資源。

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

下一步