API de ingestão de produto para máquinas virtuais

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. A API permite criar, publicar e gerenciar recursos associados a produtos e planos em sua conta do Partner Center. Ela usa um padrão declarativo para enviar solicitações, nas quais o estado desejado é indicado em vez de especificar as etapas individuais para alcançar o estado desejado.

Este artigo fornece diretrizes sobre como começar a usar as APIs para qualquer tipo de oferta do marketplace comercial. Atualmente, a API de ingestão de produtos tem suporte para SaaS, VMs, ofertas privadas e tipos de oferta de contêiner e está em versão prévia. Para obter diretrizes específicas à sua oferta, revise as Diretrizes de API por tipo de oferta.

Introdução

A API de Ingestão de Produto pode ser acessada usando a API MSGraph sob o nome de carga de trabalho "ingestão de produto". A URL de base é https://graph.microsoft.com/rp/product-ingestion.

Para usar a API de Ingestão de Produto, é necessário adquirir os seguintes pré-requisitos:

• Uma ID do Microsoft Entra e verifique se você tem permissões de administrador global para o diretório
• Um aplicativo do Microsoft Entra
• Um token de acesso do Microsoft Entra

Siga estas instruções de integração para começar. Depois que isso tiver sido configurado uma vez, você poderá obter um token de acesso do Microsoft Entra para chamar as APIs com o cabeçalho Authorization para cada método de API.

Conceitos

Antes de começar, você precisa entender alguns conceitos básicos.

Recursos

A API é estruturada em torno de tipos de recursos, em que cada tipo é descrito usando uma definição de esquema dedicada, conforme referenciado pela propriedade "$schema". O esquema consiste nas propriedades de configuração desse recurso. Os recursos são fundamentais para criar e atualizar a configuração de vários aspectos de um determinado produto. Para obter uma lista completa de tipos de recursos e seus esquemas, consulte a Referência da API de Recurso.

ID durável

Um ID durável é um identificador global gerado pelo sistema usado para identificar exclusivamente qualquer recurso. Cada recurso tem uma propriedade "ID" associada, que, quando combinada com o nome do tipo de recurso, compõe a ID durável de um recurso. A ID durável é usada ao referenciar recursos para recuperar ou modificar.

Formato:

\<resource-type>/\<id>

Exemplo:

        { 
            "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
            "id": "product/12345678-abcd-efgh-1234-12345678901", // durable ID
            "identity": {
              "externalID": "ds-contoso-image-resize-demo"
            },
            "type": "softwareAsAService", // Product types that can be specified include azureContainer, azureVirtualMachine, softwareAsAService 
            "alias": "Contoso Image Resizing Service"
        }

ID Externa

Uma ID externa é outro identificador exclusivo que pode ser usado para fazer referência a produtos ou planos específicos. Essa é uma maneira alternativa de referenciar esses recursos em vez de usar a ID durável. A ID externa de um produto é convertida em seu "offerID" e a ID externa de um plano é convertida em seu "planID", conforme definido na criação na propriedade "identity".

Exemplo:

            { 
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
                "id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
                "identity": {
                  "externalID": "gold-annual"
                },
                "azureRegions": [
                    "azureGlobal"
                  ],
                "alias": "Gold - Annual payment",
                "product": "product/12345678-abcd-efgh-1234-12345678901",
            }

Métodos de API

Há quatro APIs de gerenciamento que podem ser usadas para executar ações diferentes, como consultar recursos existentes, fazer atualizações de configuração e verificar o status de uma solicitação.

Tipo de API	Descrição	Método e caminho HTTP
Consulta	Recupera os recursos existentes por: -Método 1: tipo de recurso "árvore de recursos" -Método 2: o durable-id -Método 3: parâmetros de string de consulta	-Método 1: GET resource-tree/<product-durableID> -Método 2: GET <resource-durableID> -Método 3: GET <resourceType>?<query parameters>
Configurar envio	Envia solicitações para criar ou atualizar um ou mais recursos. Após o processamento bem-sucedido, um jobID é retornado, que pode ser usado para recuperar o status da solicitação. Esse tipo de API pode ser usado para atualizar o estado de rascunho e publicar alterações, sincronizar audiências privadas e modificar o estado do ciclo de vida do recurso.	POST configure
Configurar status	Recupera o status de uma solicitação pendente por meio do jobID.	GET configure/<jobID>/status
Configurar detalhes de status	Recupera um resumo detalhado de uma solicitação concluída, incluindo os recursos atualizados, por meio do jobID.	GET configure/<jobID>
Cancelar configuração	Cancela o trabalho de configuração especificado.	POST configure/<jobID>/cancel

