建立及管理提交Create and manage submissions

使用Microsoft Store 提交 API ,以程式設計方式針對您的或貴組織的合作夥伴中心帳戶,查詢並建立應用程式、附加元件和包裹航班的提交。Use the Microsoft Store submission API to programmatically query and create submissions for apps, add-ons and package flights for your or your organization's Partner Center account. 如果您的帳戶管理多個應用程式或附加元件,而且您想要自動化與最佳化這些資產的提交程序,這個 API 非常有用。This API is useful if your account manages many apps or add-ons, and you want to automate and optimize the submission process for these assets. 這個 API 使用 Azure Active Directory (Azure AD) 來驗證您應用程式或服務的呼叫。This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

下列步驟說明使用 Microsoft Store 提交 API 的端對端處理程序︰The following steps describe the end-to-end process of using the Microsoft Store submission API:

  1. 請確定您已經完成所有先決條件Make sure that you have completed all the prerequisites.
  2. 在呼叫 Microsoft Store 提交 API 中的方法之前,請先取得 Azure AD 存取權杖Before you call a method in the Microsoft Store submission API, obtain an Azure AD access token. 取得權杖之後,在權杖到期之前,您有 60 分鐘的時間可以使用這個權杖呼叫 Microsoft Store 提交 API。After you obtain a token, you have 60 minutes to use this token in calls to the Microsoft Store submission API before the token expires. 權杖到期之後,您可以產生新的權杖。After the token expires, you can generate a new token.
  3. 呼叫 Microsoft Store 提交 APICall the Microsoft Store submission API.

重要

如果您使用此 API 來建立應用程式、套件航班或附加元件的提交,請務必使用 API (而不是在合作夥伴中心)對提交進行進一步變更。If you use this API to create a submission for an app, package flight, or add-on, be sure to make further changes to the submission only by using the API, rather than in Partner Center. 如果您使用合作夥伴中心來變更原本使用 API 所建立的提交,則您將無法再使用 API 來變更或認可該提交。If you use Partner Center to change a submission that you originally created by using the API, you will no longer be able to change or commit that submission by using the API. 有時候提交可能會處於錯誤狀態,而無法繼續提交過程。In some cases, the submission could be left in an error state where it cannot proceed in the submission process. 若發生這種情形,您必須刪除提交並建立新的提交。If this occurs, you must delete the submission and create a new submission.

重要

您無法使用此 API 來發佈 透過商務用 Microsoft Store 和教育用 Microsoft Store 大量購買 的提交或直接向企業發佈 LOB 應用程式 的提交。You cannot use this API to publish submissions for volume purchases through the Microsoft Store for Business and Microsoft Store for Education or to publish submissions for LOB apps directly to enterprises. 在這兩種情況下,您都必須使用 [在合作夥伴中心發佈提交]。For both of these scenarios, you must use publish the submission in Partner Center.

注意

此 API 無法搭配應用程式或使用強制性應用程式更新以及 Microsoft Store 管理的可消耗附加元件的附加元件來使用。This API cannot be used with apps or add-ons that use mandatory app updates and Store-managed consumable add-ons. 如果您將 Microsoft Store 提交 API 用於使用上述其中一個功能的 App 或附加元件,API 將會傳回 409 錯誤碼。If you use the Microsoft Store submission API with an app or add-on that uses one of these features, the API will return a 409 error code. 在此情況下,您必須使用 [合作夥伴中心] 來管理應用程式或附加元件的提交。In this case, you must use Partner Center to manage the submissions for the app or add-on.

步驟 1︰完成使用 Microsoft Store 提交 API 的先決條件Step 1: Complete prerequisites for using the Microsoft Store submission API

