コマーシャル マーケットプレース用の Product Ingestion API
Product Ingestion API は、すべてのコマーシャル マーケットプレース製品にわたって既存のすべての申請 API を統合する最新化された API です。 この API を使用すると、パートナー センター アカウント内の製品とプランに関連付けられているリソースを作成、発行、管理できます。 宣言型パターンを使用して要求を送信します。このパターンでは、目的の状態に到達するための個々のステップを指定するのではなく、目的の状態が示されます。
この記事では、コマーシャル マーケットプレース オファーの種類に応じて API の使用を開始する方法に関するガイダンスを提供します。 製品インジェスト API は現在、SaaS、VM、プライベート オファー、コンテナー オファーの種類でサポートされており、プレビュー段階です。 ご自分のオファーに固有のガイダンスについては、オファーの種類ごとの API ガイダンスを確認してください。
重要
Azure Active Directory (Azure AD) Graph は、2023 年 6 月 30 日の時点で非推奨となっています。 今後、Azure AD Graph への投資は行いません。 Azure AD Graph API には、セキュリティ関連の修正プログラムを超える SLA またはメインテナント コミットメントはありません。 新機能への投資は Microsoft Graph に対してのみ行われます。
アプリケーションを Microsoft Graph API に移行するのに十分な時間を確保できるように、段階的な手順で Azure AD Graph を廃止します。 後日お知らせしますが、Azure AD Graph を使用して新しいアプリケーションの作成をブロックします。
詳細については、「重要: Azure AD Graph の廃止と PowerShell モジュールの廃止」を参照してください。
作業の開始
製品インジェスト API には、ワークロード名 "product-ingestion" の下にある MSGraph API を使用してアクセスできます。 ベース URL は https://graph.microsoft.com/rp/product-ingestion です。
Product Ingestion API を使用するには、まず次の情報を取得する必要があります。
- Microsoft Entra ID。ディレクトリに対するグローバル管理者のアクセス許可があることを確認します
- Microsoft Entra アプリケーション
- Microsoft Entra アクセス トークン
手順 1: 前提条件を満たす
Product Ingestion API を呼び出すコードの記述を開始する前に、次の前提条件を満たしていることを確認してください。
- ユーザー (または組織) は Microsoft Entra ディレクトリを持っている必要があり、ディレクトリの全体管理者アクセス許可が必要です。 Microsoft 365 または Microsoft の他のビジネス サービスを既に使用している場合は、Microsoft Entra ディレクトリが既にあります。 それ以外の場合は、パートナー センターで新しい Microsoft Entra ID を追加料金なしで作成できます。
- Microsoft Entra アプリケーションをパートナー センター アカウントに関連付け、テナント ID、クライアント ID、キーを取得する必要があります。 Microsoft Store 申請 API の呼び出しで使用する Microsoft Entra アクセス トークンを取得するには、これらのトークンが必要です。
Microsoft Entra アプリケーションをパートナー センター アカウントに関連付ける
Product Ingestion API を使用するには、Microsoft Entra アプリケーションをパートナー センター アカウントに関連付け、アプリケーションのテナント ID とクライアント ID を取得し、キーを生成する必要があります。 Microsoft Entra アプリケーションは、製品インジェスト API を呼び出すアプリまたはサービスを表します。 API に渡す Microsoft Entra アクセス トークンを取得するには、テナント ID、クライアント ID、キーが必要です。
Note
このタスクは 1 度だけ実行する必要があります。 テナント ID、クライアント ID、およびキーを取得したら、新しい Microsoft Entra アクセス トークンを作成する必要がある場合は、いつでもそれらを再利用できます。
- パートナー センターで、 組織のパートナー センター アカウント を組織の Microsoft Entra ディレクトリに関連付けます。
- パートナー センターの [アカウント設定] セクションの [ユーザー] ページから、パートナー センター アカウントの申請にアクセスするために使用するアプリまたはサービスを表す Microsoft Entra アプリケーションを追加します。 このアプリケーションにマネージャー ロールを確実に割り当てます。 アプリケーションが Microsoft Entra ディレクトリにまだ存在しない場合は、 パートナー センターで新しい Microsoft Entra アプリケーション を作成します。 パートナー センターは、アプリケーションの 2 種類のエントリをサービス プリンシパルとして作成し、もう 1 つは Microsoft Entra アプリケーションの種類として作成します。
- [ユーザー] ページに戻り、Microsoft Entra アプリケーションの名前を選択してアプリケーション設定に移動し、テナント ID とクライアント ID の値をコピーします。
- [新しいキーを追加] を選択します。 次の画面で、キーの値をコピーしておきます。 このページを離れると、この情報にアクセスすることはできなくなります。 詳細については、「Microsoft Entra アプリケーションのキーを管理する」を参照してください。
手順 2: Microsoft Entra アクセス トークンを取得する
Product Ingestion API 内のいずれかのメソッドを呼び出すには、まず Microsoft Entra アクセス トークンを取得して、API 内の各メソッドの Authorization ヘッダーに渡す必要があります。 アクセス トークンは、発行後 60 分が経過すると有効期限が切れます。 その後、更新することで、将来の API 呼び出しで使用できるようになります。
アクセス トークンを取得するには、「クライアント資格情報を使用したサービス間の呼び出し」の指示に従って、HTTP POST を https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token エンドポイントに送信します。 要求のサンプルを次に示します。
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
POST URI の tenant_id の値と client_id および client_secret のパラメーターには、前のセクションでパートナー センターから取得したアプリケーションのテナント ID、クライアント ID、キーを指定します。 scope パラメーターには、 を指定する必要がありますhttps://graph.microsoft.com/.default。
概念
作業を開始する前に、いくつかの基本的な概念を理解しておく必要があります。
リソース
API はリソースの種類を中心に構成されており、各型は "$schema" プロパティによって参照される専用のスキーマ定義を使用して記述されます。 スキーマは、そのリソースの構成プロパティで構成されます。 リソースは、特定の製品のさまざまな側面の構成を作成および更新する上で基本的なものです。 リソースの種類とそのスキーマの完全なリストについては、「Resource API リファレンス」を参照してください。
永続 ID
永続 ID は、リソースを一意に識別するために使用されるシステムによって生成されるグローバル識別子です。 すべてのリソースには関連付けられた "ID" プロパティがあり、リソースの種類名と組み合わせると、リソースの永続 ID が構成されます。 永続 ID は、リソースを参照して取得または変更するときに使用されます。
形式:
\<resource-type>/\<id>
例:
{
"$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"
}
External ID
"外部 ID" は、特定の製品またはプランを参照するために使用できるもう 1 つの一意識別子です。 これは、永続 ID を使用する代わりに、これらのリソースを参照する別の方法です。 製品の外部 ID は "offerID" に変換され、プランの外部 ID は"id" プロパティの作成時に定義された "planID" に変換されます。
例:
{
"$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 メソッド
管理 API は 4 つあり、既存のリソースに対するクエリの実行、構成の更新、要求の状態の確認など、さまざまなアクションを実行するために使用できます。
Note
すべての要求では、応答の一部として必要なスキーマ バージョン ($version クエリ パラメーター) を設定する必要があります。
| [API の種類] | 説明 | HTTP メソッドとパス |
|---|---|---|
| クエリ | 次の方法で既存のリソースを取得します。 -Method 1: "resource-tree" リソースの種類 -Method 2: durable-id -Method 3: クエリ文字列パラメーター |
-Method 1: GET resource-tree/<product-durableID>-方法 2: GET <resource-durableID>-Method 3: GET <resourceType>?<query parameters> |
| 送信の構成 | 1 つ以上のリソースを作成または更新するための要求を送信します。 処理が成功すると、jobID が返されます。これは、要求の状態を取得するために使用できます。 この API の種類を使用して、ドラフト状態の更新と変更の発行、プライベート 対象ユーザーの同期、リソース ライフサイクルの状態の変更を行うことができます。 | POST configure |
| 状態の構成 | jobID を使用して保留中の要求の状態を取得します。 | GET configure/<jobID>/status |
| 状態の詳細を構成する | jobID を使用して、完了した要求の詳細な概要 (更新されたリソースを含む) を取得します。 | GET configure/<jobID> |
| 構成の取り消し | 指定した構成ジョブを取り消します。 | POST configure/<jobID>/cancel |
一般的なワークフロー
既存のリソースを更新するための一般的なワークフローは次のようになります。
- 既存のリソース構成を取得する (API の種類: リソース ツリーを使用したクエリ)*
- 必要な更新を行い、構成要求を送信します (API の種類: 送信の構成)
- 要求の状態を確認する (API の種類: 状態の構成と状態の詳細の構成)
* 新しいリソースを作成するときに、これと同じワークフローを適用できますが、リソースを取得する (手順 1) 代わりに、Resource API 参照テーブルを使用して、作成するリソースの種類に現在のスキーマが確実に使用されるようにします。
要約すると、この画像は、新しいリソースを作成するか既存のリソースを変更しているかに関係なく、構成要求の送信に使用される一般的な呼び出しパターンを示しています。
Note
オファーの種類ごとの API ガイダンスセクションを参照して、管理しているオファーの種類に固有の追加の前提条件を確認してください。
既存のリソース構成を取得する
既存のリソースを更新する前に、最初にそれらを取得して、最新の構成を確保することが重要です。 GET 呼び出しを使用してリソースを取得する方法はいくつかあります。 1 つの API 呼び出しで特定の製品内のすべてのリソースを取得するには、以下のメソッド 1 を参照してください。
メソッド 1: resource-tree
Schema: https://``schema.mp.microsoft.com``/schema/resource-tree/2022-03-01-preview2
GET resource-tree/<product-durableID>?$version=<schema-version>
"resource-tree" リソースの種類と製品の永続 ID を使用して、特定の製品内のすべてのリソース構成を取得できます。
使用可能な最新のスキーマ バージョンは、リソースごとに異なる場合があります。 リソース ツリー要求を実行する場合、指定されたスキーマ バージョンによって、製品内の各リソースに対して返されるバージョンが決まります。 指定されたバージョンは、同じまたはそれより低いバージョンのすべてのリソースで使用可能な最新のスキーマ バージョンを返すという点で、"最大" バージョン制限として機能します。 たとえば、使用可能な最新のプラン一覧バージョンが "2022-03-01-preview3" の場合、リソース ツリー GET 要求で "2022-03-01-preview5" を指定した場合、応答はこのバージョンを表示します。 ただし、リソース ツリー バージョンとして "2022-03-01-preview2" を要求すると、使用可能な最新バージョンが "2022-03-01-preview3" であっても、"2022-03-01-preview2" プランの一覧リソースが返されます。 各リソースの利用可能な最新バージョンを使用して、新しくサポートされる機能で更新されたスキーマを確実に使用することをお勧めします。
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": "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.
{
...
}]
}
メソッド 2: 永続 ID
GET <resource-durableID>?$version=<schema-version>
永続 ID を使用して特定のリソースを 取得します。 リソースが作成されると、永続 ID は常に同じメインされ、GET メソッドを呼び出すことによって、そのリソースの最新のドラフト変更を取得するために使用できます。 たとえば、次の要求では、"2022-03-01-preview3" スキーマ バージョンを使用して、この特定の製品のドラフト構成が返されます。
GET product/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview3
重要
このメソッドは、ドラフト構成の取得にのみ使用されます。 プレビューまたはライブ データを取得する場合は、上記のように "resource-tree" メソッドを使用します。
リソースの永続 ID を見つけるには、次のいずれかを実行できます。
- "resource-tree" メソッドを使用して、製品内のすべてのリソースをそれぞれの永続 ID と共にフェッチするか、または
- 完了した リソース構成要求の詳細を取得します。これには、要求の一部として作成または更新されたすべてのリソースの永続 ID が含まれます。
"ID" プロパティは、それぞれのリソースの durable-id です。
メソッド 3: クエリ文字列パラメーター
GET <resourceType>?<query parameters>&$version=<schema-version>
このメソッドは、特定のアカウントに関連付けられている特定のリソースの種類のクエリに使用されます。 たとえば、1 回の GET 呼び出しで、特定の製品の種類のすべての製品を取得できます。 クエリ文字列パラメーターは、製品、プラン、または申請に関連する詳細を照会するために使用されます。
次の表は、サポートされているリソースの種類ごとにサポートされているクエリ パラメーターを示しています。 すべてのリソースの種類で、各クエリ パラメーターがサポートされているわけではありません。 現在サポートされているクエリ文字列の完全なリストについては、この表を参照してください。
| リソースの種類 | パラメーター | クエリ文字列の例 |
|---|---|---|
| 計画 | 製品*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> |
| 提出 | targetType $maxpagesize continuationToken$version * |
GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version> |
| resource-tree | targetType$version* |
GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version> |
* 製品パラメーターと$versionパラメーターは常に必要です。
サポートされている各クエリ パラメーターの機能:
- product – "plan" リソースの種類のコンテキストで "product" パラメーターを渡すと、その特定の製品内のすべてのプランが返されます。
- externalID – 製品またはプランのコンテキストで "externalID" パラメーターを渡すと、その製品またはプランの構成が返されます。 "resource-tree" メソッドとは異なり、このクエリ文字列パラメーターは、そのリソース内のすべてのリソースではなく、そのリソースの詳細のみを返します。
- type – "product" リソースの種類のコンテキストで "type" パラメーターを渡すと、アカウントに関連付けられているその型のすべての製品が返されます。 たとえば、"type=softwareAsAService" を指定すると、すべての SaaS 製品が返されます。
- targetType – 使用されているリソースの種類のコンテキストで特定の環境のデータを返します。 サポートされている "targetType" 値は、"draft"、"preview"、または "live" です。
- $maxpagesize – このパラメーターを使用して最大ページ サイズを正の整数の形式で指定すると、以前の申請に対してクエリを実行するときの検索結果を制限できます。
- continuationToken – このパラメーターを "$maxpagesize" パラメーターと共に使用して、検索で使用できる別の結果セットに対してクエリを実行できます。 "continuationToken" 値は、前のページの応答で指定されます。
- $version – これはすべての呼び出しに必要なパラメーターであり、行った要求からの応答に必要なスキーマ バージョンを指定します。 使用可能な最新のスキーマ バージョンはリソースごとに異なる場合があり、指定されたバージョンは "最大" バージョン制限として機能します。 システムは、使用可能な場合は正確なスキーマ バージョン、または要求されたバージョンより古い最も近いバージョンを返します。 これは、新しいスキーマの変更がある場合でもコードが動作メインに役立ちますが、最新の機能を利用するには、各スキーマの利用可能な最新バージョンを使用することをお勧めします。
申請のクエリを実行する
GET submission/<product-durableID> を実行して、既存の製品の申請を取得できます。 既定では、下書き参照を含むすべてのアクティブな申請が返されますが、"targetType" クエリ パラメーター (GET submission/<product-durableID>?targetType=<environment>&$version=<version>) を使用して特定の環境に対してクエリを実行することもできます。
重要
"プレビュー" 申請が "ライブ" にプッシュされると、以前の "ライブ" 申請が置き換えられます。 これが発生すると、新しい申請が "プレビュー" に発行されるまで、データは "プレビュー" 環境と "ライブ" 環境の両方を表すようになりました。
要求のサンプル:
GET https://graph.microsoft.com/rp/product-ingestion/submission/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview2
応答のサンプル:
この例では、製品 ID "12345678-abcd-efgh-1234-12345678901" に関連付けられているアクティブな申請に対する GET 要求を示します。 アクティブな "Live" 申請 (submission/12345678-abcd-efgh-1234-12345678901/1152921515689847470) は、最初にプレビューに公開され、その後公開されました。 この申請が 2022 年 1 月 25 日に公開にプッシュされたとき、2022 年 2 月 4 日に新しいプレビュー申請 (submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683) が作成されるまで、プレビューとライブの両方を表していました。
{
"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"
}
]
}
新しい製品とリソースを作成する
1 つの構成要求の一部として、新しい製品を含む新しいリソースを作成できます。 Resource API 参照テーブルを使用すると、作成するリソースの種類のスキーマを取得できます。 これにより、最新のスキーマを使用していることが保証されるため、リソースを作成するために必要なすべてのプロパティを構成できます。
新しい製品を作成する場合、要件は製品の種類によって異なります。 そのため、さまざまなリソースを提供する必要があります。 それぞれの製品の種類に対応するコマーシャル マーケットプレースのドキュメントを参照して、要求で基本的な要件を構成していることを確認できます。 または、製品リソースのみを使用して構成要求を行うことができます。 製品を作成した後、構成状態の詳細 API を呼び出して、作成された製品リソースを取得し、リソース ツリークエリ API を呼び出す永続 ID を見つけます。 応答は、作成した製品の種類に対してサポートされている該当するリソースを返します。
同様に、既存の製品内に新しいリソースを作成するには、その特定のリソースの種類の最新のスキーマを取得する必要もあります。 リソースの依存関係を確認して、構成要求の一部として依存リソースを指定していることを確認します。
スキーマを使用してリソースを構築した後、構成要求を行う方法について説明します。
既存の製品とリソースを変更する
構成ペイロードを使用して更新を送信できます。 このペイロードは 1 つ以上のリソースの種類で構成され、"$schema" プロパティは参照されているリソースの種類を示します。
ヒント
最新の構成を確実に活用するために、更新プログラムを発行する前に、まず既存のリソースを取得することをお勧めします。
リソースを変更した後、構成要求を行う方法について説明します。
構成要求
同じペイロードで編集および発行できます。 構成要求を送信するには、構成 API の HTTP POST メソッドを使用します。 構成ペイロードは、必要な変更を示すリソースの配列で構成されます。 下書きの変更を公開するために提出リソースを明示的に送信するまで、すべての編集は下書きバージョンにのみ影響します。 プレビューまたはライブに発行する場合は、申請リソースを含め、ターゲット環境を指定します。 要求を送信する前に、リソースを参照し、その依存関係を理解する方法を理解しておく必要があります。
Schema:<https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2>
構成要求を送信すると、要求の進行状況と結果を追跡するために使用できる jobID を持つ configure-status オブジェクトが返されます。
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
リソース参照と依存関係
リファレンス
構成要求で既存のリソースを参照するには、リソースの "$schema" の種類とリソースの永続 ID を指定します。 製品やプランの場合は、外部 ID を使用してこれらのリソースを参照することもできます。
永続 ID は、たとえば、別のリソースで参照する製品リソースである場合など、"ID" プロパティにあります。
{
"$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"
}
永続 ID は "product/071b135e-9faf-4ff7-b113-a3f25bb0f468" になります。
次のリスト リソースの例では、次のように "product" リソース スキーマ プロパティに設定することで、永続 ID を使用できます。
{
"$schema": "https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468", // product durable ID
...
}
製品リソースとプラン リソースの外部 ID は、"ID" プロパティ内で定義されます。
{
"$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",
...
}
プランの外部 ID "gold-annual" は、次の形式で他の後続のリソースから参照できます。
{
"$schema": "https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"}
"plan": {"externalID": "gold-annual"}
...
}
要求のサンプル:
この例では、構成ペイロードを使用して、外部 ID が "ds-contoso-image-resize-demo" の新しい SaaS 製品を作成します。 この製品を作成すると、後で永続的 ID または外部 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"
}
]
}
応答の例:
{
"$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": []
}
その後、Configure Status API を使用して jobID を使用して、要求の状態をチェックできます。
依存関係
特定のリソースには、前提条件として別のリソースの作成への依存関係があります。 この状況では、同じペイロード内で "resourceName" プロパティを使用して、プラン リソース内の製品リソースの依存関係を示します。これは、同じ要求で両方を作成する場合です。
"resourceName" は、実行している構成要求の一部として各リソースを識別するためにのみ使用されます。 この値はリソースのデータの一部ではなく、保存されず、顧客に公開されることもありません。 さらに、構成要求の一部としてエラーがある場合は、エラーが属するリソースを呼び出すために "resourceName" が使用されます。
要求のサンプル:
この例では、プランの前に製品を作成する必要があるため、"resourceName" プロパティが使用されます。 作成される製品 "myNewProduct" は、"resourceName" に使用され、依存プラン リソース内で参照される値になります。
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"}
...
},
}]
}
申請のリソース
"プレビュー" または "ライブ" に発行する場合は、申請リソースを要求に含めます。これには次のものが含まれます。
- "product" プロパティ。永続 ID または外部 ID によって参照される更新対象の製品を示します
- ターゲット環境を指定する "targetType" プロパティ
公開する場合は、具体的には、公開しようとしているプレビュー申請の "ID" を次に示します。
{
"$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" }
}
Note
提出リソースを含めない場合、変更はドラフト状態にのみ行われます。
プレビューへの発行
商用製品の種類はプレビュー環境をサポートしており、各更新プログラムはライブの前にプレビューに発行する必要があります。 ライブに直接発行することはできません。
重要
この例外は、プランのプライベート対象ユーザーに変更を加える場合です。 特にプライベート対象ユーザーに更新プログラムを同期すると、これらの変更はプレビューとライブの両方に同時に反映されます。
プレビュー環境にリソースを発行するには、2 つの方法があります。 プレビュー申請に変更を加える必要がある場合は、別の GET 要求を実行し、必要な変更を行い、変更をもう一度プッシュします。 最初に最初の変更を反映する必要はありません。
メソッド 1: すべてのドラフト リソースを発行する
下書きのすべての変更を発行する場合は、プレビュー環境を "targetType" として設定する申請リソースを使用して構成要求を送信できます。 次の例に示すように、このメソッドはすべての変更をターゲット環境 (この場合はプレビュー) に発行するため、更新を必要とするすべてのリソースを明示的に指定する必要はありません。 構成 API エンドポイントと申請リソースを指定するだけで済みます。
要求のサンプル:
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" }
}
]
}
方法 2: 特定のドラフト リソースを発行する (モジュール公開とも呼ばれます)
または、さまざまなリソース間ですべてのドラフト変更を発行する準備ができていない場合は、発行するリソースを申請リソースとともに指定してモジュール発行をトリガーします。 また、この方法を使用して、メソッド 1 で行われるように、一括更新の一部としてではなく、リソースに変更を加えて同時に発行することもできます。 モジュール型の発行では、製品の種類に該当する製品レベルの詳細 (リスト、可用性、パッケージ、リセラーなど) を除くすべてのリソースが必要です。
要求のサンプル:
この例では、製品内のリソースは、モジュール発行の一部として明示的に指定され、その後に申請リソースが続きます。
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" }
}
]
}
ライブへの発行
プレビューの変更がテストおよび検証されたら、プレビュー申請の "ID" と "targetType" が "live" に設定された構成要求を送信することで、変更をライブにプッシュできます。 構成要求に組み込むプレビュー申請の "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": [
// 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" }
}
]
}
要求の状態を確認する
構成要求に含まれるリソースや行っている変更に関係なく、 要求が正常に処理されると、要求を送信した直後に、応答に configure-status オブジェクトが返されます。 "jobID" は、後で要求の状態をチェックするために使用できるため、重要です。
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
送信された要求に対する応答のサンプル:
{
"$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": []
}
保留中の要求の状態
次の呼び出しを使用し、要求の "jobID" を入力して、ジョブが完了するまで状態を取得できます。 要求に問題がある場合は、オブジェクトにエラーの一覧が含まれている場合もあります。
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>/status?$version=2022-03-01-preview2
完了までの時間は、要求の複雑さによって異なる場合があることに注意してください。
完了した要求の概要
構成要求ジョブが正常に完了するか失敗した場合は、"jobID" を使用して作成または更新されたリソースの一覧を取得できます。
Note
ジョブが完了する前にこの呼び出しを行うと、失敗します。 さらに、正常に完了したリソースのみが返されます。キャンセルの場合は、取り消し前に完了したリソースのみが返されます。
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
要求のサンプル:
次の例では、GET 要求を使用して、新しい SaaS 製品を作成した前の例で使用した構成要求の概要の詳細を取得します。 応答は、作成された製品リソースとその永続 ID を含むリソース配列を持つ configure-detail オブジェクトです。
GET https://graph.microsoft.com/rp/product-ingestion/configure/071b135e-9faf-4ff7-b113-a3f25bb0f468?$version=2022-03-01-preview2
応答の例:
{
"$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"
}
]
}
構成要求を取り消す
ジョブが完了する前に、必要に応じて取り消しを試みることができます。 "プレビュー" や "ライブ" への発行など、実行時間の長い要求の場合、ジョブが完全に処理されるのに十分な場合、キャンセル要求は拒否される可能性があります。
ジョブを取り消すには、キャンセル エンドポイントに POST 呼び出しを行い、取り消す要求のジョブ ID を指定します。
POST https://graph.microsoft.com/rp/product-ingestion/configure<jobID>/cancel?$version=2022-03-01-preview2
要求のサンプル:
POST <https://graph.microsoft.com/rp/product-ingestion/configure/d4261631-c583-4949-a612-5150882632e9/cancel?$version=2022-03-01-preview2>
キャンセル要求が成功した場合の応答のサンプル:
{
"$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": []
}
取り消しが許可されていない場合の応答例: HTTP Status code: 400
内容:
{
"error": {
"code": "badRequest",
"message": "Cannot cancel job, job has already completed.",
"details": []
}
}
重要
取り消しは、まだ処理されていないリソースにのみ適用されることに注意してください。 一部のリソースは既に処理を完了しており、要求の取り消しにもかかわらず、最新の構成更新プログラムを反映している可能性があります。
取り消し後に 構成要求 の概要をフェッチして、取り消しの前に既に処理されたリソース (ある場合) を確認できます。
プライベート対象ユーザーを同期する
ライブ製品の場合、ドラフト、プレビュー、ライブ環境のプライベート 対象ユーザーに対する更新は、公開を必要とせずに同時に実行できます。 特定のプランに追加または削除する対象ユーザーを指定することで、"price-and-availability-update-private-audience" リソースを使用してプライベート対象ユーザーを同期できます。 これにより、ドラフト、プレビュー、ライブ環境が同期され、プライベート対象ユーザーの値が同じになります。 プライベート対象ユーザーを同期するときに、申請リソースを指定する必要はありません。
ドラフト対象ユーザーを編集するには、"price-and-availability-plan" リソースと "privateAudiences" プロパティを使用します。 これは、プレビューとライブで設定する値の通常の発行フローを通過する必要があります。
重要
サポートされている対象ユーザーの種類は "subscription"、"ea"、"msdn"、"tenant" ですが、これらのサポートは製品の種類によって異なります。 プライベート対象ユーザーを構成するために複数の種類の識別子 (テナント ID とサブスクリプション 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/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"
}
]
}
}
]
}
リード管理の設定
顧客が関心を示したり、製品を展開したりしたときに顧客の連絡先情報を受け取ることができるように、顧客関係管理 (CRM) システムをコマーシャル マーケットプレース製品に接続します。 この接続は、製品の作成中または作成後にいつでも変更できます。 詳細については、「顧客リードを取得する」を参照してください。
リード管理を構成するためのサンプル要求:
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"
}
}
]
}
リソースのライフサイクル状態
リソースのライフサイクル状態にマップするために実行できるさまざまなアクションがあります。 すべてのリソースにライフサイクル状態があるわけではありません。また、すべてのライフサイクル状態がすべてのリソースでサポートされているわけではありません。 リソースにライフサイクル状態があり、どの値がサポートされているかを検出するには、プロパティ "lifecycleState" の存在についてリソース スキーマをチェックできます。 サポートされているさまざまなライフサイクル状態について、以下で詳しく説明します。
削除済み
"lifecycleState" プロパティを "deleted" に更新することで、特定のリソースを削除できます。 以前に公開されていないドラフト リソースのみを削除できます。 この削除操作は元に戻すことができません。
要求のサンプル:
次の例では、"基本" ドラフト プランが削除されます。
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"
}
]
}
"非推奨"
非推奨にすると、商用マーケットプレースからそのリソースが削除されます。 非推奨にするには、それをサポートするリソースで "lifecycleState" プロパティを "deprecated" に設定します。 廃止にはさまざまなレベルがあります。 すべての製品の種類では、製品全体とその中の個々のプランの非推奨がサポートされています。 非推奨のリソースを後で復元するには、"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/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"
}
]
}
プランを非推奨にする場合は、 "lifecycleState" プロパティを "非推奨" に変更し、非推奨を有効にするには変更を "プレビュー" に発行してから "ライブ" に発行する必要があります。 これは、製品レベルの非推奨とは異なり、非推奨はライブ環境で自動的に構成されます。
プランの廃止要求のサンプル:
次の例では、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"
}
]
}
製品の種類によって異なる非推奨のその他の形式があります。 SaaS、仮想マシン、コンテナーの廃止について 詳しく説明します。
一般に入手可能
generallyAvailable は、すべてのリソースの既定のライフサイクル状態です。 リソースが非推奨になったら、"lifecycleState" プロパティを "generallyAvailable" に戻すことで、リソースを復元できます。 非推奨の製品を復元するには、製品を公開してプレビューしてからライブにする必要があります。 SaaS、VM、コンテナーの例については、それぞれの記事を参照してください。
プランの復元要求のサンプル:
次の例では、プランを復元することを目的としています。 この変更を適用するには、後で申請リソースを使用してすべての方法を公開する必要があります。
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"
}
]
}
リソース API リファレンス
以下のスキーマ バージョンはプレビューにのみ適用され、API が一般公開されると変更されます。
Note
既存の使用可能なリソースとそのバージョンについては、resources-index を参照 してください。
製品の種類ごとの API ガイダンス
製品インジェスト API は、今後他の製品の種類で使用できるようになります。 サポートされる製品の種類が増えるにつれて、各製品の種類に固有のガイダンスが利用可能になります。
| 製品の種類 | 製品の種類固有のリソース |
|---|---|
| プライベート オファー | Product Ingestion API を使用してプライベート オファーを作成および管理する |
| SaaS | 製品インジェスト API を使用して SaaS オファーを作成および管理する |
| 仮想マシン | Product Ingestion API を使用して仮想マシン オファーを作成および管理する |
| Containers | Product Ingestion API を使用してコンテナー オファーを作成および管理する |
API のバージョンと更新プログラム
| 更新プログラム | 変更された内容 |
|---|---|
| 11-2023 | すべてのスキーマ エンドポイントが product-ingestion.azureedge.net から schema.mp.microsoft.com に更新されました |
| 12-2022 | 顧客リードの PC インジェスト API の新しいスキーマ バージョン 2022-03-01-preview3 が利用可能になりました。この API は、顧客リードの構成中に clientID と clientSecret を受け入れ、serverID と連絡先の電子メール フィールドのキャプチャを停止します。 新しいバージョンに切り替え、clientID と clientSecret を指定して、マーケットプレース オファー用の Marketo コネクタの構成を続行します。 新しいスキーマ URL: https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3 |
| 09-2022 | コンテナー プレビューのサポートがバージョン 2022-03-01-preview4 としてリリースされました |
| 08-2022 | サービスとしてのソフトウェア プレビューのサポートがバージョン 2022-03-01-preview3 としてリリースされる |
| 08-2022 | バージョン 2022-07-01 としてのプライベート オファーのパブリック リリース |
| 05-2022 | 仮想マシン プレビューのサポートがバージョン 2022-03-01-preview2 としてリリースされました |
次のステップ
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示