アドオンの申請の管理

[アーティクル]
04/06/2023

Microsoft Store 申請 API には、アプリのアドオン (アプリ内製品または IAP とも呼ばれます) 申請を管理するために使用できるメソッドが用意されています。 Microsoft Store 申請 API の概要については、「Microsoft Store サービスを使用した申請の作成と管理」をご覧ください。この API を使用するための前提条件などの情報があります。

重要

Microsoft Store 申請 API を使ってアドオンの提出を作成する場合、申請にさらに変更を加えるには、パートナーセンターで変更を行うのではなく API のみを使用してください。最初に API を使って作成した申請を、パートナーセンターを使って変更した場合、API を使ってその申請を変更またはコミットすることができなくなります。場合によっては、申請がエラー状態のままになり、申請プロセスを進めることができなくなります。この場合、申請を削除して新しい申請を作成する必要があります。

アドオンの申請を管理するためのメソッド

アドオンの申請を取得、作成、更新、コミット、または削除するには、次のメソッドを使用します。これらのメソッドを使用するには、アドオンをお客様自身のパートナーセンターアカウントに用意しておく必要があります。アドオンは、製品の種類と製品 ID を定義するか、「アドオンの管理」で説明されている Microsoft Store 申請 API のメソッドを使って、パートナーセンターで作成できます。

認証方法	URI	説明
GET	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	既存のアドオンの申請を取得します
GET	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status	既存のアドオンの申請の状態を取得します
POST	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions	新しいアドオンの申請を作成します
PUT	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	既存のアドオンの申請を更新します
POST	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit	新しいアドオンの申請または更新されたアドオンの申請をコミットします
DELETE	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	アドオンの申請の削除

アドオンの申請の作成

アドオンの申請を作成するには、次のプロセスに従います。

「Microsoft Store サービスを使用した申請の作成と管理」に記載されている前提条件が満たされていない場合は、前提条件を整えてください。これには、Azure AD アプリケーションのパートナーセンターアカウントへの関連付けや、クライアント ID およびキーの取得が含まれます。この作業は 1 度行うだけでよく、クライアント ID とキーを入手したら、新しい Azure AD アクセストークンの作成が必要になったときに、いつでもそれらを再利用できます。
Azure AD のアクセストークンを取得します。このアクセストークンを Microsoft Store 申請 API のメソッドに渡す必要があります。アクセストークンを取得した後、アクセストークンを使用できるのは、その有効期限が切れるまでの 60 分間です。トークンの有効期限が切れたら新しいトークンを取得できます。
Microsoft Store 申請 API の次のメソッドを実行します。このメソッドによって、新しい申請が作成され、審査中になります。これは、前回発行した申請のコピーです。詳しくは、「アドオンの申請の作成」をご覧ください。
```
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions
```
応答本文には、新しい申請の ID、申請用のアドオンアイコンを Azure Blob Storage にアップロードするための共有アクセス署名 (SAS) URI、および新しい申請のためのすべてのデータ (登録情報や料金情報など) を含むアドオンの申請リソースが含まれます。

注意

SAS URI では、アカウントキーを必要とせずに、Azure Storage 内のセキュリティで保護されたリソースにアクセスできます。 SAS URI の背景情報と Azure Blob Storage での SAS URI の使用については、「Shared Access Signatures、第 1 部: SAS モデルについて」と「Shared Access Signature、第 2 部: BLOB ストレージでの SAS の作成と使用」を参照してください。
申請用に新しいアイコンを追加する場合は、アイコンを準備して、ZIP アーカイブに追加します。
新しい申請用に必要な変更を行ってアドオンの申請データを更新し、次のメソッドを実行して申請を更新します。詳しくは、「アドオンの申請の更新」をご覧ください。
```
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}
```
注意

