Productopname-API voor de commerciële marketplace

Artikel
01/29/2025

De Productopname-API is een gemoderniseerde API waarmee alle bestaande inzendings-API's in alle commerciële marketplace-producten worden gecombineerd. Met de API kunt u resources maken, publiceren en beheren die zijn gekoppeld aan producten en plannen binnen uw Partnercentrum-account. Er wordt een declaratief patroon gebruikt om aanvragen in te dienen, waarbij de gewenste status wordt aangegeven in plaats van de afzonderlijke stappen op te geven om de gewenste status te bereiken.

Dit artikel bevat richtlijnen voor het aan de slag gaan met de API's voor elk aanbiedingstype voor commerciële marketplace. De Productopname-API wordt momenteel ondersteund voor SaaS, VM's, privéaanbiedingen en containeraanbiedingstypen en is in preview. Raadpleeg de API-richtlijnen per aanbiedingstype voor hulp die specifiek zijn voor uw aanbieding.

Belangrijk

Azure Active Directory (Azure AD) Graph is vanaf 30 juni 2023 afgeschaft. In de toekomst doen we geen verdere investeringen in Azure AD Graph. Azure AD Graph-API's hebben geen SLA of onderhoudsverplichting buiten beveiligingsgerelateerde oplossingen. Investeringen in nieuwe functies en functionaliteiten worden alleen gedaan in Microsoft Graph.

Azure AD Graph wordt in incrementele stappen buiten gebruik gesteld, zodat u voldoende tijd hebt om uw toepassingen te migreren naar Microsoft Graph-API's. Op een later tijdstip dat we zullen aankondigen, blokkeren we het maken van nieuwe toepassingen met behulp van Azure AD Graph.

Zie Belangrijk: Buitengebruikstelling van Azure AD Graph en Afschaffing van Powershell-module voor meer informatie.

Aan de slag

De Productopname-API kan worden geopend met behulp van de MSGraph-API onder de naam van de workload productopname. De basis-URL is https://graph.microsoft.com/rp/product-ingestion.

Als u de Productopname-API wilt gebruiken, moet u eerst het volgende verkrijgen:

Een Microsoft Entra-id en zorg ervoor dat u globale beheerdersmachtigingen voor de directory hebt
Een Microsoft Entra-toepassing
Een Microsoft Entra-toegangstoken

Stap 1: Vereisten voltooien

Voordat u begint met het schrijven van code om de Productopname-API aan te roepen, moet u ervoor zorgen dat u aan de volgende vereisten voldoet.

U (of uw organisatie) moet beschikken over een Microsoft Entra-directory en u moet beschikken over globale beheerdersmachtigingen voor de directory. Als u Al Microsoft 365 of andere zakelijke services van Microsoft gebruikt, hebt u al de directory Microsoft Entra. Anders kunt u zonder extra kosten een nieuwe Microsoft Entra-id maken in het Partnercentrum.
U moet een Microsoft Entra-toepassing koppelen aan uw Partnercentrum-account en uw tenant-id, client-id en sleutel verkrijgen. U hebt deze nodig om het Microsoft Entra-toegangstoken te verkrijgen dat u gebruikt in aanroepen naar de Microsoft Store-inzendings-API.

Een Microsoft Entra-toepassing koppelen aan uw Partnercentrum-account

Als u de Productopname-API wilt gebruiken, moet u een Microsoft Entra-toepassing koppelen aan uw Partnercentrum-account, de tenant-id en client-id voor de toepassing ophalen en een sleutel genereren. De Microsoft Entra-toepassing vertegenwoordigt de app of service van waaruit u de Productopname-API wilt aanroepen. U hebt de tenant-id, client-id en sleutel nodig om een Microsoft Entra-toegangstoken te verkrijgen dat moet worden doorgegeven aan de API.

Notitie

U hoeft deze taak slechts één keer uit te voeren. Nadat u de tenant-id, client-id en sleutel hebt, kunt u deze telkens opnieuw gebruiken wanneer u een nieuw Microsoft Entra-toegangstoken moet maken.

Koppel in Partnercentrum het Partnercentrum-account van uw organisatie aan de Microsoft Entra-adreslijst van uw organisatie.
Voeg op de pagina Gebruikers in het gedeelte Accountinstellingen sectie van Het Partnercentrum de Microsoft Entra-toepassing toe die de app of service vertegenwoordigt die u gebruikt voor toegang tot inzendingen voor uw Partnercentrum-account. Zorg ervoor dat u deze toepassing de rol Manager toewijst. Als de toepassing nog niet bestaat in uw Microsoft Entra-directory, maakt u een nieuwe Microsoft Entra-toepassing in Partnercentrum. Partnercentrum maakt twee typen vermeldingen voor de toepassing: een als de service-principal en de andere als het toepassingstype Microsoft Entra.
Ga terug naar de pagina Gebruikers, selecteer de naam van uw Microsoft Entra-toepassing om naar de toepassingsinstellingen te gaan en kopieer de waarden voor tenant-iden client-id.
Selecteer Nieuwe sleutel toevoegen. Kopieer in het volgende scherm de sleutelwaarde. U hebt geen toegang meer tot deze gegevens nadat u deze pagina hebt verlaten. Zie Sleutels beheren voor een Microsoft Entra-toepassing voor meer informatie.

Stap 2: een Microsoft Entra-toegangstoken verkrijgen