Um fluxo de trabalho típico

Para atualizar um recurso existente, um fluxo de trabalho típico seria:

1. Recuperar uma configuração de recurso existente (tipo de API: consulta via árvore de recursos)*
2. Faça as atualizações necessárias e envie uma solicitação de configuração (tipo de API: Configure submit)
3. Verificar o status da solicitação (tipo de API: Configurar status e Configurar detalhes do status)

* Esse mesmo fluxo de trabalho pode ser aplicado ao criar novos recursos, mas em vez de recuperar recursos (Etapa 1), use a tabela Referência da API de Recursos para garantir que você esteja usando o esquema atual para o tipo de recurso que você está criando.

Para resumir, esta imagem mostra o padrão de chamada típico usado para enviar uma solicitação de configuração, independentemente de você estar criando um novo ou modificando um recurso existente.

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 o Método 1, detalhado abaixo, para recuperar todos os recursos dentro de um produto específico em uma única chamada à API.

Método 1: árvore de recursos

Schema: https://``schema.mp.microsoft.com``/schema/resource-tree/2022-03-01-preview2

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 mais recente do esquema disponível pode ser diferente para cada recurso. Ao executar uma solicitação de árvore de recursos, a versão do esquema especificada determina qual versão é retornada para cada recurso no produto. A versão especificada serve como um limite de versão "max", pois retorna a versão mais recente do esquema disponível para todos os recursos de versão igual ou inferior. Por exemplo, se a versão mais recente da listagem de planos disponível for "2022-03-01-preview3", a resposta exibirá essa versão se você especificar "2022-03-01-preview5" na solicitação GET da árvore de recursos. No entanto, se solicitar "2022-03-01-preview2" como a versão da árvore de recursos, isso retornará o recurso de listagem de planos "2022-03-01-preview2", mesmo que a versão mais recente disponível seja "2022-03-01-preview3". É recomendável usar a versão mais recente disponível de cada recurso para garantir que você esteja usando o esquema atualizado com recursos recém-suportados.

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": "ds-contoso-image-resize-demo"
            },
            "type": "softwareAsAService",
            "alias": "Contoso Image Resizing Service"
          },
          { 
            "$schema": "https://schema.mp.microsoft.com/schema/property/2022-03-01-preview3",
            "id": "property/12345678-abcd-efgh-1234-12345678901/public/main",
            "product": "product/12345678-abcd-efgh-1234-12345678901",
            "kind": "azureSaaS",
            "termsConditions": "false",
            "categories": {
          "developer-tools-saas": [
            "devService"
          ]
            }
          },
          {
            "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
            "id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
            "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
          ...
          }, 
              // The response would include all existing resources within this product.
          {
              ...
          }]
        }

Método 2: ID durável

GET <resource-durableID>?$version=<schema-version>

Recupere um recurso específico usando sua ID durável. Depois que um recurso é criado, a ID durável sempre permanece a mesma e pode ser usada para recuperar as alterações de rascunho mais recentes desse recurso chamando o método GET. Por exemplo, a solicitação a seguir retornará a configuração de rascunho desse produto específico usando a versão de esquema "2022-03-01-preview3".

GET product/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview3

Para localizar a ID durável para seus recursos, você pode:

• Use o método "resource-tree" para buscar todos os recursos dentro do produto junto com cada um de seus respectivos IDs duráveis, ou
• Recupere os detalhes de uma solicitação de configuração de recurso concluída, que inclui as IDs duráveis de todos os recursos criados ou atualizados como parte da solicitação.

Lembre-se de que a propriedade "ID" é a durable-id do respectivo recurso.

Método 3: parâmetros de cadeia de caracteres de consulta

GET <resourceType>?<query parameters>&$version=<schema-version>

Esse método é usado para consultar determinados tipos de recursos associados a uma conta específica. Por exemplo, você pode recuperar todos os seus produtos de um tipo de produto específico com uma única chamada GET. Os parâmetros de string de consulta são usados para consultar detalhes relativos a seus produtos, planos ou envios.

Esta tabela mostra os parâmetros de consulta com suporte para cada um dos tipos de recursos compatíveis. Nem todos os tipos de recursos oferecem suporte a cada um dos parâmetros de consulta. Faça referência a esta tabela para obter a lista completa das cadeias de caracteres de consulta com suporte no momento.