申請用に新しいアイコンを追加する場合、ZIP アーカイブ内のアイコンのファイルの名前と相対パスを参照するように、申請データを更新してください。
申請用に新しいアイコンを追加する場合は、上記で呼び出した POST メソッドの応答本文に含まれていた SAS URI を使用して、ZIP アーカイブを Azure Blob Storage にアップロードします。さまざまなプラットフォームでこれを行うために使用できる、次のようなさまざまな Azure ライブラリがあります。
次の C# コード例は、.NET 用 Azure Storage クライアントライブラリの CloudBlockBlob クラスを使って ZIP アーカイブを Azure Blob Storage にアップロードする方法を示しています。この例では、ZIP アーカイブが既にストリームオブジェクトに書き込まれていることを前提としています。
```
string sasUrl = "https://productingestionbin1.blob.core.windows.net/ingestion/26920f66-b592-4439-9a9d-fb0f014902ec?sv=2014-02-14&sr=b&sig=usAN0kNFNnYE2tGQBI%2BARQWejX1Guiz7hdFtRhyK%2Bog%3D&se=2016-06-17T20:45:51Z&sp=rwl";
Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob blockBob =
  new Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob(new System.Uri(sasUrl));
await blockBob.UploadFromStreamAsync(stream);
```
次のメソッドを実行して、申請をコミットします。これで、申請が完了し、更新がアカウントに適用されていることがパートナーセンターに通知されます。詳しくは、「アドオンの申請のコミット」をご覧ください。
```
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit
```
次のメソッドを実行して、コミットの状態を確認します。詳しくは、「アドオンの申請の状態の取得」をご覧ください。
```
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status
```
申請の状態を確認するには、応答本文の status の値を確認します。この値が CommitStarted から PreProcessing (要求が成功した場合) または CommitFailed (要求でエラーが発生した場合) に変わっています。エラーがある場合は、statusDetails フィールドにエラーについての詳細情報が含まれています。
コミットが正常に処理されると、インジェストのために申請がストアに送信されます。上記のメソッドを使うか、パートナーセンターのダッシュボードから、申請の進行状況を引き続き監視できます。

コード例

次の記事では、さまざまなプログラミング言語でアドオンの申請を作成する方法を説明する詳しいコード例を紹介します。

StoreBroker PowerShell モジュール

Microsoft Store 申請 API を直接呼び出す代わりに、API の上にコマンドラインインターフェイスを実装するオープンソースの PowerShell モジュールも用意されています。このモジュールは、StoreBroker と呼ばれています。このモジュールを使うと、Microsoft Store 申請 API を直接呼び出さずに、コマンドラインからアプリ、フライト、アドオンの申請を管理できます。また、ソースを参照して、この API を呼び出す方法の例を確認することもできます。 StoreBroker モジュールは、多くのファーストパーティアプリケーションをストアに申請する主要な方法として Microsoft 内で積極的に使っています。

詳しくは、GitHub の StoreBroker に関するページをご覧ください。

データリソース

アドオンの申請を管理するための Microsoft Store 申請 API のメソッドでは、次の JSON データリソースが使われます。

アドオンの申請のリソース

このリソースは、アドオンの申請を記述しています。

