管理附加元件提交

發行項
07/05/2024

Microsoft Store 提交 API 提供可用來管理應用程式附加元件 (也稱為應用程式內產品或 IAP) 提交的方法。如需 Microsoft Store 提交 API 的簡介，包括使用 API 的先決條件，請參閱使用 Microsoft Store 服務建立和管理提交。

重要

如果您使用 Microsoft Store 提交 API 建立附加元件的提交，請務必只使用 API 對提交進行進一步變更，而不是在合作夥伴中心進行變更。如果您使用合作夥伴中心來變更您最初使用 API 建立的提交，您將無法再使用 API 變更或認可該提交。在某些情況下，提交可能會處於錯誤狀態，而無法在提交程序中繼續。如果發生這種情況，您必須刪除提交並建立新的提交。

管理附加元件提交的方法

使用下列方法來取得、建立、更新、認可或刪除附加元件提交。附加元件必須先存在於您的合作夥伴中心帳戶中，才能使用這些方法。您可以在合作夥伴中心建立附加元件，方法是定義其產品類型和產品識別碼或使用管理附加元件中所述的 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 應用程式與您的合作夥伴中心帳戶建立關聯，以及取得您的用戶端識別碼和金鑰。您只需要執行此動作一次，擁有用戶端識別碼和金鑰之後，您可以隨時重複使用它們，以建立新的 Azure AD 存取權杖。
取得 Azure AD 存取權杖。您必須將此存取權杖傳遞至 Microsoft Store 提交 API 中的方法。取得存取權杖之後，您在其到期之前有 60 分鐘的時間可以使用。權杖到期之後，您可以取得新的權杖。
在 Microsoft Store 提交 API 中執行下列方法。此方法會建立新的進行中提交，這是您上次發佈的提交複本。如需詳細資訊，請參閱建立附加元件提交。
```
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions
```
回應本文包含附加元件提交資源，其中包含新提交的識別碼、共用存取簽章 (SAS) URI，用於上傳提交的任何附加元件圖示至 Azure Blob 儲存體，以及新提交的所有資料 (例如清單和定價資訊)。

注意

SAS URI 可讓您存取 Azure 儲存體中的安全資源，而不需要帳戶金鑰。如需 SAS URI 及其搭配 Azure Blob 儲存體使用的背景資訊，請參閱共用存取簽章，第 1 部分：瞭解 SAS 模型和共用存取簽章，第 2 部分：建立和使用具有 Blob 記憶體的 SAS。
如果您要為提交新增圖示，請準備圖示，並將其新增至 ZIP 封存。
使用新提交的任何必要變更來更新附加元件提交資料，然後執行下列方法來更新提交。如需詳細資訊，請參閱更新附加元件提交。
```
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}
```
注意

