Condividi tramite

API di inserimento prodotti per SaaS

  • Articolo

L'API di inserimento prodotti è un'API modernizzata che unifica tutte le API di invio esistenti in tutti i prodotti del marketplace commerciale. Per informazioni dettagliate su come iniziare, vedere API di inserimento prodotti.

Questo articolo fornisce indicazioni su come usare le API specificamente per il tipo di offerta SaaS.

Recuperare le configurazioni delle risorse esistenti

Prima di aggiornare le risorse esistenti, è importante recuperarle per assicurarsi di avere la configurazione più recente. Esistono diversi modi per recuperare le risorse tramite una chiamata GET. Vedere la sezione seguente, Metodo 1, per recuperare tutte le risorse all'interno di un prodotto specifico in una singola chiamata API.

Metodo 1: Albero delle risorse

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

È possibile recuperare tutte le configurazioni delle risorse all'interno di un prodotto specifico usando il tipo di risorsa "albero delle risorse" insieme all'ID durevole del prodotto. La versione dello schema specificata verrà usata come versione massima supportata per ognuna delle risorse applicabili del prodotto richiesto.

Nota

Se non si conosce l'ID durevole del prodotto, è possibile recuperare prima la risorsa del prodotto usando l'ID esterno del prodotto ed eseguendo GET product?externalID=<product-externalID>&$version=<product-schema-version>. Questa richiesta sfrutta un parametro della stringa di query, descritto in Dettaglio nel metodo 3. La risposta includerà l'ID durevole del prodotto, che è possibile usare per le richieste future.

Per impostazione predefinita, quando si esegue una chiamata GET usando l'albero delle risorse, viene restituita la versione bozza delle risorse. Tuttavia, passando il parametro di query "targetType", è possibile specificare la destinazione desiderata per recuperare i dati "preview" o "live". Nell'esempio seguente la chiamata GET restituisce la configurazione dell'ambiente di anteprima per tutte le risorse nel prodotto "12345678-abcd-efgh-1234-12345678901".

Chiamata GET di esempio:

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

Risposta campione:

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

Stati del ciclo di vita delle risorse

Esistono diverse azioni che è possibile eseguire per eseguire il mapping allo stato del ciclo di vita di una risorsa. Non tutte le risorse hanno uno stato del ciclo di vita e non tutti gli stati del ciclo di vita sono supportati da tutte le risorse. Controllare lo schema della risorsa per l'esistenza del ciclo di vita della proprietàState per verificare se una risorsa ha uno stato del ciclo di vita e quali valori sono supportati. Di seguito sono riportati alcuni esempi per impostare lo stato del ciclo di vita delle risorse per il tipo di offerta SaaS.

Deprecato

La deprecazione rimuove la risorsa dal marketplace commerciale. Per deprecare, impostare la proprietà "lifecycleState" su "deprecata" nelle risorse che lo supportano. Diversi livelli di deprecazione sono supportati a seconda del tipo di prodotto. Ad esempio, per i prodotti SaaS, è possibile deprecare i piani o l'intero prodotto. Quando i piani sono deprecati, è necessario modificare "lifecycleState" e le modifiche devono quindi essere pubblicate in anteprima per rendere effettiva la deprecazione. Questa operazione è diversa da una deprecazione a livello di prodotto in cui questa impostazione avvia automaticamente la deprecazione nell'ambiente live. Per ripristinare in un secondo momento una risorsa deprecata, fare riferimento allo stato del ciclo di vita "generalmenteAvailable".

Pianificare la richiesta di esempio di deprecazione:

Nell'esempio seguente un piano all'interno di un prodotto SaaS è impostato su deprecato. Tenere presente che per applicare questa modifica, è possibile pubblicare in un secondo momento usando la risorsa di invio.

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

Richiesta di esempio di deprecazione del prodotto:

Nell'esempio seguente l'invio live del prodotto è impostato su deprecato. Dopo l'applicazione di questa modifica, viene pubblicata automaticamente in tempo reale per rendere effettiva la modifica.

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

Generalmente disponibile

generalmenteAvailable è lo stato predefinito del ciclo di vita per tutte le risorse. Dopo aver deprecato una risorsa, è possibile ripristinarla modificando la proprietà lifecycleState in genereAvailable. Per ripristinare un prodotto deprecato, è necessario pubblicare il prodotto ancora una volta in anteprima e quindi in tempo reale.

Pianificare la richiesta di esempio di ripristino:

Nell'esempio seguente un piano deve essere ripristinato. Per applicare questa modifica, in un secondo momento è necessario pubblicare tutto il modo in cui vivere usando la risorsa di invio.

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

Passaggi successivi