Compartilhar via

Gerenciar envios de pacote de pré-lançamento

  • Artigo

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.

  1. 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.

  2. 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.

  3. 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}/submissions

    O 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.

  4. Se você estiver adicionando novos pacotes para o envio, prepare os pacotes e adicione-os a um arquivo ZIP.

  5. 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.

  6. 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:

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

  7. 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}/commit

  8. Verifique 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}/status

    Para 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.

  9. 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:

  1. Crie um envio de pacote de pré-lançamento ou obtenha um envio de pacote de pré-lançamento.
  2. 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.
  3. 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:
  • Nenhum
  • Canceled
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Publicando
  • Publicado
  • PublishFailed
  • PreProcessing
  • PreProcessingFailed
  • Certificação
  • CertificationFailed
  • Versão
  • ReleaseFailed
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:
  • Imediata
  • Manual
  • SpecificDate
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:
  • Nenhum
  • PendingUpload
  • Carregado
  • PendingDelete
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:
  • Nenhum
  • DirectX93
  • DirectX100
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:
  • Nenhum
  • Memória2GB

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:
  • PackageRolloutNotStarted
  • PackageRolloutInProgress
  • PacoteRolloutComplete
  • PackageRolloutStopped
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.