SaaS 用 Product Ingestion API
Product Ingestion API は、すべてのコマーシャル マーケットプレース製品にわたって既存のすべての申請 API を統合する最新化された API です。 使用を開始する方法の詳細については、製品インジェスト API を参照してください。
この記事では、SaaS オファーの種類に特化した API の使用方法に関するガイダンスを提供します。
既存のリソース構成を取得する
既存のリソースを更新する前に、最初にそれらを取得して、最新の構成を確保することが重要です。 GET 呼び出しを使用してリソースを取得する方法はいくつかあります。 1 つの API 呼び出しで特定の製品内のすべてのリソースを取得するには、メソッド 1 の次のセクションを参照してください。
メソッド 1: resource-tree
GET resource-tree/<product-durableID>?$version=<schema-version>
"resource-tree" リソースの種類と製品の永続 ID を使用して、特定の製品内のすべてのリソース構成を取得できます。 指定したスキーマ バージョンは、要求された製品の該当する各リソースでサポートされている最大バージョンとして使用されます。
Note
製品の永続 ID がわからない場合は、代わりに製品の外部 ID を使用し、 GET product?externalID=<product-externalID>&$version=<product-schema-version>を実行することで、まず製品リソースを取得できます。 この要求では、メソッド 3 で詳しく説明されているクエリ文字列パラメーターを利用します。 応答には、将来の要求に使用できる製品の永続 ID が含まれます。
既定では、"resource-tree" を使用して GET 呼び出しを実行すると、リソースのドラフト バージョンが返されます。 ただし、"targetType" クエリ パラメーターを渡すことで、"プレビュー" または "ライブ" データを取得する目的のターゲットを指定できます。 次の例では、GET 呼び出しは、製品 "12345678-abcd-efgh-1234-12345678901" のすべてのリソースのプレビュー環境の構成を返します。
GET 呼び出しの例:
GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?targetType="preview"&$version=2022-03-01-preview5
応答の例:
{
"$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.
{
...
}]
}
リソースのライフサイクル状態
リソースのライフサイクル状態にマップするために実行できるさまざまなアクションがあります。 すべてのリソースにライフサイクル状態があるわけではありません。また、すべてのライフサイクル状態がすべてのリソースでサポートされているわけではありません。 リソース スキーマにプロパティ lifecycleState が存在するかどうかを確認して、リソースにライフサイクル状態があるかどうか、およびサポートされている値を確認します。 SaaS オファーの種類のリソース ライフサイクルの状態を設定する例を次に示します。
"非推奨"
非推奨にすると、商用マーケットプレースからそのリソースが削除されます。 非推奨にするには、それをサポートするリソースで "lifecycleState" プロパティを "deprecated" に設定します。 製品の種類に応じて、さまざまなレベルの非推奨がサポートされます。 たとえば、SaaS 製品の場合、プランまたは製品全体を非推奨にすることができます。 プランを非推奨にする場合は、"lifecycleState" を変更し、その後、非推奨を有効にするために変更をプレビューに公開する必要があります。 これは、これを設定するとライブ環境での非推奨が自動的に開始される製品レベルの非推奨とは異なります。 非推奨のリソースを後で復元するには、"generallyAvailable" ライフサイクル状態を参照してください。
非推奨のサンプル要求を計画します:
次の例では、SaaS 製品内のプランは非推奨に設定されています。 この変更を適用するには、後で申請リソースを使用して発行できます。
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"
}
]
}
製品非推奨のサンプル要求:
次の例では、製品のライブ送信は非推奨に設定されています。 この変更が適用されると、有効にするために自動的に公開されます。
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"
}
]
}
一般公開
generallyAvailable は、すべてのリソースの既定のライフサイクル状態です。 リソースが非推奨になったら、 lifecycleState プロパティを generallyAvailable に戻すことで復元できます。 非推奨の製品を復元するには、製品をもう一度公開してプレビューしてから公開する必要があります。
復元のサンプル要求を計画します:
次の例では、プランを復元することを目的としています。 この変更を適用するには、後で申請リソースを使用してすべての方法を公開する必要があります。
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"
}
]
}