Produkterfassungs-API für den kommerziellen Marketplace

Artikel
06/14/2024

Die Produktaufnahme-API ist eine modernisierte API, die alle vorhandenen Übermittlungs-APIs für alle kommerziellen Marketplace-Produkte vereint. Mit der API können Sie Ressourcen erstellen, veröffentlichen und verwalten, die Mit Produkten und Plänen in Ihrem Partner Center-Konto verknüpft sind. Die API verwendet ein deklaratives Muster zum Übermitteln von Anforderungen, bei dem der gewünschte Zustand angegeben wird, anstatt die einzelnen Schritte zum Erreichen des gewünschten Zustands zu spezifizieren.

Dieser Artikel enthält Anleitungen für die ersten Schritte mit den APIs für jeden kommerziellen Marketplace-Angebotstyp. Die Produktaufnahme-API wird derzeit für SaaS-, VMs-, Private Angebote- und Containerangebotstypen unterstützt und befindet sich in der Vorschau. Informationen zu einer Anleitung speziell für Ihr Angebot finden Sie unter API-Leitfaden nach Angebotstyp.

Wichtig

Azure Active Directory (Azure AD) Graph ist ab dem 30. Juni 2023 veraltet. In Zukunft investieren wir nicht mehr in Azure AD Graph. Azure AD Graph-APIs haben keine SLA- oder Wartungsverpflichtungen, die über sicherheitsbezogene Fixes hinausgehen. Investitionen in neue Features und Funktionalitäten werden nur für Microsoft Graph vorgenommen.

Azure AD Graph wird inkrementellen Schritten eingestellt, sodass Sie genügend Zeit haben, um Ihre Anwendungen zu Microsoft Graph-APIs zu migrieren. Zu einem späteren Zeitpunkt, an dem wir ihnen mitteilen werden, werden wir die Erstellung neuer Anwendungen mit Azure AD Graph blockieren.

Weitere Informationen finden Sie unter "Wichtig": Veraltetes Azure AD Graph- und Powershell-Modul.To learn more, see Important: Azure AD Graph Retirement and Powershell Module Deprecation.

Erste Schritte

Auf die Produktaufnahme-API kann mithilfe der MSGraph-API unter dem Workloadnamen "product-ingestion" zugegriffen werden. Die Basis-URL lautet https://graph.microsoft.com/rp/product-ingestion.

Um die Produktaufnahme-API zu verwenden, müssen Sie zuerst Folgendes abrufen:

Eine Microsoft Entra-ID und sicherstellen, dass Sie über globale Administratorberechtigungen für das Verzeichnis verfügen
Eine Microsoft Entra-Anwendung
Ein Microsoft Entra-Zugriffstoken

Schritt 1: Abschließen der Voraussetzungen

Bevor Sie mit dem Schreiben von Code zum Aufrufen der Produkteingestion-API beginnen, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllt haben.

Sie (oder Ihre Organisation) müssen über ein Microsoft Entra-Verzeichnis verfügen und über globale Administratorberechtigungen für das Verzeichnis verfügen. Wenn Sie Microsoft 365 oder andere Geschäftsdienste bereits von Microsoft verwenden, verfügen Sie bereits über das Microsoft Entra-Verzeichnis. Andernfalls können Sie eine neue Microsoft Entra-ID im Partner Center ohne zusätzliche Kosten erstellen.
Sie müssen ihrer Partner Center-Konto eine Microsoft Entra-Anwendung zuordnen und Ihre Mandanten-ID, Client-ID und Ihren Schlüssel abrufen. Sie benötigen diese, um das Microsoft Entra-Zugriffstoken abzurufen, das Sie in Aufrufen der Microsoft Store-Übermittlungs-API verwenden.

Zuordnen einer Microsoft Entra-Anwendung zu Ihrem Partner Center-Konto

Um die Produktaufnahme-API zu verwenden, müssen Sie Ihrem Partner Center-Konto eine Microsoft Entra-Anwendung zuordnen, die Mandanten-ID und die Client-ID für die Anwendung abrufen und einen Schlüssel generieren. Die Microsoft Entra-Anwendung stellt die App oder den Dienst dar, aus der Sie die Produktaufnahme-API aufrufen möchten. Sie benötigen die Mandanten-ID, Die Client-ID und den Schlüssel, um ein Microsoft Entra-Zugriffstoken abzurufen, das an die API übergeben wird.

Hinweis

Sie müssen diese Aufgabe nur einmal ausführen. Nachdem Sie über die Mandanten-ID, die Client-ID und den Schlüssel verfügen, können Sie diese jederzeit wiederverwenden, wenn Sie ein neues Microsoft Entra-Zugriffstoken erstellen müssen.

Ordnen Sie im Partner Center das Partner Center-Konto Ihrer Organisation dem Microsoft Entra-Verzeichnis Ihrer Organisation zu .
Fügen Sie auf der Seite "Benutzer " im Abschnitt "Kontoeinstellungen " des Partner Center die Microsoft Entra-Anwendung hinzu, die die App oder den Dienst darstellt, die Sie für den Zugriff auf Übermittlungen für Ihr Partner Center-Konto verwenden. Stellen Sie sicher, dass Sie dieser Anwendung die Rolle Verwalter zuweisen. Wenn die Anwendung noch nicht in Ihrem Microsoft Entra-Verzeichnis vorhanden ist, erstellen Sie eine neue Microsoft Entra-Anwendung im Partner Center. Partner Center erstellt zwei Arten von Einträgen für die Anwendung als Dienstprinzipal und den anderen als Microsoft Entra-Anwendungstyp.
Kehren Sie zur Seite "Benutzer" zurück, wählen Sie den Namen Ihrer Microsoft Entra-Anwendung aus, um zu den Anwendungseinstellungen zu wechseln, und kopieren Sie die Werte für Mandanten-ID und Client-ID.
Klicken Sie dann auf Neuen Schlüssel hinzufügen. Notieren Sie auf dem folgenden Bildschirm den Wert von Schlüssel. Nachdem Sie diese Seite verlassen haben, können Sie nicht mehr auf diese Informationen zugreifen. Weitere Informationen finden Sie unter Verwalten von Schlüsseln für eine Microsoft Entra-Anwendung.

Schritt 2: Abrufen eines Microsoft Entra-Zugriffstokens

