プライベートオファー送信 API の概要

[アーティクル]
01/02/2024

プライベートオファーでは、パブリッシャーは、カスタマイズした条件で期限付きの価格を作成し、Azure Marketplace で 1 つ以上の製品を顧客と取引できます。プライベートオファー申請 API を使用すると、パブリッシャーは、顧客や CSP パートナーのプライベートオファーをプログラムで作成および管理できます。この API は、Microsoft Entra ID を使用して、アプリまたはサービスからの呼び出しを認証します。

パートナーセンターで利用でき、プライベートオファー申請 API でサポートされているプライベートオファーには、次の 3 種類のメインがあります。

ISV から顧客へのプライベートオファー – パートナーセンターの顧客プライベートオファーとも呼ばれます。これは、AZURE Marketplace の特定の製品に対してカスタマイズされた用語と価格を持つ、ISV と特定の顧客との間のカスタム取引です。 ISV から顧客へのプライベートオファーの詳細をご覧ください。
ISV から CSP パートナーへのプライベートオファー – パートナーセンターの CSP パートナープライベートオファーとも呼ばれます。この種類のプライベートオファーを使用すると、ISV は期限付きマージンを指定して、CSP パートナーの卸売価格を作成できます。 CSP パートナーのプライベートオファーへの ISV の詳細について説明します。
マルチパーティプライベートオファー (MPO) – AZURE Marketplace の特定の製品に対してカスタマイズされた条件と価格を持つ特定の顧客の ISV と優先販売パートナーによって共同で構成されたカスタム取引。 ISV は、パートナーが利用できる割引卸売価格を定義し、販売パートナーは卸売価格の上にマークアップを追加して最終的な顧客価格に到達し、受け入れと購入のために顧客にオファーを提示できます。 MPO の受け入れと購入は、顧客のプライベートオファーに対する ISV と同じフローに従います。マルチパーティプライベートオファーについて詳しくは、こちらをご覧ください。

用語

MPO 発信者 – MPO は、特定の顧客に対して同じカスタム取引で ISV と販売パートナー間のコラボレーションであり、最初に MPO を作成する当事者は、オファーの "発信元" (通常は MPO に含まれる製品の ISV) に指定されます。特定の MPO に対して使用できる発信元は 1 つだけです。
MPO 販売者 – 最終的な顧客価格でオファーを準備し、顧客にオファーを提示する販売パートナーは、MPO の販売者です。特定の MPO の販売者は 1 つだけです。
製品 – Azure Marketplace でのオファーを表す 1 つのユニット。登録情報ページごとに 1 つの製品があります。
プラン – 特定の製品の 1 つのバージョン。特定の製品には、さまざまなレベルの価格または条件を表す複数のプランが存在する場合があります。
ジョブ – この API で要求を行うときに作成されるタスク。この API を使用してプライベートオファーとマルチパーティプライベートオファーを管理する場合は、要求を完了するためのジョブが作成されます。ジョブが完了すると、関連する (マルチパーティ) プライベートオファーに関する詳細情報を取得できます。

サポートされるシナリオ

この API を使用する準備をする

プライベートオファー API を呼び出すコードを書く前に、次の前提条件を満たしていることを確認してください。すべての公開パートナーにも同じ前提条件が適用されます。

手順 1: Microsoft Product Ingestion API を使うための前提条件を満たす (1 回限り)

ユーザーまたは組織には、Microsoft Entra ディレクトリとグローバル管理者のアクセス許可が必要です。 Microsoft 365 または Microsoft の他のビジネスサービスを既に使用している場合は、Microsoft Entra ディレクトリが既にあります。そうでない場合は、パートナーセンターで新しい Microsoft Entra ID を無料で作成できます。

Microsoft Entra ID アプリケーションをパートナーセンターアカウントに関連付け、テナント ID、クライアント ID、キーを取得する必要があります。プライベートオファー API の呼び出しで使用する Microsoft Entra アクセストークンを取得するには、これらの値が必要です。

手順 2: Microsoft Entra アクセストークンを取得する (毎回)

Microsoft Store 申請 API のいずれかのメソッドを呼び出す前に、API 内の各メソッドの承認ヘッダーに渡す Microsoft Entra アクセストークンが必要です。トークンは、60 分の有効期限が切れる前に使用します。有効期限が切れた後は、トークンを更新してそれ以降の API 呼び出しで引き続き使用できます。

アクセストークンを取得するには、「クライアント資格情報を使用したサービス間の呼び出し」を参照して、HTTP POST を https://login.microsoftonline.com/<tenant_id>/oauth2/token エンドポイントに送信します。要求のサンプルを次に示します。

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://graph.microsoft.com/

