API de ingesta de productos para el marketplace comercial

Artículo
06/14/2024

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. La API le permite crear, publicar y administrar recursos asociados a productos y planes dentro de la cuenta del Centro de partners. Usa un patrón declarativo para enviar solicitudes en las que se indica el estado deseado en lugar de especificar los pasos individuales para alcanzar el estado deseado.

En este artículo se proporcionan instrucciones sobre cómo empezar a trabajar con las API de cualquier tipo de oferta de Marketplace comercial. La API de ingesta de productos se admite actualmente para los tipos de ofertas saaS, máquinas virtuales, privadas y contenedores, y está en versión preliminar. Para obtener instrucciones específicas de la oferta, consulte la guía de API por tipo de oferta.

Importante

Azure Active Directory (Azure AD) Graph está en desuso a partir del 30 de junio de 2023. En el futuro, no estamos realizando más inversiones en Azure AD Graph. Las API de Graph de Azure AD no tienen ningún acuerdo de nivel de servicio ni compromiso de mantenimiento más allá de las correcciones relacionadas con la seguridad. Las inversiones en las nuevas características y funcionalidades solo se realizarán en Microsoft Graph.

Retiraremos Azure AD Graph en pasos incrementales para que tenga tiempo suficiente para migrar las aplicaciones a las API de Microsoft Graph. En una fecha posterior que anunciaremos, bloquearemos la creación de aplicaciones nuevas mediante Azure AD Graph.

Para más información, consulte Importante: Retirada de Azure AD Graph y Desuso del módulo de PowerShell.

Introducción

Se puede acceder a la API de ingesta de productos mediante MSGraph API en el nombre de carga de trabajo "product-ingestion". La dirección URL base es https://graph.microsoft.com/rp/product-ingestion.

Para usar la API de ingesta de productos, primero debe adquirir lo siguiente:

Identificador de Microsoft Entra y asegúrese de que tiene permisos de administrador global para el directorio.
Una aplicación de Microsoft Entra
Un token de acceso de Microsoft Entra

Paso 1: Completar los requisitos previos

Antes de empezar a escribir código para llamar a la API de ingesta de productos, asegúrese de que ha completado los siguientes requisitos previos.

Usted (o su organización) debe tener un directorio de Microsoft Entra y debe tener permiso de administrador global para el directorio. Si ya usa Microsoft 365 u otros servicios empresariales de Microsoft, ya tiene el directorio Microsoft Entra. De lo contrario, puede crear un nuevo identificador de Entra de Microsoft en el Centro de partners sin ningún cargo adicional.
Debe asociar una aplicación de Microsoft Entra a su cuenta del Centro de partners y obtener el identificador de inquilino, el identificador de cliente y la clave. Necesitas estos para obtener el token de acceso de Microsoft Entra que usarás en llamadas a la API de envío de Microsoft Store.

Asociar una aplicación de Microsoft Entra a su cuenta del Centro de partners

Para usar la API de ingesta de productos, debe asociar una aplicación de Microsoft Entra a su cuenta del Centro de partners, recuperar el identificador de inquilino y el identificador de cliente de la aplicación y generar una clave. La aplicación Microsoft Entra representa la aplicación o el servicio desde el que desea llamar a la API de ingesta de productos. Necesita el identificador de inquilino, el identificador de cliente y la clave para obtener un token de acceso de Microsoft Entra para pasar a la API.

Nota:

Solo tiene que realizar esta operación una vez. Después de tener el identificador de inquilino, el identificador de cliente y la clave, puede reutilizarlos cada vez que necesite crear un nuevo token de acceso de Microsoft Entra.

En el Centro de partners, asocie la cuenta del Centro de partners de su organización con el directorio Microsoft Entra de la organización.
En la página Usuarios de la sección Configuración de la cuenta del Centro de partners, agregue la aplicación Microsoft Entra que representa la aplicación o el servicio que usará para acceder a los envíos de la cuenta del Centro de partners. Asegúrese de asignar a esta aplicación el rol Administrador. Si la aplicación aún no existe en el directorio de Microsoft Entra, cree una nueva aplicación de Microsoft Entra en el Centro de partners. El Centro de partners creará dos tipos de entradas para la aplicación uno como la entidad de servicio y la otra como el tipo de aplicación Microsoft Entra.
Vuelva a la página Usuarios, seleccione el nombre de la aplicación De Microsoft Entra para ir a la configuración de la aplicación y copie los valores id. de inquilino e Id. de cliente.
Seleccione Agregar nueva clave. En la pantalla siguiente, copie el valor de Clave. Después de salir de esta página no podrá tener acceso de nuevo a esta información. Para obtener más información, consulte Administrar claves para una aplicación de Microsoft Entra.