Um eine der Methoden in der Produkteingestion-API aufzurufen, müssen Sie zuerst ein Microsoft Entra-Zugriffstoken abrufen, um den Autorisierungsheader jeder Methode in der API zu übergeben. Ein Zugriffstoken läuft 60 Minuten nach der Ausstellung ab. Danach können Sie es aktualisieren, damit Sie es in zukünftigen Aufrufen der API verwenden können.

Um das Zugriffstoken zu erhalten, befolgen Sie die Anweisungen in Verwenden von Clientanmeldeinformationen für Dienst-zu-Dienst-Aufrufe, um eine HTTP POST-Anweisung an den Endpunkt https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token zu senden. Hier ist eine Beispielanforderung:

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

Für den Wert Mandant_id im POST-URI und die Parameter Client_id und Client_secret geben Sie die ID des Mandanten, die ID des Clients und den Schlüssel für Ihre Anwendung an, den Sie im vorherigen Abschnitt vom Partner Center erhalten haben. Für den Bereichsparameter müssen Sie https://graph.microsoft.com/.default angeben.

Konzepte

Bevor Sie beginnen, müssen Sie einige grundlegende Konzepte verstehen.

Ressourcen

Die API ist um Ressourcentypen herum strukturiert, wobei jeder Typ mithilfe einer dedizierten Schemadefinition beschrieben wird, auf die durch die Eigenschaft "$schema" verwiesen wird. Das Schema besteht aus den Konfigurationseigenschaften dieser Ressource. Ressourcen spielen eine wichtige Rolle beim Erstellen und Aktualisieren der Konfiguration verschiedener Aspekte eines bestimmten Produkts. Eine vollständige Liste der Ressourcentypen und der zugehörigen Schemas finden Sie in der Ressourcen-API-Referenz.

Dauerhafte ID

Eine dauerhafte ID ist ein vom System generierter globaler Bezeichner, der verwendet wird, um jede Ressource eindeutig zu identifizieren. Jede Ressource verfügt über eine zugeordnete "ID"-Eigenschaft, die in Kombination mit dem Ressourcentypnamen die dauerhafte ID einer Ressource bildet. Die dauerhafte ID wird beim Verweisen auf Ressourcen verwendet, um diese entweder abzurufen oder zu ändern.

Format:

\<resource-type>/\<id>

Beispiel:

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

Eine externe ID ist ein weiterer eindeutiger Bezeichner, mit dem auf bestimmte Produkte oder Pläne verwiesen werden kann. Die externe ID kann alternativ zur dauerhaften ID zum Referenzieren dieser Ressourcen verwendet werden. Die externe ID eines Produkts wird in seine "offerID" übersetzt, und die externe ID eines Plans wird in seine "planID" übersetzt, wie bei der Erstellung unter der "Identity"-Eigenschaft definiert.

Beispiel:

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

Es gibt vier Verwaltungs-APIs, mit denen Sie verschiedene Aktionen ausführen können, z. B. die Abfrage vorhandener Ressourcen, die Aktualisierung der Konfiguration und die Überprüfung des Status einer Anforderung.

Hinweis

Alle Anforderungen erfordern, dass Sie die schemaversion ($version Abfrageparameter) festlegen, die Sie als Teil der Antwort wünschen.

API-Typ	Beschreibung	HTTP-Methode und Pfad
Abfrage	Ruft vorhandene Ressourcen ab über: -Methode 1: Ressourcentyp "resource-tree" -Methode 2: die dauerhafte ID -Methode 3: Abfragezeichenfolgenparameter	-Methode 1: `GET resource-tree/<product-durableID>` -Methode 2: `GET <resource-durableID>` -Methode 3: `GET <resourceType>?<query parameters>`
Konfigurieren der Übermittlung	Sendet Anforderungen zum Erstellen oder Aktualisieren einer oder mehrerer Ressourcen. Bei erfolgreicher Verarbeitung wird eine Auftrags-ID zurückgegeben, die zum Abrufen des Status der Anforderung verwendet werden kann. Dieser API-Typ kann verwendet werden, um den Entwurfsstatus zu aktualisieren und Änderungen zu veröffentlichen, private Zielgruppen zu synchronisieren und den Ressourcenlebenszyklusstatus zu ändern.	`POST configure`
Konfigurieren des Status	Ruft den Status einer ausstehenden Anforderung über die jobID ab.	`GET configure/<jobID>/status`
Konfigurieren von Statusdetails	Ruft eine detaillierte Zusammenfassung einer abgeschlossenen Anforderung, einschließlich der aktualisierten Ressourcen, über die jobID ab.	`GET configure/<jobID>`
Konfigurieren abbrechen	Bricht den angegebenen Konfigurationsauftrag ab.	`POST configure/<jobID>/cancel`

Typischer Workflow

Ein typischer Workflow zum Aktualisieren einer vorhandenen Ressource sieht folgendermaßen aus:

Abrufen einer vorhandenen Ressourcenkonfiguration (API-Typ: Abfrage über Ressourcenstruktur)*
Nehmen Sie alle erforderlichen Updates vor, und übermitteln Sie dann eine Konfigurationsanforderung (API-Typ: Submit konfigurieren)
Überprüfen sie den Status der Anforderung (API-Typ: Status konfigurieren und Statusdetails konfigurieren)

* Derselbe Workflow kann auch beim Erstellen neuer Ressourcen angewendet werden. Anstatt jedoch Ressourcen abzurufen (Schritt 1), verwenden Sie die Tabelle Ressourcen-API-Referenz, um sicherzustellen, dass Sie das aktuelle Schema für den zu erstellenden Ressourcentyp verwenden.

Diese Abbildung zeigt das typische Aufrufmuster, das zum Senden einer Konfigurationsanforderung verwendet wird, unabhängig davon, ob Sie eine neue Ressource erstellen oder ändern.

Screenshot, der das typische Anrufmuster veranschaulicht, das zum Senden einer Konfigurationsanforderung verwendet wird.

Hinweis

Überprüfen Sie unbedingt alle zusätzlichen Voraussetzungen, die für den von Ihnen verwalteten Angebotstyp gelten, indem Sie auf den API-Leitfaden pro Angebotstypabschnitt verweisen.

Abrufen vorhandener Ressourcenkonfigurationen

