管理套件正式發行前小眾測試版提交

發行項
07/05/2024

Microsoft Store 提交 API 提供可用來管理應用程式套件正式發行前小眾測試版提交的方法，包括漸進式套件推出。如需 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/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}	取得現有的套件正式發行前小眾測試版提交
GET	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status	取得現有套件正式發行前小眾測試版提交的狀態
POST	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions	建立新的套件正式發行前小眾測試版提交
PUT	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}	更新現有的套件正式發行前小眾測試版提交
POST	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit	認可新的或更新的套件正式發行前小眾測試版提交
DELETE	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/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/applications/{applicationId}/flights/{flightId}/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/applications/{applicationId}/flights/{flightId}/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/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit
```
執行下列方法來取得套件正式發行前小眾測試版提交的狀態，以檢查認可狀態。
```
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status
```
若要確認提交狀態，請檢閱回應本文中的狀態值。如果要求成功，此值應該從 CommitStarted 變更為 PreProcessing，如果要求中有錯誤，則變更為 CommitFailed。如果發生錯誤，statusDetails 欄位會包含有關錯誤的進一步詳細資料。
認可成功完成之後，提交會傳送至 Store 進行擷取。您可以使用先前的方法，或造訪合作夥伴中心，繼續監視提交進度。

程式碼範例

下列文章提供詳細的程式碼範例，示範如何以數種不同的程式設計語言建立套件正式發行前小眾測試版提交：

StoreBroker PowerShell 模組

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

如需詳細資訊，請參閱 GitHub 上的 StoreBroker 頁面。

管理套件正式發行前小眾測試版提交的漸進式套件推出

您可以依照 Windows 10 和 Windows 11 上應用程式客戶的百分比逐漸推出套件正式發行前小眾測試版提交的更新套件。如此您就能監視特定套件的意見反應和分析資料，以確保更新沒有問題後再擴大推出。您可以變更已發佈提交的推出百分比 (或停止更新)，而不需要建立新的提交。如需詳細資訊，包括如何在合作夥伴中心啟用和管理漸進式套件推出的相關指示，請參閱這篇文章。

若要以程式設計方式啟用套件正式發行前小眾測試版提交的漸進式套件推出，請使用 Microsoft Store 提交 API 中的方法遵循此流程：

建立套件正式發行前小眾測試版提交或取得套件正式發行前小眾測試版提交。
在回應資料中，找到 packageRollout 資源，將 [isPackageRollout] 欄位設定為 true，然後將 [packageRolloutPercentage] 欄位設定為應該取得更新封裝的應用程式客戶百分比。
將更新的套件正式發行前小眾測試版提交資料傳遞至更新套件正式發行前小眾測試版提交方法。

在套件正式發行前小眾測試版啟用漸進式套件推出之後，您可以使用下列方法，以程式設計方式取得、更新、停止或完成漸進式推出。

方法	URI	描述
GET	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout	取得套件正式發行前小眾測試版提交的漸進式推出資訊
POST	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage	更新套件正式發行前小眾測試版提交的漸進式推出百分比
POST	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout	停止套件正式發行前小眾測試版提交的漸進式推出
POST	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout	完成套件正式發行前小眾測試版提交的漸進式推出

資料資源

管理套件正式發行前小眾測試版提交的 Microsoft Store 提交 API 方法會使用下列 JSON 資料資源。

正式發行前小眾測試版提交資源

此資源描述套件正式發行前小眾測試版提交。

{
  "id": "1152921504621243649",
  "flightId": "cd2e368a-0da5-4026-9f34-0e7934bc6f23",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [],
    "warnings": [],
    "certificationReports": []
  },
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
  "fileUploadUrl": "https://productingestionbin1.blob.core.windows.net/ingestion/8b389577-5d5e-4cbe-a744-1ff2e97a9eb8?sv=2014-02-14&sr=b&sig=wgMCQPjPDkuuxNLkeG35rfHaMToebCxBNMPw7WABdXU%3D&se=2016-06-17T21:29:44Z&sp=rwl",
  "targetPublishMode": "Immediate",
  "targetPublishDate": "",
  "notesForCertification": "No special steps are required for certification of this app."
}

此資源有下列值。

值	類型	描述
id	字串	提交的識別碼。
flightId	字串	提交相關聯的套件正式發行前小眾測試版識別碼。
status	字串	提交的狀態。這可以是下列其中一值：無已取消 PendingCommit CommitStarted CommitFailed PendingPublication 發佈已發行 PublishFailed PreProcessing PreProcessingFailed 認證 CertificationFailed 版本 ReleaseFailed
statusDetails	object	狀態詳細資料資源，其中包含提交狀態的其他詳細資料，包括任何錯誤的相關資訊。
flightPackages	陣列	包含正式發行前小眾測試版套件資源，提供提交中每個套件的詳細資訊。
packageDeliveryOptions	object	套件傳遞選項資源，其中包含提交的漸進式套件推出和強制更新設定。
fileUploadUrl	字串	用於上傳提交任何套件的共用存取簽章 (SAS) URI。如果您要為提交新增套件，請將包含套件的 ZIP 封存上傳至此 URI。如需詳細資訊，請參閱建立套件正式發行前小眾測試版提交。
targetPublishMode	字串	提交的發佈模式。這可以是下列其中一值：立即手動 SpecificDate
targetPublishDate	字串	如果 targetPublishMode 設定為 SpecificDate，則會以 ISO 8601 格式顯示提交的發行日期。
notesForCertification	字串	提供認證測試人員的額外資訊，例如：測試帳戶憑證，以及存取和驗證功能的步驟。如需詳細資訊，請參閱認證注意事項。

狀態詳細資料資源

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

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

狀態詳細資料資源

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

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

認證報告資源

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

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

正式發行前小眾測試版套件資源

此資源提供提交中套件的詳細資料。

{
  "flightPackages": [
    {
      "fileName": "newPackage.appx",
      "fileStatus": "PendingUpload",
      "id": "",
      "version": "1.0.0.0",
      "languages": ["en-us"],
      "capabilities": [],
      "minimumDirectXVersion": "None",
      "minimumSystemRam": "None"
    }
  ],
}

此資源有下列值。

注意

呼叫更新套件正式發行前小眾測試版提交方法時，只需要回應本文中此物件的 fileName、fileStatus、minimumDirectXVersion 和 minimumSystemRam 值。合作夥伴中心會填入其他值。

值	類型	描述
fileName	字串	封裝的名稱。
fileStatus	字串	套件的狀態。這可以是下列其中一值：無 PendingUpload 已上傳 PendingDelete
id	字串	可唯一識別套件的識別碼。此值是由合作夥伴中心使用。
version	字串	應用程式套件的版本。如需詳細資訊，請參閱套件版本編號方法。
架構	字串	應用程式套件的架構 (例如 ARM)。
語言	陣列	應用程式支援語言的語言代碼陣列。如需詳細資訊，請參閱支持的語言。
能力	陣列	套件所需的功能陣列。如需功能的詳細資訊，請參閱應用程式功能宣告。
minimumDirectXVersion	字串	應用程式套件所支援的最低 DirectX 版本。這僅適用於以 Windows 8.x 為目標的應用程式設定，若為以其他版本為目標的應用程式，則會忽略它。這可以是下列其中一值：無 DirectX93 DirectX100
minimumSystemRam	字串	應用程式套件所需的最低 RAM。這僅適用於以 Windows 8.x 為目標的應用程式設定，若為以其他版本為目標的應用程式，則會忽略它。這可以是下列其中一值：無 Memory2GB

套件傳遞選項資源

此資源包含提交的漸進式套件推出和強制更新設定。

{
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
}

此資源有下列值。

值	類型	描述
packageRollout	object	套件推出資源，其中包含提交的漸進式套件推出設定。
isMandatoryUpdate	boolean	指出您是否要將此提交中的套件視為自我安裝應用程式更新的必要項目。如需自我安裝應用程式更新的必要套件詳細資訊，請參閱下載並安裝應用程式的套件更新。
mandatoryUpdateEffectiveDate	date	此提交中的套件日期和時間變成必要，要以 ISO 8601 格式和 UTC 時區顯示。

套件推出資源

此資源包含提交的漸進式套件推出設定。此資源有下列值。

值	類型	描述
isPackageRollout	boolean	指出是否針對提交啟用漸進式套件推出。
packageRolloutPercentage	float	在漸進式推出中接收到套件的使用者百分比。
packageRolloutStatus	字串	下列其中一個字串，指出漸進式套件推出的狀態： PackageRolloutNotStarted PackageRolloutInProgress PackageRolloutComplete PackageRolloutStopped
fallbackSubmissionId	字串	不會取得漸進式推出套件的客戶所收到的提交識別碼。

注意

packageRolloutStatus 和 fallbackSubmissionId 值是由合作夥伴中心指派，並非預計由開發人員設定。如果您在要求本文中包含這些值，則會忽略這些值。

列舉

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

提交狀態代碼

下列程式碼代表提交的狀態。

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

共用方式為

管理套件正式發行前小眾測試版提交

管理套件正式發行前小眾測試版提交的方法

建立套件發行小眾測試版提交

程式碼範例

StoreBroker PowerShell 模組

管理套件正式發行前小眾測試版提交的漸進式套件推出

資料資源

正式發行前小眾測試版提交資源

狀態詳細資料資源

狀態詳細資料資源

認證報告資源

正式發行前小眾測試版套件資源

套件傳遞選項資源

套件推出資源

列舉

提交狀態代碼

意見反應

其他資源

共用方式為

管理套件正式發行前小眾測試版提交

管理套件正式發行前小眾測試版提交的方法

建立套件發行小眾測試版提交

程式碼範例

StoreBroker PowerShell 模組

管理套件正式發行前小眾測試版提交的漸進式套件推出

資料資源

正式發行前小眾測試版提交資源

狀態詳細資料資源

狀態詳細資料資源

認證報告資源

正式發行前小眾測試版套件資源

套件傳遞選項資源

套件推出資源

列舉

提交狀態代碼

相關主題

意見反應

其他資源