Tipo de recurso	Parâmetros	Exemplos de cadeia de caracteres de consulta
plano	produto* externalID $maxpagesize continuationToken$version*	GET plan?product=<product-durableID>&$version=<schema-version> GET plan?product=<product-durableID>&externalID=<plan-externalID>&$version=<schema-version> GET plan?product=<product-durableID>&$maxpagesize=<#>&$version=<schema-version> GET plan?product=<product-durableID>&continuationToken=<token>&$version=<schema-version>
product	externalID tipo $maxpagesize continuationToken$version*	GET product?externalID=<product-externalID>&$version=<schema-version> GET product?type=<product-type>&$version=<schema-version> GET product?$maxpagesize=<#>&$version=<schema-version> GET product?continuationToken=<token>&$version=<schema-version>
submissão	targetType $maxpagesize continuationToken$version*	GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version> GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version>
árvore de recursos	targetType$version*	GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version>

* Os parâmetros do produto e $version são sempre necessários.

Funcionalidade de cada um dos parâmetros de consulta com suporte:

• product – Ao passar o parâmetro "product" no contexto do tipo de recurso "plan", ele retorna todos os planos dentro desse produto específico.
• externalID – Ao passar o parâmetro "externalID" no contexto de um produto ou plano, ele retorna a configuração desse respectivo produto ou plano. Ao contrário do método "resource-tree", esse parâmetro de cadeia de caracteres de consulta retornará apenas os detalhes desse recurso, não todos os recursos dentro dele.
• type – Ao passar o parâmetro "type" no contexto do tipo de recurso "product", ele retorna todos os produtos desse tipo associados à sua conta. Por exemplo, ao especificar "type=softwareAsAService", todos os seus produtos SaaS serão retornados.
• targetType – Retorna os dados de um ambiente específico no contexto do tipo de recurso usado. Os valores "targetType" com suporte são "draft", "preview" ou "live".
• $maxpagesize – Ao especificar o tamanho máximo da página, na forma de um número inteiro positivo, esse parâmetro é usado para limitar os resultados da pesquisa ao consultar seus envios anteriores.
• continuationToken – Esse parâmetro pode ser usado com o parâmetro "$maxpagesize" para consultar outro conjunto de resultados disponíveis em sua pesquisa. O valor "continuationToken" é fornecido na resposta da página anterior.
• $version – Este é um parâmetro obrigatório para todas as chamadas, ele especifica qual versão do esquema você deseja para a resposta da solicitação feita. A versão mais recente do esquema disponível pode ser diferente para cada recurso e a versão especificada serve como um limite de versão "máximo". O sistema retorna a versão exata do esquema, se disponível, ou a versão mais próxima que é mais antiga que a versão solicitada. Isso pode ajudar a manter seu código funcionando mesmo se houver alterações de esquema mais recentes, mas para utilizar os recursos mais recentes, é recomendável usar a versão mais recente disponível de cada esquema.

Consultas de envios

Você pode recuperar os envios de produtos existentes realizando GET submission/<product-durableID>. Por padrão, você recebe de volta todos os seus envios ativos, incluindo a referência de rascunho, mas também pode consultar um ambiente específico usando o parâmetro de consulta "targetType": (GET submission/<product-durableID>?targetType=<environment>&$version=<version>).

Solicitação de exemplo:

GET https://graph.microsoft.com/rp/product-ingestion/submission/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview2

Resposta de exemplo:

Este exemplo mostra uma solicitação GET para os envios ativos associados à ID do produto "12345678-abcd-efgh-1234-12345678901". O envio "ao vivo" ativo (submission/12345678-abcd-efgh-1234-12345678901/1152921515689847470) foi publicado para visualização primeiro e depois para o ativo. Quando esse envio foi enviado para o ar em 25 de janeiro de 2022, ele representava a versão prévia e o ao vivo até que um novo envio de visualização (submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683) fosse criado em 4 de fevereiro de 2022.

            {
              "value": [
                {
                  "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                  "id": "submission/12345678-abcd-efgh-1234-12345688901/0",
                  "product": "product/12345678-abcd-efgh-1234-12345678901",
                  "target": {
                    "targetType": "draft"
                  }
                },
                {
                  "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                  "id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689847470",
                  "product": "product/12345678-abcd-efgh-1234-12345678901",
                  "target": {
                    "targetType": "live"
                  },
                  "status": "completed",
                  "result": "succeeded",
                  "created": "2022-01-25T07:13:06.4408032Z"
                },
                {
                  "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                  "id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683",
                  "product": "product/12345678-abcd-efgh-1234-12345678901",
                  "target": {
                    "targetType": "preview"
                  },
                  "status": "completed",
                  "result": "succeeded",
                  "created": "2022-02-04T20:07:22.4220588Z"
                }
              ]
            }

Criar novos produtos e recursos

