Productopname-API voor de commerciële marketplace

Artikel
12/14/2023

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 workloadnaam 'product-opname'. 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 gaat gebruiken 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 van 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 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.

Resources

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 id

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 resources om ze op te halen of te wijzigen.

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 wordt omgezet in de 'offerID' en de externe id van een plan wordt omgezet in de 'planID', zoals gedefinieerd bij het maken onder 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.

Type API	Beschrijving	HTTP-methode en -pad
Query	Hiermee worden bestaande resources opgehaald door: -Methode 1: resourcestructuur-resourcetype -Methode 2: de durable-id -Methode 3: queryreeksparameters	-Methode 1: `GET resource-tree/<product-durableID>` -Methode 2: `GET <resource-durableID>` -Methode 3: `GET <resourceType>?<query parameters>`
Verzenden configureren	Hiermee worden aanvragen ingediend om een of meer resources 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: Verzenden configureren)
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.

Screenshot illustrating the typical calling pattern used to submit a configuration request.

Notitie

Zorg ervoor dat u aanvullende vereisten bekijkt die specifiek zijn voor het aanbiedingstype dat u beheert door te verwijzen naar de API-richtlijnen per sectie van het aanbiedingstype.

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, hieronder beschreven, om alle resources binnen een specifiek product op te halen in één API-aanroep.

Methode 1: Resourcestructuur

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

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

U kunt alle resourceconfiguraties binnen een specifiek product ophalen met behulp van het resourcetype resourcestructuur, 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 abonnementsversie bijvoorbeeld '2022-03-01-preview3' is, wordt deze versie weergegeven als u '2022-03-01-preview5' opgeeft in de GET-aanvraag van de resourcestructuur. Als u echter '2022-03-01-preview2' aanvraagt als de versie van de resourcestructuur, retourneert dit het plan '2022-03-01-preview2' met de resource, ook al is de nieuwste beschikbare versie '2022-03-01-preview3'. 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 functies.

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 deze uit te voerenGET product?externalID=<product-externalID>&$version=<product-schema-version>. Deze aanvraag maakt gebruik van een queryreeksparameter, die wordt beschreven in methode 3 hieronder. 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 met behulp van de duurzame id. Zodra een resource is gemaakt, blijft de duurzame id altijd hetzelfde en kan deze worden gebruikt om de meest recente conceptwijzigingen 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 'resource-tree', zoals hierboven beschreven.

Als u de duurzame id voor uw resources wilt vinden, kunt u het volgende doen:

Gebruik de methode 'resource-tree' om alle resources in 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.

Houd er rekening mee dat de eigenschap ID de durable-id is voor de betreffende resource.

