Gerenciar envios de pacote de pré-lançamento
A API de envio da Microsoft Store oferece métodos que é possível usar para gerenciar envios de pacote de pré-lançamento dos aplicativos, inclusive distribuições de pacote graduais. Para obter uma introdução à API de envio da Microsoft Store, inclusive pré-requisitos para usar a API, consulte Criar e gerenciar envios usando 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 outras alterações no envio apenas usando a API, em vez do Partner Center. Se você usar o painel para alterar um envio que criou originalmente usando a API, você não poderá alterar ou confirmar esse envio usando a API. Em alguns casos, o envio pode ficar em um estado de erro em que ele não pode continuar no processo de envio. Se isso ocorrer, você deve excluir o envio e criar um novo.
Métodos para gerenciar envios do pacote 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 poder 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 |
| POST | 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 |
| POST | 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 (excluir) | 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 fez isso, conclua os pré-requisitos descritos em Criar e gerenciar envios usando os serviços da Microsoft Store, incluindo associar um aplicativo Azure AD à sua conta do Partner Center e obter a ID e a chave do cliente. Você só precisa fazer uma vez. Depois que você tiver a ID e a chave do cliente, poderá reutilizá-las sempre que precisar criar um novo token de acesso do Azure AD.
Obtenha um token de acesso Azure AD. Você deve passar esse token de acesso aos 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.
Criar um envio de pacote de pré-lançamento executando o seguinte método na API de envio da Microsoft Store. Esse método cria um novo envio em andamento, que é uma cópia de seu ú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 versão de pré-lançamento que inclui a ID do novo envio, o URI de SAS (assinatura de acesso compartilhado) para carregar todos os pacotes para o envio para Armazenamento de Blobs do Azure e os dados para o novo envio (incluindo todas as listagens e informações de preços).
Observação
Um URI SAS dá 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 Armazenamento de Blobs do Azure, consulte Assinaturas de Acesso Compartilhado, Parte 1: Noções básicas sobre 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 versão de pré-lançamento com as alterações necessárias para o novo envio e execute o método a seguir para atualizar o envio de 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, atualize os dados de envio para fazer referência ao nome e caminho relativo desses arquivos no arquivo ZIP.
Se você estiver adicionando novos pacotes para o envio, carregue o arquivo ZIP para Armazenamento de Blobs do Azure usando o URI sas que foi fornecido no corpo da resposta do método POST que você chamou anteriormente. Existem bibliotecas do Azure diferentes que é possível usar para fazer isso em uma grande variedade de plataformas, inclusive:
- Biblioteca de Clientes do Armazenamento do Azure para .NET
- SDK de Armazenamento do Azure para Java
- SDK de Armazenamento do Azure para Python
O exemplo de código C# a seguir demonstra como carregar um arquivo ZIP para Armazenamento de Blobs do Azure usando a classe CloudBlockBlob na Biblioteca de Clientes do Armazenamento do Azure para .NET. Este exemplo pressupõe que o arquivo ZIP já tenha sido escrito para 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 realizando 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 de confirmação executando o método a seguir para obter o status de envio de pacote de pré-lançamento.
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/statusPara confirmar o status de envio, examine o valor de status no corpo da resposta. Esse valor deve mudar de CommitStarted para PreProcessing se a solicitação for bem-sucedida ou CommitFailed se houver erros na solicitação. Se houver erros, o campo statusDetails contém mais detalhes sobre o erro.
Após a confirmação ser concluída, o envio será enviado para a Loja para inclusão. Você pode continuar monitorando o progresso do envio usando o método anterior ou visitando o Partner Center.
Exemplos de código
Os artigos a seguir dão exemplos de código detalhados que demonstram como criar um envio de pacote de pré-lançamento em diversas linguagens de programação diferentes:
Módulo StoreBroker do PowerShell
Como uma alternativa à chamada direta à API de envio da Microsoft Store, nós também fornecemos um módulo do PowerShell de software livre que implementa uma interface de linha de comando sobre API. Esse módulo é chamado StoreBroker. Você pode usar esse módulo para gerenciar seu app, versão de pré-lançamento e envios de complemento na linha de comando em vez de chamar diretamente a API de envio da Microsoft Store, ou você pode simplesmente procurar a fonte para ver mais exemplos de como chamar essa API. O módulo StoreBroker ativamente é usado dentro da Microsoft como a principal forma de muitos apps de terceiros serem enviados para a Store.
Para obter mais informações, consulte nossa Página do StoreBroker no GitHub.
Gerenciar uma distribuição de pacote gradual para um envio de pacote 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 em Windows 10 e Windows 11. Isso permite que você monitore comentários e dados de análise dos pacotes específicos para verificar se a atualização é necessária antes de implantá-la mais amplamente. Você pode alterar a porcentagem de distribuição (ou parar a atualização) para 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 pacotes no Partner Center, consulte este artigo.
Para habilitar programaticamente uma distribuição de pacote gradual para um envio de pacote de pré-lançamento, siga esse processo usando métodos na API de envio da Microsoft Store:
- Criar um envio de pacote de pré-lançamento ou obter 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 dos clientes do aplicativo que devem obter os pacotes atualizados.
- Passe os dados de envio do pacote de pré-lançamento atualizados para o método atualizar um envio de pacote de pré-lançamento.
Depois que uma distribuição de pacote gradual for habilitada para um envio de pacote de pré-lançamento, será possível 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 |
| POST | 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 |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout | Interromper a distribuição gradual para um envio de pacote de pré-lançamento |
| POST | 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 da API de envio da Microsoft Store para gerenciar envios do pacote de pré-lançamento usam os recursos de dados JSON a seguir.
Recurso de envio da versão de pré-lançamento
Esse recurso descreve um envio do 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."
}
Esse recurso tem os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| id | string | A ID do envio. |
| flightId | 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 do status que contém detalhes adicionais sobre o status do envio, inclusive informações sobre eventuais erros. |
| flightPackages | array | Contém recursos do pacote da versão de pré-lançamento que fornecem detalhes sobre cada pacote no envio. |
| packageDeliveryOptions | objeto | Um recurso de opções de entrega do pacote que contém configurações da distribuição de pacote gradual e da atualização obrigatória para o envio. |
| fileUploadUrl | string | O URI da assinatura de acesso compartilhado (SAS) para carregar todos os pacotes para o envio. Se você estiver adicionando novos pacotes para o envio, carregue o arquivo ZIP que contém os pacotes para essa URI. Para saber mais, veja Criar um envio de pacote de pré-lançamento. |
| targetPublishMode | string | O modo de publicação do envio. Esse valor pode ser um dos seguintes:
|
| targetPublishDate | string | A data de publicação do envio em formato ISO 8601, se o targetPublishMode estiver definido como SpecificDate. |
| notesForCertification | string | Fornece informações adicionais para os testadores de certificação, como credenciais da conta de teste e as etapas para acessar e confirmar recursos. Para obter mais informações, consulte Notas para certificação. |
Recurso de detalhes do status
Esse recurso contém detalhes adicionais sobre o status de um envio. Esse recurso tem os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| erros | objeto | Uma matriz de recursos de detalhes do status que contêm detalhes do erro para o envio. |
| warnings | objeto | Uma matriz de recursos de detalhes do status que contêm detalhes do aviso para o envio. |
| certificationReports | objeto | Uma matriz de recursos do relatório de certificação que dão acesso aos dados do relatório de certificação para o envio. Será possível examinar esses relatórios para obter mais informações, se a certificação falhar. |
Recurso de detalhes do status
Esse recurso contém informações adicionais sobre todos os erros ou avisos relacionados a um envio. Esse recurso tem os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| code | string | Um código de status do envio que descreve o tipo de erro ou aviso. |
| detalhes | string | Uma mensagem com mais detalhes sobre o problema. |
Recurso do relatório de certificação
Esse recurso dá acesso aos dados do relatório de certificação para um envio. Esse recurso tem os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| date | string | A data e a hora em que o relatório foi gerado, no formato ISO 8601. |
| reportUrl | string | A URL na qual é possível acessar o relatório. |
Recurso do pacote da versão de pré-lançamento
Esse 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"
}
],
}
Esse recurso tem os valores a seguir.
Observação
Durante a chamada do método atualizar um envio de 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 de aplicativo (por exemplo, ARM). |
| idiomas | array | Uma matriz de códigos de idioma para os idiomas com suporte do aplicativo. Para obter mais informações, consulte Idiomas suportados. |
| funcionalidades | array | Uma matriz de recursos necessários pelo pacote. Para obter mais informações sobre recursos, consulte Declarações de recursos de aplicativos. |
| minimumDirectXVersion | string | A versão mínima do DirectX que é compatível com o pacote do aplicativo. Isso pode ser definido apenas para aplicativos que visam o Windows 8.x; isso é ignorado para aplicativos destinados a outras versões. Esse valor pode ser um dos seguintes:
|
| minimumSystemRam | string | A RAM mínima necessária para o pacote do aplicativo. Isso pode ser definido apenas para aplicativos que visam o Windows 8.x; isso é ignorado para aplicativos destinados a outras versões. Esse valor pode ser um dos seguintes:
|
Recurso de opções de entrega do pacote
Esse recurso contém configurações da distribuição de pacote gradual e da atualização obrigatória para o envio.
{
"packageDeliveryOptions": {
"packageRollout": {
"isPackageRollout": false,
"packageRolloutPercentage": 0.0,
"packageRolloutStatus": "PackageRolloutNotStarted",
"fallbackSubmissionId": "0"
},
"isMandatoryUpdate": false,
"mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
},
}
Esse recurso tem os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| packageRollout | objeto | Um recurso de distribuição de pacote que contém configurações da distribuição de pacote gradual para o envio. |
| isMandatoryUpdate | booleano | Indica se você deseja tratar os pacotes nesse envio como obrigatórios para instalar automaticamente atualizações de aplicativo. Para obter mais informações sobre pacotes obrigatórios para instalar automaticamente as atualizações de aplicativos, consulte Baixar e instalar atualizações de pacote para seu app. |
| mandatoryUpdateEffectiveDate | date | A data e hora em que os pacotes nesse envio se tornam obrigatórios, em formato ISO 8601 e fuso horário UTC. |
Recurso de distribuição de pacote
Esse recurso contém configurações de distribuição de pacote gradual para o envio. Esse recurso tem os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| isPackageRollout | booleano | Indica se a distribuição de pacote gradual está habilitada para o envio. |
| packageRolloutPercentage | FLOAT | O percentual de usuários que receberão os pacotes na distribuição gradual. |
| packageRolloutStatus | string | Uma das seguintes sequências que indicam o status da distribuição de pacote gradual:
|
| fallbackSubmissionId | string | A ID da submissão que será recebido por clientes que não recebem os pacotes de lançamento 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 no corpo da solicitação, esses valores serão ignorados.
Enumerações
Esses métodos usam as enumerações a seguir.
Código de status do 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 não é válido ou tem um formato de arquivo não reconhecido. |
| MissingFiles | O arquivo ZIP não tem todos os arquivos que foram listados nos seus dados de envio ou estão no local errado no arquivo. |
| PackageValidationFailed | Falha ao validar um ou mais pacotes no seu envio. |
| InvalidParameterValue | Um dos parâmetros no corpo da solicitação não é válido. |
| InvalidOperation | A operação tentada não é válida. |
| InvalidState | A operação tentada não é válida para o estado atual do pacote de pré-lançamento. |
| ResourceNotFound | O pacote de pré-lançamento especificado não foi encontrado. |
| ServiceError | Um erro de serviço interno impediu o êxito da solicitação. Repita a solicitação. |
| ListingOptOutWarning | O desenvolvedor removeu uma listagem de um envio anterior ou não incluiu informações de listagem que são compatíveis com o pacote. |
| ListingOptInWarning | O desenvolvedor adicionou uma listagem. |
| UpdateOnlyWarning | O desenvolvedor está tentando inserir algo que só tem suporte para a atualização. |
| Outro | O envio 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