Produkterfassungs-API für SaaS
Die Produktaufnahme-API ist eine modernisierte API, die alle vorhandenen Übermittlungs-APIs für alle kommerziellen Marketplace-Produkte vereint. Ausführliche Informationen zu den ersten Schritten finden Sie in der Produktaufnahme-API.
Dieser Artikel enthält Anleitungen zur Verwendung der APIs speziell für den SaaS-Angebotstyp.
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. Informationen zum Abrufen aller Ressourcen innerhalb eines bestimmten Produkts in einem einzelnen API-Aufruf finden Sie im folgenden Abschnitt, Methode 1.
Methode 1: Ressourcenstruktur
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 von Ihnen bereitgestellte Schemaversion wird als maximal unterstützte Version für jede der anwendbaren Ressourcen des angeforderten Produkts verwendet.
Hinweis
Wenn Sie die dauerhafte ID des Produkts nicht kennen, können Sie zuerst die Produktressource abrufen, indem Sie stattdessen die externe ID des Produkts verwenden und ausgeführt werden GET product?externalID=<product-externalID>&$version=<product-schema-version>. Diese Anforderung nutzt einen Abfragezeichenfolgenparameter, der in Methode 3 detailliert beschrieben ist. 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": "product_external_id_example"
},
"type": "softwareAsAService",
"alias": "product_example"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2",
"id": "commercial-marketplace-setup/12345678-abcd-efgh-1234-12345678901",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"sellThroughMicrosoft": true,
"useMicrosoftLicenseManagementService": false
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/98756328-04e9-55ae-9403-52b6c971a956
...
},
// The response would include all existing resources within this product.
{
...
}]
}
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. Überprüfen Sie das Ressourcenschema auf das Vorhandensein des EigenschaftslebenszyklusState, um festzustellen, ob eine Ressource über einen Lebenszyklusstatus verfügt und welche Werte unterstützt werden. Im Folgenden sind einige Beispiele zum Festlegen des Ressourcenlebenszyklusstatus für den SaaS-Angebotstyp aufgeführt.
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. Je nach Produkttyp werden verschiedene Stufen der Veralterung unterstützt. Beispielsweise können Sie für SaaS-Produkte Pläne oder das gesamte Produkt veraltet sein. Wenn Pläne veraltet sind, muss der "lifecycleState" geändert werden, und die Änderungen müssen dann veröffentlicht werden, um eine Vorschau anzuzeigen, damit die Veraltetkeit wirksam wird. Dies unterscheidet sich von der Deaktivierung auf Produktebene, bei der die Einstellung automatisch die Veraltetkeit in der Liveumgebung startet. Informationen zum späteren Wiederherstellen einer veralteten Ressource finden Sie im Lebenszyklusstatus "allgemein Verfügbar".
Planen der Veraltetkeitsbeispielanforderung:
Im folgenden Beispiel ist ein Plan innerhalb eines SaaS-Produkts auf 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"
}
]
}
Beispielanforderung für produktdeaktive Produkte:
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"
}
]
}
Allgemein verfügbar
"generallyAvailable " ist der Standardlebenszyklusstatus für alle Ressourcen. Sobald eine Ressource veraltet ist, können Sie sie wiederherstellen, indem Sie die LifecycleState-Eigenschaft wieder in "allgemein Verfügbar" ändern. Um ein veraltetes Produkt wiederherzustellen, müssen Sie das Produkt erneut veröffentlichen, um eine Vorschau anzuzeigen und dann live zu verwenden.
Planen der Beispielanforderung für die Wiederherstellung:
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"
}
]
}