Você pode criar novos recursos, incluindo novos produtos, como parte de uma única solicitação de configuração. Usando a tabela de Referência da API de Recursos, você pode recuperar o esquema para o tipo de recurso que deseja criar. Isso garante que você esteja usando o esquema mais recente e, portanto, configurando todas as propriedades necessárias para criar o recurso.

Se você estiver criando um novo produto, os requisitos variam de acordo com o tipo de produto. Portanto, você precisa fornecer recursos diferentes. Você pode consultar a documentação do marketplace comercial correspondente para o respectivo tipo de produto para garantir que está configurando os requisitos básicos em sua solicitação. Como alternativa, você pode fazer uma solicitação de configuração usando apenas o recurso do produto. Depois de criar o produto, chame a API configure status details para recuperar o recurso de produto criado e encontrar sua ID durável para chamar a API de consulta da árvore de recursos. A resposta retorna os recursos com suporte aplicáveis para o tipo de produto que você criou.

Da mesma forma, para criar um novo recurso em um produto existente, você também precisa recuperar o esquema mais recente desse tipo de recurso específico. Verifique se você fornece os recursos dependentes como parte da solicitação de configuração revisando as dependências do recurso.

Depois de construir seus recursos usando os esquemas, saiba como fazer uma solicitação de configuração.

Modificar produtos e recursos existentes

Você pode enviar atualizações usando o conteúdo de configuração. Essa carga consiste em um ou mais tipos de recursos e a propriedade "$schema" indica o tipo de recurso que está sendo referenciado.

Depois de modificar seus recursos, saiba como fazer uma solicitação de configuração.

Solicitações de configuração

Você pode editar e publicar no mesmo conteúdo. Para enviar uma solicitação de configuração, use o método HTTP POST da API de configuração. O conteúdo de configuração consiste em uma matriz de recursos que indicam as alterações desejadas. Todas as edições afetam apenas a versão de rascunho até que você envie explicitamente um recurso de envio para publicar suas alterações de rascunho. Ao publicar para visualização ou ao vivo, inclua o recurso de envio e especifique o ambiente de destino. Antes de enviar uma solicitação, você precisa saber como referenciar recursos e entender suas dependências.

Schema:https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2

Ao enviar sua solicitação de configuração, você recebe de volta um objeto configure-status com o jobID que pode ser usado para acompanhar o progresso e os resultados da solicitação.

Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>

Referências e dependências de recursos

Referências

Para fazer referência a um recurso existente em uma solicitação de configuração, forneça o tipo "$schema" do recurso junto com a ID durável do recurso. No caso de produtos e planos, você também pode fazer referência a esses recursos por meio de sua ID externa.

A ID durável pode ser encontrada na propriedade "ID", por exemplo, se esse for o recurso de produto que queremos referenciar em outro recurso:

            { 
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
                "id": "product/12345678-abcd-efgh-1234-12345678901",
                "identity": {
                  "externalID": "ds-contoso-image-resize-demo"
                },
                "type": "softwareAsAService",
                "alias": "Contoso Image Resizing Service"
            }

O ID durável seria "product/071b135e-9faf-4ff7-b113-a3f25bb0f468".

A ID durável pode ser usada no exemplo de recurso de listagem abaixo, definindo-a na propriedade de esquema de recurso "product" desta forma:

            {
                "$schema": "https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5", 
                "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468", // product durable ID
                  ...
              }

A ID externa dos recursos do produto e do plano é definida na propriedade "identity".

            {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2", 
                "alias": "Gold - Annual payment",
                "identity": {"externalID": "gold-annual"},
                "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
                  ...
              }

A ID externa do plano "anual-ouro" pode ser referenciada por outros recursos subsequentes no seguinte formato:

              {
                "$schema": "https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5", 
                "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"}
                "plan": {"externalID": "gold-annual"}
                  ...
              }

Solicitação de exemplo:

Neste exemplo, o conteúdo de configuração é usado para criar um novo produto SaaS com uma ID externa de "ds-contoso-image-resize-demo". Após a criação deste produto, você pode consultá-lo posteriormente usando seu ID durável ou ID externo.

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/product/2022-03-01-preview3",
                "identity": {
                  "externalID": "ds-contoso-image-resize-demo"
                },
                "type": "softwareAsAService",
                "alias": " Contoso Image Resizing Service"
              }
              ]
            }

Resposta de exemplo:

            {
  "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
  "jobID": "071b135e-9faf-4ff7-b113-a3f25bb0f468",
  "jobStatus": "running",
  "jobResult": "pending",
  "jobStart": "2022-08-18T16:35:56.5917185Z",
  "jobEnd": "0001-01-01T00:00:00",
  "errors": []
}

Em seguida, você pode usar o jobID por meio da API Configure Status para verificar o status da sua solicitação.

Dependências

Determinados recursos têm dependências na criação de outro recurso como um pré-requisito. Nessa circunstância, estamos usando a propriedade "resourceName" dentro da mesma carga para denotar a dependência do recurso do produto no recurso do plano, pois estamos criando ambos na mesma solicitação.

O "resourceName" é usado apenas para identificar cada recurso como parte da solicitação de configuração que você está fazendo. O valor não fará parte dos dados dos recursos, não será armazenado nem exposto aos clientes. Além disso, se houver algum erro como parte da solicitação de configuração, o "resourceName" será usado para chamar o recurso ao qual o erro pertence.

Solicitação de exemplo:

Neste exemplo, o produto deve ser criado antes do plano e, portanto, a propriedade "resourceName" é usada. O produto que está sendo criado, "myNewProduct", será o valor usado para "resourceName" e referenciado no recurso do plano dependente.

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/product/2022-03-01-preview3", 
                "resourceName": "myNewProduct", 
                "alias": "Contoso Image Resizing Service",
                ...
              }, 
              {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2", 
                "alias": " Gold - Annual payment",
                "product": {"resourceName": "myNewProduct"}
                  ...
              }, 
              }]
            }

Recurso de envio

Se publicar em "visualização" ou "ao vivo", inclua o recurso de envio em sua solicitação, que contém:

• A propriedade "product", que indica o produto que está sendo atualizado conforme referenciado por sua ID durável ou ID externa
• A propriedade "targetType", que indica o ambiente de destino

Ao publicar especificamente em tempo real, o "ID" do envio de visualização que você deseja publicar:

              {
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",    
                "product": "product/12345678-abcd-efgh-1234-12345678901", 
                "target": { "targetType": "live" }
              }

Publicação para versão prévia

Os tipos de produtos comerciais oferecem suporte a um ambiente de versão prévia e cada atualização deve ser publicada primeiro na versão prévia antes de entrar ao vivo. Você não pode publicar diretamente para ao vivo.

Há duas maneiras de publicar seus recursos no ambiente de versão prévia. Se alguma alteração precisar ser feita no envio de versão prévia, faça outra solicitação GET, faça as alterações necessárias e envie as alterações novamente por push. Você não precisa primeiro ativar suas alterações iniciais.

Método 1: publicar todos os recursos de rascunho

Se você quiser publicar todas as alterações de rascunho feitas, poderá enviar uma solicitação de configuração com um recurso de envio que define o ambiente de visualização como o "targetType". Conforme mostrado no exemplo abaixo, você não precisa fornecer explicitamente todos os recursos que exigem uma atualização, pois esse método publica todas as alterações no ambiente de destino, que, nesse caso, é a versão prévia. Você só precisa fornecer o ponto de extremidade de API configurado e o recurso de envio.

Solicitação de exemplo:

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": [
              {
            // Below is the submission resource to publish to preview
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
                "target": { "targetType": "preview" }
              }
              ]
            }

Método 2: Publicar recursos de rascunho específicos (também conhecidos como publicação modular)

Como alternativa, se não estiver preparado para publicar todas as alterações de rascunho em vários recursos, basta fornecer os recursos que deseja publicar junto ao recurso de envio para disparar uma publicação modular. Você também pode usar essa abordagem para fazer alterações nos recursos e publicá-los ao mesmo tempo, em vez de como parte de uma atualização em massa, como é feito por meio do Método 1. Para uma publicação modular, todos os recursos são necessários, exceto os detalhes no nível do produto (por exemplo, listagem, disponibilidade, pacotes, revendedor), conforme aplicável ao seu tipo de produto.

Solicitação de exemplo:

Neste exemplo, os recursos no produto são fornecidos explicitamente como parte da publicação modular seguida pelo 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/product/2022-03-01-preview2", 
                "id": "product/12345678-abcd-efgh-1234-12345678901",
                ...
              },
              {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2", 
                  ...
              }, 
              // additional resources
              {
                  ...
              },
              // Below is the submission resource to publish to preview
              {
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
                "target": { "targetType": "preview" }
              }
              ]
            }

Publicação ao vivo

Depois que suas alterações na versão prévia forem testadas e verificadas, você poderá enviar suas alterações para o ativo enviando uma solicitação de configuração com a "ID" do envio de visualização e o "targetType" definido como "ao vivo". Para encontrar a "ID" do envio de visualização a ser incorporada à solicitação de configuração, consulte Consultando seus envios.

Solicitação de exemplo:

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": [
              // Below is the submission resource, including the preview submission id, to publish to live.
              {
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",    
                "product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
                "target": { "targetType": "live" }
              }
              ]
            }