開始撰寫程式碼以呼叫 Microsoft Store 提交 API 之前,請先確定您已完成下列先決條件。Before you start writing code to call the Microsoft Store submission API, make sure that you have completed the following prerequisites.

  • 您 (或您的組織) 必須擁有 Azure AD 目錄,而且您必須具備目錄的全域系統管理員權限。You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. 如果您已經使用 Office 365 或其他 Microsoft 所提供的商務服務,您就已經擁有 Azure AD 目錄。If you already use Office 365 or other business services from Microsoft, you already have Azure AD directory. 否則,您可以在合作夥伴中心建立新的 Azure AD ,而不需要額外付費。Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • 您必須將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯,並取得您的租使用者識別碼、用戶端識別碼和金鑰。You must associate an Azure AD application with your Partner Center account and obtain your tenant ID, client ID and key. 您需要這些值才能取得 Azure AD 存取權杖,您將會在呼叫 Microsoft Store 提交 API 時使用權杖。You need these values to obtain an Azure AD access token, which you will use in calls to the Microsoft Store submission API.

  • 準備您的 App 與 Microsoft Store 提交 API 搭配使用︰Prepare your app for use with the Microsoft Store submission API:

    • 如果您的應用程式尚未存在於合作夥伴中心,您必須在合作夥伴中心保留其名稱,以建立您的應用程式If your app does not yet exist in Partner Center, you must create your app by reserving its name in Partner Center. 您無法使用 Microsoft Store 提交 API 在合作夥伴中心建立應用程式;您必須在合作夥伴中心工作以建立它,然後您就可以使用 API 來存取應用程式,並以程式設計方式為它建立提交。You cannot use the Microsoft Store submission API to create an app in Partner Center; you must work in Partner Center to create it, and then after that you can use the API to access the app and programmatically create submissions for it. 不過,您可以使用 API 以程式設計方式建立附加元件和套件正式發行前小眾測試版,再建立提交。However, you can use the API to programmatically create add-ons and package flights before you create submissions for them.

    • 在您可以使用此 API 為指定的應用程式建立提交之前,您必須先在合作夥伴中心為該應用程式建立一個提交,包括回答年齡分級問卷。Before you can create a submission for a given app using this API, you must first create one submission for the app in Partner Center, including answering the age ratings questionnaire. 執行這個動作之後,您就能夠使用 API 以程式設計方式建立此 App 的新提交。After you do this, you will be able to programmatically create new submissions for this app using the API. 您不需要先建立附加元件提交或套件正式發行前小眾測試版提交,才能使用 API 進行這些類型的提交。You do not need to create an add-on submission or package flight submission before using the API for those types of submissions.

    • 如果您要建立或更新 App 提交,而且必須包含 App 套件,請準備 App 套件If you are creating or updating an app submission and you need to include an app package, prepare the app package.

    • 如果您要建立或更新 App 提交,而且必須包含市集清單的螢幕擷取畫面或影像,請準備 App 螢幕擷取畫面與影像If you are creating or updating an app submission and you need to include screenshots or images for the Store listing, prepare the app screenshots and images.

    • 如果您要建立或更新附加元件提交,而且必須包含圖示,請準備圖示If you are creating or updating an add-on submission and you need to include an icon, prepare the icon.

如何將 Azure AD 應用程式與您的合作夥伴中心帳戶產生關聯How to associate an Azure AD application with your Partner Center account

您必須先將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯、取得應用程式的租使用者識別碼和用戶端識別碼,並產生金鑰,您才能使用 Microsoft Store 提交 API。Before you can use the Microsoft Store submission API, you must associate an Azure AD application with your Partner Center account, retrieve the tenant ID and client ID for the application and generate a key. Azure AD 應用程式代表您要呼叫 Microsoft Store 提交 API 的 App 或服務。The Azure AD application represents the app or service from which you want to call the Microsoft Store submission API. 您需要租用戶識別碼、用戶端識別碼和金鑰,才能取得傳遞給 API 的 Azure AD 存取權杖。You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

注意