Als u een van de methoden in de Productopname-API wilt aanroepen, moet u eerst een Microsoft Entra-toegangstoken verkrijgen om door te geven aan de autorisatieheader van elke methode in de API. Een toegangstoken verloopt 60 minuten na uitgifte. Daarna kunt u het vernieuwen, zodat u deze in toekomstige aanroepen naar de API kunt gebruiken.

Als u het toegangstoken wilt verkrijgen, volgt u de instructies in Service to Service-aanroepen met behulp van clientreferenties om een HTTP POST naar het https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token eindpunt te verzenden. Hier volgt een voorbeeldaanvraag:

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

Geef voor de tenant_id waarde in de POST-URI en de parameters client_id en client_secret de tenant-id, client-id en de sleutel op voor uw toepassing die u in de vorige sectie hebt opgehaald uit het Partnercentrum. Voor de bereikparameter moet u opgeven https://graph.microsoft.com/.default.

Concepten

Voordat u aan de slag gaat, moet u enkele basisconcepten begrijpen.

Middelen

De API is gestructureerd rond resourcetypen, waarbij elk type wordt beschreven met behulp van een toegewezen schemadefinitie waarnaar wordt verwezen door de eigenschap '$schema'. Het schema bestaat uit de configuratie-eigenschappen van die resource. Resources zijn essentieel voor het maken en bijwerken van de configuratie van verschillende aspecten van een bepaald product. Zie de resource-API-verwijzing voor een volledige lijst met resourcetypen en hun schema's.

Duurzame identificatie

Een duurzame id is een door het systeem gegenereerde globale id die wordt gebruikt om elke resource uniek te identificeren. Elke resource heeft een bijbehorende id-eigenschap, die, in combinatie met de naam van het resourcetype, de duurzame id van een resource vormt. De duurzame ID wordt gebruikt bij het verwijzen naar hulpmiddelen om ze te raadplegen of aan te passen.

Indeling:

\<resource-type>/\<id>

Voorbeeld:

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

Externe ID

Een externe id is een andere unieke id die kan worden gebruikt om te verwijzen naar specifieke producten of plannen. Dit is een alternatieve manier om naar deze resources te verwijzen in plaats van de duurzame id te gebruiken. De externe ID van een product komt overeen met de 'offerID' en de externe ID van een plan komt overeen met de 'planID', zoals bij het aanmaken is gedefinieerd in de eigenschap 'identiteit'.

Voorbeeld:

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

API-methoden

Er zijn vier beheer-API's die kunnen worden gebruikt om verschillende acties uit te voeren, zoals het uitvoeren van query's op bestaande resources, het maken van configuratie-updates en het controleren van de status van een aanvraag.

Notitie

Voor alle aanvragen moet u de gewenste schemaversie ($version queryparameter) instellen als onderdeel van het antwoord.

API-type	Beschrijving	HTTP-methode en -pad
Query	Bestaande bronnen worden opgehaald door: -Methode 1: resource-structuur resourcetype -Methode 2: de duurzame-ID -Methode 3: parameters van de querystring	-Methode 1: `GET resource-tree/<product-durableID>` -Methode 2: `GET <resource-durableID>` -Methode 3: `GET <resourceType>?<query parameters>`
Verzenden configureren	Hiermee dient u verzoeken in om een of meer bronnen te maken of bij te werken. Na een geslaagde verwerking wordt een jobID geretourneerd, die kan worden gebruikt om de status van de aanvraag op te halen. Dit API-type kan worden gebruikt om de conceptstatus bij te werken en wijzigingen te publiceren, privé-doelgroepen te synchroniseren en de levenscyclusstatus van de resource te wijzigen.	`POST configure`
Status configureren	Haalt de status van een aanvraag in behandeling op via de job-id.	`GET configure/<jobID>/status`
Statusdetails configureren	Hiermee wordt een gedetailleerd overzicht opgehaald van een voltooide aanvraag, inclusief de bijgewerkte resources, via de jobID.	`GET configure/<jobID>`
Configureren annuleren	Hiermee wordt de opgegeven taak Configureren geannuleerd.	`POST configure/<jobID>/cancel`

Een typische werkstroom

Als u een bestaande resource wilt bijwerken, moet u het volgende doen:

Een bestaande resourceconfiguratie ophalen (API-type: Query via resourcestructuur)*
Breng eventuele benodigde updates aan en dien vervolgens een configuratieaanvraag in (API-type: Configureren indienen)
Controleer de status van de aanvraag (API-type: Status configureren en Statusdetails configureren)

* Dezelfde werkstroom kan worden toegepast bij het maken van nieuwe resources, maar in plaats van resources op te halen (stap 1), gebruikt u de resource-API-referentietabel om ervoor te zorgen dat u het huidige schema gebruikt voor het resourcetype dat u maakt.

Samenvattend ziet u in deze afbeelding het typische aanroeppatroon dat wordt gebruikt om een configuratieaanvraag in te dienen, ongeacht of u een nieuwe resource maakt of een bestaande resource wijzigt.

Schermopname van het typische belpatroon dat wordt gebruikt om een configuratieaanvraag in te dienen.

Notitie

Controleer alle andere vereisten die specifiek zijn voor het aanbiedingstype dat u beheert door te verwijzen naar de API-richtlijnen per aanbiedingstype sectie.

Bestaande resourceconfiguraties ophalen

Voordat u bestaande resources bijwerkt, is het belangrijk om ze eerst op te halen om ervoor te zorgen dat u over de nieuwste configuratie beschikt. Er zijn verschillende manieren om resources op te halen via een GET-aanroep. Zie methode 1 om alle resources binnen een specifiek product op te halen in één API-aanroep.