Paso 2: Obtener un token de acceso de Microsoft Entra

Para llamar a cualquiera de los métodos de la API de ingesta de productos, primero debe obtener un token de acceso de Microsoft Entra para pasar al encabezado Authorization de cada método de la API. Un token de acceso tarda 60 minutos en expirar desde su emisión. Después, puede actualizarlo para poder usarlo en futuras llamadas a la API.

Para obtener el token de acceso, siga las instrucciones de Llamadas entre servicios mediante las credenciales del cliente para enviar una HTTP POST al punto de conexión https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token. Esta es una solicitud de ejemplo:

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded;

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&scope=https://graph.microsoft.com/.default

Para el valor tenant_id en el URI POST y los parámetros client_id y client_secret, especifique el identificador de inquilino, el identificador de cliente y la clave de la aplicación que recuperó del Centro de partners en la sección anterior. Para el parámetro scope, tiene que especificar https://graph.microsoft.com/.default.

Conceptos

Antes de empezar, debe comprender algunos conceptos básicos.

Recursos

La API se estructura en torno a los tipos de recursos, donde cada tipo se describe mediante una definición de esquema dedicada a la que hace referencia la propiedad "$schema". El esquema consta de las propiedades de configuración de ese recurso. Los recursos son fundamentales para crear y actualizar la configuración de varios aspectos de un producto determinado. Para obtener una lista completa de los tipos de recursos y sus esquemas, consulte la referencia de la API de recurso.

Identificador duradero

Un identificador duradero es un identificador global generado por el sistema que se usa para identificar de forma única cualquier recurso. Cada recurso tiene una propiedad "ID" asociada, que cuando se combina con el nombre del tipo de recurso, constituye el identificador duradero de un recurso. El identificador duradero se usa cuando se hace referencia a los recursos para recuperarlos o modificarlos.

Formato:

\<resource-type>/\<id>

Ejemplo:

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

Un identificador externo es otro identificador único que se puede usar para hacer referencia a productos o planes específicos. Se trata de una forma alternativa de hacer referencia a estos recursos en lugar de usar el identificador duradero. El identificador externo de un producto se traduce en su "offerID" y el identificador externo de un plan se traduce en su "planID", tal como se define al crearse en la propiedad "identity".