POST URI の tenant_id の値と client_id および client_secret のパラメーターには、前のセクションでパートナーセンターから取得したアプリケーションのテナント ID、クライアント ID、キーを指定します。リソースパラメーターには、次を指定 https://graph.microsoft.com/する必要があります。

製品、プラン、プライベートオファー ID を確認する

ID	検索する場所
client_id	「Microsoft Entra アプリケーションをパートナーセンターアカウントに関連付ける」を参照してください。
tenant_id	「Microsoft Entra アプリケーションをパートナーセンターアカウントに関連付ける」を参照してください。
client_secret	「Microsoft Entra アプリケーションをパートナーセンターアカウントに関連付ける」を参照してください。
productId	この記事の「製品を取得する」を参照してください。
planId	この記事の「特定の製品のプランを取得する」を参照してください。
privateofferId	この記事の「プライベートオファーを取得する」を参照してください。

製品を取得する

プライベートオファーは、パートナーセンターアカウントの既存の製品に基づいています。パートナーセンターアカウントに関連付けられている製品の一覧を表示するには、この API 呼び出しを使用します。

GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01

応答は、次のサンプル形式で表示されます。

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "type": "enum",
      "alias": "string"
    }
  ],
  "@nextLink": "opaque_uri"
}

特定の製品のプランを取得する

複数のプランを含む製品の場合は、1 つの特定のプランに基づいてプライベートオファーを作成できます。その場合は、そのプランの ID が必要です。次の API 呼び出しを使用して、製品のプラン (バリアントや SKU など) の一覧を取得します。

GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01

応答は、次のサンプル形式で表示されます。

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
      "product": "string",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "alias": "string"
    }
  ]
}

プライベートオファーを取得する

アカウントに関連付けられているマルチパーティプライベートオファーを含むすべてのプライベートオファーの一覧を表示するには、次の API 呼び出しを使用します。

GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15

API の使用方法

プライベートオファー API を使用すると、パートナーセンターアカウント内の製品とプランに関連付けられているプライベートオファーを作成および管理できます。この API を使用する場合の一般的な呼び出しパターンの概要を次に示します。

手順 1: 要求を行う

プライベートオファーを作成、削除、取り消し、またはアップグレードするための API 呼び出しを行うと、要求したタスクを完了するための新しいジョブが作成されます。 API 応答には、ジョブに関連付けられている jobId が含まれています。

手順 2: ジョブの状態をポーリングする

最初の API 応答の jobId を 使用して、ポーリングしてジョブの状態を取得します。ジョブの状態は [実行中] または [完了] になります。ジョブが完了すると、結果は [成功] または [失敗] になります。パフォーマンスの問題を回避するために、ジョブのポーリングは 1 分間に 1 回までにしてください。

ジョブステータス	説明
NotStarted	ジョブはまだ開始されていません。これは最初の要求の応答の一部です。
実行中	ジョブはまだ実行中です。
完了済み	ジョブが完了しました。詳細については、 jobResult を参照してください。
jobResult	説明
保留中	ジョブはまだ完了していません。
Succeeded	ジョブが正常に完了しました。このジョブは、ジョブに関連するプライベートオファーを参照する resourceURI も返します。この resourceURI は、プライベートオファーのすべての詳細を取得するために使用します。
Failed	ジョブは失敗しました。これにより、エラーの原因を特定するのに役立つ関連するエラーも返されます。

詳細については、「既存のジョブの状態を照会する」を参照してください。

手順 3: 完了したジョブから情報を取得する

成功したジョブは、関連するプライベートオファーを参照する resourceUri を返します。このリソース URI は、今後、プライベートオファーに関する詳細 (privateofferId など) を取得するために使用します。

失敗したジョブには、ジョブが失敗した理由と問題を解決する方法の詳細を示すエラーが含まれています。

詳細については、「既存のプライベートオファーの詳細を取得する」を参照してください。

ISV と販売パートナーがマルチパーティプライベートオファーに API を共同で使用する方法

ISV と販売パートナーの両方が、特定の MPO の作成と管理に同じ API を使用できます。ただし、API に影響を与える可能性がある MPO 内のリソースは、API の呼び出し元が MPO の ISV (発信元) か販売パートナー (販売者) かによって異なります。同じ ISV/販売パートナー発行フローと、パートナーセンターを管理するビジネスルールが API にミラーされます。概要を次に示します。