Methode 1: Hulpmiddelenboom

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

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

U kunt alle configuraties van middelen binnen een specifiek product ophalen met behulp van het resourcetype "resourceboom" samen met de duurzame ID van het product.

De meest recente schemaversie die beschikbaar is, kan voor elke resource verschillen. Bij het uitvoeren van een resourcestructuuraanvraag bepaalt de opgegeven schemaversie welke versie wordt geretourneerd voor elke resource in het product. De versie die is opgegeven, fungeert als een maximale versielimiet, omdat hiermee de meest recente schemaversie wordt geretourneerd die beschikbaar is voor alle resources van gelijke of lagere versie. Als de meest recente beschikbare planversie bijvoorbeeld '2022-03-01-preview3' is, wordt deze versie weergegeven als u '2022-03-01-preview5' opgeeft in de GET-aanvraag van de bronnenhiërarchie. Als u echter '2022-03-01-preview2' aanvraagt als de versie van de resourcestructuur, leidt dit tot het retourneren van de '2022-03-01-preview2'-planningsresource, zelfs als de nieuwste beschikbare versie '2022-03-01-preview3' is. Het is raadzaam om de nieuwste beschikbare versie van elke resource te gebruiken om ervoor te zorgen dat u een bijgewerkt schema gebruikt met nieuw ondersteunde functionaliteiten.

Notitie

Als u de duurzame ID van het product niet weet, kunt u de externe ID van het product gebruiken om de productresource op te halen door het script uit te voerenGET product?externalID=<product-externalID>&$version=<product-schema-version>. Deze aanvraag maakt gebruik van een queryreeksparameter, die wordt beschreven in methode 3. Het antwoord bevat de duurzame id van het product, die u kunt gebruiken voor toekomstige aanvragen.

Wanneer u een GET-aanroep uitvoert met behulp van de 'resourcestructuur', krijgt u standaard de conceptversie van uw resources terug. Door de queryparameter targetType door te geven, kunt u echter het gewenste doel opgeven om de gegevens 'preview' of 'live' op te halen. In het volgende voorbeeld retourneert de GET-aanroep de configuratie van de preview-omgeving voor alle resources onder het product '12345678-abcd-efgh-1234-12345678901'.

Voorbeeld van GET-aanroep:

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

Voorbeeldantwoord:

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

Methode 2: Duurzame ID

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

Haal een specifieke resource op via de durable ID. Zodra een resource is gemaakt, blijft de duurzame ID altijd hetzelfde en kan deze worden gebruikt om de meest recente conceptaanpassingen van die resource op te halen door de GET-methode aan te roepen. De volgende aanvraag retourneert bijvoorbeeld de conceptconfiguratie van dit specifieke product met behulp van de schemaversie 2022-03-01-preview3.

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

Belangrijk

Deze methode wordt alleen gebruikt voor het ophalen van de conceptconfiguratie. Als u voorbeeld- of livegegevens wilt ophalen, gebruikt u de methode 'resourcestructuur', zoals eerder beschreven.

Om de duurzame ID voor uw resources te vinden, kunt u het volgende doen:

Gebruik de "resource-tree"-methode om alle resources binnen het product op te halen, samen met elk van hun respectieve duurzame ID's, of
Haal de details op van een voltooide resourceconfiguratieaanvraag, inclusief de duurzame id's voor alle resources die zijn gemaakt of bijgewerkt als onderdeel van de aanvraag.

Vergeet niet dat de eigenschap 'ID' de duurzame id voor de betreffende resource is.

Methode 3: Queryparameters

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

Deze methode wordt gebruikt om een query uit te voeren op bepaalde resourcetypen die zijn gekoppeld aan een specifiek account. U kunt bijvoorbeeld al uw producten van een specifiek producttype ophalen met één GET-aanroep. Queryreeksparameters worden gebruikt om querygegevens op te vragen die betrekking hebben op uw producten, abonnementen of inzendingen.

Deze tabel bevat de ondersteunde queryparameters voor elk van de ondersteunde resourcetypen. Niet alle resourcetypen ondersteunen elk van de queryparameters. Raadpleeg deze tabel voor de volledige lijst met momenteel ondersteunde queryreeksen.

Resourcetype	Parameters	Voorbeelden van queryreeksen
plan	product`` 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>`
onderwerping	targetType $maxpagesize continuationToken$version`*`	`GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>` `GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version>`
resourcestructuur	targetType$version`*`	`GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version>`

* De parameters product en $version zijn altijd vereist.

Functionaliteit van elk van de ondersteunde queryparameters:

product: wanneer de parameter 'product' wordt doorgegeven in de context van het resourcetype Plan, worden alle plannen binnen dat specifieke product geretourneerd.
externalID : wanneer de parameter 'externalID' wordt doorgegeven in de context van een product of plan, wordt de configuratie van dat betreffende product of plan geretourneerd. In tegenstelling tot de methode ‘resourcestructuur’, retourneert deze querystring-parameter alleen de details van die resource, niet van alle resources erin.
type: wanneer de parameter 'type' wordt doorgegeven in de context van het resourcetype Product, worden alle producten van dat type geretourneerd die aan uw account zijn gekoppeld. Als u bijvoorbeeld 'type=softwareAsAService' opgeeft, worden al uw SaaS-producten geretourneerd.
targetType : hiermee worden de gegevens van een specifieke omgeving geretourneerd in de context van het resourcetype dat wordt gebruikt. De ondersteunde waarden 'targetType' zijn 'concept', 'preview' of 'live'.
$maxpagesize– Door het maximale paginaformaat op te geven, in de vorm van een positief geheel getal, wordt deze parameter gebruikt om de resultaten van uw zoekopdracht te beperken bij het opvragen van uw vorige inzendingen.
continuationToken : deze parameter kan worden gebruikt met de parameter '$maxpagesize' om een query uit te voeren op een andere set resultaten die beschikbaar zijn in uw zoekopdracht. De waarde 'continuationToken' wordt opgegeven in het antwoord van de vorige pagina.
$version: dit is een vereiste parameter voor alle aanroepen. Hiermee geeft u op welke schemaversie u wilt gebruiken voor het antwoord van de aanvraag die u hebt gedaan. De meest recente schemaversie die beschikbaar is, kan voor elke resource verschillen en de opgegeven versie fungeert als een maximale versielimiet. Het systeem retourneert de exacte schemaversie indien beschikbaar of de dichtstbijzijnde versie die ouder is dan de aangevraagde versie. Dit kan u helpen uw code te laten werken, zelfs als er nieuwere schemawijzigingen zijn, maar als u de nieuwste functies wilt gebruiken, is het raadzaam om de nieuwste beschikbare versie van elk schema te gebruiken.

Uw inzendingen opvragen

U kunt uw bestaande productinzendingen ophalen door dit te doen GET submission/<product-durableID>. Standaard krijgt u al uw actieve inzendingen, inclusief de conceptreferentie, terug, maar u kunt ook een query uitvoeren op een specifieke omgeving met behulp van de queryparameter targetType: (GET submission/<product-durableID>?targetType=<environment>&$version=<version>).

Belangrijk

Zodra een 'Preview-' wordt verzonden naar 'Live-', wordt de vorige 'Live' inzending vervangen. Als dit gebeurt, vertegenwoordigen de gegevens nu zowelpreview-' als 'Live' omgevingen totdat een nieuwe inzending is gepubliceerd op 'Preview-'.

Voorbeeldaanvraag:

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

Voorbeeldantwoord:

In dit voorbeeld ziet u een GET-aanvraag voor de actieve inzendingen die zijn gekoppeld aan product-id "12345678-abcd-efgh-1234-12345678901." De actieve "Live" inzending (inzending/12345678-abcd-efgh-1234-12345678901/1152921515689847470) is gepubliceerd om eerst en daarna live te bekijken. Toen deze inzending op 25 januari 2022 werd gepusht naar live, vertegenwoordigde deze zowel de preview als de live-versie, totdat er op 4 februari 2022 een nieuwe preview-inzending (submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683) werd gemaakt.

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

Nieuwe producten en middelen creëren

U kunt nieuwe resources maken, inclusief nieuwe producten, als onderdeel van één configuratieaanvraag. Met behulp van de resource-API-referentietabel kunt u het schema ophalen voor het resourcetype dat u wilt maken. Dit zorgt ervoor dat u het meest recente schema gebruikt en daarom alle benodigde eigenschappen configureert om de resource te maken.

Als u een nieuw product maakt, variëren de vereisten per producttype. Daarom moet u verschillende hulpbronnen opgeven. U kunt verwijzen naar de bijbehorende commerciële marketplace-documentatie voor het betreffende producttype om ervoor te zorgen dat u de basisvereisten in uw aanvraag configureert. U kunt ook een configuratieaanvraag indienen met alleen de productresource. Nadat u het product hebt gemaakt, roept u de API voor configuratiestatusdetails aan om de gemaakte productresource op te halen. Vind vervolgens de duurzame id en gebruik deze om de resource-tree Query API aan te roepen. Het antwoord retourneert de toepasselijke ondersteunde resources voor het producttype dat u hebt gemaakt.

Als u een nieuwe resource in een bestaand product wilt maken, moet u ook het meest recente schema van dat specifieke resourcetype ophalen. Zorg ervoor dat u de afhankelijke resources opgeeft als onderdeel van de configuratieaanvraag door de resourceafhankelijkheden te controleren.

Nadat u uw resources hebt gemaakt met behulp van de schema's, leert u hoe u een configuratieaanvraag kunt indienen.

Bestaande producten en middelen wijzigen

U kunt updates indienen met behulp van de configureerbare payload. Deze nettolading bestaat uit een of meer resourcetypen en de eigenschap '$schema' geeft het resourcetype aan waarnaar wordt verwezen.

Tip

U wordt aangeraden eerst bestaande resources op te halen voordat u updates publiceert om ervoor te zorgen dat u de nieuwste configuratie gebruikt.

Nadat u uw resources hebt gewijzigd, leert u hoe u een configuratieaanvraag kunt indienen.

Configuratieaanvragen

U kunt bewerken en publiceren binnen dezelfde payload. Als u een configuratieaanvraag wilt indienen, gebruikt u de HTTP POST-methode van de configuratie-API. De configureerbare payload bestaat uit een reeks resources die de gewenste wijzigingen aangeven. Alle bewerkingen zijn alleen van invloed op de conceptversie totdat u expliciet een inzendingsresource verzendt om uw conceptwijzigingen te publiceren. Wanneer u publiceert naar preview of live, neemt u de inzendingsresource op en geeft u de doelomgeving op. Voordat u een aanvraag indient, moet u weten hoe u naar resources verwijst en de bijbehorende afhankelijkheden begrijpt.

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

Wanneer u uw configuratieaanvraag indient, krijgt u een configuratiestatusobject terug met de jobID die u kunt gebruiken om de voortgang en resultaten van uw aanvraag bij te houden.

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

Resourceverwijzingen en afhankelijkheden

Verwijzingen

Als u wilt verwijzen naar een bestaande resource in een configuratieaanvraag, geeft u het type '$schema' van de resource op, samen met de duurzame id van de resource. Voor producten en abonnementen kunt u ook naar deze bronnen verwijzen via hun externe ID.

De duurzame id vindt u in de eigenschap ID, bijvoorbeeld als dit de productresource is waarnaar we in een andere resource willen verwijzen:

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

De duurzame ID zou "product/071b135e-9faf-4ff7-b113-a3f25bb0f468" zijn.

De duurzame ID kan vervolgens worden gebruikt in de lijstresource, bijvoorbeeld door deze in te stellen in de resource-schema-eigenschap "product", als volgt:

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

De externe id van product- en planbronnen wordt gedefinieerd binnen de eigenschap 'identiteit'.

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

De externe plan-id 'gold-annual' kan vervolgens worden gebruikt door andere bronnen in het volgende formaat:

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

Voorbeeldaanvraag:

In dit voorbeeld wordt de configureer-payload gebruikt om een nieuw SaaS-product te maken met een externe ID van 'ds-contoso-image-resize-demo'. Na de creatie van dit product kunt u later naar dit product verwijzen met behulp van de persistente ID of externe ID.

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

Voorbeeldantwoord:

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

Vervolgens kunt u de jobID gebruiken via de API Configuratie Status om de status van uw aanvraag te controleren.

Afhankelijkheden

Bepaalde middelen zijn afhankelijk van het creëren van een andere bron als noodzakelijke voorwaarde. In dit geval gebruiken we de eigenschap resourceName binnen dezelfde payload om de afhankelijkheid van de productresource in de planresource aan te geven, omdat we beide in dezelfde aanvraag creëren.

De 'resourceName' wordt alleen gebruikt om elke resource te identificeren als onderdeel van de configuratieaanvraag die u uitvoert. De waarde maakt geen deel uit van de gegevens van de resources, deze wordt niet opgeslagen en wordt ook niet blootgesteld aan klanten. Als er fouten zijn als onderdeel van de configuratieaanvraag, wordt de resourceName gebruikt om de resource aan te roepen waartoe de fout behoort.

Voorbeeldaanvraag:

In dit voorbeeld moet het product worden gemaakt vóór het plan en daarom wordt de eigenschap resourceName gebruikt. Het product dat wordt gemaakt, 'myNewProduct', is de waarde die wordt gebruikt voor 'resourceName' en waarnaar wordt verwezen in de afhankelijke planresource.

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

Inzendhulpbron

Als u publiceert naar 'preview' of 'live', neemt u de inzendresource op in uw aanvraag, die het volgende bevat:

De eigenschap 'product', die aangeeft dat het product wordt bijgewerkt, zoals wordt aangeduid door de duurzame ID of externe ID.
De eigenschap targetType, die de doelomgeving aangeeft

Wanneer u specifiek naar live publiceert, is de id van de preview-inzending die u wilt publiceren:

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

Notitie

Als u de inzendingsresource niet opneemt, worden de wijzigingen alleen aangebracht in de conceptstatus.

Publiceren voor voorbeeldweergave

Commerciële producttypen ondersteunen een preview-omgeving en elke update moet eerst worden gepubliceerd naar preview voordat u live gaat. U kunt niet rechtstreeks publiceren naar live.

Belangrijk

De uitzondering hierop is wanneer u wijzigingen aanbrengt in de privé-doelgroep van uw plannen. Wanneer updates synchroniseren met de privé-doelgroep specifiek, worden deze wijzigingen tegelijkertijd doorgegeven aan zowel preview als live.

Er zijn twee manieren waarop u uw resources kunt publiceren naar de preview-omgeving. Als er wijzigingen moeten worden aangebracht in de preview-indiening, voert u een andere GET-aanvraag uit, voert u de benodigde wijzigingen aan en pusht u de wijzigingen opnieuw. U hoeft niet eerst live te gaan met uw eerste wijzigingen.

Methode 1: Alle conceptbronnen publiceren

Als u elke conceptwijziging wilt publiceren die u hebt aangebracht, kunt u een configuratieaanvraag verzenden met een inzendingsresource waarmee de preview-omgeving wordt ingesteld als targetType. Zoals in het volgende voorbeeld wordt weergegeven, hoeft u niet expliciet elke resource op te geven waarvoor een update is vereist, omdat met deze methode alle wijzigingen in de doelomgeving worden gepubliceerd, die in dit geval een preview-versie is. U hoeft alleen het configuratie-API-eindpunt en de inzendingsresource op te geven.

Voorbeeldaanvraag:

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

Methode 2: Specifieke conceptbronnen publiceren (ook wel modulair publiceren genoemd)

Als u niet voorbereid bent op het publiceren van alle conceptwijzigingen in verschillende resources, geeft u de resources op die u wilt publiceren, samen met de inzendingsresource om een modulaire publicatie te activeren. U kunt deze methode ook gebruiken om wijzigingen aan te brengen in resources en deze tegelijkertijd te publiceren in plaats van als onderdeel van een bulkupdate, zoals wordt gedaan via methode 1. Voor een modulaire publicatie zijn alle resources vereist, met uitzondering van de details op productniveau (bijvoorbeeld vermelding, beschikbaarheid, pakketten, reseller) die van toepassing zijn op uw producttype.

Voorbeeldaanvraag:

In dit voorbeeld worden resources in het product expliciet verstrekt als onderdeel van de modulaire publicatie, gevolgd door de inzendingsresource.

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

Publiceren naar de live-omgeving

Zodra uw wijzigingen in de preview zijn getest en geverifieerd, kunt u uw wijzigingen live pushen door een configuratieaanvraag te verzenden met de 'ID' van uw preview-inzending en de 'targetType' ingesteld op 'live'. Zie Query's uitvoeren op uw inzendingenom de 'id' van uw preview-inzending te vinden die u wilt opnemen in uw configuratieaanvraag.

Belangrijk

In tegenstelling tot publiceren naar preview, is er geen optie om een modulaire publicatie uit te voeren bij het publiceren naar live. Daarom is het belangrijk om ervoor te zorgen dat u uw preview-inzending hebt gecontroleerd voordat u live gaat met uw wijzigingen.

Voorbeeldaanvraag:

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

De status van een aanvraag controleren

Ongeacht de resources die zijn opgenomen in uw configuratieaanvraag of de wijzigingen die u aanbrengt, krijgt u een configuratiestatusobject terug in het antwoord kort nadat deze is verwerkt. De 'jobID' is belangrijk omdat deze later kan worden gebruikt om de status van de aanvraag te controleren.

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

Voorbeeldantwoord op een ingediende aanvraag:

            {
                "$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 van een aanvraag in behandeling

U kunt de status ophalen totdat de taak is voltooid met behulp van de volgende aanroep en het invoeren van de 'jobID' van de aanvraag. Het object kan ook een lijst met fouten bevatten als er problemen zijn met uw aanvraag.

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

Houd er rekening mee dat de te voltooien tijd kan variëren, afhankelijk van de complexiteit van uw aanvraag,

Samenvatting van een voltooide aanvraag

Zodra een taak voor een configuratieaanvraag is voltooid, succesvol of met een fout, kunt u de lijst met resources ophalen die zijn gemaakt of bijgewerkt met behulp van dejobID.

Notitie

Als u deze aanroep doet voordat de taak is voltooid, mislukt deze. Daarnaast worden alleen de resources geretourneerd die zijn voltooid, of in het geval van een annulering alleen de resources die zijn voltooid vóór de annulering.

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

Voorbeeldaanvraag:

In het volgende voorbeeld wordt een GET-aanvraag gebruikt om de samenvattingsgegevens op te halen van de configuratieaanvraag die in het vorige voorbeeld is gebruikt, waarmee een nieuw SaaS-product is gemaakt. Het antwoord is het configuratiedetailobject met de resource-array die de productresource bevat die samen met zijn duurzame ID is gemaakt.

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

Voorbeeldantwoord:

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

Een configuratieaanvraag annuleren

Voordat een taak is voltooid, kunt u deze indien nodig annuleren. Voor langlopende aanvragen, zoals publiceren naar 'preview' of 'live', kan de annuleringsaanvraag worden geweigerd als de taak ver genoeg is om volledig te worden verwerkt.

Als u een taak wilt annuleren, voert u een POST-aanroep uit naar het eindpunt voor annuleren en geeft u de taak-id op van de aanvraag die u wilt annuleren.

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

Voorbeeldaanvraag:

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

Voorbeeldantwoord van een geslaagde annuleringsaanvraag:

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

Voorbeeldantwoord in het geval dat annulering niet is toegestaan: HTTP Status code: 400

Inhoud:

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

Belangrijk

Houd er rekening mee dat de annulering alleen van toepassing is op resources die nog niet zijn verwerkt. Sommige resources hebben de verwerking mogelijk al voltooid en weerspiegelen de meest recente configuratie-updates, ondanks de annulering van de aanvraag.

U kunt de samenvatting van de configuratieaanvraag na annulering ophalen om te controleren welke resources (indien aanwezig) al vóór de annulering zijn verwerkt.

Privé-doelgroepen synchroniseren

Voor een liveproduct kunnen updates voor privé-doelgroepen in de concept-, preview- en liveomgevingen tegelijkertijd worden uitgevoerd zonder dat hiervoor een publicatie is vereist. U kunt de privé-doelgroep synchroniseren met behulp van de resource 'prijs-en-beschikbaarheid-update-privé-doelgroepen' door op te geven welke doelgroepen u wilt toevoegen aan of verwijderen uit een specifiek abonnement. Hiermee worden de concept-, preview- en liveomgevingen gesynchroniseerd zodat ze identieke privé-doelgroepwaarden hebben. U hoeft de inzendingsresource niet op te geven bij het synchroniseren van de privé-doelgroep.

Als u de conceptdoelgroepen wilt bewerken, gebruikt u de resource 'price-and-availability-plan' en de eigenschap privateAudiences. Dit moet de gebruikelijke publicatiestroom doorlopen om de waarden in de preview- en live-modus in te stellen.

Belangrijk

De ondersteunde doelgroeptypen zijn 'abonnement', 'ea', 'msdn' en 'tenant', maar ondersteuning hiervoor verschilt per producttype. Als uw product meer dan één type id ondersteunt om de privé-doelgroep te configureren (bijvoorbeeld tenant-id's en abonnements-id's), moet u een volledige publicatie uitvoeren als u voor het eerst een nieuw id-type opgeeft. In dit geval kunt u de privé-doelgroep niet synchroniseren.

Voorbeeldaanvraag voor het synchroniseren van de configuratie van de privé-doelgroep:

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

Leadbeheer configureren

Verbind uw CRM-systeem (Customer Relationship Management) met uw commerciële marketplace-product, zodat u contactgegevens van klanten kunt ontvangen wanneer een klant interesse heeft of uw product implementeert. U kunt deze verbinding op elk gewenst moment wijzigen tijdens of na het maken van het product. Zie voor meer informatie Leads van klanten verkrijgen.

Voorbeeldaanvraag voor het configureren van leadbeheer:

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

Statussen van de levenscyclus van resources

Er zijn verschillende acties die u kunt uitvoeren die overeenkomen met de levenscyclusstatus van een resource. Niet alle resources hebben een levenscyclusstatus en niet alle levenscyclusstatussen worden ondersteund door alle resources. Als u wilt ontdekken of een resource een levenscyclusstatus heeft en welke waarden worden ondersteund, kunt u het resourceschema controleren op het bestaan van de eigenschap 'lifecycleState'. Verschillende ondersteunde levenscyclusstatussen worden later gedetailleerd beschreven.

Verwijderd

U kunt specifieke resources verwijderen door de eigenschap 'lifecycleState' bij te werken naar 'verwijderd'. U kunt alleen conceptbronnen verwijderen die nog niet eerder zijn gepubliceerd. Deze actie kan niet ongedaan worden gemaakt.

Voorbeeldaanvraag:

In het volgende voorbeeld wordt het conceptplan 'basic' verwijderd.

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

Afgeschaft

Met afschaffing wordt de resource uit de commerciële markt verwijderd. Als u de eigenschap lifecycleState wilt verwijderen, stelt u de eigenschap 'lifecycleState' in op 'afgeschaft' voor de resources die deze ondersteunen. Er zijn verschillende niveaus van veroudering. Alle producttypen ondersteunen het afschaven van het hele product en afzonderlijke abonnementen hierin. Als u een afgeschafte resource later wilt herstellen, raadpleegt u de levenscyclusstatus 'generallyAvailable'.

Voorbeeld van een aanvraag voor uitfasering van een product:

In het volgende voorbeeld wordt de actieve indiening van het product ingesteld op uitfaseren. Zodra deze wijziging is toegepast, wordt deze automatisch gepubliceerd op live om van kracht te worden.

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

Wanneer u plannen afschaffen, moet de eigenschap lifecycleState worden gewijzigd in Afgeschaft en moeten de wijzigingen vervolgens worden gepubliceerd naar 'preview' en vervolgens 'live' om de afschaffing van kracht te laten worden. Dit verschilt van een afschaffing op productniveau waarbij de afschaffing automatisch wordt geconfigureerd in de liveomgeving.

Voorbeeldaanvraag voor de uitfasering van een plan:

In het volgende voorbeeld wordt een plan binnen een SaaS-product ingesteld om uit te faseren. Houd er rekening mee dat u deze wijziging later kunt publiceren met behulp van de inzendingsresource.

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

Er zijn andere vormen van afschaffing die variëren, afhankelijk van het producttype. Meer informatie over afschaffing van SaaS, virtuele machines en containers.

Algemeen beschikbaar

generallyAvailable is de standaardlevenscyclusstatus voor alle resources. Zodra een resource is afgeschaft, kunt u deze herstellen door de eigenschap lifecycleState weer te wijzigen in 'generallyAvailable'. Als u een afgeschaft product wilt herstellen, moet u het product publiceren om vervolgens live te kunnen bekijken. U vindt voorbeelden voor SaaS, VM's en containers in hun respectieve artikelen.

Aanvraag van een voorbeeld van herstel van een plan:

In het volgende voorbeeld is een plan bedoeld om te worden hersteld. Als u deze wijziging wilt toepassen, moet u later helemaal live publiceren met behulp van de inzendingsresource.

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

Naslaginformatie voor bron-API

De volgende schemaversies zijn alleen van toepassing voor een preview en zullen wijzigen zodra de API algemeen beschikbaar wordt.

Notitie

U kunt de bestaande beschikbare resources en de bijbehorende versies hier bekijken: resources-index

Resourcetype	Beschrijving	Schema
opzet-van-de-commerciële-marktplaats	Beschrijft de transactable configuratie van producten in de commerciële marketplace.	https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2
klant-leads	Hiermee kunt u verbinding maken met een CRM-systeem om leads van klanten te ontvangen.	https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3
Aanbieding	Dit omvat de beschrijvingen van uw product, die worden weergegeven in de webwinkels van Microsoft commerciële marketplace.	https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5
listing-asset	Schermopnamen en uw marketingmaterialen die gekoppeld zijn aan de vermeldingsbron.	https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5
listing-trailer	Video-items die zijn gekoppeld aan de vermeldingsbron.	https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5
microsoft365-integratie	Inschakeling van Microsoft 365 en selectie van type.	https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2
plan	Om plannen te maken, waarnaar vervolgens wordt verwezen door de op het planniveau geconfigureerde resources, zoals een planlijst.	https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2
planoverzicht	Definieer de naam en beschrijving van het plan zoals u wilt dat ze worden weergegeven in de commerciële marketplace.	https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5
prijs-en-beschikbaarheid-op-maat-gemaakte-meter	Definieer de aangepaste meters die in uw abonnementen worden gedeeld.	https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3
prijs- en beschikbaarheidsaanbieding	Definieer een beperkt publiek dat uw product kan bekijken voordat u het live publiceert.	https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3
prijs- en beschikbaarheidsplan	Configureer de markten waarin dit plan beschikbaar is, het gewenste model voor inkomsten, prijzen en factureringsvoorwaarden.	https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4
update-prijs-en-beschikbaarheid-voor-privédoelgroepen	Updates voor privé-doelgroepen in de concept-, preview- en liveomgeving kunnen tegelijkertijd worden uitgevoerd zonder dat er een publicatie nodig is.	https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3
privé-en-beschikbaarheid-prive-aanbod-plan	Wordt gebruikt voor het configureren van de absolute prijsgegevens van een product-/abonnementsprijs die in een privéaanbieding wordt gebruikt	https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01
privéaanbieding	Definieert de naam en het type privéaanbieding, met de voorwaarden en details van de aanbieding, samen met de inbegrepen producten/abonnementen en hun prijzen	https://schema.mp.microsoft.com/schema/private-offer/2022-07-01
product	Dit is de belangrijkste resource, definieert de naam en het type van het product, alle resources verwijzen ernaar.	https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3
eigenschap	Definieer de categorieën en branches die van toepassing zijn op uw aanbieding, uw app-versie en juridische contracten.	https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5
Reseller	Configureer de partners in het CSP-programma (Cloud Solution Providers) waarvoor u uw product beschikbaar wilt maken.	https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2
resourcestructuur	Beschrijft een lijst met resources voor dat product in de huidige toestand voor de opgegeven doelomgeving.	https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2
technische configuratie voor software-als-een-dienst	Technische details die de commerciële marketplace van Microsoft helpen verbinding te maken met uw oplossing.	https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3
onderwerping	Kan worden gebruikt om verschillende acties op uw product te activeren en de publicatiestatus van uw productverschillende omgevingen (concept, preview en live) aan te geven.	https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2
virtual-machine-plan-technical-configuration	Technische details over de virtuele machine en de locatie van de afbeelding.	https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3
containerplan-technische-configuratie	Technische details over de eigenschappen van de containerafbeelding.	https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3

API-richtlijnen per producttype

De API voor productopname wordt in de toekomst beschikbaar gesteld aan andere producttypen. Naarmate er meer producttypen worden ondersteund, worden er meer richtlijnen beschikbaar gesteld die specifiek zijn voor elk producttype.

Producttype	Producttype-specifieke bronnen
Persoonlijke aanbiedingen	Privéaanbiedingen maken en beheren via productopname-API
SaaS	SaaS-aanbiedingen maken en beheren via productopname-API
Virtuele machines	Aanbiedingen voor virtuele machines maken en beheren via productopname-API
Containers	Containeraanbiedingen maken en beheren via productopname-API

API-versies en -updates

Bijwerken	Wat is er veranderd?
11-2023	Alle schema-eindpunten zijn bijgewerkt van product-ingestion.azureedge.net naar schema.mp.microsoft.com
12-2022	Er is nu een nieuwe schemaversie 2022-03-01-preview3 van de PC-opname-API beschikbaar voor klantleads, die clientID en clientSecret accepteren tijdens het configureren van klantleads en stopt met het registreren van de server-id en de contact e-mail-velden. Schakel over naar de nieuwe versie en geef de clientID en clientSecret op om de Marketo-connector te blijven configureren voor marketplace-aanbiedingen. Nieuwe schema-URL: https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3
09-2022	Ondersteuning voor containervoorbeelden wordt uitgebracht als versie 2022-03-01-preview4
08-2022	Ondersteuning voor Software as a Service Preview wordt uitgebracht als versie 2022-03-01-preview3
08-2022	Privéaanbieding openbare release als versie 2022-07-01
05-2022	Preview-ondersteuning voor virtuele machines wordt uitgebracht als versie 2022-03-01-preview2

Delen via

Productopname-API voor de commerciële marketplace

Aan de slag

Stap 1: Vereisten voltooien

Een Microsoft Entra-toepassing koppelen aan uw Partnercentrum-account

Stap 2: een Microsoft Entra-toegangstoken verkrijgen

Concepten

Middelen

Duurzame identificatie

Externe ID

API-methoden

Een typische werkstroom

Bestaande resourceconfiguraties ophalen

Methode 1: Hulpmiddelenboom

Methode 2: Duurzame ID

Methode 3: Queryparameters

Uw inzendingen opvragen

Nieuwe producten en middelen creëren

Bestaande producten en middelen wijzigen

Configuratieaanvragen

Resourceverwijzingen en afhankelijkheden

Verwijzingen

Afhankelijkheden

Inzendhulpbron

Publiceren voor voorbeeldweergave

Methode 1: Alle conceptbronnen publiceren

Methode 2: Specifieke conceptbronnen publiceren (ook wel modulair publiceren genoemd)

Publiceren naar de live-omgeving

De status van een aanvraag controleren

Status van een aanvraag in behandeling

Samenvatting van een voltooide aanvraag

Een configuratieaanvraag annuleren

Privé-doelgroepen synchroniseren

Leadbeheer configureren

Statussen van de levenscyclus van resources

Verwijderd

Afgeschaft

Algemeen beschikbaar

Naslaginformatie voor bron-API

API-richtlijnen per producttype

API-versies en -updates

Gerelateerde inhoud

Feedback

Aanvullende resources