API de ingestão de produtos para SaaS
A API de ingestão de produtos é uma API modernizada que unifica todas as APIs de envio existentes em todos os produtos de 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 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 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 de um produto específico utilizando o tipo de recurso "hierarquia de recursos" juntamente com a ID permanente 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á 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 pode executar que correspondem ao 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 de 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, pode descontinuar planos ou todo o produto. Ao descontinuar planos, o "lifecycleState" deve ser alterado e as alterações devem ser publicadas para pré-visualização e depois ao vivo, para que a descontinuação entre em vigor. Isso é diferente de uma descontinuação no nível do produto, na qual essa configuração inicia automaticamente a descontinuação no ambiente ao vivo. Para restaurar posteriormente um recurso preterido, consulte o estado do ciclo de vida "geralmente disponível".
Pedido de amostra para descontinuação de plano:
No exemplo a seguir, um plano dentro de um produto SaaS está prestes a ser descontinuado. 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 descontinuação de produto:
No exemplo a seguir, o envio ao vivo do produto é definido como obsoleto. 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"
}
]
}
Disponível ao público em 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 geralmenteDisponível. Para restaurar um produto preterido, deve publicar o produto novamente para pré-visualização e, em seguida, para produção.
Planejar solicitação de amostra de restauração:
No exemplo a seguir, pretende-se restaurar um plano. 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"
}
]
}