Bevor Sie vorhandene Ressourcen aktualisieren, müssen Sie sie zuerst abrufen, um sicherzustellen, dass Sie über die neueste Konfiguration verfügen. Es gibt mehrere Möglichkeiten, Ressourcen über einen GET-Aufruf abzurufen. Sehen Sie sich die nachfolgend beschriebene Methode 1 an, um alle Ressourcen innerhalb eines bestimmten Produkts mit einem einzigen API-Aufruf abzurufen.

Methode 1: Ressourcenstruktur

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

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

Sie können alle Ressourcenkonfigurationen innerhalb eines bestimmten Produkts abrufen, indem Sie den Ressourcentyp "resource-tree" zusammen mit der dauerhaften ID des Produkts verwenden.

Die neueste verfügbare Schemaversion kann für jede Ressource unterschiedlich sein. Beim Ausführen einer Ressourcenstrukturanforderung bestimmt die angegebene Schemaversion, welche Version für jede Ressource im Produkt zurückgegeben wird. Die angegebene Version dient als "max"-Versionsbeschränkung, da sie die neueste Schemaversion zurückgibt, die für alle Ressourcen mit gleicher oder niedrigerer Version verfügbar ist. Wenn beispielsweise die neueste Verfügbare Planauflistungsversion "2022-03-01-preview3" lautet, wird diese Version von der Antwort angezeigt, wenn Sie "2022-03-01-preview5" in der GET-Anforderung der Ressourcenstruktur angeben würden. Wenn Sie jedoch "2022-03-01-preview2" als Ressourcenstrukturversion anfordern, gibt dies die Planauflistungsressource "2022-03-01-preview2" zurück, obwohl die neueste verfügbare Version "2022-03-01-preview3" lautet. Es wird empfohlen, die neueste verfügbare Version jeder Ressource zu verwenden, um sicherzustellen, dass Sie ein aktualisiertes Schema mit neu unterstützten Features verwenden.

Hinweis

Wenn Sie die dauerhafte ID des Produkts nicht kennen, können Sie die externe ID des Produkts verwenden, um die Produktressource abzurufen, indem Sie ausführenGET product?externalID=<product-externalID>&$version=<product-schema-version>. Diese Anforderung nutzt einen Abfragezeichenfolgenparameter, der in Methode 3 weiter unten beschrieben wird. Die Antwort enthält die dauerhafte ID des Produkts, die Sie für zukünftige Anforderungen verwenden können.

Wenn Sie einen GET-Aufruf mit der "Ressourcenstruktur" ausführen, erhalten Sie standardmäßig die Entwurfsversion Ihrer Ressourcen. Durch Übergeben des Abfrageparameters "targetType" können Sie jedoch das gewünschte Ziel angeben, um die "Vorschau" oder "Live"-Daten abzurufen. Im folgenden Beispiel gibt der GET-Aufruf die Konfiguration der Vorschauumgebung für alle Ressourcen unter dem Produkt "12345678-abcd-efgh-1234-12345678901" zurück.

Get-Beispielanruf:

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