Verificar o status de uma solicitação

Independentemente dos recursos incluídos em sua solicitação de configuração ou das alterações que você está fazendo, você receberá um objeto configure-status de volta na resposta logo após enviar uma solicitação assim que ela for processada com êxito. O "jobID" é importante, pois pode ser usado posteriormente para verificar o status da solicitação.

Schema: <https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2>

Exemplo de resposta a uma solicitação enviada:

            {
                "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
                "jobID": "d4261631-c583-4949-a612-5150882632e9",
                "jobStatus": "notStarted",
                "jobResult": "pending",
                "jobStart": "2022-03-01T13:32:43.123456Z",
                "jobEnd": "0001-01-01T00:00:00",
                "errors": []
            }

Status de uma solicitação pendente

Você pode recuperar o status até que o trabalho seja concluído usando a chamada a seguir e inserindo o "jobID" da solicitação. O objeto também pode conter uma lista de erros se houver algum problema com sua solicitação.

GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>/status?$version=2022-03-01-preview2

Lembre-se de que o tempo de conclusão pode variar dependendo da complexidade da sua solicitação,

Resumo de uma solicitação concluída

Depois que um trabalho de solicitação de configuração for concluído, com êxito ou com falha, você poderá obter a lista de recursos criados ou atualizados usando o "jobID".

Schema: <https://schema.mp.microsoft.com/schema/configure-detail/2022-03-01-preview2>

GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>?$version=2022-03-01-preview2

Solicitação de exemplo:

No exemplo abaixo, uma solicitação GET é usada para recuperar os detalhes resumidos da solicitação de configuração usada no exemplo anterior que criou um novo produto SaaS. A resposta é o objeto configure-detail com a matriz resources que contém o recurso do produto que foi criado junto com sua ID durável.

GET https://graph.microsoft.com/rp/product-ingestion/configure/071b135e-9faf-4ff7-b113-a3f25bb0f468?$version=2022-03-01-preview2

Resposta de exemplo:

            {
"$schema": "https://schema.mp.microsoft.com/schema/configure-detail/2022-03-01-preview2",
"resources": [
{ 
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
                "id": "product/12345678-abcd-efgh-1234-12345678901",
                "identity": {
                  "externalID": "ds-contoso-image-resize-demo "
                },
                "type": "softwareAsAService",
                "alias": "Contoso Image Resizing Service"
              }
]
}             

Cancelar uma solicitação de configuração

Antes de um trabalho ser concluído, você pode tentar cancelá-lo, se necessário. Para solicitações de execução longa, como publicação em "visualização" ou "ao vivo", a solicitação de cancelamento poderá ser rejeitada se o trabalho estiver avançado o suficiente para ser totalmente processado.

Para cancelar um trabalho, faça uma chamada POST para o ponto de extremidade de cancelamento e forneça a ID do trabalho da solicitação que você deseja cancelar.

POST https://graph.microsoft.com/rp/product-ingestion/configure<jobID>/cancel?$version=2022-03-01-preview2

Solicitação de exemplo:

POST <https://graph.microsoft.com/rp/product-ingestion/configure/d4261631-c583-4949-a612-5150882632e9/cancel?$version=2022-03-01-preview2>

Exemplo de resposta de uma solicitação de cancelamento bem-sucedida:

            {
                "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
                "jobID": "d4261631-c583-4949-a612-5150882632e9",
                "jobStatus": "completed",
                "jobResult": "cancelled",
                "jobStart": "2022-03-01-T13:32:43.123456Z",
                "jobEnd": "2022-03-01T17:34:21.5225132Z",
                "errors": []
            }

Exemplo de resposta caso o cancelamento não seja permitido: HTTP Status code: 400

Conteúdo:

            {
              "error": {
                "code": "badRequest",
                "message": "Cannot cancel job, job has already completed.",
                "details": []
              }
}

Você pode buscar o resumo da solicitação de configuração após o cancelamento para verificar quais recursos (se houver) já foram processados antes do cancelamento.

Sincronizar públicos-alvo privados

Para um produto ao vivo, as atualizações para audiências privadas nos ambientes de rascunho, visualização e ao vivo podem ser executadas ao mesmo tempo sem a necessidade de uma publicação. Você pode sincronizar o público privado usando o recurso "price-and-availability-update-private-audiences" especificando quais públicos você deseja adicionar ou remover de um plano específico. Isso sincronizará os ambientes de rascunho, visualização e ao vivo para ter os mesmos valores de público privado. Você não precisa fornecer o recurso de envio ao sincronizar o público-alvo privado.