{
  "id": "1152921504621243680",
  "contentType": "EMagazine",
  "keywords": [
    "books"
  ],
  "lifetime": "FiveDays",
  "listings": {
    "en": {
      "description": "English add-on description",
      "icon": {
        "fileName": "add-on-en-us-listing2.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (English)"
    },
    "ru": {
      "description": "Russian add-on description",
      "icon": {
        "fileName": "add-on-ru-listing.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (Russian)"
    }
  },
  "pricing": {
    "marketSpecificPricings": {
      "RU": "Tier3",
      "US": "Tier4",
    },
    "sales": [],
    "priceId": "Free",
    "isAdvancedPricingModel": true
  },
  "targetPublishDate": "2016-03-15T05:10:58.047Z",
  "targetPublishMode": "Immediate",
  "tag": "SampleTag",
  "visibility": "Public",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [
      {
        "code": "None",
        "details": "string"
      }
    ],
    "warnings": [
      {
        "code": "ListingOptOutWarning",
        "details": "You have removed listing language(s): []"
      }
    ],
    "certificationReports": [
      {
      }
    ]
  },
  "fileUploadUrl": "https://productingestionbin1.blob.core.windows.net/ingestion/26920f66-b592-4439-9a9d-fb0f014902ec?sv=2014-02-14&sr=b&sig=usAN0kNFNnYE2tGQBI%2BARQWejX1Guiz7hdFtRhyK%2Bog%3D&se=2016-06-17T20:45:51Z&sp=rwl",
  "friendlyName": "Submission 2"
}

このリソースには、次の値があります。

値	種類	説明
id	string	申請 ID。この ID は、アドオンの申請の作成要求、すべてのアドオンの取得要求、アドオンの取得要求に対する応答データで確認できます。アプリの申請をパートナーセンターで作成した場合、この ID は、パートナーセンターの申請ページの URL でも確認できます。
contentType	string	アドオンで提供されているコンテンツの種類です。次のいずれかの値を指定できます。 NotSet BookDownload EMagazine ENewspaper MusicDownload MusicStream OnlineDataStorage VideoDownload VideoStream Asp OnlineDownload
keywords	array	アドオンのキーワードの文字列を最大 10 個含む配列です。アプリでは、これらのキーワードを使ってアドオンを照会できます。
有効期間	string	アドオンの有効期間です。次のいずれかの値を指定できます。無期限 OneDay ThreeDays FiveDays OneWeek TwoWeeks OneMonth TwoMonths ThreeMonths SixMonths OneYear
listings	object	キーと値のペアのディクショナリです。各キーは 2 文字の ISO 3166-1 alpha-2 の国コードで、各値はアドオンの登録情報が保持される登録情報リソースです。
価格	object	アドオンの価格設定情報が保持される価格リソースです。
targetPublishMode	string	申請の公開モードです。次のいずれかの値を指定できます。即時手動 SpecificDate
targetPublishDate	string	targetPublishMode が SpecificDate に設定されている場合、ISO 8601 形式での申請の公開日です。
tag	string	アドオンのカスタムの開発者データ(この情報は従来タグと呼ばれていました)。
参照可能範囲	string	アドオンの可視性です。次のいずれかの値を指定できます。非表示パブリックプライベート NotSet
status	string	申請の状態。次のいずれかの値を指定できます。なし Canceled PendingCommit CommitStarted CommitFailed PendingPublication 発行公開済み PublishFailed PreProcessing PreProcessingFailed 認定資格 CertificationFailed リリース ReleaseFailed
statusDetails	object	エラーに関する情報など、申請のステータスに関する追加情報が保持されるステータスの詳細に関するリソースです。
fileUploadUrl	string	申請のパッケージのアップロードに使用する共有アクセス署名 (SAS) URI です。申請用に新しいパッケージを追加する場合は、パッケージを含む ZIP アーカイブをこの URI にアップロードします。詳しくは、「アドオンの申請の作成」をご覧ください。
friendlyName	string	パートナーセンターに表示される申請のフレンドリ名です。この値は、申請を作成するときに生成されます。

登録情報リソース

このリソースにはアドオンの登録情報が保持されます。このリソースには、次の値があります。

値	種類	説明
description	string	アドオンの登録情報についての説明です。
icon	object	アドオンの登録情報に使用されるアイコンのデータが保持されるアイコンリソースです。
title	string	アドオンの登録情報のタイトルです。

アイコンリソース

このリソースにはアドオンの登録情報のアイコンデータが保持されます。このリソースには、次の値があります。

値	種類	説明
fileName	string	申請用にアップロードした ZIP アーカイブに含まれているアイコンファイルの名前です。このアイコンには、300 x 300 ピクセルの .png ファイルを使用する必要があります。
fileStatus	string	アイコンファイルの状態です。次のいずれかの値を指定できます。なし PendingUpload アップロード完了 PendingDelete

価格リソース

このリソースにはアドオンの価格設定情報が保持されます。このリソースには、次の値があります。

値	種類	説明
marketSpecificPricings	object	キーと値のペアのディクショナリです。各キーは 2 文字の ISO 3166-1 alpha-2 の国コードで、各値は価格帯です。これらの項目は、特定の市場でのアドオンのカスタム価格を表します。このディクショナリに含まれる項目は、指定された市場の priceId の値によって指定されている基本価格を上書きします。
営業	array	推奨されなくなった値です。アドオンの販売情報が保持されるセールリソースの配列です。
priceId	string	アドオンの基本価格を規定する価格帯です。
isAdvancedPricingModel	boolean	true の場合、開発者アカウントは 0.99 USD ～ 1999.99 USD の拡張された価格セットにアクセスできます。 false の場合、開発者アカウントは 0.99 USD ～ 999.99 USD の元の価格帯セットにアクセスできます。各種価格帯について詳しくは、「価格帯」をご覧ください。注このフィールドは読み取り専用です。

セールリソース

このリソースにはアドオンのセール情報が保持されます。

重要

セール リソースはサポートを終了しました。現在、Microsoft Store 申請 API を使ってアドオンの申請の販売データを取得または変更することはできません。将来的には、Microsoft Store 申請 API を更新して、アドオンの申請のセール情報にプログラムでアクセスする新しい方法を導入する予定です。

アドオンの申請を取得する GET メソッドを呼び出すと、セール リソースは空になります。引き続きパートナーセンターを使って、アドオン申請のセールデータを取得することができます。
アドオンの申請を更新する PUT メソッドを呼び出すとき、セールの値に含まれた情報は無視されます。引き続きパートナーセンターを使って、アドオン申請のセールデータを変更することができます。

このリソースには、次の値があります。

値	種類	説明
name	string	セールの名前です。
basePriceId	string	セールの基本価格として使用する価格帯です。
startDate	string	ISO 8601 形式で表したセールの開始日です。
endDate	string	ISO 8601 形式で表したセールの終了日です。
marketSpecificPricings	object	キーと値のペアのディクショナリです。各キーは 2 文字の ISO 3166-1 alpha-2 の国コードで、各値は価格帯です。これらの項目は、特定の市場でのアドオンのカスタム価格を表します。このディクショナリに含まれる項目は、指定された市場の basePriceId の値によって指定されている基本価格を上書きします。

ステータスの詳細に関するリソース

このリソースには、申請の状態についての追加情報が保持されます。このリソースには、次の値があります。

値	種類	説明
エラー	object	申請のエラーの詳細が保持されるステータスの詳細リソースの配列です。
warnings	object	申請の警告の詳細が保持されるステータスの詳細リソースの配列です。
certificationReports	object	申請の認定レポートデータへのアクセスを提供する認定レポートリソースです。認定されなかった場合に、これらのレポートから詳しい情報を知ることができます。

ステータスの詳細に関するリソース

このリソースには、申請に関連するエラーや警告についての追加情報が保持されます。このリソースには、次の値があります。

値	種類	説明
code	string	エラーや警告の種類を説明する申請ステータスコードです。
details	string	問題についての詳細が含まれるメッセージです。

認定レポートリソース

このリソースは、申請の認定レポートデータへのアクセスを提供します。このリソースには、次の値があります。

値	種類	説明
date	string	ISO 8601 形式で表された、レポートが生成された日付と時刻です。
reportUrl	string	レポートにアクセスできる URL です。

列挙型

これらのメソッドでは、次の列挙型が使用されます。

価格レベル

次の値は、価格リソースにおける、アドオンの申請に利用できる価格帯を表します。

値	説明
ベース	価格帯が設定されていない場合、アドオンの基本価格が使用されます。
NotAvailable	アドオンは指定された地域で提供されていません。
Free	アドオンは無償です。
Tierxxxx	アドオンの価格帯を指定する文字列 (Tierxxxx の形式)。現在のところ、次の範囲の価格帯がサポートされています。価格リソースの isAdvancedPricingModel 値が true の場合、アカウントで利用可能な価格帯値は Tier1012 - Tier1424 です。価格リソースの isAdvancedPricingModel 値が false の場合、アカウントで利用可能な価格帯値は Tier2 - Tier96 です。各価格帯に関連付けられた市場固有の価格を含む、開発者アカウントで利用可能な価格帯の詳しい表を参照するには、パートナーセンターでいずれかのアプリ申請の[価格と使用可能状況] ページにアクセスし、[市場と特別価格] セクションで [view table] (表を表示) リンクをクリックします (一部の開発者アカウントでは、このリンクは [Pricing] (価格) セクションにあります)。

申請の状態コード

次の値は、申請の状態コードを表します。

値	説明
なし	コードが指定されていません。
InvalidArchive	パッケージが含まれる ZIP アーカイブは無効であるか、認識できないアーカイブ形式です。
MissingFiles	ZIP アーカイブに、申請データで指定されているすべてのファイルが含まれていないか、ファイルのアーカイブ内の場所が正しくありません。
PackageValidationFailed	申請の 1 つ以上のパッケージを検証できませんでした。
InvalidParameterValue	要求本文に含まれるパラメーターの 1 つが無効です。
InvalidOperation	実行された操作は無効です。
InvalidState	実行された操作は、パッケージフライトの現在の状態では無効です。
ResourceNotFound	指定されたパッケージフライトは見つかりませんでした。
ServiceError	内部サービスエラーのため、要求を処理できませんでした。もう一度要求を行ってください。
ListingOptOutWarning	開発者が以前の申請の登録情報を削除しているか、パッケージによってサポートされる登録情報を含めていませんでした。
ListingOptInWarning	開発者が登録情報を追加しました。
UpdateOnlyWarning	開発者が、更新サポートしかないものを挿入しようとしています。
その他	申請が非認識または未分類の状態です。
PackageValidationWarning	パッケージ検証プロセスの結果、警告が生成されました。

次の方法で共有

アドオンの申請の管理

アドオンの申請を管理するためのメソッド

アドオンの申請の作成

コード例

StoreBroker PowerShell モジュール

データリソース

アドオンの申請のリソース

登録情報リソース

アイコンリソース

価格リソース

セールリソース

ステータスの詳細に関するリソース

ステータスの詳細に関するリソース

認定レポートリソース

列挙型

価格レベル

申請の状態コード

フィードバック

その他のリソース

次の方法で共有

アドオンの申請の管理

アドオンの申請を管理するためのメソッド

アドオンの申請の作成

コード例

StoreBroker PowerShell モジュール

データ リソース

アドオンの申請のリソース

登録情報リソース

アイコン リソース

価格リソース

セール リソース

ステータスの詳細に関するリソース

ステータスの詳細に関するリソース

認定レポート リソース

列挙型

価格レベル

申請の状態コード

関連トピック

フィードバック

その他のリソース

データリソース

アイコンリソース

セールリソース

認定レポートリソース