Methode 3: Queryreeksparameters

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>`
Indiening	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 'resource-tree', retourneert deze querytekenreeksparameter alleen de details van die resource, niet 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 'targetType'-waarden 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.

Query's uitvoeren op uw inzendingen

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'-inzending naar 'Live' is gepusht, vervangt deze de vorige 'Live'-inzending. Wanneer dit gebeurt, vertegenwoordigen de gegevens nu zowel preview- als liveomgevingen totdat een nieuwe inzending wordt gepubliceerd naar 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 een voorbeeld te bekijken en vervolgens later live te gaan. Toen deze inzending werd gepusht naar live op 25 januari 2022, vertegenwoordigde het zowel preview als live totdat een nieuwe preview-inzending (submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683) werd gemaakt op 4 februari 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"
                }
              ]
            }

Nieuwe producten en resources maken

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 resources 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 de configuratiestatusdetails aan om de gemaakte productresource op te halen en de duurzame id te vinden om de query-API van de resourcestructuur 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 resources wijzigen

U kunt updates verzenden met behulp van de nettolading configureren. 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 deze bewerken en publiceren in dezelfde nettolading. Als u een configuratieaanvraag wilt indienen, gebruikt u de HTTP POST-methode van de configuratie-API. De geconfigureerde nettolading bestaat uit een matrix met 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. In het geval van producten en plannen kunt u ook naar deze resources 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 het onderstaande voorbeeld van de vermeldingsresource door deze in te stellen in de resourceschema-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 verwezen door andere volgende resources in de volgende indeling:

              {
                "$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 nettolading configureren gebruikt om een nieuw SaaS-product te maken met een externe id van 'ds-contoso-image-resize-demo'. Na het maken van dit product kunt u later naar dit product verwijzen met behulp van de duurzame 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 Status configureren om de status van uw aanvraag te controleren.

Afhankelijkheden

Bepaalde resources hebben afhankelijkheden van het maken van een andere resource als een vereiste. In dit geval gebruiken we de eigenschap resourceName binnen dezelfde nettolading om de afhankelijkheid van de productresource in de planresource aan te geven, omdat we beide in dezelfde aanvraag maken.

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

Inzendingsresource

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

De eigenschap 'product' die aangeeft dat het product wordt bijgewerkt, zoals wordt verwezen 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 naar voorbeeld

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 specifiek worden gesynchroniseerd met de privé-doelgroep , 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 onderstaande 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 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 live

Zodra uw wijzigingen in preview zijn getest en geverifieerd, kunt u uw wijzigingen live pushen door een configuratieaanvraag te verzenden met de 'id' van uw preview-inzending en het 'targetType' ingesteld op 'live'. Zie Query's uitvoeren op uw inzendingen om 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 configuratieaanvraagtaak is voltooid, of met een fout, kunt u de lijst met resources ophalen die zijn gemaakt of bijgewerkt met behulp van de 'jobID'.

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 vóór de annulering zijn voltooid.

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 onderstaande 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 resourcesmatrix die de productresource bevat die is gemaakt samen met de duurzame id.

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 met dezelfde privé-doelgroepwaarden. 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 normale publicatiestroom doorlopen om de waarden in preview en live 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

Verbinding maken 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 Leads van klanten ophalen voor meer informatie.

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 worden toegewezen aan 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'. Hieronder worden verschillende ondersteunde levenscyclusstatussen 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 onderstaande 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 marketplace 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 afschaffing. 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'.

Voorbeeldaanvraag van een productafschaffen:

In het onderstaande voorbeeld wordt de live indiening van het product ingesteld op afschaffing. 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 van een afschaffing van een plan:

In het onderstaande voorbeeld wordt een plan binnen een SaaS-product ingesteld op afschaffing. 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.

Voorbeeldaanvraag van een planherstel:

In het onderstaande 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 over resource-API

De onderstaande schemaversies zijn alleen van toepassing op preview en worden gewijzigd zodra de API algemeen beschikbaar is.

Notitie

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

Resourcetype	Beschrijving	Schema
azure-test-drive-technical-configuration	Technische details waarmee de commerciële Marketplace van Microsoft verbinding kan maken met uw test drive-oplossing.	https://schema.mp.microsoft.com/schema/azure-test-drive-technical-configuration/2022-03-01-preview3
commercial-marketplace-setup	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 commerciële marketplace van Microsoft.	https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5
listing-asset	Schermopnamen en uw marketingassets die zijn gekoppeld aan de vermeldingsresource.	https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5
listing-trailer	Videoassets die zijn gekoppeld aan de vermeldingsresource.	https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5
microsoft365-integratie	Microsoft 365-inschakeling en typeselectie.	https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2
Plan	Als u plannen wilt maken, waarnaar vervolgens wordt verwezen door de resources op planniveau die u configureert, zoals planlijst.	https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2
plan-listing	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-aangepaste 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 beschikbaarheidsabonnement	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
prijs-en-beschikbaarheid-update-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
private-and-availability-private-offer-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 het product een lijst met resources voor dat product in de huidige status voor de opgegeven doelomgeving.	https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2
software-as-a-service-technical-configuration	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
Indiening	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
Proefrit	Geef aan of u uw klanten het product gedurende een beperkte periode gratis wilt laten uitproberen.	https://schema.mp.microsoft.com/schema/test-drive/2022-03-01-preview2
test-drive-listing	Definieer de details over hoe klanten uw product kunnen uitproberen.	https://schema.mp.microsoft.com/schema/test-drive-listing/2022-03-01-preview3
virtual-machine-plan-technical-configuration	Technische details over de virtuele machine en de locatie van de installatiekopieën.	https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3
virtual-machine-test-drive-technical-configuration	Technische details waarmee de commerciële Marketplace van Microsoft verbinding kan maken met uw test drive-oplossing.	https://schema.mp.microsoft.com/schema/virtual-machine-test-drive-technical-configuration/2022-03-01-preview2
container-plan-technical-configuration	Technische informatie over de eigenschappen van de containerinstallatiekopieën.	https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3

API-richtlijnen per producttype

De Productopname-API wordt in de toekomst beschikbaar gemaakt voor andere producttypen. Naarmate er meer producttypen worden ondersteund, worden er meer richtlijnen beschikbaar gesteld voor elk producttype.

Producttype	Producttypespecifieke resources
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 potentiële klanten die clientID en clientSecret accepteren tijdens het configureren van klantleiders en stopt met het vastleggen van de server-id en e-mailvelden. 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	Openbare release van persoonlijke aanbieding 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

Resources

Duurzame id

Externe id

API-methoden

Een typische werkstroom

Bestaande resourceconfiguraties ophalen

Methode 1: Resourcestructuur

Methode 2: Duurzame id

Methode 3: Queryreeksparameters

Query's uitvoeren op uw inzendingen

Nieuwe producten en resources maken

Bestaande producten en resources wijzigen

Configuratieaanvragen

Resourceverwijzingen en afhankelijkheden

Verwijzingen

Afhankelijkheden

Inzendingsresource

Publiceren naar voorbeeld

Methode 1: Alle conceptbronnen publiceren

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

Publiceren naar live

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 over resource-API

API-richtlijnen per producttype

API-versies en -updates

Volgende stappen

Feedback

Feedback

Aanvullende resources