您只需要執行此工作一次。You only need to perform this task one time. 有了租用戶識別碼、用戶端識別碼和金鑰,每當您必須建立新的 Azure AD 存取權杖時,就可以重複使用它們。After you have the tenant ID, client ID and key, you can reuse them any time you need to create a new Azure AD access token.

  1. 在合作夥伴中心,將組織的合作夥伴中心帳戶與組織的 Azure AD 目錄建立關聯In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. 接下來,從 [合作夥伴中心] 的 [帳戶設定] 區段中的 [使用者] 頁面,新增代表您將用來存取合作夥伴中心帳戶提交之應用程式或服務的Azure AD 應用程式Next, from the Users page in the Account settings section of Partner Center, add the Azure AD application that represents the app or service that you will use to access submissions for your Partner Center account. 請確定您指派此應用程式 [管理員] 角色。Make sure you assign this application the Manager role. 如果您的 Azure AD 目錄中尚未存在該應用程式,您可以在合作夥伴中心建立新的 Azure AD 應用程式If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. 返回 [使用者] 頁面,按一下您 Azure AD 應用程式的名稱來移至應用程式設定,然後複製 [租用戶識別碼][用戶端識別碼] 的值。Return to the Users page, click the name of your Azure AD application to go to the application settings, and copy down the Tenant ID and Client ID values.

  4. 按一下 [加入新的金鑰]Click Add new key. 在下列畫面中,複製 [金鑰] 的值。On the following screen, copy down the Key value. 您離開這個頁面之後就無法再存取此資訊。You won't be able to access this info again after you leave this page. 如需詳細資訊,請參閱管理 Azure AD 應用程式的金鑰For more information, see Manage keys for an Azure AD application.

步驟 2:取得 Azure AD 存取權杖Step 2: Obtain an Azure AD access token

在 Microsoft Store 提交 API 中呼叫任何方法之前,您必須先取得傳遞至 API 中每個方法的 Authorization 標頭的 Azure AD 存取權杖。Before you call any of the methods in the Microsoft Store submission API, you must first obtain an Azure AD access token that you pass to the Authorization header of each method in the API. 在您取得存取權杖之後,您在權杖到期之前有 60 分鐘的時間可以使用權杖。After you obtain an access token, you have 60 minutes to use it before it expires. 權杖到期之後,您可以重新整理權杖以便在後續呼叫 API 時繼續使用。After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

若要取得存取權杖,請按照使用用戶端認證的服務對服務呼叫中的指示,將 HTTP POST 傳送至 https://login.microsoftonline.com/<tenant_id>/oauth2/token 端點。To obtain the access token, follow the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. 以下是範例要求。Here is a sample request.

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://manage.devcenter.microsoft.com

針對 [POST URI] 和 [用戶端_識別碼] 和 [用戶端 _密碼] 參數中的租使用者_識別碼值,指定您在上一節中從合作夥伴中心抓取之應用程式的租使用者識別碼、用戶端識別碼和金鑰。For the tenant_id value in the POST URI and the client_id and client_secret parameters, specify the tenant ID, client ID and the key for your application that you retrieved from Partner Center in the previous section. 對於 resource 參數,您必須指定 https://manage.devcenter.microsoft.comFor the resource parameter, you must specify https://manage.devcenter.microsoft.com.

存取權杖到期之後,您可以按照這裡的指示,重新整理權杖。After your access token expires, you can refresh it by following the instructions here.

如需示範如何使用 C#、Java 或 Python 程式碼來取得存取權杖的範例,請參閱 Microsoft Store 提交 API 程式碼範例For examples that demonstrate how to obtain an access token by using C#, Java, or Python code, see the Microsoft Store submission API code examples.

步驟 3:使用 Microsoft Store 提交 APIStep 3: Use the Microsoft Store submission API

取得 Azure AD 存取權杖之後,您就可以呼叫 Microsoft Store 提交 API 中的方法。After you have an Azure AD access token, you can call methods in the Microsoft Store submission API. API 包含許多方法,可以分成適用於 App、附加元件與套件正式發行前小眾測試版的案例。The API includes many methods that are grouped into scenarios for apps, add-ons, and package flights. 若要建立或更新提交,您通常要以特定順序呼叫 Microsoft Store 提交 API 中的多個方法。To create or update submissions, you typically call multiple methods in the Microsoft Store submission API in a specific order. 如需每個案例及每個方法之語法的相關資訊,請參閱下表中的文章。For information about each scenario and the syntax of each method, see the articles in the following table.

注意

取得存取權杖之後,在權杖到期之前,您有 60 分鐘的時間可以呼叫 Microsoft Store 提交 API 中的方法。After you obtain an access token, you have 60 minutes to call methods in the Microsoft Store submission API before the token expires.