Ejemplo:

            { 
                "$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

Existen cuatro API de administración que se pueden usar para realizar diferentes acciones, como consultar recursos existentes, realizar actualizaciones de configuración y comprobar el estado de una solicitud.

Nota:

Todas las solicitudes requieren que establezca la versión del esquema ($version parámetro de consulta) que desee como parte de la respuesta.

Tipo de API	Descripción	Método y ruta de acceso HTTP
Consultar	Recupera los recursos existentes por: -Método 1: tipo de recurso "resource-tree" -Method 2: durable-id -Method 3: parámetros de cadena de consulta	-Método 1: `GET resource-tree/<product-durableID>` -Método 2: `GET <resource-durableID>` -Método 3: `GET <resourceType>?<query parameters>`
Configuración del envío	Envía solicitudes para crear o actualizar uno o varios recursos. Tras un procesamiento correcto, se devuelve un jobID, que se puede usar para recuperar el estado de la solicitud. Este tipo de API se puede usar para actualizar el estado de borrador y publicar cambios, sincronizar audiencias privadas y modificar el estado del ciclo de vida de los recursos.	`POST configure`
Configuración de estado	Recupera el estado de una solicitud pendiente a través del jobID.	`GET configure/<jobID>/status`
Configuración de los detalles de estado	Recupera un resumen detallado de una solicitud completada, incluidos los recursos actualizados, a través del jobID.	`GET configure/<jobID>`
Cancelar configuración	Cancela el trabajo De configuración especificado.	`POST configure/<jobID>/cancel`

Un flujo de trabajo típico

Para actualizar un recurso existente, un flujo de trabajo típico sería:

Recuperación de una configuración de recursos existente (tipo de API: Consulta a través del árbol de recursos)*
Realice las actualizaciones necesarias y envíe una solicitud de configuración (tipo de API: Configurar envío)
Compruebe el estado de la solicitud (tipo de API: Configuración del estado y Configuración de los detalles del estado)

* Este mismo flujo de trabajo se puede aplicar cuando se crean nuevos recursos, aún así, en lugar de recuperar recursos (paso 1), use la tabla de referencia de la API de recurso para asegurarse de que está usando el esquema actual para el tipo de recurso que está creando.

En resumen, esta imagen muestra el patrón de llamada típico que se usa para enviar una solicitud de configuración, independientemente de si va a crear un recurso nuevo o modificarlo.

Captura de pantalla que ilustra el patrón de llamada típico que se usa para enviar una solicitud de configuración.

Nota:

Asegúrese de revisar los requisitos previos adicionales específicos del tipo de oferta que administra haciendo referencia a la sección guía de API por tipo de oferta.

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 el método 1, que se detalla a continuación, para recuperar todos los recursos de un producto específico en una sola llamada a API.

Método 1: árbol de recursos

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

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 más reciente disponible puede ser diferente para cada recurso. Al realizar una solicitud de árbol de recursos, la versión de esquema especificada determina qué versión se devuelve para cada recurso del producto. La versión especificada actúa como límite de versión "max" en que devuelve la versión de esquema más reciente disponible para todos los recursos de la versión igual o inferior. Por ejemplo, si la versión más reciente de la lista de planes disponible es "2022-03-01-preview3", la respuesta mostrará esta versión si tenía que especificar "2022-03-01-preview5" en la solicitud GET del árbol de recursos. Sin embargo, si solicita "2022-03-01-preview2" como versión del árbol de recursos, devolverá el recurso de descripción del plan "2022-03-01-preview2", aunque la versión más reciente disponible sea "2022-03-01-preview3". Se recomienda usar la versión más reciente disponible de cada recurso para asegurarse de que usa el esquema actualizado con características recién admitidas.

Nota:

Si no conoce el identificador duradero del producto, puede usar el identificador externo del producto para recuperar el recurso del producto mediante la ejecución GET product?externalID=<product-externalID>&$version=<product-schema-version>de . Esta solicitud utiliza un parámetro de cadena de consulta, que se detalla en el método 3 siguiente. 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": "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: identificador duradero

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

Recupere un recurso específico mediante su identificador duradero. Una vez creado un recurso, el identificador duradero siempre sigue siendo el mismo y se puede usar para recuperar los últimos cambios de borrador de ese recurso llamando al método GET. Por ejemplo, la siguiente solicitud devolverá la configuración de borrador de este producto específico mediante la versión de esquema "2022-03-01-preview3".

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

Importante

Este método solo se usa para recuperar la configuración de borrador. Si desea recuperar datos en versión preliminar o dinámicos, use el método "resource-tree", como se ha detallado anteriormente.

Para buscar el identificador duradero de los recursos, puede:

Use el método "resource-tree" para capturar todos los recursos del producto junto con cada uno de sus respectivos identificadores duraderos, o bien
Recupere los detalles de una solicitud de configuración de recursos completada, que incluye los identificadores duraderos para todos los recursos creados o actualizados como parte de la solicitud.

Recuerde que la propiedad "ID" es durable-id para el recurso correspondiente.

Método 3: parámetros de cadena de consulta

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

Este método se usa para consultar determinados tipos de recursos asociados a una cuenta específica. Por ejemplo, puede recuperar todos los productos de un tipo de producto específico con una sola llamada GET. Los parámetros de cadena de consulta se usan para consultar los detalles relacionados con los productos, planes o envíos.

En esta tabla se muestran los parámetros de consulta admitidos para cada uno de los tipos de recursos admitidos. No todos los tipos de recursos admiten todos los parámetros de consulta. Puede tomar como referencia esta tabla para obtener la lista completa de cadenas de consulta que se admiten actualmente.

Tipo de recurso	Parámetros	Ejemplos de cadenas de consulta
plan	producto`` 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 type $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>`
Sumisión	targetType $maxpagesize continuationToken$version`*`	`GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>` `GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version>`
árbol de recursos	targetType$version`*`	`GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version>`

* Los parámetros product y $version siempre son necesarios.

Funciones de cada uno de los parámetros de consulta admitidos:

product : al pasar el parámetro "product" en el contexto del tipo de recurso "plan", devuelve todos los planes dentro de ese producto específico.
externalID : al pasar el parámetro "externalID" en el contexto de un producto o plan, devuelve la configuración de ese producto o plan correspondiente. A diferencia del método "resource-tree", este parámetro de cadena de consulta solo devolverá los detalles de ese recurso, no todos los recursos que contiene.
type : al pasar el parámetro "type" en el contexto del tipo de recurso "product", devuelve todos los productos de ese tipo asociados a su cuenta. Por ejemplo, especificando "type=softwareAsAService", se devolverán todos los productos saaS.
targetType : devuelve los datos de un entorno específico en el contexto del tipo de recurso que se usa. Los valores "targetType" admitidos son "draft", "preview" o "live".
$maxpagesize: este parámetro, cuando se especifica el tamaño máximo de página en forma de número entero positivo, se usa para limitar los resultados de la búsqueda cuando se consultan los envíos anteriores.
continuationToken : este parámetro se puede usar con el parámetro "$maxpagesize" para consultar otro conjunto de resultados disponibles en la búsqueda. El valor "continuationToken" se proporciona en la respuesta de la página anterior.
$version: este es un parámetro necesario para todas las llamadas, especifica la versión de esquema que desea para la respuesta de la solicitud realizada. La versión de esquema más reciente disponible puede ser diferente para cada recurso y la versión especificada actúa como límite de versión "max". El sistema devuelve la versión exacta del esquema si está disponible o la versión más cercana anterior a la versión solicitada. Esto puede ayudar a mantener el código funcionando incluso si hay cambios de esquema más recientes, pero para usar las características más recientes, se recomienda usar la versión más reciente disponible de cada esquema.

Consulta de los envíos

Para recuperar los envíos de productos existentes, realice GET submission/<product-durableID>. De forma predeterminada, obtendrá todos los envíos activos, incluida la referencia de borrador, pero también puede consultar un entorno específico mediante el parámetro de consulta "targetType": (GET submission/<product-durableID>?targetType=<environment>&$version=<version>).

Importante

Cuando un envío "Preview" se inserta a "Live", se reemplaza cualquier envío "Live" anterior. Cuando esto sucede, los datos ahora representan los entornos "Preview" y "Live" hasta que se publica un nuevo envío en "Preview".

Solicitud de ejemplo:

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

Respuesta de ejemplo:

En este ejemplo se muestra una solicitud GET para los envíos activos asociados al identificador de producto "12345678-abcd-efgh-1234-12345678901". El envío activo "Live" (envío/12345678-abcd-efgh-1234-12345678901/1152921515689847470) se publicó en versión preliminar en primer lugar y, después, en directo. Cuando este envío se insertó en directo el 25 de enero de 2022, representó tanto la versión preliminar como la activa hasta que se creó un nuevo envío de versión preliminar (envío/12345678-abcd-efgh-1234-12345678901/1152921515689848683) el 4 de febrero 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"
                }
              ]
            }

Creación de nuevos productos y recursos

Puede crear nuevos recursos, incluidos los productos nuevos, como parte de una única solicitud de configuración. Mediante la tabla de referencia de la API de recurso, puede recuperar el esquema del tipo de recurso que quiere crear. Así, se garantiza el uso del esquema más reciente y, por tanto, configura todas las propiedades necesarias para crear el recurso.

Si va a crear un nuevo producto, los requisitos varían según el tipo de producto. Por lo tanto, debe proporcionar diferentes recursos. Puede hacer referencia a la documentación correspondiente del marketplace comercial correspondiente para el tipo de producto correspondiente para asegurarse de que está configurando los requisitos básicos en la solicitud. Como alternativa, puede realizar una solicitud de configuración con solo el recurso del producto. Después de crear el producto, llame a la API de detalles de estado de configuración para recuperar el recurso de producto creado y busque su identificador duradero para llamar a la API de consulta del árbol de recursos. La respuesta devuelve los recursos admitidos aplicables para el tipo de producto que creó.

De forma similar, para crear un nuevo recurso dentro de un producto existente, también debe recuperar el esquema más reciente de ese tipo de recurso específico. Asegúrese de proporcionar los recursos dependientes como parte de la solicitud de configuración de manera que revise las dependencias de recursos.

Después de construir los recursos mediante los esquemas, aprenda a realizar una solicitud de configuración.

Modificación de los productos y recursos existentes

Puede enviar actualizaciones mediante la carga útil de configuración. Esta carga consta de uno o varios tipos de recursos y la propiedad "$schema" indica el tipo de recurso al que se hace referencia.

Sugerencia

Se recomienda recuperar primero los recursos existentes antes de publicar actualizaciones para asegurarse de que está utilizando la configuración más reciente.

Después de modificar los recursos, aprenda a realizar una solicitud de configuración.

Solicitudes de configuración

Puede editar y publicar en la misma carga. Para enviar una solicitud de configuración, use el método HTTP POST de la API de configuración. La carga de configuración consta de un conjunto de recursos que indica los cambios deseados. Todas las modificaciones solo afectan a la versión de borrador hasta que envíe explícitamente un recurso de envío para publicar los cambios de borrador. Al publicar en versión preliminar o activa, incluya el recurso de envío y especifique el entorno de destino. Antes de enviar una solicitud, debe saber cómo hacer referencia a recursos y comprender sus dependencias.

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

Al enviar la solicitud de configuración, obtendrá un objeto de estado de configuración con el jobID que puede usar para realizar el seguimiento del progreso y los resultados de la solicitud.

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

Referencias y dependencias de recursos

Referencias

Para hacer referencia a un recurso existente en una solicitud de configuración, proporcione el tipo "$schema" del recurso junto con el identificador duradero del recurso. En el caso de productos y planes, también puede hacer referencia a estos recursos a través de su identificador externo.

El identificador duradero se puede encontrar en la propiedad "ID", por ejemplo, si se trata del recurso de producto al que queremos hacer referencia en otro 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"
            }

El identificador duradero sería "product/071b135e-9faf-4ff7-b113-a3f25bb0f468".

A continuación, el identificador duradero se puede usar en el ejemplo de recurso de lista siguiente estableciendolo en la propiedad de esquema de recursos "product" como esta:

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

El identificador externo de los recursos de producto y plan se define dentro de la propiedad "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 continuación, se puede hacer referencia al identificador externo del plan "gold-annual" por otros recursos posteriores en el siguiente 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"}
                  ...
              }

Solicitud de ejemplo:

En este ejemplo, la carga de configuración se usa para crear un nuevo producto SaaS con un identificador externo de "ds-contoso-image-resize-demo". Tras la creación de este producto, puede hacer referencia posteriormente a este producto mediante su identificador duradero o identificador 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"
              }
              ]
            }

Respuesta de ejemplo:

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

Después, puede usar el jobID a través de la API Configurar estado para comprobar el estado de la solicitud.

Dependencias

Algunos recursos tienen dependencias en la creación de otro recurso como requisito previo. En esta circunstancia, estamos usando la propiedad "resourceName" dentro de la misma carga para indicar la dependencia del recurso de producto en el recurso del plan, ya que estamos creando ambas en la misma solicitud.

"resourceName" solo se usa para identificar cada recurso como parte de la solicitud de configuración que está realizando. El valor no formará parte de los datos de los recursos, no se almacena ni se expone a los clientes. Además, si hay algún error como parte de la solicitud de configuración, se usará "resourceName" para llamar al recurso al que pertenece el error.

Solicitud de ejemplo:

En este ejemplo, el producto debe crearse antes del plan y, por tanto, se usa la propiedad "resourceName". El producto que se va a crear, "myNewProduct", será el valor que se usa para "resourceName" y se hace referencia a él dentro del recurso del plan dependiente.

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 envío

Si publica en "versión preliminar" o "activa", incluya el recurso de envío en la solicitud, que contiene:

La propiedad "product", que indica que el producto se está actualizando como al que hace referencia su identificador duradero o identificador externo.
La propiedad "targetType", que indica el entorno de destino

Al publicar en vivo específicamente, el "id." del envío de versión preliminar que desea 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" }
              }

Nota:

Si no incluye el recurso de envío, los cambios solo se realizarán en el estado borrador.

Publicación en versión preliminar

Los tipos de productos comerciales admiten un entorno de versión preliminar y cada actualización debe publicarse primero así antes de iniciarse. No se puede publicar directamente en directo.

Importante

Existe una excepción cuando se realizan cambios en la audiencia privada de los planes. Al sincronizar las actualizaciones con la audiencia privada específicamente, estos cambios se propagarán tanto a la versión preliminar como a la misma hora.

Existen dos maneras de publicar los recursos en el entorno de versión preliminar. Si es necesario realizar algún cambio en el envío de versión preliminar, realice otra solicitud GET, inserte los cambios necesarios e inserte los cambios de nuevo. No es necesario empezar a trabajar con los cambios iniciales.

Método 1: publicación de todos los recursos de borrador

Si desea publicar todos los cambios realizados en el borrador, puede enviar una solicitud de configuración con un recurso de envío que establezca el entorno de versión preliminar como "targetType". Como se muestra en el ejemplo siguiente, no es necesario proporcionar explícitamente todos los recursos que requieren una actualización, ya que este método publica todos los cambios en el entorno de destino, que en este caso es una versión preliminar. Solo tiene que proporcionar el punto de conexión de la API de configuración y el recurso de envío.

Solicitud de ejemplo:

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 borrador específicos (también conocidos como publicación modular)

Como alternativa, si no está preparado para publicar todos los cambios de borrador en varios recursos, simplemente proporcione los recursos que desea publicar y el recurso de envío para desencadenar una publicación modular. También puede usar este método para realizar cambios en los recursos y publicarlos al mismo tiempo en lugar de una actualización masiva, como se hace a través del método 1. Para una publicación modular, se requieren todos los recursos, excepto los detalles del nivel de producto (por ejemplo, lista, disponibilidad, paquetes, revendedor) según corresponda al tipo de producto.

Solicitud de ejemplo:

En este ejemplo, los recursos del producto se proporcionan de forma explícita como parte de la publicación modular seguida del 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/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" }
              }
              ]
            }

Publicación en directo

Una vez que los cambios en la versión preliminar se hayan probado y comprobado, puede insertar los cambios en directo mediante el envío de una solicitud de configuración con el "identificador" del envío de versión preliminar y el "targetType" establecido en "live". Para buscar el "identificador" del envío de versión preliminar que se va a incorporar dentro de la solicitud de configuración, consulte Consulta de los envíos.

Importante

A diferencia de cuando se publica en versión preliminar, cuando se publica en directo no existe ninguna opción para realizar una publicación modular. Por lo tanto, es importante asegurarse de que ha comprobado el envío de la versión preliminar antes de pasar a estar en directo con los cambios.

Solicitud de ejemplo:

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

Verificación del estado de una solicitud

Independientemente de los recursos incluidos en la solicitud de configuración o los cambios que realice, obtendrá un objeto de estado de configuración en la respuesta poco después de enviar una solicitud una vez que se haya procesado correctamente. El "jobID" es importante, ya que se puede usar más adelante para comprobar el estado de la solicitud.

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

Respuesta de ejemplo a una solicitud 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": []
            }

Estado de una solicitud pendiente

Puede recuperar el estado hasta que finalice el trabajo mediante la siguiente llamada y la entrada del "jobID" de la solicitud. El objeto también puede contener una lista de errores si hay algún problema con la solicitud.

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

Tenga en cuenta que el tiempo de finalización puede variar en función de la complejidad de la solicitud,

Resumen de una solicitud completa

Una vez completado un trabajo de solicitud de configuración, ya sea correctamente o con un error, puede obtener la lista de recursos creados o actualizados mediante el "jobID".

Nota:

Si realiza esta llamada antes de que se complete el trabajo, se producirá un error. Además, solo devolverá los recursos que se completaron correctamente, o en el caso de una cancelación solo las completadas antes de la cancelación.

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

Solicitud de ejemplo:

En el ejemplo siguiente, se usa una solicitud GET para recuperar los detalles de resumen de la solicitud de configuración usada en el ejemplo anterior que creó un nuevo producto SaaS. La respuesta es el objeto configure-detail con la matriz de recursos que contiene el recurso de producto que se creó junto con su identificador duradero.

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

Respuesta de ejemplo:

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

Cancelación de una solicitud de configuración

Antes de completar un trabajo, puede intentar cancelarlo si es necesario. En el caso de las solicitudes de larga duración, como publicar en "versión preliminar" o "activa", la solicitud de cancelación podría rechazarse si el trabajo es lo suficientemente largo como para procesarse por completo.

Para cancelar un trabajo, realice una llamada POST al punto de conexión de cancelación y proporcione el identificador de trabajo de la solicitud que desea cancelar.

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

Solicitud de ejemplo:

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

Respuesta de ejemplo de una solicitud de cancelación correcta:

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

No se permite la respuesta de ejemplo en caso de cancelación: HTTP Status code: 400

Content:

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

Importante

Tenga en cuenta que la cancelación solo se aplica a los recursos que aún no se han procesado. Es posible que algunos recursos ya hayan completado el procesamiento y reflejarán las actualizaciones de configuración más recientes, a pesar de la cancelación de la solicitud.

Puede capturar el resumen de la solicitud de configuración después de la cancelación para comprobar qué recursos (si los hubiera) ya se han procesado antes de la cancelación.

Sincronización de audiencias privadas

En el caso de un producto activo, las actualizaciones de audiencias privadas en los entornos de borrador, versión preliminar y en directo se pueden realizar al mismo tiempo sin necesidad de publicar. Puede sincronizar la audiencia privada mediante el recurso "price-and-availability-update-private-audiences" especificando qué audiencias desea agregar o quitar de un plan específico. Esto sincronizará los entornos de borrador, versión preliminar y activo para tener los mismos valores de audiencia privada. No es necesario proporcionar el recurso de envío al sincronizar la audiencia privada.

Para editar los borradores de audiencias, use el recurso "price-and-availability-plan" y la propiedad "privateAudiences". Tendrá que pasar por el flujo de publicación normal para que los valores se establezcan en versión preliminar y dinámica.

Importante

Los tipos de audiencia admitidos son "subscription", "ea", "msdn" y "tenant", pero la compatibilidad con estos varía según el tipo de producto. Si el producto admite más de un tipo de identificador para configurar la audiencia privada (por ejemplo, los identificadores de inquilino y los identificadores de suscripción), debe realizar una publicación completa si proporciona un nuevo tipo de identificador por primera vez. En este caso, no se puede sincronizar la audiencia privada.

Ejemplo de solicitud para sincronizar la configuración de audiencia privada:

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 administración de clientes potenciales

Conecte el sistema de administración de relaciones con el cliente (CRM) con el producto de Marketplace comercial para que pueda recibir información de contacto del cliente cuando un cliente expresa interés o implementa el producto. Puede modificar esta conexión en cualquier momento durante o después de la creación del producto. Para más información, consulte Obtención de clientes potenciales.

Solicitud de ejemplo para configurar la administración de cliente potencial:

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 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. Para detectar si un recurso tiene un estado de ciclo de vida y qué valores se admiten, puede comprobar el esquema de recursos para comprobar la existencia de la propiedad "lifecycleState". A continuación se detallan los diferentes estados de ciclo de vida que se admiten.

Eliminado

Puede eliminar recursos específicos actualizando la propiedad "lifecycleState" a "deleted". Solo puede eliminar los recursos de borrador que no se han publicado antes. Esta acción no se puede deshacer.

Solicitud de ejemplo:

En el ejemplo siguiente, se elimina el plan de borrador "básico".

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

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. Hay varios niveles de desuso. Todos los tipos de productos admiten el desuso de todo el producto y los planes individuales dentro de él. Para restaurar posteriormente un recurso en desuso, consulte el estado del ciclo de vida "generalmenteAvailable".

Solicitud de ejemplo de desuso de un 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"
                }
              ]
            }

Al dejar de usar planes, la propiedad "lifecycleState" debe cambiarse a "en desuso" y los cambios deben publicarse en "versión preliminar" y luego "live" para que la desuso surta efecto. Esto es diferente de un desuso de nivel de producto en el que la desuso se configurará automáticamente en el entorno activo.

Solicitud de ejemplo de desuso de un plan:

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

Hay otras formas de desuso que varían según el tipo de producto. Obtenga más información sobre el desuso de SaaS, máquinas virtuales y contenedores.

Disponibilidad general

generallyAvailable es el estado predeterminado del ciclo de vida de 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 para obtener una vista previa y, a continuación, estar activo. Puede encontrar ejemplos de SaaS, máquinas virtuales y contenedores en sus respectivos artículos.

Solicitud de ejemplo de una restauración del plan:

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

Referencia de la API de recursos

Las versiones de esquema siguientes solo son aplicables a la versión preliminar y cambiarán una vez que la API esté disponible con carácter general.

Nota:

Puede ver los recursos disponibles existentes y sus versiones aquí: resources-index

Tipo de recurso	Descripción	Esquema
commercial-marketplace-setup	Describe la configuración procesable de productos en marketplace comercial.	https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2
clientes potenciales	Permite conectarse a un sistema CRM para recibir clientes potenciales.	https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3
listado	Esto incluye las descripciones del producto, que se mostrarán en los escaparates del marketplace comercial de Microsoft.	https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5
listing-asset	Capturas de pantalla y los recursos de marketing vinculados al recurso de descripción.	https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5
listing-trailer	Recursos de vídeo vinculados al recurso de lista.	https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5
microsoft365-integration	Selección de tipos y habilitación de Microsoft 365.	https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2
plan	Para crear planes, a los que se hará referencia a continuación, los recursos de nivel de plan que configure, como la lista de planes.	https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2
plan-listing	Defina el nombre y la descripción del plan como desee que aparezcan en el marketplace comercial.	https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5
price-and-availability-custom-meter	Defina los medidores personalizados compartidos entre los planes.	https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3
price-and-availability-offer	Defina un público limitado que pueda revisar el producto antes de publicarlo en directo.	https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3
price-and-availability-plan	Configure los mercados en los que está disponible este plan, el modelo de monetización deseado, el precio y los términos de facturación.	https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4
price-and-availability-update-private-audiences	Las actualizaciones de audiencias privadas en entornos de borrador, versión preliminar y en directo se pueden realizar al mismo tiempo sin necesidad de publicación.	https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3
private-and-availability-private-offer-plan	Se usa para configurar los detalles absolutos de precios de un precio de producto o plan usado dentro de una oferta privada.	https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01
private-offer	Define el nombre y el tipo de oferta privada, con los términos y detalles de la oferta, junto con los productos o planes incluidos y sus precios	https://schema.mp.microsoft.com/schema/private-offer/2022-07-01
product	Este es el recurso principal, define el nombre y el tipo del producto, todos los recursos hacen referencia a esto.	https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3
property	Defina las categorías y sectores aplicables a la oferta, la versión de la aplicación y los contratos legales.	https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5
revendedor	Configure los asociados en el programa Proveedor de soluciones en la nube s (CSP) para que el producto esté disponible.	https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2
árbol de recursos	Describe el producto una lista de recursos para ese producto en estado actual para el entorno de destino especificado.	https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2
software como servicio-technical-configuration	Detalles técnicos que ayudan al marketplace comercial de Microsoft a conectarse a la solución.	https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3
Sumisión	Se puede usar para desencadenar diferentes acciones en el producto e indicar el estado de publicación de los entornos indiferentes del producto (borrador, versión preliminar y activo).	https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2
virtual-machine-plan-technical-configuration	Detalles técnicos que describen la máquina virtual y la ubicación de la imagen.	https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3
container-plan-technical-configuration	Detalles técnicos que describen las propiedades de la imagen de contenedor.	https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3

Guía de API por tipo de producto

La API de ingesta de productos estará disponible para otros tipos de productos en el futuro. A medida que se admiten más tipos de producto, se proporcionarán más instrucciones específicas para cada tipo de producto.

Tipo de producto	Recursos específicos del tipo de producto
Ofertas privadas	Creación y administración de ofertas privadas mediante la API de ingesta de productos
SaaS	Creación y administración de ofertas de SaaS mediante la API de ingesta de productos
Máquinas virtuales	Creación y administración de ofertas de máquinas virtuales a través de la API de ingesta de productos
Contenedores	Creación y administración de ofertas de contenedor mediante la API de ingesta de productos

Versiones y actualizaciones de API

Actualizar	¿Qué ha cambiado?
11-2023	Todos los puntos de conexión de esquema se han actualizado de product-ingestion.azureedge.net a schema.mp.microsoft.com
12-2022	Ahora hay disponible una nueva versión de esquema 2022-03-01-preview3 de la API de ingesta de PC para clientes potenciales que acepta clientID y clientSecret al configurar clientes potenciales y deja de capturar los campos serverID y contacto de correo electrónico. Cambie a la nueva versión y proporcione clientID y clientSecret para continuar configurando el conector marketo para las ofertas de Marketplace. Nueva dirección URL de esquema: https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3
09-2022	La compatibilidad con la versión preliminar del contenedor se publica como versión 2022-03-01-preview4
08-2022	La compatibilidad con la versión preliminar de software como servicio se publica como versión 2022-03-01-preview3
08-2022	Versión pública de la oferta privada como versión 2022-07-01
05-2022	La compatibilidad con la versión preliminar de la máquina virtual se publica como versión 2022-03-01-preview2

Compartir vía

API de ingesta de productos para el marketplace comercial

Introducción

Paso 1: Completar los requisitos previos

Asociar una aplicación de Microsoft Entra a su cuenta del Centro de partners

Paso 2: Obtener un token de acceso de Microsoft Entra

Conceptos

Recursos

Identificador duradero

Id. externo

Métodos de API

Un flujo de trabajo típico

Recuperar las configuraciones de recursos existentes

Método 1: árbol de recursos

Método 2: identificador duradero

Método 3: parámetros de cadena de consulta

Consulta de los envíos

Creación de nuevos productos y recursos

Modificación de los productos y recursos existentes

Solicitudes de configuración

Referencias y dependencias de recursos

Referencias

Dependencias

Recurso de envío

Publicación en versión preliminar

Método 1: publicación de todos los recursos de borrador

Método 2: Publicar recursos de borrador específicos (también conocidos como publicación modular)

Publicación en directo

Verificación del estado de una solicitud

Estado de una solicitud pendiente

Resumen de una solicitud completa

Cancelación de una solicitud de configuración

Sincronización de audiencias privadas

Configurar administración de clientes potenciales

Estados del ciclo de vida de los recursos

Eliminado

En desuso

Disponibilidad general

Referencia de la API de recursos

Guía de API por tipo de producto

Versiones y actualizaciones de API

Contenido relacionado

Comentarios

Recursos adicionales