API de ingestão de produto para SaaS
A API de ingestão de produtos é uma API modernizada que unifica todas as APIs de envio existentes em todos os produtos do marketplace comercial. Consulte API de assimilação de produtos para obter detalhes sobre como começar.
Este artigo fornece diretrizes sobre como usar as APIs especificamente para o tipo de oferta SaaS.
Recuperar configurações de recurso existentes
Antes de atualizar os recursos existentes, é importante primeiro recuperá-los 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 em 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 em 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.
Observação
Se você não souber a ID durável do produto, poderá recuperá-lo 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ê obtém de volta a versão de rascunho de seus recursos. No entanto, ao passar 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 no 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
Resposta de exemplo:
{
"$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 do recurso
Há diferentes ações que você pode executar que mapeiam 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 é compatível com 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 reprovação remove o recurso do marketplace comercial. Para preterir, defina a propriedade "lifecycleState" como "preterida" nos recursos que dão suporte a ela. Há suporte para vários níveis de reprovação dependendo do tipo de produto. Por exemplo, para produtos SaaS, você pode substituir planos ou o produto inteiro. Ao descontinuar planos, o "lifecycleState" deve ser alterado e as alterações devem ser publicadas para visualização e, em seguida, ativas para que a substituição entre em vigor. Isso é diferente de uma descontinuação no nível do produto em que a configuração inicia automaticamente a descontinuação no ambiente ativo. Para restaurar posteriormente um recurso preterido, consulte o estado do ciclo de vida "geralmenteDisponível".
Solicitação de exemplo de substituição de plano:
No exemplo a seguir, um plano dentro de um produto SaaS é definido como preterido. 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 preterido. Depois que essa alteração é aplicada, ela é publicada automaticamente 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"
}
]
}
Disponível para o público geral
generallyAvailable é o estado padrão do ciclo de vida de todos os recursos. Depois que um recurso é preterido, você pode restaurá-lo alterando a propriedade lifecycleState de volta para generallyAvailable. Para restaurar um produto preterido, você deve publicar o produto mais uma vez para visualização e, em seguida, para ativar.
Solicitação de exemplo de restauração do plano:
No exemplo a seguir, um plano deve ser restaurado. Para aplicar essa alteração, você precisará publicar até o momento 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"
}
]
}