如果您要為提交新增圖示，請務必更新提交資料，以參考 ZIP 封存中這些檔案的名稱和相對路徑。
如果您要新增提交的新圖示，請使用您稍早呼叫的 POST 方法回應本文中提供的 SAS URI，將 ZIP 封存上傳至 Azure Blob 儲存體。您可以使用不同的 Azure 程式庫在各種平台上執行這項操作，包括：
下列 C# 程式碼範例示範如何使用適用於 .NET 的 Azure 儲存體用戶端程式庫中的 CloudBlockBlob 類別，將 ZIP 封存上傳至 Azure Blob 儲存體。此範例假設 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
```
若要確認提交狀態，請檢閱回應本文中的狀態值。如果要求成功，此值應該從 CommitStarted 變更為 PreProcessing，如果要求中有錯誤，則變更為 CommitFailed。如果發生錯誤，statusDetails 欄位會包含有關錯誤的進一步詳細資料。
認可成功完成之後，提交會傳送至 Store 進行擷取。您可以使用先前的方法，或造訪合作夥伴中心，繼續監視提交進度。

程式碼範例

下列文章提供詳細的程式碼範例，示範如何以數種不同的程式設計語言建立附加元件提交：

StoreBroker PowerShell 模組

作為直接呼叫 Microsoft Store 提交 API 的替代方案，我們也提供開放原始碼 PowerShell 模組，以在 API 之上實作命令列介面。此模組稱為 StoreBroker。您可以使用此模組，從命令列管理應用程式、發行小眾測試版和附加元件提交，而不是直接呼叫 Microsoft Store 提交 API，您也可以直接瀏覽來源來查看更多如何呼叫此 API 的範例。 Microsoft 內會主動使用 StoreBroker 模組，作為許多第一方應用程式提交至市集的主要方式。

如需詳細資訊，請參閱 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	字串	提交的識別碼。此識別碼可在回應資料中取得，用於要求建立附加元件提交、取得所有附加元件，以及取得附加元件。針對在合作夥伴中心建立的提交，此識別碼也可以在合作夥伴中心提交頁面的 URL 中取得。
contentType	字串	附加元件中提供的內容類型。這可以是下列其中一值： NotSet BookDownload EMagazine ENewspaper MusicDownload MusicStream OnlineDataStorage VideoDownload VideoStream Asp OnlineDownload
關鍵字	陣列	用於附加元件最多達 10 個關鍵字的字串陣列。您的應用程式可以使用這些關鍵字來查詢附加元件。
存留期	字串	附加元件的存留期。這可以是下列其中一值： Forever OneDay ThreeDays FiveDays OneWeek TwoWeeks OneMonth TwoMonths ThreeMonths SixMonths OneYear
listings	object	索引鍵和值組的字典，其中每個索引鍵都是雙字母 ISO 3166-1 alpha-2 國家/地區代碼，而每個值都是包含附加元件清單資訊的清單資源。
價格	object	包含附加元件定價資訊的定價資源。
targetPublishMode	字串	提交的發佈模式。這可以是下列其中一值：立即手動 SpecificDate
targetPublishDate	字串	如果 targetPublishMode 設定為 SpecificDate，則會以 ISO 8601 格式顯示提交的發行日期。
標籤	字串	附加元件的自訂開發人員資料 (這項資訊先前稱為標籤)。
可視性	字串	附加元件可見度。這可以是下列其中一值：已隱藏公開私人 NotSet
status	字串	提交的狀態。這可以是下列其中一值：無已取消 PendingCommit CommitStarted CommitFailed PendingPublication 發佈已發行 PublishFailed PreProcessing PreProcessingFailed 認證 CertificationFailed 版本 ReleaseFailed
statusDetails	object	狀態詳細資料資源，其中包含提交狀態的其他詳細資料，包括任何錯誤的相關資訊。
fileUploadUrl	字串	用於上傳提交任何套件的共用存取簽章 (SAS) URI。如果您要為提交新增套件，請將包含套件的 ZIP 封存上傳至此 URI。如需詳細資訊，請參閱建立附加元件提交。
friendlyName	字串	提交的易記名稱，如合作夥伴中心所示。當您建立提交時，會產生此值。

清單資源

此資源包含附加元件的清單資訊。此資源有下列值。

值	類型	描述
description	字串	附加元件清單的描述。
圖示	object	包含附加元件清單圖示資料的圖示資源。
title	字串	附加元件清單的標頭。

圖示資源

此資源包含附加元件清單的圖示資料。此資源有下列值。

值	類型	描述
fileName	字串	您為提交上傳的 ZIP 封存中圖示檔案的名稱。圖示必須是 .png 檔案，且量值正好為 300 x 300 像素。
fileStatus	字串	圖示檔案的狀態。這可以是下列其中一值：無 PendingUpload 已上傳 PendingDelete

定價資源

此資源包含附加元件的定價資訊。此資源有下列值。

值	類型	描述
marketSpecificPricings	object	索引鍵和值組的字典，其中每個索引鍵都是雙字母 ISO 3166-1 alpha-2 國家/地區代碼，而每個值都是定價層。這些項目代表特定市場中附加元件的自訂價格。此字典中的任何項目都會覆寫指定市場中 priceId 值所指定的基本價格。
sales	陣列	已取代。銷售資源陣列，其中包含附加元件的銷售資訊。
priceId	字串	定價層指定附加元件的基本價格。
isAdvancedPricingModel	boolean	如果為 true，您的開發人員帳戶就能夠存取從 0.99 美元到 1999.99 美元擴充的定價層。如果為 false，您的開發人員帳戶就能夠存取從 0.99 美元到 999.99 美元原本的定價層。如需不同層級的詳細資訊，請參閱定價層。注意：此欄位是唯讀欄位。

銷售資源

此資源包含附加元件的銷售資訊。

重要

不再支援銷售資源，目前您無法使用 Microsoft Store 提交 API 取得或修改附加元件提交的銷售資料。未來，我們將更新 Microsoft Store 提交 API，推出以程式設計方式存取附加元件提交的銷售資訊新方法。

呼叫 GET 方法以取得附加元件提交之後，銷售值會是空的。您可以繼續使用合作夥伴中心來取得附加元件提交的銷售資料。
呼叫 PUT 方法來更新附加元件提交時，會忽略銷售值中的資訊。您可以繼續使用合作夥伴中心來變更附加元件提交的銷售資料。

此資源有下列值。

值	類型	Description
NAME	字串	銷售的名稱。
basePriceId	字串	要用於銷售基本價格的定價層。
startDate	字串	以 ISO 8601 格式顯示銷售開始日期。
endDate	字串	以 ISO 8601 格式顯示銷售結束日期。
marketSpecificPricings	object	索引鍵和值組的字典，其中每個索引鍵都是雙字母 ISO 3166-1 alpha-2 國家/地區代碼，而每個值都是定價層。這些項目代表特定市場中附加元件的自訂價格。此字典中的任何項目都會覆寫指定市場中 basePriceId 值所指定的基本價格。

狀態詳細資料資源

此資源包含提交狀態的其他詳細資料。此資源有下列值。

值	類型	描述
錯誤	object	狀態詳細資料資源的陣列，其中包含提交的錯誤詳細資料。
warnings	object	狀態詳細資料資源的陣列，其中包含提交的警告詳細資料。
certificationReports	object	認證報告資源的陣列，可提供存取至提交的認證報告資料。如果認證失敗，您可以檢查這些報告以取得詳細資訊。

狀態詳細資料資源

此資源包含有關提交的任何錯誤或警告的其他資訊。此資源有下列值。

值	類型	描述
code	字串	描述錯誤或警告類型的提交狀態代碼。
詳細資料	字串	包含有關問題的詳細資料訊息。

認證報告資源

此資源可讓您存取提交的認證報告資料。此資源有下列值。

值	類型	描述
date	字串	以 ISO 8601 格式產生報表的日期和時間。
reportUrl	字串	您可以存取報表的 URL。

列舉

這些方法會使用下列列舉。

定價層

下列值代表附加元件提交的定價資源中可用的定價層。

值	Description
基本	定價層未設定，使用附加元件的基本價格。
NotAvailable	附加元件無法在指定的區域中使用。
免費	附加元件是免費的。
Tierxxxx	指定附加元件的定價層字串，格式為 Tierxxxx。目前支援下列定價層的範圍：如果定價資源的值 isAdvancedPricingModel 為 true，則您帳戶的可用定價層值為 Tier1012 - Tier1424。如果定價資源的值 isAdvancedPricingModel 為 false，則您帳戶的可用定價層值為 Tier2 - Tier96。若要查看開發人員帳戶可用的定價層完整資料表，包括與每一層相關聯的市場特定價格，請前往 [定價和可用性] 查看合作夥伴中心中任何應用程式提交，然後在市場和自訂價格區段上按一下 [檢視資料表] 連結 (對於部分開發人員帳戶，此連結位於定價區段)。

提交狀態代碼

下列值代表提交的狀態代碼。

值	描述
None	未指定任何程式碼。
InvalidArchive	包含套件的 ZIP 封存無效，或具有無法辨識的封存格式。
MissingFiles	ZIP 封存沒有提交資料中列出的所有檔案，或檔案位於封存中的錯誤位置。
PackageValidationFailed	提交中的一或多個套件無法驗證。
InvalidParameterValue	要求主文中的其中一個參數無效。
InvalidOperation	您嘗試的作業無效。
InvalidState	您嘗試的作業對套件發行前小眾測試版的目前狀態無效。
ResourceNotFound	找不到指定的套件發行小眾測試版。
ServiceError	內部服務錯誤導致要求無法成功。請再次嘗試要求。
ListingOptOutWarning	開發人員已從先前提交中移除清單，或不包含套件所支援的清單資訊。
ListingOptInWarning	開發人員已新增清單。
UpdateOnlyWarning	開發人員正嘗試插入只有更新支援的項目。
其他	提交處於無法辨識或未分類的狀態。
PackageValidationWarning	套件驗證程式會產生警告。

共用方式為

管理附加元件提交

管理附加元件提交的方法

建立附加元件提交

程式碼範例

StoreBroker PowerShell 模組

資料資源

附加元件提交資源

清單資源

圖示資源

定價資源

銷售資源

狀態詳細資料資源

狀態詳細資料資源

認證報告資源

列舉

定價層

提交狀態代碼

意見反應

其他資源

共用方式為

管理附加元件提交

管理附加元件提交的方法

建立附加元件提交

程式碼範例

StoreBroker PowerShell 模組

資料資源

附加元件提交資源

清單資源

圖示資源

定價資源

銷售資源

狀態詳細資料資源

狀態詳細資料資源

認證報告資源

列舉

定價層

提交狀態代碼

相關主題

意見反應

其他資源