Beispielantwort:

        {
          "$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: Dauerhafte ID

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

Rufen Sie eine bestimmte Ressource mithilfe ihrer dauerhaften ID ab. Sobald eine Ressource erstellt wurde, bleibt die dauerhafte ID immer gleich und kann verwendet werden, um die neuesten Entwurfsänderungen dieser Ressource durch Aufrufen der GET-Methode abzurufen. Die folgende Anforderung gibt beispielsweise die Entwurfskonfiguration dieses bestimmten Produkts mithilfe der Schemaversion "2022-03-01-preview3" zurück.

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

Wichtig

Diese Methode wird nur zum Abrufen der Entwurfskonfiguration verwendet. Wenn Sie Vorschau- oder Livedaten abrufen möchten, verwenden Sie die Methode "resource-tree", wie oben beschrieben.

Um die dauerhafte ID für Ihre Ressourcen zu finden, können Sie eine der folgenden Aktionen ausführen:

Verwenden Sie die Methode "resource-tree" , um alle Ressourcen innerhalb des Produkts zusammen mit den jeweiligen dauerhaften IDs abzurufen, oder
Rufen Sie die Details einer abgeschlossenen Ressourcenkonfigurationsanforderung ab, die die dauerhaften IDs für alle Ressourcen enthält, die als Teil der Anforderung erstellt oder aktualisiert wurden.

Denken Sie daran, dass die "ID"-Eigenschaft die dauerhafte ID für die jeweilige Ressource ist.

Methode 3: Abfragezeichenfolgenparameter

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

Bei dieser Methode werden bestimmte Ressourcentypen abgefragt, die einem spezifischen Konto zugeordnet sind. Sie können beispielsweise alle Ihre Produkte eines bestimmten Produkttyps mit einem einzigen GET-Aufruf abrufen. Abfragezeichenfolgenparameter werden verwendet, um Details zu Ihren Produkten, Plänen oder Übermittlungen abzufragen.

Diese Tabelle zeigt die unterstützten Abfrageparameter für jeden der unterstützten Ressourcentypen. Nicht alle Ressourcentypen unterstützen jeden der Abfrageparameter. In dieser Tabelle finden Sie die vollständige Liste der derzeit unterstützten Abfragezeichenfolgen.

Ressourcentyp	Parameter	Beispiele für Abfragezeichenfolgen
Plan	Produkt`` 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 Typ $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>`
Unterwerfung	targetType $maxpagesize continuationToken$version`*`	`GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>` `GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version>`
Ressourcenstruktur	targetType$version`*`	`GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version>`

* Das Produkt und $version Parameter sind immer erforderlich.

Funktionsweise der einzelnen unterstützten Abfrageparameter:

product – Wenn der Parameter "product" im Kontext des Ressourcentyps "plan" übergeben wird, werden alle Pläne innerhalb dieses bestimmten Produkts zurückgegeben.
externalID – Wenn der Parameter "externalID" im Kontext eines Produkts oder Plans übergeben wird, wird die Konfiguration dieses jeweiligen Produkts oder Plans zurückgegeben. Im Gegensatz zur Methode "resource-tree" gibt dieser Abfragezeichenfolgenparameter nur die Details dieser Ressource zurück, nicht alle Ressourcen darin.
type – Wenn der Parameter "type" im Kontext des Ressourcentyps "product" übergeben wird, werden alle Produkte dieses Typs zurückgegeben, die Ihrem Konto zugeordnet sind. Wenn Sie beispielsweise "type=softwareAsAService" angeben, werden alle Ihre SaaS-Produkte zurückgegeben.
targetType – Gibt die Daten einer bestimmten Umgebung im Kontext des verwendeten Ressourcentyps zurück. Die unterstützten "targetType"-Werte sind "draft", "preview" oder "live".
$maxpagesize: Mit diesem Parameter können Sie die maximale Seitengröße in Form einer positiven ganzen Zahl angeben, um bei der Abfrage Ihrer früheren Übermittlungen die Suchergebnisse einzuschränken.
continuationToken – Dieser Parameter kann mit dem Parameter "$maxpagesize" verwendet werden, um eine andere Gruppe von Ergebnissen abzufragen, die in Ihrer Suche verfügbar sind. Der Wert "continuationToken" wird in der Antwort der vorherigen Seite bereitgestellt.
$version – Dies ist ein erforderlicher Parameter für alle Aufrufe, es gibt an, welche Schemaversion für die Antwort von der von Ihnen vorgenommenen Anforderung verwendet werden soll. Die neueste verfügbare Schemaversion kann für jede Ressource unterschiedlich sein, und die angegebene Version dient als "max"-Versionslimit. Das System gibt entweder die genaue Schemaversion zurück, falls verfügbar oder die nächstgelegene Version, die älter als die angeforderte Version ist. Dies kann dazu beitragen, dass Ihr Code funktioniert, auch wenn neuere Schemaänderungen vorhanden sind, aber um die neuesten Features zu nutzen, empfiehlt es sich, die neueste verfügbare Version jedes Schemas zu verwenden.

Abfragen Ihrer Übermittlungen

Sie können Ihre vorhandenen Produktübermittlungen mithilfe von GET submission/<product-durableID> abrufen. Standardmäßig erhalten Sie alle aktiven Übermittlungen einschließlich des Entwurfsverweises zurück, sie können aber auch eine bestimmte Umgebung mithilfe des Abfrageparameters "targetType" abfragen: (GET submission/<product-durableID>?targetType=<environment>&$version=<version>).

Wichtig

Sobald eine Preview-Übermittlung an die Live-Umgebung gepusht wird, ersetzt sie die vorherige Live-Übermittlung. In diesem Fall stellen die Daten jetzt sowohl "Vorschau"- als auch "Live"-Umgebungen dar, bis eine neue Übermittlung in "Vorschau" veröffentlicht wird.

Beispiel für eine Anforderung:

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

Beispielantwort:

Dieses Beispiel zeigt eine GET-Anforderung für die aktiven Übermittlungen, die der Produkt-ID "12345678-abcd-efgh-1234-12345678901" zugeordnet sind. Die aktive "Live"-Übermittlung (Einreichung/12345678-abcd-efgh-1234-12345678901/1152921515689847470) wurde zuerst in der Vorschau und später zu Live veröffentlicht. Als diese Übermittlung am 25. Januar 2022 live übertragen wurde, wurde sie sowohl vorschau als auch live dargestellt, bis eine neue Vorschau-Übermittlung (Übermittlung/12345678-abcd-efgh-1234-12345678901/1152921515689848683) am 4. Februar 2022 erstellt wurde.

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

Erstellen neuer Produkte und Ressourcen

Sie können neue Ressourcen, einschließlich neuer Produkte, im Rahmen einer einzigen Konfigurationsanforderung erstellen. Mithilfe der Tabelle Ressourcen-API-Referenz können Sie das Schema für den zu erstellenden Ressourcentyp abrufen. So wird sichergestellt, dass Sie das neueste Schema verwenden und somit alle erforderlichen Eigenschaften zum Erstellen der Ressource konfigurieren.

Wenn Sie ein neues Produkt erstellen, variieren die Anforderungen je nach Produkttyp. Daher müssen Sie verschiedene Ressourcen bereitstellen. Sie können auf die entsprechende Kommerzielle Marketplace-Dokumentation für den jeweiligen Produkttyp verweisen, um sicherzustellen, dass Sie die grundlegenden Anforderungen in Ihrer Anforderung konfigurieren. Alternativ können Sie eine Konfigurationsanforderung nur mithilfe der Produktressource vornehmen. Rufen Sie nach dem Erstellen des Produkts die API zum Konfigurieren der Statusdetails auf, um die erstellte Produktressource abzurufen, und suchen Sie die dauerhafte ID, um die Api für die Ressourcenstrukturabfrage aufzurufen. Die Antwort gibt die anwendbaren unterstützten Ressourcen für den von Ihnen erstellten Produkttyp zurück.

Ebenso müssen Sie zum Erstellen einer neuen Ressource innerhalb eines vorhandenen Produkts auch das neueste Schema dieses bestimmten Ressourcentyps abrufen. Stellen Sie sicher, dass Sie die abhängigen Ressourcen als Bestandteil der Konfigurationsanforderung bereitstellen, indem Sie die Ressourcenabhängigkeiten überprüfen.

Nachdem Sie Ihre Ressourcen mithilfe der Schemas erstellt haben, erfahren Sie, wie Sie eine Konfigurationsanforderung erstellen.

Ändern vorhandener Produkte und Ressourcen

Sie können Aktualisierungen mithilfe der Nutzdaten für die Konfiguration übermitteln. Diese Nutzlast besteht aus einem oder mehreren Ressourcentypen, und die Eigenschaft "$schema" gibt den Ressourcentyp an, auf den verwiesen wird.

Tipp

Wir empfehlen Ihnen, vor der Veröffentlichung von Aktualisierungen zunächst vorhandene Ressourcen abzurufen, um sicherzustellen, dass Sie die neueste Konfiguration verwenden.

Nachdem Sie Ihre Ressourcen geändert haben, erfahren Sie, wie Sie eine Konfigurationsanforderung erstellen.

Konfigurationsanforderungen

Sie können innerhalb derselben Nutzdaten Bearbeitungen und Veröffentlichungen durchführen. Um eine Konfigurationsanforderung zu übermitteln, verwenden Sie die HTTP POST-Methode der Konfigurations-API. Die Nutzdaten für die Konfiguration bestehen aus einem Array von Ressourcen, die die gewünschten Änderungen angeben. Alle Bearbeitungen wirken sich nur auf die Entwurfsversion aus, bis Sie eine Übermittlungsressource explizit übermitteln, um Ihre Entwurfsänderungen zu veröffentlichen. Schließen Sie beim Veröffentlichen in der Vorschau oder live die Übermittlungsressource ein, und geben Sie die Zielumgebung an. Bevor Sie eine Anforderung übermitteln, müssen Sie wissen, wie Sie auf Ressourcen verweisen und deren Abhängigkeiten verstehen.

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

Wenn Sie Ihre Konfigurationsanforderung übermitteln, erhalten Sie ein Configure-Status-Objekt mit der JobID, die Sie verwenden können, um den Fortschritt und die Ergebnisse Ihrer Anforderung nachzuverfolgen.

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

Ressourcenverweise und Abhängigkeiten

References

Um auf eine vorhandene Ressource in einer Konfigurationsanforderung zu verweisen, geben Sie den Typ "$schema" der Ressource zusammen mit der dauerhaften ID der Ressource an. Im Falle von Produkten und Plänen können Sie diese Ressourcen auch über die externe ID referenzieren.

Die dauerhafte ID befindet sich in der Eigenschaft "ID", z. B. wenn es sich um die Produktressource handelt, auf die in einer anderen Ressource verwiesen werden soll:

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

Die dauerhafte ID wäre "product/071b135e-9faf-4ff7-b113-a3f25bb0f468".

Die dauerhafte ID kann dann im unten aufgeführten Ressourcenbeispiel verwendet werden, indem sie in der Ressourcenschemaeigenschaft "product" wie folgt festgelegt wird:

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

Die externe ID von Produkt- und Planressourcen wird innerhalb der Eigenschaft "Identity" definiert.

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

Die externe Plan-ID "gold-annual" kann dann von anderen nachfolgenden Ressourcen im folgenden Format referenziert werden:

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

Beispiel für eine Anforderung:

In diesem Beispiel wird die Konfigurationsnutzlast verwendet, um ein neues SaaS-Produkt mit einer externen ID von "ds-contoso-image-resize-demo" zu erstellen. Bei der Erstellung dieses Produkts können Sie später mithilfe ihrer dauerhaften ID oder externen ID auf dieses Produkt verweisen.

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

Beispielantwort:

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

Anschließend können Sie die JobID über die Configure Status API verwenden, um den Status Ihrer Anforderung zu überprüfen.

Abhängigkeiten

Bestimmte Ressourcen sind von der Erstellung einer anderen Ressource abhängig. In diesem Fall verwenden wir die Eigenschaft "resourceName" innerhalb derselben Nutzlast, um die Abhängigkeit der Produktressource in der Planressource zu kennzeichnen, während wir beide in derselben Anforderung erstellen.

Der "resourceName" wird nur verwendet, um jede Ressource als Teil der konfigurierten Anforderung zu identifizieren, die Sie ausführen. Der Wert ist nicht Teil der Daten der Ressourcen, nicht gespeichert oder für Kunden verfügbar gemacht. Wenn im Rahmen der Configure-Anforderung Fehler auftreten, wird der "resourceName" verwendet, um die Ressource aufzurufen, zu der der Fehler gehört.

Beispiel für eine Anforderung:

In diesem Beispiel muss das Produkt vor dem Plan erstellt werden und daher wird die Eigenschaft "resourceName" verwendet. Das produkt, das erstellt wird, "myNewProduct", ist der Wert, der für "resourceName" verwendet wird und innerhalb der abhängigen Planressource referenziert wird.

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

Submission-Ressource

Wenn sie in "Vorschau" oder "live" veröffentlicht werden, fügen Sie die Übermittlungsressource in Ihre Anforderung ein, die Folgendes enthält:

Die Eigenschaft "product", die angibt, dass das Produkt durch seine dauerhafte ID oder externe ID aktualisiert wird.
Die Eigenschaft "targetType", die die Zielumgebung angibt

Wenn Sie die Veröffentlichung speziell in Live ausführen, wird die "ID" der Vorschauübermittlung angezeigt, die Sie veröffentlichen möchten:

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

Hinweis

Wenn Sie die Übermittlungsressource nicht einschließen, werden die Änderungen nur am Entwurfszustand vorgenommen.

Veröffentlichung in der Vorschauumgebung

Kommerzielle Produkttypen unterstützen eine Vorschauumgebung, und jede Aktualisierung muss zuerst in der Vorschau veröffentlicht werden, bevor sie live geschaltet wird. Eine direkte Liveveröffentlichung ist nicht möglich.

Wichtig

Die einzige Ausnahme bilden Änderungen, die Sie an der privaten Zielgruppe Ihrer Pläne vornehmen. Bei der Synchronisierung von Updates mit der privaten Zielgruppe werden diese Änderungen gleichzeitig sowohl in der Vorschau als auch in live übertragen.

Es gibt zwei Möglichkeiten zum Veröffentlichen Ihrer Ressourcen in der Vorschauumgebung. Wenn Änderungen an der Vorschau vorgenommen werden müssen, führen Sie eine weitere GET-Anforderung aus, nehmen Sie die erforderlichen Änderungen vor, und pushen Sie die Änderungen erneut. Sie müssen nicht zuerst mit Ihren anfänglichen Änderungen live gehen.

Methode 1: Veröffentlichen aller Entwurfsressourcen

Wenn Sie alle von Ihnen vorgenommenen Entwurfsänderungen veröffentlichen möchten, können Sie eine Konfigurationsanforderung mit einer Übermittlungsressource senden, die die Vorschauumgebung als "targetType" festlegt. Wie im folgenden Beispiel gezeigt, müssen Sie nicht explizit jede Ressource bereitstellen, die eine Aktualisierung erfordert, da diese Methode alle Änderungen an der Zielumgebung veröffentlicht, was in diesem Fall eine Vorschau ist. Sie müssen lediglich den API-Endpunkt „configure“ und die Übermittlungsressource angeben.

Beispiel für eine Anforderung:

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: Veröffentlichen bestimmter Entwurfsressourcen (auch als modularer Veröffentlichen bezeichnet)

Wenn Sie nicht alle Entwurfsänderungen an den verschiedenen Ressourcen veröffentlichen möchten, können Sie alternativ nur die zu veröffentlichenden Ressourcen gemeinsam mit der Übermittlungsressource angeben, um eine modulare Veröffentlichung auszulösen. Sie können diesen Ansatz auch nutzen, um Änderungen an Ressourcen vorzunehmen und diese gleichzeitig zu veröffentlichen, anstatt sie im Rahmen einer Massenaktualisierung zu veröffentlichen, wie dies bei Methode 1 der Fall ist. Bei einer modularen Veröffentlichung sind alle Ressourcen mit Ausnahme der Produktebenendetails (z. B. Eintrag, Verfügbarkeit, Pakete, Händler) für Ihren Produkttyp erforderlich.

Beispiel für eine Anforderung:

In diesem Beispiel werden die Ressourcen im Produkt explizit als Teil der modularen Veröffentlichung angegeben, gefolgt von der Übermittlungsressource.

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

Veröffentlichung in der Liveumgebung

Nachdem Ihre Änderungen in der Vorschau getestet und überprüft wurden, können Sie Ihre Änderungen per Push an live senden, indem Sie eine Konfigurationsanfrage mit der "ID" Ihrer Vorschauübermittlung und dem auf "live" festgelegten "targetType" senden. Informationen zum Suchen der "ID" Ihrer Vorschauübermittlung, die in Ihre Konfigurationsanforderung integriert werden soll, finden Sie unter Abfragen Ihrer Übermittlungen.

Wichtig

Anders als bei der Veröffentlichung in der Vorschau ist bei einer Veröffentlichung in der Liveumgebung keine modulare Veröffentlichung möglich. Daher ist es wichtig, sicherzustellen, dass Sie Ihre Vorschauübermittlung überprüft haben, bevor Sie mit Ihren Änderungen live gehen.

Beispiel für eine Anforderung:

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

Überprüfen des Status einer Anforderung

Unabhängig von den Ressourcen, die in Ihrer Konfigurationsanforderung enthalten sind oder die änderungen, die Sie vornehmen, erhalten Sie kurz nach dem Erfolgreichen Verarbeiten einer Anforderung ein Configure-Status-Objekt zurück in der Antwort. Die "jobID" ist wichtig, da sie später verwendet werden kann, um den Status der Anforderung zu überprüfen.

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

Beispielantwort auf eine übermittelte Anforderung:

            {
                "$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 einer ausstehenden Anforderung

Sie können den Status abrufen, bis der Auftrag abgeschlossen ist, indem Sie den folgenden Aufruf verwenden und die "jobID" der Anforderung eingeben. Das Objekt kann auch eine Liste von Fehlern enthalten, wenn Probleme mit Ihrer Anforderung aufgetreten sind.

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

Denken Sie daran, dass die Dauer der Fertigstellung je nach Komplexität Ihrer Anforderung variieren kann,

Zusammenfassung einer abgeschlossenen Anforderung

Nachdem ein Anforderungsauftrag konfiguriert wurde, entweder erfolgreich oder mit einem Fehler, können Sie die Liste der mithilfe der "jobID" erstellten oder aktualisierten Ressourcen abrufen.

Hinweis

Wenn Sie diesen Aufruf senden, bevor der Auftrag abgeschlossen ist, kommt es zu einem Fehler. Darüber hinaus werden nur die Ressourcen zurückgegeben, die erfolgreich abgeschlossen wurden, oder im Falle einer Kündigung nur die, die vor der Kündigung abgeschlossen wurden.

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

Beispiel für eine Anforderung:

Im folgenden Beispiel wird eine GET-Anforderung verwendet, um die Zusammenfassungsdetails der konfigurationsanforderung abzurufen, die im vorherigen Beispiel verwendet wurde, das ein neues SaaS-Produkt erstellt hat. Die Antwort ist das Configure-Detail-Objekt mit dem Ressourcenarray, das die Produktressource enthält, die zusammen mit seiner dauerhaften ID erstellt wurde.

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

Beispielantwort:

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

Abbrechen einer Konfigurationsanforderung

Bevor ein Auftrag abgeschlossen ist, können Sie versuchen, ihn bei Bedarf abzubrechen. Für lange ausgeführte Anforderungen, z. B. für die Veröffentlichung in "Vorschau" oder "live", wird die Abbruchanforderung möglicherweise abgelehnt, wenn der Auftrag weit genug ist, um vollständig verarbeitet zu werden.

Um einen Auftrag abzubrechen, tätigen Sie einen POST-Aufruf an den Abbruchendpunkt, und geben Sie die Auftrags-ID der Anforderung an, die Sie abbrechen möchten.

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

Beispiel für eine Anforderung:

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

Beispielantwort einer erfolgreichen Abbruchanforderung:

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

Beispielantwort im Fall einer Abbruchmeldung ist nicht zulässig: HTTP Status code: 400

Inhalt:

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

Wichtig

Beachten Sie, dass der Abbruch nur für Ressourcen gilt, die noch nicht verarbeitet wurden. Einige Ressourcen haben möglicherweise bereits die Verarbeitung abgeschlossen und spiegeln die neuesten Konfigurationsupdates wider, obwohl die Anforderung abgebrochen wurde.

Sie können die Zusammenfassung der Konfigurationsanforderung nach dem Abbruch abrufen, um zu überprüfen, welche Ressourcen (sofern vorhanden) bereits vor dem Abbruch verarbeitet wurden.

Private Zielgruppen synchronisieren

Für ein Liveprodukt können Updates für private Zielgruppen im Entwurf, in der Vorschau und in live-Umgebungen gleichzeitig ausgeführt werden, ohne dass eine Veröffentlichung erforderlich ist. Sie können die private Zielgruppe mit der Ressource "preis-and-availability-update-private-audiences" synchronisieren, indem Sie angeben, welche Benutzergruppen Sie einem bestimmten Plan hinzufügen oder entfernen möchten. Dadurch werden Entwürfe, Vorschau und Liveumgebungen synchronisiert, um die gleichen Privaten Zielgruppenwerte zu haben. Beim Synchronisieren der privaten Zielgruppe ist es nicht erforderlich, die Übermittlungsressource anzugeben.

Verwenden Sie zum Bearbeiten der Entwurfsgruppen die Ressource "Preis- und Verfügbarkeitsplan" und die Eigenschaft "privateAudiences". Dies muss den regulären Veröffentlichungsfluss durchlaufen, damit die Werte in der Vorschau und live festgelegt werden.

Wichtig

Die unterstützten Zielgruppentypen sind "subscription", "ea", "msdn" und "tenant", aber die Unterstützung für diese variiert je nach Produkttyp. Wenn Ihr Produkt mehr als einen Bezeichnertyp zur Konfiguration der privaten Zielgruppe unterstützt (z. B. sowohl Mandanten-IDs als auch Abonnement-IDs), müssen Sie eine vollständige Veröffentlichung durchführen, wenn Sie zum ersten Mal einen neuen Bezeichnertyp bereitstellen. In diesem Fall können Sie die private Zielgruppe nicht synchronisieren.

Beispielanforderung zum Synchronisieren der Konfiguration der privaten Zielgruppe:

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

Leadverwaltung konfigurieren

Verbinden Sie Ihr CRM-System (Customer Relationship Management) mit Ihrem kommerziellen Marketplace-Produkt, damit Sie Kundenkontaktinformationen erhalten können, wenn ein Kunde Interesse bekundet oder Ihr Produkt bereitstellt. Sie können diese Verbindung jederzeit während oder nach der Produkterstellung ändern. Weitere Informationen finden Sie unter Abrufen von Kundenkontakten.

Beispielanforderung zum Konfigurieren der Leadverwaltung:

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

Status im Ressourcenlebenszyklus

Es gibt verschiedene Aktionen, die Sie ausführen können, um den Lebenszyklusstatus einer Ressource zuzuordnen. Nicht alle Ressourcen verfügen über einen Lebenszyklusstatus, und nicht alle Lebenszyklusstatus werden von allen Ressourcen unterstützt. Um zu ermitteln, ob eine Ressource über einen Lebenszyklusstatus verfügt und welche Werte unterstützt werden, können Sie das Ressourcenschema auf das Vorhandensein der Eigenschaft "lifecycleState" überprüfen. Im Folgenden werden die verschiedenen unterstützten Lebenszyklusstatus aufgeführt.

Gelöscht

Sie können bestimmte Ressourcen löschen, indem Sie die Eigenschaft "lifecycleState" auf "deleted" aktualisieren. Sie können nur Entwurfsressourcen löschen, die noch nicht veröffentlicht worden sind. Diese Aktion kann nicht rückgängig gemacht werden.

Beispiel für eine Anforderung:

Im folgenden Beispiel wird der "standard"-Entwurfsplan gelöscht.

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

Als veraltet markiert

Durch die Kennzeichnung einer Ressource als veraltet wird diese aus dem kommerziellen Marketplace entfernt. Um veraltet zu sein, legen Sie die Eigenschaft "lifecycleState" auf "veraltet" für die Ressourcen fest, die sie unterstützen. Es gibt verschiedene Veraltetkeitsebenen. Alle Produkttypen unterstützen die Veraltetkeit des gesamten Produkts und einzelner Pläne darin. Informationen zum späteren Wiederherstellen einer veralteten Ressource finden Sie im Lebenszyklusstatus "allgemein Verfügbar".

Beispielanforderung für eine Veraltetkeit eines Produkts:

Im folgenden Beispiel wird die Live-Übermittlung des Produkts als veraltet festgelegt. Sobald diese Änderung angewendet wurde, wird sie automatisch in Live veröffentlicht, um wirksam zu werden.

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

Wenn Pläne veraltet sind, muss die Eigenschaft "lifecycleState" in "veraltet" geändert werden, und die Änderungen müssen dann in "Vorschau" veröffentlicht werden, damit die Veraltetkeit wirksam wird. Dies unterscheidet sich von einer Veraltetkeit auf Produktebene, bei der die Veraltetkeit automatisch in der Liveumgebung konfiguriert wird.

Beispielanforderung für eine Veraltetkeit eines Plans:

Im folgenden Beispiel wird ein Plan innerhalb eines SaaS-Produkts als veraltet festgelegt. Denken Sie daran, dass Sie diese Änderung später mithilfe der Übermittlungsressource veröffentlichen können.

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

Es gibt andere Arten von Veraltetkeit, die je nach Produkttyp variieren. Erfahren Sie mehr über das Veraltet von SaaS, virtuellen Computern und Containern.

Allgemein verfügbar

generallyAvailable ist der Standardlebenszyklusstatus für alle Ressourcen. Sobald eine Ressource veraltet ist, können Sie sie wiederherstellen, indem Sie die Eigenschaft "lifecycleState" wieder in "allgemein Verfügbar" ändern. Um ein veraltetes Produkt wiederherzustellen, müssen Sie das Produkt veröffentlichen, um dann live eine Vorschau anzuzeigen. Beispiele für SaaS, VMs und Container finden Sie in ihren jeweiligen Artikeln.

Beispielanforderung für eine Planwiederherstellung:

Im folgenden Beispiel soll ein Plan wiederhergestellt werden. Um diese Änderung anzuwenden, müssen Sie später die gesamte Nutzung der Übermittlungsressource veröffentlichen.

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

Ressourcen-API-Referenz

Die folgenden Schemaversionen gelten nur für die Vorschau und ändern sich, sobald die API allgemein verfügbar ist.

Hinweis

Sie können die vorhandenen verfügbaren Ressourcen und deren Versionen hier anzeigen: ressourcenindex

Ressourcentyp	Beschreibung	Schema
Commercial-marketplace-setup	Beschreibt die transaktionsfähige Konfiguration von Produkten auf dem kommerziellen Markt.	https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2
Kundenkontakte	Ermöglicht das Herstellen einer Verbindung mit einem CRM-System, um Kundenkontakte zu erhalten.	https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3
Auflistung	Dies schließt die Beschreibungen Ihres Produkts ein, die im Microsoft Commercial Marketplace Storefronts angezeigt werden.	https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5
Listing-Asset	Screenshots und Ihre Marketingressourcen, die mit der Eintragsressource verknüpft sind.	https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5
Listing-Trailer	Videoressourcen, die mit der Eintragsressource verknüpft sind.	https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5
Microsoft365-Integration	Microsoft 365-Aktivierung und Auswahl eingeben.	https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2
Plan	Zum Erstellen von Plänen, auf die dann von den von Ihnen konfigurierten Ressourcen auf Planebene verwiesen wird, z. B. planauflistung.	https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2
Planauflistung	Definieren Sie den Plannamen und die Beschreibung so, wie sie auf dem kommerziellen Markt angezeigt werden sollen.	https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5
Preis- und Verfügbarkeits-Custom-Meter	Definieren Sie die für Ihre Pläne freigegebenen benutzerdefinierten Zähler.	https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3
Preis- und Verfügbarkeitsangebot	Definieren Sie eine begrenzte Zielgruppe, die Ihr Produkt überprüfen kann, bevor Sie es live veröffentlichen.	https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3
Preis- und Verfügbarkeitsplan	Konfigurieren Sie die Märkte, in dem dieser Plan verfügbar ist, das gewünschte Monetarisierungsmodell, den Preis und die Abrechnungsbedingungen.	https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4
preis-and-availability-update-private-audiences	Aktualisierungen an privaten Zielgruppen in der Entwurfs-, Vorschau- und Liveumgebung können gleichzeitig durchgeführt werden, ohne dass eine Veröffentlichung erforderlich ist.	https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3
Private-and-availability-private-offer-plan	Wird verwendet, um die absoluten Preisdetails eines Produkts/Eines Plans zu konfigurieren, das in einem privaten Angebot verwendet wird.	https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01
Privates Angebot	Definiert den Namen und die Art des privaten Angebots sowie die Angebotsbedingungen und Details sowie die enthaltenen Produkte/Pläne sowie deren Preise.	https://schema.mp.microsoft.com/schema/private-offer/2022-07-01
product	Dies ist die Hauptressource, definiert den Namen und Typ des Produkts, alle Ressourcen verweisen darauf.	https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3
property	Definieren Sie die Kategorien und Branchen, die für Ihr Angebot, Ihre App-Version und gesetzliche Verträge gelten.	https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5
Wiederverkäufer	Konfigurieren Sie die Partner im CSP-Programm (Cloud Solution Providers), dem Sie Ihr Produkt zur Verfügung stellen möchten.	https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2
Ressourcenstruktur	Beschreibt das Produkt eine Liste der Ressourcen für dieses Produkt im aktuellen Zustand für die angegebene Zielumgebung.	https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2
software-as-a-service-technical-configuration	Technische Details, die dem kommerziellen Microsoft Marketplace helfen, sich mit Ihrer Lösung zu verbinden.	https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3
Unterwerfung	Kann verwendet werden, um verschiedene Aktionen für Ihr Produkt auszulösen und den Veröffentlichungsstatus Ihres Produkts indifferenten Umgebungen (Entwurf, Vorschau und Live) anzugeben.	https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2
Virtual-machine-plan-technical-configuration	Technische Details zur Beschreibung des virtuellen Computers und des Imagespeicherorts.	https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3
containerplantechnische Konfiguration	Technische Details zur Beschreibung der Containerimageeigenschaften.	https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3

API-Leitfaden pro Produkttyp

Die Produktaufnahme-API wird künftig anderen Produkttypen zur Verfügung gestellt. Da weitere Produkttypen unterstützt werden, werden spezifischere Anleitungen für jeden Produkttyp zur Verfügung gestellt.

Produkttyp	Produkttypspezifische Ressourcen
Private Angebote	Erstellen und Verwalten privater Angebote über die Produktaufnahme-API
SaaS	Erstellen und Verwalten von SaaS-Angeboten über die Produktaufnahme-API
Virtuelle Computer	Erstellen und Verwalten virtueller Computerangebote über die Produktaufnahme-API
Container	Erstellen und Verwalten von Containerangeboten über die Produktaufnahme-API

API-Versionen und -Updates

Aktualisieren	Was hat sich geändert?
11-2023	Alle Schemaendpunkte wurden von product-ingestion.azureedge.net auf schema.mp.microsoft.com aktualisiert.
12-2022	Eine neue Schemaversion 2022-03-01-preview3 der PC Ingestion-API für Kundenkontakte ist jetzt verfügbar, die clientID und clientSecret akzeptiert, während Kundenkontakte konfiguriert und die Erfassung der ServerID- und Kontakt-E-Mail-Felder beendet wird. Wechseln Sie zur neuen Version, und stellen Sie die clientID und clientSecret bereit, um den Marketo-Connector für Marketplace-Angebote weiter zu konfigurieren. Neue Schema-URL: https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3
09-2022	Containervorschauunterstützung wird als Version 2022-03-01-preview4 veröffentlicht.
08-2022	Software as a Service Preview Support wird als Version 2022-03-01-preview3 veröffentlicht
08-2022	Privates Angebot öffentliche Version als Version 2022-07-01
05-2022	Vorschauunterstützung für virtuelle Computer wird als Version 2022-03-01-preview2 veröffentlicht.

Freigeben über

Produkterfassungs-API für den kommerziellen Marketplace

Erste Schritte

Schritt 1: Abschließen der Voraussetzungen

Zuordnen einer Microsoft Entra-Anwendung zu Ihrem Partner Center-Konto

Schritt 2: Abrufen eines Microsoft Entra-Zugriffstokens

Konzepte

Ressourcen

Dauerhafte ID

Externe ID

API-Methoden

Typischer Workflow

Abrufen vorhandener Ressourcenkonfigurationen

Methode 1: Ressourcenstruktur

Methode 2: Dauerhafte ID

Methode 3: Abfragezeichenfolgenparameter

Abfragen Ihrer Übermittlungen

Erstellen neuer Produkte und Ressourcen

Ändern vorhandener Produkte und Ressourcen

Konfigurationsanforderungen

Ressourcenverweise und Abhängigkeiten

References

Abhängigkeiten

Submission-Ressource

Veröffentlichung in der Vorschauumgebung

Methode 1: Veröffentlichen aller Entwurfsressourcen

Methode 2: Veröffentlichen bestimmter Entwurfsressourcen (auch als modularer Veröffentlichen bezeichnet)

Veröffentlichung in der Liveumgebung

Überprüfen des Status einer Anforderung

Status einer ausstehenden Anforderung

Zusammenfassung einer abgeschlossenen Anforderung

Abbrechen einer Konfigurationsanforderung

Private Zielgruppen synchronisieren

Leadverwaltung konfigurieren

Status im Ressourcenlebenszyklus

Gelöscht

Als veraltet markiert

Allgemein verfügbar

Ressourcen-API-Referenz

API-Leitfaden pro Produkttyp

API-Versionen und -Updates

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen