Compartilhar via

Gerenciar submissões de voos de pacotes

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 submissão da Microsoft Store para criar uma submissão para um voo de pacote, certifique-se de fazer outras alterações na submissão apenas usando a API, do que o 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 em que 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 voo

Utilize os métodos a seguir para obter, criar, atualizar, confirmar ou excluir uma submissão de voo de pacote. Antes de usar esses métodos, o pacote de voo já deve existir no Partner Center. Você pode criar um voo de pacote no Partner Center ou usar os métodos de API de envio da Microsoft Store, conforme descrito em Gerenciar voos de pacotes.

Método URI Descrição
OBTER https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Obter uma submissão de voo de pacote existente
OBTER 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
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions Criar uma nova submissão de voo de pacote
COLOCAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Atualizar uma submissão de pacote de voo existente
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit Enviar um novo ou atualizado envio de pacote para teste
EXCLUIR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} Excluir um envio de pacote de voo

Criar uma remessa de pacote de voo

Para criar uma submissão para um vôo de pacote, siga este processo.

  1. 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 do Azure AD à sua conta do Partner Center e obter sua ID e chave do cliente. Você só precisa fazer isso uma vez; depois de ter a ID e a chave do cliente, você poderá reutilizá-los sempre que precisar criar um novo token de acesso do Azure AD.

  2. Obter um token de acesso do Azure AD. Você deve passar esse token de acesso para os métodos na API de submissão da Microsoft Store. Depois de obter um token de acesso, você terá 60 minutos para usá-lo antes que ele expire. Depois que o token expirar, você poderá obter um novo.

  3. Criar um envio de pacote flight por meio da execução do 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 seu último envio publicado.

    POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions

    O corpo da resposta contém um envio de pré-lançamento recurso que inclui a ID do novo envio, o URI de 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 de SAS fornece acesso a um recurso seguro no armazenamento do Azure sem a necessidade de 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: Noções básicas sobre o modelo SAS e Assinaturas de Acesso Compartilhado, Parte 2: Criar e usar uma SAS com o Armazenamento de Blobs.

  4. Se você estiver adicionando novos pacotes para o envio, preparar os pacotes e adicioná-los a um arquivo ZIP.

  5. Revise os dados de envio 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 se referir ao nome e ao caminho relativo desses arquivos no arquivo ZIP.

  6. Se você estiver adicionando novos pacotes para o envio, carregue o arquivo ZIP para o Armazenamento de Blobs do Azure usando o URI SAS fornecido no corpo da resposta do método POST que você chamou anteriormente. Há bibliotecas diferentes do Azure que você pode usar para fazer isso em várias plataformas, incluindo:

    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 Clientes do 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);

  7. Efetuar o envio de pacote executando o seguinte método. 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}/commit

  8. Verifique o status do commit executando o método a seguir para obter o status do envio do pacote.

    GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status

    Para confirmar o status do envio, examine o valor do status no corpo da resposta. Esse valor deve ser alterado 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.

  9. Depois que o commit for concluído com êxito, a submissão é enviada à Loja para ingestã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 fornecem exemplos de código detalhados que demonstram como criar uma submissão de pacote de voo em várias linguagens de programação:

Módulo do PowerShell do StoreBroker

Como alternativa para chamar diretamente a API de envio da Microsoft Store, também fornecemos um módulo do PowerShell de software livre que implementa uma interface de linha de comando na parte superior da API. Este módulo é chamado StoreBroker. Você pode usar este módulo para gerenciar suas submissões de aplicativos, voos e complementos a partir da linha de comando, em vez de chamar diretamente a API de submissão da Microsoft Store, ou pode simplesmente navegar pelo código-fonte 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 de primeira parte são enviados para a Loja.

Para obter mais informações, consulte nossa página StoreBroker no GitHub.