Para editar os públicos de rascunho, use o recurso "price-and-availability-plan" e a propriedade "privateAudiences". Isso precisará passar pelo fluxo de publicação regular para que os valores sejam definidos na versão prévia e ao vivo.

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/price-and-availability-update-private-audiences/2022-03-01-preview2",
            "product": "product/12345678-abcd-efgh-1234-12345678901", // product durable ID
            "plan": "plan/12345678-abcd-efgh-1234-12345678901/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b", //plan durable ID 
            "privateAudiences":
            {
              "add ":
              [
                  {
            "type": "tenant",
                    "id": "4c2bdcdc-f10e-468d-8a2a-0832e089215b",
                    "label": "test 1"
                  }
              ],
              "remove ":
              [
                {
            "type": "subscription",
                    "id": "412c45bf-c99a-4e96-b683-77b0aa2dd09e",
                    "label": "test 2"
                }
              ]
            }
          }
          ]
        }

Configurar o gerenciamento de clientes potenciais

Conecte seu sistema de gerenciamento de relacionamento com o cliente (CRM) ao seu produto de marketplace comercial para que você possa receber informações de contato do cliente quando um cliente manifestar interesse ou implantar seu produto. Você pode modificar essa conexão a qualquer momento durante ou após a criação do produto. Para saber mais, consulte Obter clientes potenciais.

Exemplo de solicitação para configurar o gerenciamento de leads:

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/customer-leads/2022-03-01-preview3",
            "id": "customer-leads/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
            "product": "product/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
            "leadDestination": "httpsEndpoint",
            "httpsEndpointLeadConfiguration": {
              "httpsEndpointUrl": "https://www.your-crm.com/triggers/invoke"
            }
          }  
          ]
        }

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. Para descobrir se um recurso tem um estado de ciclo de vida e quais valores são suportados, você pode verificar o esquema de recursos para a existência da propriedade "lifecycleState". Vários estados de ciclo de vida com suporte são detalhados abaixo.

Excluído

Você pode excluir recursos específicos atualizando a propriedade "lifecycleState" para "deleted". Você só pode excluir recursos de rascunho que ainda não foram publicados. Essa ação não pode ser desfeita.

Solicitação de exemplo:

No exemplo abaixo, o rascunho do plano "básico" é excluído.

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

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. Existem vários níveis de depreciação. Todos os tipos de produtos suportam a substituição de todo o produto e planos individuais dentro dele. Para restaurar posteriormente um recurso preterido, consulte o estado do ciclo de vida "geralmenteDisponível".

Exemplo de solicitação de substituição de um produto:

No exemplo abaixo, 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"
                }
              ]
            }

Ao descontinuar planos, a propriedade "lifecycleState" deve ser alterada para "preterida" e as alterações devem ser publicadas em "preview" e depois em "live" para que a substituição entre em vigor. Isso é diferente de uma substituição no nível do produto na qual a substituição será configurada automaticamente no ambiente ativo.

Exemplo de solicitação de substituição de um plano:

No exemplo abaixo, 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"
                }
              ]
            }

Existem outras formas de substituição que variam consoante o tipo de produto. Saiba mais sobre a substituição de SaaS, máquinas virtuais e contêineres.

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 obsoleto, você deve publicar o produto para visualização e depois ao vivo. Você pode encontrar exemplos de SaaS, VMs e contêineres em seus respectivos artigos.

Exemplo de solicitação de restauração de um plano:

No exemplo abaixo, 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"
                }
              ]
            }     

Referência da API de recursos

As versões de esquema abaixo são aplicáveis somente para visualização e serão alteradas assim que a API estiver disponível para o público em geral.