API 操作	ISV (発信元)	販売パートナー (販売者)
作成	対象ユーザーは、 API 呼び出しが投稿されたときに販売パートナー (販売者) です。エンドカスタマーは、販売パートナーが送信するまでプライベートオファーを表示しません編集可能なリソース: 発効日対象の受益者 (顧客) 販売パートナーがオファーで共同作業を行う(プライベートオファーあたり 1 個に制限) プライベートオファーの状態を通知する追加の ISV 連絡先 ISV カスタム使用条件プライベートオファーに含まれる製品/プラン各製品/プランの契約期間各製品に含まれる数量 (該当する場合) 予測不可能なプラン属性 (該当する場合) 含まれる製品/プランで販売パートナーが利用できる割引卸売価格 ISV 販売ノート	API 呼び出しが投稿されたときに、対象ユーザーがエンドカスタマーである編集可能なリソース: 販売パートナーのカスタム使用条件次の方法で準備します。プライベートオファーに含まれる各製品/プランの ISV 卸売価格に加える顧客調整 (マークアップ率) は、最終的なエンドカスタマー価格を決定しますプライベートオファーの状態を通知する追加の販売パートナーの連絡先販売パートナーの販売メモ
削除	ドラフト状態のプライベートオファーでサポートされます	サポートされていません
撤回	ISV によって公開されたプライベートオファーでサポートされていますが、販売パートナーによってまだ公開されていないか、販売パートナーによって引き出された場合	公開され、エンドカスタマーが利用できるプライベートオファーでサポートされていますが、まだ受け入れられません

API 操作

ISV (発信元)

販売パートナー (販売者)

作成

対象ユーザーは、 API 呼び出しが投稿されたときに販売パートナー (販売者) です。エンドカスタマーは、販売パートナーが送信するまでプライベートオファーを表示しません

編集可能なリソース:

発効日
対象の受益者 (顧客)
販売パートナーがオファーで共同作業を行う(プライベートオファーあたり 1 個に制限)
プライベートオファーの状態を通知する追加の ISV 連絡先
ISV カスタム使用条件
プライベートオファーに含まれる製品/プラン
各製品/プランの契約期間
各製品に含まれる数量 (該当する場合)
予測不可能なプラン属性 (該当する場合)
含まれる製品/プランで販売パートナーが利用できる割引卸売価格
ISV 販売ノート

API 呼び出しが 投稿されたときに、対象ユーザーがエンドカスタマー である

編集可能なリソース:

販売パートナーのカスタム使用条件
次の方法で準備します。
プライベートオファーに含まれる各製品/プランの ISV 卸売価格に加える顧客調整 (マークアップ率) は、最終的なエンドカスタマー価格を決定します
プライベートオファーの状態を通知する追加の販売パートナーの連絡先
販売パートナーの販売メモ

削除

ドラフト状態のプライベートオファーでサポートされます

サポートされていません

撤回

ISV によって公開されたプライベートオファーでサポートされていますが、販売パートナーによってまだ公開されていないか、販売パートナーによって引き出された場合

公開され、エンドカスタマーが利用できるプライベートオファーでサポートされていますが、まだ受け入れられません

Share via

プライベートオファー送信 API の概要

用語

サポートされるシナリオ

この API を使用する準備をする

手順 1: Microsoft Product Ingestion API を使うための前提条件を満たす (1 回限り)

手順 2: Microsoft Entra アクセストークンを取得する (毎回)

製品、プラン、プライベートオファー ID を確認する

製品を取得する

特定の製品のプランを取得する

プライベートオファーを取得する

API の使用方法

手順 1: 要求を行う

手順 2: ジョブの状態をポーリングする

手順 3: 完了したジョブから情報を取得する

ISV と販売パートナーがマルチパーティプライベートオファーに API を共同で使用する方法

次のステップ

フィードバック

フィードバック

その他のリソース

Share via

プライベート オファー送信 API の概要

用語

サポートされるシナリオ

この API を使用する準備をする

手順 1: Microsoft Product Ingestion API を使うための前提条件を満たす (1 回限り)

手順 2: Microsoft Entra アクセス トークンを取得する (毎回)

製品、プラン、プライベート オファー ID を確認する

製品を取得する

特定の製品のプランを取得する

プライベート オファーを取得する

API の使用方法

手順 1: 要求を行う

手順 2: ジョブの状態をポーリングする

手順 3: 完了したジョブから情報を取得する

ISV と販売パートナーがマルチパーティ プライベート オファーに API を共同で使用する方法

次のステップ

フィードバック

フィードバック

その他のリソース

プライベートオファー送信 API の概要

手順 2: Microsoft Entra アクセストークンを取得する (毎回)

製品、プラン、プライベートオファー ID を確認する

プライベートオファーを取得する

ISV と販売パートナーがマルチパーティプライベートオファーに API を共同で使用する方法