API de ingesta de productos para SaaS

  • Artículo

La API de ingesta de productos es una API modernizada que unifica todas las API de envío existentes en todos los productos de Marketplace comercial. Consulte Api de ingesta de productos para obtener más información sobre cómo empezar.

En este artículo se proporcionan instrucciones sobre cómo usar las API específicamente para el tipo de oferta de SaaS.

Recuperar las configuraciones de recursos existentes

Antes de actualizar los recursos existentes, es importante recuperarlos primero para asegurarse de que tiene su configuración más reciente. Existen varias maneras de recuperar recursos a través de una llamada GET. Consulte la sección siguiente, Método 1, para recuperar todos los recursos de un producto específico en una sola llamada API.

Método 1: árbol de recursos

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

Puede recuperar todas las configuraciones de recursos dentro de un producto específico mediante el tipo de recurso "árbol de recursos" junto con el identificador duradero del producto. La versión de esquema que proporcione se usará como la versión máxima admitida para cada uno de los recursos aplicables del producto solicitado.

Nota:

Si no conoce el identificador duradero del producto, puede recuperar primero el recurso del producto mediante el identificador externo del producto y la ejecución GET product?externalID=<product-externalID>&$version=<product-schema-version>de . Esta solicitud aprovecha un parámetro de cadena de consulta, que se detalla en el método 3. La respuesta incluirá el identificador duradero del producto, que puede usar para solicitudes futuras.

De forma predeterminada, cuando se ejecuta una llamada GET mediante el "árbol de recursos", se devuelve la versión de borrador de los recursos. Sin embargo, si pasa el parámetro de consulta "targetType", puede especificar el destino deseado para recuperar los datos "preview" o "live". En el ejemplo siguiente, la llamada GET devuelve la configuración del entorno de vista previa para todos los recursos del producto "12345678-abcd-efgh-1234-12345678901".

Llamada GET de ejemplo:

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

Respuesta de ejemplo:

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

Estados del ciclo de vida de los recursos

Hay diferentes acciones que puede realizar que se asignen al estado del ciclo de vida de un recurso. No todos los recursos tienen un estado de ciclo de vida y no todos los estados de ciclo de vida son compatibles con todos los recursos. Compruebe el esquema de recursos para comprobar la existencia de la propiedad lifecycleState para ver si un recurso tiene un estado de ciclo de vida y qué valores se admiten. A continuación se muestran algunos ejemplos para establecer el estado del ciclo de vida de los recursos para el tipo de oferta de SaaS.

En desuso

El desuso elimina el recurso del marketplace comercial. Para dejar de usar, establezca la propiedad "lifecycleState" en "en desuso" en los recursos que lo admiten. Se admiten varios niveles de desuso en función del tipo de producto. Por ejemplo, para los productos SaaS, puede dejar de usar planes o todo el producto. Al dejar de usar los planes, se debe cambiar "lifecycleState" y los cambios deben publicarse para obtener una vista previa y, a continuación, estar activos para que la desuso surta efecto. Esto es diferente de un desuso de nivel de producto en el que esta configuración inicia automáticamente el desuso en el entorno activo. Para restaurar posteriormente un recurso en desuso, consulte el estado del ciclo de vida "generalmenteAvailable".

Planear la solicitud de ejemplo de desuso:

En el ejemplo siguiente, un plan dentro de un producto SaaS se establece en desuso. Recuerde que para aplicar este cambio, puede publicarlo más adelante mediante el recurso de envío.

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

Solicitud de ejemplo de desuso del producto:

En el ejemplo siguiente, el envío en vivo del producto se establece en desuso. Una vez aplicado este cambio, se publica automáticamente para que surta efecto.

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

Disponibilidad general

generalmenteAvailable es el estado de ciclo de vida predeterminado para todos los recursos. Una vez que un recurso está en desuso, puede restaurarlo cambiando la propiedad lifecycleState a generallyAvailable. Para restaurar un producto en desuso, debe publicar el producto una vez más para obtener una vista previa y, a continuación, para estar activo.

Planear la solicitud de ejemplo de restauración:

En el ejemplo siguiente, se pretende restaurar un plan. Para aplicar este cambio, más adelante debe publicar todo el modo de vida mediante el recurso de envío.

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

Pasos siguientes