Gerenciar uma distribuição gradual de pacote para uma submissão de voo de pacote

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 comentários e dados analíticos para os 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 distribuição (ou interromper 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 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:

  1. Criar um pacote de submissão de voo ou obter um pacote de submissão de voo.
  2. Nos dados de resposta, localize o recurso packageRollout, defina o campo isPackageRollout como true e defina o campo packageRolloutPercentage para o percentual de clientes do aplicativo que devem obter os pacotes atualizados.
  3. Passe os dados atualizados do envio de voo do pacote para o método de atualizar um envio de voo do pacote.

Depois que uma distribuição gradual do pacote for habilitada para um envio de voo, você poderá usar os métodos a seguir para obter, atualizar, interromper ou finalizar a distribuição gradual programaticamente.

Método URI Descrição
OBTER https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout Obter as informações de implementação gradual de um envio de pacote
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage Atualizar a porcentagem de lançamento gradual para uma submissão de pacote em voo
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout Suspender a implementação gradual de um pacote de testes de voo
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout Finalizar a distribuição gradual para a submissão de pacote de voo

Recursos de dados

Os métodos da API de envio da Microsoft Store para gerenciar pacotes de voo usam os seguintes recursos JSON de dados.

Recurso de envio de teste de voo

Esse recurso descreve uma submissão de pacote de voo.

{
  "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 seguintes valores.

Valor Tipo Descrição
id corda O ID do envio.
ID do voo corda O ID do voo do pacote ao qual a submissão está associada.
estado corda A situação do envio. Esse valor pode ser um dos seguintes:
  • Nenhum
  • Cancelado
  • CompromissoPendente
  • Comprometimento Iniciado
  • Falha na submissão
  • Publicação Pendente
  • Publicação
  • Publicado
  • Falha na publicação
  • Pré-processamento
  • Falha no pré-processamento
  • Certificação
  • Falha na certificação
  • Liberação
  • Falha no lançamento
detalhes do status objeto Um recurso de detalhes de status que contém detalhes adicionais sobre o status da submissão, incluindo informações sobre quaisquer erros.
flightPackages conjunto Contém recursos de pacote de pré-lançamento que fornecem detalhes sobre cada pacote no envio.
opçõesDeEntregaDePacotes objeto Um recurso de opções de entrega de pacotes que inclui configurações de distribuição gradual e de atualização obrigatória para a submissão.
fileUploadUrl corda A URI de SAS (assinatura de acesso compartilhado) para carregar qualquer pacote 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 uma submissão de pacote de voo.
modo de publicação alvo corda O modo de publicação da submissão. Esse valor pode ser um dos seguintes:
  • Imediato
  • Manual
  • Data específica
data-alvo de publicação corda A data de publicação do envio no formato ISO 8601, se o targetPublishMode estiver definido como uma data específica.
notasParaCertificação corda Fornece informações adicionais para os testadores de certificação, como credenciais de conta de teste e etapas para acessar e verificar os recursos. Para obter mais informações, consulte Notas para certificação.

Detalhes do recurso de status

Esse recurso contém detalhes adicionais sobre o status de um envio. Esse recurso tem os seguintes valores.

Valor Tipo Descrição
Erros objeto Uma matriz de recursos de detalhes de status que contêm detalhes de erro para o envio.
Avisos objeto Um conjunto de recursos de detalhes de status que contêm detalhes de alerta para o envio.
relatórios de certificação objeto Um conjunto de recursos de relatório de certificação que fornecem acesso aos dados do relatório de certificação para a submissão. Você pode examinar esses relatórios para obter mais informações se a certificação falhar.

Detalhes do recurso de status

Esse recurso contém informações adicionais sobre quaisquer erros ou avisos relacionados para um envio. Esse recurso tem os seguintes valores.

Valor Tipo Descrição
código corda Um código de status de envio que descreve o tipo de erro ou aviso.
detalhes corda Uma mensagem com mais detalhes sobre o problema.

Ferramenta de relatório de certificação

Esse recurso fornece acesso aos dados do relatório de certificação para um envio. Esse recurso tem os seguintes valores.

Valor Tipo Descrição
data corda A data e a hora em que o relatório foi gerado, no formato ISO 8601.
URL do relatório corda A URL na qual você pode acessar o relatório.

Recurso de pacote de voo

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 seguintes valores.

Observação

Ao chamar o método de submissão de atualização de pacote, somente os valores fileName, fileStatus, minimumDirectXVersione minimumSystemRam desse objeto são necessários no corpo da solicitação. Os outros valores são preenchidos pelo Partner Center.

Valor Tipo Descrição
nome do arquivo corda O nome do pacote.
fileStatus corda O status do pacote. Esse valor pode ser um dos seguintes:
  • Nenhum
  • Envio Pendente
  • Enviado
  • Deleção Pendente
id corda Uma ID que identifica exclusivamente o pacote. Esse valor é usado pelo Partner Center.
versão corda A versão do pacote do aplicativo. Para obter mais informações, consulte numeração de versão de pacotes.
arquitetura corda A arquitetura do pacote do aplicativo (por exemplo, ARM).
Idiomas conjunto 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.
Capacidades conjunto Uma matriz de funcionalidades exigida pelo pacote. Para obter mais informações sobre recursos, consulte declarações de funcionalidade de aplicativo.
versão mínima do DirectX corda A versão mínima do DirectX compatível com o pacote do aplicativo. Isso pode ser definido apenas para aplicativos destinados ao Windows 8.x; ele é ignorado para aplicativos direcionados a outras versões. Esse valor pode ser um dos seguintes:
  • Nenhum
  • DirectX93
  • DirectX100
memória RAM mínima do sistema corda A RAM mínima exigida pelo pacote do aplicativo. Isso pode ser definido apenas para aplicativos destinados ao Windows 8.x; ele é ignorado para aplicativos direcionados a outras versões. Esse valor pode ser um dos seguintes:
  • Nenhum
  • Memory2GB

Recurso de opções para entrega de pacotes

Este recurso contém configurações de distribuição gradual do pacote e de atualização obrigatória para submissão.

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

Esse recurso tem os seguintes valores.

Valor Tipo Descrição
packageRollout objeto Um recurso de distribuição de pacote que contém configurações graduais de distribuição de pacote para o envio.
éAtualizaçãoObrigatória booleano Indica se você deseja tratar os pacotes neste envio como obrigatórios para auto-instalação de atualizações de aplicativo. Para obter mais informações sobre pacotes obrigatórios para atualizações automáticas de aplicativos, consulte Baixar e instalar atualizações de pacotes para seu aplicativo.
Data de entrada em vigor da atualização obrigatória data 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 graduais de distribuição de pacote para o envio. Esse recurso tem os seguintes valores.

Valor Tipo Descrição
isPackageRollout booleano Indica se a distribuição gradual do pacote está habilitada para a submissão.
porcentagemDeImplementaçãoDoPacote flutuar O percentual de usuários que receberão os pacotes na distribuição gradual.
packageRolloutStatus corda Uma das seguintes strings que indicam o status da distribuição gradual do pacote:
  • ImplantaçãoDoPacoteNãoIniciada
  • DistribuiçãoDoPacoteEmProgresso
  • Implementação de Pacote Concluída
  • ImplementaçãoDoPacoteInterrompida
fallbackSubmissionId corda O ID da submissão que será fornecido aos clientes que não recebem 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 as enumerações a seguir.

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.
Arquivo Inválido 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 contém todos os arquivos que foram listados nas informações enviadas, ou eles estão no local errado dentro do arquivo ZIP.
FalhaNaValidaçãoDoPacote Um ou mais pacotes em seu envio não foram validados.
ValorDoParâmetroInválido Um dos parâmetros no corpo da solicitação é inválido.
Operação Inválida A operação que você tentou é inválida.
EstadoInválido A operação que você tentou não é válida para o estado atual do pacote de voo.
Recurso Não Encontrado Não foi possível encontrar o pacote de voo especificado.
Erro de Serviço Um erro de serviço interno impediu que a solicitação tivesse êxito. Tente a solicitação novamente.
Aviso de Exclusão de Listagem O desenvolvedor removeu uma listagem de um envio anterior ou não incluiu informações de listagem compatíveis com o pacote.
AvisoDeAdesãoÀListagem O desenvolvedor adicionou uma listagem.
UpdateOnlyWarning O desenvolvedor está tentando inserir algo que só tem suporte para atualização.
Outros O envio está em um estado desconhecido ou não categorizado.
Aviso de Validação de Pacote O processo de validação do pacote resultou em um aviso.