案例Scenario 描述Description
應用程式Apps 針對已註冊至合作夥伴中心帳戶的所有應用程式,以及建立應用程式的提交,取得其資料。Retrieve data for all the apps that are registered to your Partner Center account and create submissions for apps. 如需這些方法的詳細資訊,請參閱下列文章:For more information about these methods, see the following articles:
附加元件Add-ons 取得、建立或刪除您 App 的附加元件,然後取得、建立或刪除附加元件的提交。Get, create, or delete add-ons for your apps, and then get, create, or delete submissions for the add-ons. 如需這些方法的詳細資訊,請參閱下列文章:For more information about these methods, see the following articles:
套件正式發行前小眾測試版Package flights 取得、建立或刪除您 App 的套件正式發行前小眾測試版,然後取得、建立或刪除套件正式發行前小眾測試版的提交。Get, create, or delete package flights for your apps, and then get, create, or delete submissions for the package flights. 如需這些方法的詳細資訊,請參閱下列文章:For more information about these methods, see the following articles:

程式碼範例Code examples

下列文章提供詳細的程式碼範例,示範如何以多個不同的程式設計語言使用 Microsoft Store 提交 API:The following articles provide detailed code examples that demonstrate how to use the Microsoft Store submission API in several different programming languages:

StoreBroker PowerShell 模組StoreBroker PowerShell module

另一種直接呼叫 Microsoft Store 提交 API 的方法,我們也提供了開放原始碼 PowerShell 模組,該模組在 API 上方實作命令列介面。As an alternative to calling the Microsoft Store submission API directly, we also provide an open-source PowerShell module which implements a command-line interface on top of the API. 這個模組稱為 StoreBrokerThis module is called StoreBroker. 您可以使用此模組從命令列來管理您的應用程式、正式發行前小眾測試版和附加元件提交,而不是直接直接呼叫 Microsoft Store 提交 API,也可以簡單瀏覽來源以檢視有關如何呼叫此 API 的更多範例。You can use this module to manage your app, flight, and add-on submissions from the command line instead of calling the Microsoft Store submission API directly, or you can simply browse the source to see more examples for how to call this API. StoreBroker 模組在 Microsoft 中積極地被用作為將眾多第一方應用程式提交至 Microsoft Store 的主要方式。The StoreBroker module is actively used within Microsoft as the primary way that many first-party applications are submitted to the Store.

如需詳細資訊,請查看我們在 GitHub 上的 StoreBroker 頁面For more information, see our StoreBroker page on GitHub.

疑難排解Troubleshooting

問題Issue 解析度Resolution
從 PowerShell 呼叫 Microsoft Store 提交 API 之後,如果您使用 ConvertFrom-Json Cmdlet 從 JSON 格式轉換為 PowerShell 物件,然後使用 ConvertTo-Json Cmdlet 轉換回 JSON 格式,API 的回應資料會損毀。After calling the Microsoft Store submission API from PowerShell, the response data for the API is corrupted if you convert it from JSON format to a PowerShell object using the ConvertFrom-Json cmdlet and then back to JSON format using the ConvertTo-Json cmdlet. ConvertTo-Json Cmdlet 的 -Depth 參數預設是設為 2 層物件,這對於 Microsoft Store 提交 API 傳回的大部分 JSON 物件來說太淺。By default, the -Depth parameter for the ConvertTo-Json cmdlet is set to 2 levels of objects, which is too shallow for most of the JSON objects that are returned by the Microsoft Store submission API. 當您呼叫 ConvertTo-Json Cmdlet 時,請將 -Depth 參數設為較大的數字,例如 20。When you call the ConvertTo-Json cmdlet, set the -Depth parameter to a larger number, such as 20.

其他說明Additional help

如果您有 Microsoft Store 提交 API 的相關問題,或需要使用這個 API 管理提交的協助,請使用下列資源︰If you have questions about the Microsoft Store submission API or need assistance managing your submissions with this API, use the following resources:

  • 在我們的論壇發問。Ask your questions on our forums.
  • 請造訪我們的支援頁面,並向合作夥伴中心要求其中一個協助支援選項。Visit our support page and request one of the assisted support options for Partner Center. 如果系統提示您選擇問題類型以及類別,請分別選擇 App 提交和認證以及提交 AppIf you are prompted to choose a problem type and category, choose App submission and certification and Submitting an app, respectively.