Tipo de recurso	Descrição	Esquema
azure-test-drive-technical-configuration	Detalhes técnicos que ajudam o marketplace comercial da Microsoft a se conectar à sua solução de test drive.	https://schema.mp.microsoft.com/schema/azure-test-drive-technical-configuration/2022-03-01-preview3
configuração de mercado comercial	Descreve a configuração transacionável de produtos no marketplace comercial.	https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2
clientes	Permite conectar-se a um sistema de CRM para receber leads de clientes.	https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3
listagem	Isso inclui as descrições do seu produto, que serão exibidas nas vitrines do marketplace comercial da Microsoft.	https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5
ativo de listagem	Capturas de tela e seus ativos de marketing vinculados ao recurso de listagem.	https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5
listagem-trailer	Ativos de vídeo vinculados ao recurso de listagem.	https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5
Microsoft365-Integration	Habilitação do Microsoft 365 e seleção de tipo.	https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2
plano	Para criar planos, que serão referenciados pelos recursos de nível de plano que você configurar, como plan-listing.	https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2
lista de planos	Defina o nome e a descrição do plano como você deseja que eles apareçam no marketplace comercial.	https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5
Medidor personalizado de preço e disponibilidade	Defina os medidores personalizados compartilhados entre seus planos.	https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3
oferta de preço e disponibilidade	Defina um público limitado que possa avaliar seu produto antes de publicá-lo ao vivo.	https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3
Plano de preço e disponibilidade	Configure os mercados em que este plano está disponível, o modelo de monetização desejado, o preço e as condições de cobrança.	https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4
preço-e-disponibilidade-atualização-audiências-privadas	As atualizações para públicos-alvo privados nos ambientes de rascunho, versão prévia e ao vivo podem ser executadas ao mesmo tempo sem a necessidade de uma publicação.	https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3
plano privado e de oferta privada de disponibilidade	Usado para configurar os detalhes absolutos de preços de um produto/plano usado em uma oferta privada	https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01
oferta privada	Define o nome e o tipo de oferta privada, com os termos e detalhes da oferta, juntamente com os produtos/planos incluídos e seus preços	https://schema.mp.microsoft.com/schema/private-offer/2022-07-01
product	Este é o recurso principal, define o nome e o tipo do produto, todos os recursos fazem referência a isso.	https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3
property	Defina as categorias e os setores aplicáveis à sua oferta, à versão do aplicativo e aos contratos legais.	https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5
revendedor	Configure os parceiros no programa CSP (Provedores de Soluções na Nuvem) para o qual você deseja disponibilizar seu produto.	https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2
árvore de recursos	Descreve o produto Uma lista de recursos para esse produto no estado atual para o ambiente de destino especificado.	https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2
configuração técnica de software como serviço	Detalhes técnicos que ajudam o marketplace comercial da Microsoft a se conectar à sua solução.	https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3
submissão	Pode ser usado para acionar diferentes ações em seu produto e indicar o estado de publicação do seu produto em diferentes ambientes (rascunho, visualização e ativa).	https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2
test-drive	Defina se deseja permitir que seus clientes experimentem o produto gratuitamente por um tempo limitado.	https://schema.mp.microsoft.com/schema/test-drive/2022-03-01-preview2
lista de test-drive	Defina os detalhes sobre como os clientes podem experimentar seu produto.	https://schema.mp.microsoft.com/schema/test-drive-listing/2022-03-01-preview3
configuração técnica do plano de máquina virtual	Detalhes técnicos que descrevem a máquina virtual e o local da imagem.	https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3
configuração técnica de test-drive de máquina virtual	Detalhes técnicos que ajudam o marketplace comercial da Microsoft a se conectar à sua solução de test drive.	https://schema.mp.microsoft.com/schema/virtual-machine-test-drive-technical-configuration/2022-03-01-preview2
configuração técnica do plano de contêiner	Detalhes técnicos que descrevem as propriedades da imagem do contêiner.	https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3

Diretrizes de API por tipo de produto

A API de assimilação de produtos será disponibilizada para outros tipos de produtos no futuro. À medida que mais tipos de produtos forem suportados, mais orientações específicas para cada tipo de produto serão disponibilizadas.

Tipo de produto	Recursos específicos do tipo de produto
Ofertas privadas	Criar e gerenciar ofertas privadas por meio da API de ingestão de produtos
SaaS	Crie e gerencie ofertas de SaaS por meio da API de ingestão de produtos
Máquinas virtuais	Criar e gerenciar ofertas de máquina virtual por meio da API de ingestão de produtos
Contêineres	Criar e gerenciar ofertas de contêiner por meio da API de ingestão de produtos

Versões e atualizações da API

Atualizar	O que mudou?
12-2024	Todos os endpoints de esquema foram atualizados de product-ingestion.azureedge.net para schema.mp.microsoft.com
12-2022	Uma nova versão de esquema 2022-03-01-preview3 da API de assimilação de PC para clientes potenciais agora está disponível que aceita clientID e clientSecret ao configurar clientes potenciais do cliente e para de capturar os campos serverID e email de contato. Alterne para a nova versão e forneça clientID e clientSecret para continuar configurando o conector do Marketo para ofertas do marketplace. Nova URL do esquema: https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3
09-2022	O suporte à visualização de contêiner é lançado como versão 2022-03-01-preview4
08-2022	O suporte à visualização de software como serviço é lançado como versão 2022-03-01-preview3
08-2022	Lançamento público da oferta privada como versão 2022-07-01
05-2022	O suporte à visualização da máquina virtual é lançado como versão 2022-03-01-preview2

Conteúdo relacionado

• API de ingestão de produtos para SaaS
• API de ingestão de produto para contêineres transacionáveis