Gerenciar envios de pacote de pré-lançamento
A API de envio da Microsoft Store fornece métodos que você pode usar para gerenciar envios de pacotes de pré-lançamento para seus aplicativos, incluindo distribuições graduais de pacotes. Para obter uma introdução à API de envio da Microsoft Store, incluindo pré-requisitos para usar a API, consulte Criar e gerenciar envios usando os serviços da Microsoft Store.
Importante
Se você usar a API de envio da Microsoft Store para criar um envio para um pacote de pré-lançamento, certifique-se de fazer mais alterações no envio somente usando a API, em vez do Partner Center. Se você usar o painel para alterar um envio criado originalmente usando a API, não poderá mais alterar ou confirmar esse envio usando a API. Em alguns casos, o envio pode ser deixado em um estado de erro onde não pode prosseguir no processo de envio. Se isso ocorrer, você deverá excluir o envio e criar um novo envio.
Métodos para gerenciar envios de pacotes de pré-lançamento
Use os métodos a seguir para obter, criar, atualizar, confirmar ou excluir um envio de pacote de pré-lançamento. Antes de usar esses métodos, o pacote de pré-lançamento já deve existir no Partner Center. Você pode criar um pacote de pré-lançamento no Partner Center ou usando os métodos de API de envio da Microsoft Store descritos em Gerenciar pacotes de pré-lançamento.
| Método | URI | Descrição |
|---|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | Obter um envio de pacote de pré-lançamento existente |
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status | Obter o status de um envio de pacote de pré-lançamento existente |
| POSTAR | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions | Criar um novo envio de pacote de pré-lançamento |
| PUT | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | Atualizar um envio de pacote de pré-lançamento existente |
| POSTAR | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit | Confirmar um envio de pacote de pré-lançamento novo ou atualizado |
| DELETE | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | Excluir um envio de pacote de pré-lançamento |
Criar um envio de pacote de pré-lançamento
Para criar um envio para um pacote de pré-lançamento, siga este processo.
Se você ainda não tiver feito isso, conclua os pré-requisitos descritos em Criar e gerenciar envios usando os serviços da Microsoft Store, incluindo associar um aplicativo do Azure AD à sua conta do Partner Center e obter sua ID e chave de cliente. Você só precisa fazer isso uma vez; depois de ter o ID e a chave do cliente, você poderá reutilizá-los sempre que precisar criar um novo token de acesso do Azure AD.
Obter um token de acesso do Azure AD. Você deve passar esse token de acesso para os métodos na API de envio da Microsoft Store. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá obter um novo.
Crie um envio de pacote de pré-lançamento executando o método a seguir na API de envio da Microsoft Store. Esse método cria um novo envio em andamento, que é uma cópia do último envio publicado.
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissionsO corpo da resposta contém um recurso de envio de pré-lançamento que inclui a ID do novo envio, o URI da SAS (assinatura de acesso compartilhado) para carregar todos os pacotes para o envio ao Armazenamento de Blobs do Azure e os dados do novo envio (incluindo todas as listagens e informações de preços).
Observação
Um URI SAS fornece acesso a um recurso seguro no armazenamento do Azure sem exigir chaves de conta. Para obter informações básicas sobre URIs SAS e seu uso com o Armazenamento de Blobs do Azure, consulte Assinaturas de Acesso Compartilhado, Parte 1: Compreendendo o modelo SAS e Assinaturas de Acesso Compartilhado, Parte 2: Criar e usar uma SAS com armazenamento de Blobs.
Se você estiver adicionando novos pacotes para o envio, prepare os pacotes e adicione-os a um arquivo ZIP.
Revise os dados de envio de voo com as alterações necessárias para o novo envio e execute o método a seguir para atualizar o envio do pacote de pré-lançamento.
PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}Observação
Se você estiver adicionando novos pacotes para o envio, certifique-se de atualizar os dados do envio para se referir ao nome e ao caminho relativo desses arquivos no arquivo ZIP.
Se você estiver adicionando novos pacotes para o envio, carregue o arquivo ZIP no Armazenamento de Blobs do Azure usando o URI SAS fornecido no corpo da resposta do método POST que você chamou anteriormente. Há diferentes bibliotecas do Azure que você pode usar para fazer isso em uma variedade de plataformas, incluindo:
- Biblioteca do Cliente de Armazenamento do Azure para .NET
- SDK de Armazenamento do Azure para Java
- SDK do Armazenamento do Azure para Python
O exemplo de código C# a seguir demonstra como carregar um arquivo ZIP no Armazenamento de Blobs do Azure usando a classe CloudBlockBlob na Biblioteca de Cliente de Armazenamento do Azure para .NET. Este exemplo pressupõe que o arquivo ZIP já foi gravado em um objeto de fluxo.
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);Confirme o envio do pacote de pré-lançamento executando o método a seguir. Isso alertará o Partner Center de que você terminou seu envio e que suas atualizações agora devem ser aplicadas à sua conta.
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commitVerifique o status da confirmação executando o método a seguir para obter o status do envio do pacote de pré-lançamento.
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/statusPara confirmar o status do envio, revise o valor de status no corpo da resposta. Esse valor deve mudar de CommitStarted para PreProcessing se a solicitação for bem-sucedida ou para CommitFailed se houver erros na solicitação. Se houver erros, o campo statusDetails conterá mais detalhes sobre o erro.
Depois que a confirmação for concluída com êxito, o envio será enviado para a Loja para ingestão. Você pode continuar a monitorar o progresso do envio usando o método anterior ou visitando o Partner Center.
Exemplos de código
Os artigos a seguir fornecem exemplos de código detalhados que demonstram como criar um envio de pacote de pré-lançamento em várias linguagens de programação diferentes:
Módulo PowerShell StoreBroker
Como alternativa para chamar a API de envio da Microsoft Store diretamente, também fornecemos um módulo PowerShell de código aberto que implementa uma interface de linha de comando sobre a API. Este módulo é chamado StoreBroker. Você pode usar este módulo para gerenciar seus envios de aplicativo, voo e complemento a partir da linha de comando em vez de chamar a API de envio da Microsoft Store diretamente, ou simplesmente navegar na origem para ver mais exemplos de como chamar essa API. O módulo StoreBroker é usado ativamente na Microsoft como a principal maneira pela qual muitos aplicativos primários são enviados para a Loja.
Para obter mais informações, consulte nossa página StoreBroker no GitHub.
Gerenciar uma distribuição gradual de pacotes para um envio de pacotes de pré-lançamento
Você pode distribuir gradualmente os pacotes atualizados em um envio de pacote de pré-lançamento para uma porcentagem dos clientes do seu aplicativo no Windows 10 e no Windows 11. Isso permite que você monitore o feedback e os dados analíticos dos pacotes específicos para garantir que você esteja confiante sobre a atualização antes de distribuí-la de forma mais ampla. Você pode alterar a porcentagem de lançamento (ou interromper a atualização) de um envio publicado sem precisar criar um novo envio. Para obter mais detalhes, incluindo instruções sobre como habilitar e gerenciar uma distribuição gradual de pacote no Partner Center, consulte este artigo.
Para habilitar programaticamente uma distribuição gradual de pacote para um envio de pacote de pré-lançamento, siga este processo usando métodos na API de envio da Microsoft Store:
- Crie um envio de pacote de pré-lançamento ou obtenha um envio de pacote de pré-lançamento.
- Nos dados de resposta, localize o recurso packageRollout , defina o campo isPackageRollout como true e defina o campo packageRolloutPercentage como a porcentagem de clientes do aplicativo que devem receber os pacotes atualizados.
- Passe os dados atualizados de envio de pacotes de pré-lançamento para o método de atualização de um pacote de pré-lançamento .
Depois que uma distribuição gradual de pacote é habilitada para um envio de pacote de pré-lançamento, você pode usar os métodos a seguir para obter, atualizar, interromper ou finalizar programaticamente a distribuição gradual.
| Método | URI | Descrição |
|---|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout | Obter as informações de distribuição gradual para um envio de pacote de pré-lançamento |
| POSTAR | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage | Atualizar a porcentagem de distribuição gradual para um envio de pacote de pré-lançamento |
| POSTAR | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout | Interromper a distribuição gradual de um envio de pacote de pré-lançamento |
| POSTAR | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout | Finalizar a distribuição gradual para um envio de pacote de pré-lançamento |
Recursos de dados
Os métodos de API de envio da Microsoft Store para gerenciar envios de pacotes de pré-lançamento usam os seguintes recursos de dados JSON.
Recurso de envio de voo
Este recurso descreve um envio de pacote de pré-lançamento.
{
"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."
}
Este recurso possui os seguintes valores.
| Valor | Type | Descrição |
|---|---|---|
| id | string | O ID do envio. |
| ID do voo | string | A ID do pacote de pré-lançamento ao qual o envio está associado. |
| status | string | O status do envio. Esse valor pode ser um dos seguintes:
|
| statusDetails | objeto | Um recurso de detalhes de status que contém detalhes adicionais sobre o status do envio, incluindo informações sobre quaisquer erros. |
| pacotes de voo | matriz | Contém recursos de pacote de pré-lançamento que fornecem detalhes sobre cada pacote no envio. |
| packageDeliveryOptions | objeto | Um recurso de opções de entrega de pacote que contém a distribuição gradual do pacote e as configurações de atualização obrigatórias para o envio. |
| fileUploadUrl | string | O URI de assinatura de acesso compartilhado (SAS) para carregar quaisquer pacotes para o envio. Se você estiver adicionando novos pacotes para o envio, carregue o arquivo ZIP que contém os pacotes para esse URI. Para obter mais informações, consulte Criar um envio de pacote de pré-lançamento. |
| targetPublishMode | string | O modo de publicação para o envio. Esse valor pode ser um dos seguintes:
|
| targetPublishDate | string | A data de publicação para o envio no formato ISO 8601, se o targetPublishMode estiver definido como SpecificDate. |
| notesForCertification | string | Fornece informações adicionais para os testadores de certificação, como credenciais de conta de teste e etapas para acessar e verificar recursos. Para obter mais informações, consulte Notas para certificação. |
Recurso de detalhes de status
Este recurso contém detalhes adicionais sobre o status de um envio. Este recurso possui os seguintes valores.
| Valor | Type | Descrição |
|---|---|---|
| erros | objeto | Uma matriz de recursos de detalhes de status que contêm detalhes de erro para o envio. |
| avisos | objeto | Uma matriz de recursos de detalhes de status que contêm detalhes de aviso para o envio. |
| certificationReports | objeto | Uma matriz de recursos de relatório de certificação que fornece acesso aos dados do relatório de certificação para o envio. Você pode examinar esses relatórios para obter mais informações se a certificação falhar. |
Recurso de detalhes de status
Este recurso contém informações adicionais sobre quaisquer erros ou avisos relacionados para um envio. Este recurso possui os seguintes valores.
| Valor | Type | Descrição |
|---|---|---|
| code | string | Um código de status de envio que descreve o tipo de erro ou aviso. |
| detalhes | string | Uma mensagem com mais detalhes sobre o problema. |
Recurso de relatório de certificação
Esse recurso fornece acesso aos dados do relatório de certificação para um envio. Este recurso possui os seguintes valores.
| Valor | Type | Descrição |
|---|---|---|
| date | string | A data e hora em que o relatório foi gerado, no formato ISO 8601. |
| reportUrl | string | A URL na qual você pode acessar o relatório. |
Recurso de pacote de pré-lançamento
Este recurso fornece detalhes sobre um pacote em um envio.
{
"flightPackages": [
{
"fileName": "newPackage.appx",
"fileStatus": "PendingUpload",
"id": "",
"version": "1.0.0.0",
"languages": ["en-us"],
"capabilities": [],
"minimumDirectXVersion": "None",
"minimumSystemRam": "None"
}
],
}
Este recurso possui os seguintes valores.
Observação
Ao chamar o método de envio de atualização de um pacote de pré-lançamento , somente os valores fileName, fileStatus, minimumDirectXVersion e minimumSystemRam desse objeto são necessários no corpo da solicitação. Os outros valores são preenchidos pelo Partner Center.
| Valor | Type | Descrição |
|---|---|---|
| fileName | string | O nome do pacote. |
| fileStatus | string | O status do pacote. Esse valor pode ser um dos seguintes:
|
| ID | string | Uma ID que identifica exclusivamente o pacote. Esse valor é usado pelo Partner Center. |
| version | string | A versão do pacote do aplicativo. Para obter mais informações, consulte Numeração de versão do pacote. |
| arquitetura | string | A arquitetura do pacote do aplicativo (por exemplo, ARM). |
| idiomas | matriz | Uma matriz de códigos de idioma para os idiomas compatíveis com o aplicativo. Para obter mais informações, consulte Para obter mais informações, consulte Idiomas com suporte. |
| funcionalidades | matriz | Uma variedade de recursos exigidos pelo pacote. Para obter mais informações sobre recursos, consulte Declarações de funcionalidade do aplicativo. |
| minimumDirectXVersion | string | A versão mínima do DirectX compatível com o pacote do aplicativo. Isso só pode ser definido para aplicativos direcionados ao Windows 8.x; ele é ignorado para aplicativos direcionados a outras versões. Esse valor pode ser um dos seguintes:
|
| minimumSystemRam | string | A RAM mínima exigida pelo pacote do aplicativo. Isso só pode ser definido para aplicativos direcionados ao Windows 8.x; ele é ignorado para aplicativos direcionados a outras versões. Esse valor pode ser um dos seguintes:
|
Recurso de opções de entrega de pacotes
Este recurso contém a distribuição gradual do pacote e as configurações de atualização obrigatórias para o envio.
{
"packageDeliveryOptions": {
"packageRollout": {
"isPackageRollout": false,
"packageRolloutPercentage": 0.0,
"packageRolloutStatus": "PackageRolloutNotStarted",
"fallbackSubmissionId": "0"
},
"isMandatoryUpdate": false,
"mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
},
}
Este recurso possui os seguintes valores.
| Valor | Type | Descrição |
|---|---|---|
| lançamento do pacote | objeto | Um recurso de distribuição de pacote que contém configurações de distribuição de pacote gradual para o envio. |
| isMandatoryUpdate | boolean | Indica se você deseja tratar os pacotes neste envio como obrigatórios para atualizações de aplicativos de instalação automática. Para obter mais informações sobre pacotes obrigatórios para atualizações de aplicativos de instalação automática, consulte Baixar e instalar atualizações de pacote para seu aplicativo. |
| mandatoryUpdateEffectiveDate | date | A data e a hora em que os pacotes neste envio se tornam obrigatórios, no formato ISO 8601 e no fuso horário UTC. |
Recurso de distribuição de pacote
Esse recurso contém configurações de distribuição gradual do pacote para o envio. Este recurso possui os seguintes valores.
| Valor | Type | Descrição |
|---|---|---|
| isPackageRollout | boolean | Indica se a distribuição gradual do pacote está habilitada para o envio. |
| packageRolloutPercentage | float | A porcentagem de usuários que receberão os pacotes na distribuição gradual. |
| packageRolloutStatus | string | Uma das seguintes strings que indica o status da distribuição gradual do pacote:
|
| fallbackSubmissionId | string | A ID do envio que será recebida pelos clientes que não receberem os pacotes de distribuição gradual. |
Observação
Os valores packageRolloutStatus e fallbackSubmissionId são atribuídos pelo Partner Center e não devem ser definidos pelo desenvolvedor. Se você incluir esses valores em um corpo de solicitação, esses valores serão ignorados.
Enumerações
Esses métodos usam os seguintes enums.
Código de status de envio
Os códigos a seguir representam o status de um envio.
| Código | Descrição |
|---|---|
| Nenhum | Nenhum código foi especificado. |
| InvalidArchive | O arquivo ZIP que contém o pacote é inválido ou tem um formato de arquivo não reconhecido. |
| MissingFiles | O arquivo ZIP não tem todos os arquivos que foram listados em seus dados de envio, ou eles estão no local errado no arquivo. |
| PackageValidationFailed | Um ou mais pacotes em seu envio não foram validados. |
| InvalidParameterValue | Um dos parâmetros no corpo da solicitação é inválido. |
| InvalidOperation | A operação que você tentou é inválida. |
| InvalidState | A operação que você tentou não é válida para o estado atual do voo do pacote. |
| ResourceNotFound | O pacote de voo especificado não foi encontrado. |
| ServiceError | Um erro de serviço interno impediu que a solicitação fosse bem-sucedida. Repita a solicitação novamente. |
| ListingOptOutWarning | O desenvolvedor removeu uma listagem de um envio anterior ou não incluiu informações de listagem suportadas pelo pacote. |
| ListingOptInWarning | O desenvolvedor adicionou uma listagem. |
| UpdateOnlyWarning | O desenvolvedor está tentando inserir algo que só tem suporte para atualização. |
| Outro | A submissão está em um estado não reconhecido ou não categorizado. |
| PackageValidationWarning | O processo de validação do pacote resultou em um aviso. |
Tópicos relacionados
- Criar e gerenciar envios usando serviços da Microsoft Store
- Gerenciar pacotes de pré-lançamento usando a API de envio da Microsoft Store
- Obter um envio de pacote de pré-lançamento
- Criar um envio de pacote de pré-lançamento
- Atualizar um envio de pacote de pré-lançamento
- Confirmar um envio de pacote de pré-lançamento
- Excluir um envio de pacote de pré-lançamento
- Obter o status de um envio de pacote de pré-lançamento
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de