API de Ingestão de Produtos para SaaS

  • Artigo

A API de ingestão de produtos é uma API modernizada que unifica todas as APIs de envio existentes em todos os produtos do mercado comercial. Consulte a API de ingestão de produtos para obter detalhes sobre como começar.

Este artigo fornece orientação sobre como usar as APIs especificamente para o tipo de oferta SaaS.

Recuperar configurações de recursos existentes

Antes de atualizar os recursos existentes, é importante recuperá-los primeiro para garantir que você tenha a configuração mais recente. Há várias maneiras de recuperar recursos por meio de uma chamada GET. Consulte a seção a seguir, Método 1, para recuperar todos os recursos dentro de um produto específico em uma única chamada de API.

Método 1: Árvore de recursos

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

Você pode recuperar todas as configurações de recursos dentro de um produto específico usando o tipo de recurso "árvore de recursos" junto com a ID durável do produto. A versão do esquema fornecida será usada como a versão máxima suportada para cada um dos recursos aplicáveis do produto solicitado.

Nota

Se você não souber a ID durável do produto, poderá recuperar o recurso do produto primeiro usando a ID externa do produto e executando GET product?externalID=<product-externalID>&$version=<product-schema-version>. Essa solicitação aproveita um parâmetro de cadeia de caracteres de consulta, que é detalhado no Método 3. A resposta incluirá o ID durável do produto, que você pode usar para solicitações futuras.

Por padrão, quando você executa uma chamada GET usando a "árvore de recursos", você recebe de volta a versão de rascunho de seus recursos. No entanto, passando o parâmetro de consulta "targetType", você pode especificar o destino desejado para recuperar os dados "preview" ou "live". No exemplo a seguir, a chamada GET retorna a configuração do ambiente de visualização para todos os recursos sob o produto "12345678-abcd-efgh-1234-12345678901".

Exemplo de chamada GET:

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

Exemplo de resposta:

    {
        "$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 do ciclo de vida dos recursos

Há diferentes ações que você pode executar esse mapa para o estado do ciclo de vida de um recurso. Nem todos os recursos têm um estado de ciclo de vida e nem todos os estados do ciclo de vida são suportados por todos os recursos. Verifique o esquema de recursos para a existência da propriedade lifecycleState para ver se um recurso tem um estado de ciclo de vida e quais valores são suportados. A seguir estão alguns exemplos para definir o estado do ciclo de vida do recurso para o tipo de oferta SaaS.

Preterido

A preterição remove o recurso do mercado comercial. Para depreciar, defina a propriedade "lifecycleState" como "preterida" nos recursos que a suportam. Vários níveis de depreciação são suportados, dependendo do tipo de produto. Por exemplo, para produtos SaaS, você pode depreciar planos ou o produto inteiro. Ao substituir planos, o "lifecycleState" deve ser alterado e as alterações devem ser publicadas para visualização e, em seguida, ao vivo para que a substituição entre em vigor. Isso é diferente de uma depreciação no nível do produto, na qual essa configuração inicia automaticamente a depreciação no ambiente ao vivo. Para restaurar posteriormente um recurso preterido, consulte o estado do ciclo de vida "geralmenteDisponível".

Solicitação de amostra de substituição de plano:

No exemplo a seguir, um plano dentro de um produto SaaS é definido como depreciado. Lembre-se de que, para aplicar essa alteração, você pode publicar posteriormente usando o recurso de envio.

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

Solicitação de amostra de substituição do produto:

No exemplo a seguir, o envio ao vivo do produto é definido como depreciado. Uma vez que essa alteração é aplicada, ela é automaticamente publicada ao vivo para entrar em vigor.

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

Disponibilidade geral

geralmenteDisponível é o estado padrão do ciclo de vida para todos os recursos. Depois que um recurso for preterido, você poderá restaurá-lo alterando a propriedade lifecycleState de volta para generallyAvailable. Para restaurar um produto preterido, você deve publicar o produto mais uma vez para visualizar e, em seguida, para viver.

Planejar solicitação de amostra de restauração:

No exemplo a seguir, um plano deve ser restaurado. Para aplicar essa alteração, você precisará publicar todo o caminho ao vivo usando o recurso de envio.

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

Próximos passos