Criar e gerenciar envios

  • Artigo

Use a API de envio da Microsoft Store para consultar e criar envios programaticamente para aplicativos, complementos e pacotes de pré-lançamento para a conta do Partner Center da sua organização. Essa API será útil se sua conta gerenciar muitos aplicativos ou complementos e você quiser automatizar e otimizar o processo de envio para esses ativos. Essa API usa o Active Directory do Azure (Azure AD) para autenticar as chamadas do seu aplicativo ou serviço.

As etapas a seguir descrevem o processo completo de usar a API de envio da Microsoft Store:

  1. Certifique-se de que você tenha concluído todos os pré-requisitos.
  2. Antes de chamar um método na API de envio da Microsoft Store obtenha um token de acesso do Azure AD. Depois de obter um token, você tem 60 minutos para usá-lo em chamadas para a API de envio da Microsoft Store antes que ele expire. Depois que o token expirar, será possível gerar um novo.
  3. Chame a API de envio da Microsoft Store.

Importante

Se você usar essa API para criar um envio para um aplicativo, pacote de pré-lançamento ou complemento, certifique-se de fazer outras alterações no envio apenas usando a API, em vez de no Partner Center. Se você usar o Partner Center 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 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.

Importante

Você não pode usar essa API para publicar os envios de compras de volume por meio da Microsoft Store para Empresas e da Microsoft Store para Educação ou publicar os envios de aplicativos LOB diretamente para empresas. Para ambos os cenários, você deve usar publicar o envio no Partner Center.

Observação

Essa API não pode ser usada com apps ou complementos que usem atualizações de app obrigatórias e complementos consumíveis gerenciados pela Store. Se você usar a API de envio da Microsoft Store com um aplicativo ou um complemento que usa um desses recursos, a API retornará um código de erro 409. Nesse caso, você deve usar o Partner Center para gerenciar os envios para o aplicativo ou complemento.

Etapa 1: Concluir os pré-requisitos para usar a API de envio da Microsoft Store

Antes de começar a escrever o código para chamar a API de envio da Microsoft Store, certifique-se de que você concluiu os pré-requisitos a seguir.

  • Você (ou sua organização) deve ter um diretório do Azure AD e você deve ter permissão de Administrador global para o diretório. Se já usa o Microsoft 365 ou outros serviços comerciais da Microsoft, você já tem o diretório do Azure AD. Caso contrário, você poderá criar uma nova Azure AD no Partner Center sem custo adicional.

  • Associe um aplicativo do Azure AD à sua conta do Partner Center e obtenha a ID do locatário, a ID do cliente e a chave. Esses valores são necessários para obter um token de acesso do Azure AD, que será usado em chamadas para a API de envio da Microsoft Store.

  • Prepare seu aplicativo para uso com a API de envio da Microsoft Store:

    • Se o aplicativo ainda não existir no Partner Center, você deverá criar seu aplicativo reservando seu nome no Partner Center. Você não pode usar a API de envio da Microsoft Store para criar um aplicativo no Partner Center; você deve trabalhar no Partner Center para criá-lo e, depois disso, pode usar a API para acessar o aplicativo e criar envios programaticamente para ele. No entanto, você pode usar a API para criar complementos e pacotes de pré-lançamento programaticamente antes de criar envios para eles.

    • Antes de criar um envio para um determinado aplicativo usando essa API, você deve primeiro criar um envio para o aplicativo no Partner Center, incluindo responder ao questionário de classificações etárias . Depois que você fizer isso, você poderá criar novos envios para este aplicativo usando a API programaticamente. Você não precisa criar um envio de complemento nem o envio de versão de pré-lançamento do pacote antes de usar a API para esses tipos de envios.

    • Se você estiver criando ou atualizando um envio de aplicativo e você precisar incluir um pacote do aplicativo, prepare o pacote do aplicativo.

    • Se você estiver criando ou atualizando um envio de aplicativo e você precisar incluir capturas de tela ou imagens para a listagem da Store, prepare as imagens e capturas de tela do aplicativo.

    • Se você estiver criando ou atualizando um envio de complemento e você precisar incluir um ícone, prepare o ícone.

Como associar um aplicativo do Azure AD à sua conta do Partner Center

Antes de usar a API de envio da Microsoft Store, você deve associar um aplicativo Azure AD à sua conta do Partner Center, recuperar a ID do locatário e a ID do cliente para o aplicativo e gerar uma chave. O aplicativo do Azure AD representa o aplicativo ou serviço do qual você quer chamar a API de envio da Microsoft Store. Você precisa da ID do locatário, da ID do cliente e da chave para obter um token de acesso do Azure AD que é passado para a API.

Observação

Você só precisa executar essa tarefa uma vez. Depois de obter a ID do locatário, a ID do cliente e a chave, você poderá reutilizá-las sempre que precisar criar um novo token de acesso do Azure AD.

  1. No Partner Center, associe a conta do Partner Center da sua organização ao diretório do Azure AD da sua organização.

  2. Em seguida, na página Usuários na seção Configurações da conta do Partner Center, adicione o aplicativo do Azure AD que representa o aplicativo ou serviço que você usará para acessar os envios para sua conta do Partner Center. Lembre-se de atribuir esse aplicativo à função de Gerenciador. Se o aplicativo ainda não existir no diretório do Azure AD, crie um novo aplicativo do Azure AD no Partner Center.

  3. Retorne à página Usuários, clique no nome do seu aplicativo do Azure AD para acessar as configurações do aplicativo e copie os valores de ID do Locatário e ID do Cliente.

  4. Clique em Adicionar nova chave. Na tela a seguir, copie o valor da Chave. Você não poderá acessar essas informações novamente depois de sair da página. Para saber mais, veja Gerenciar chaves de um aplicativo do Azure AD.

Etapa 2: Obtenção de um token de acesso do Azure AD

Antes de chamar qualquer um dos métodos na API de envio da Microsoft Store, primeiro você deve obter um token de acesso do Azure AD que você passa para o cabeçalho Authorization de cada método na API. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá atualizar o token para que você possa continuar a usá-lo em outras chamadas à API.

Para obter o token de acesso, siga as instruções em Chamadas de serviço a serviço usando credenciais do cliente para enviar um HTTP POST para o ponto de extremidade https://login.microsoftonline.com/<tenant_id>/oauth2/token. Aqui está um exemplo de solicitação.

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

Para o valor de tenant_id no URI POST e os parâmetros client_id e client_secret , especifique a ID do locatário, a ID do cliente e a chave do aplicativo que você recuperou do Partner Center na seção anterior. Para o parâmetro resource, especifique https://manage.devcenter.microsoft.com.

Depois que o token de acesso expirar, você poderá buscar um novo fazendo a mesma chamada HTTP novamente.

Para obter exemplos que demonstram como obter um token de acesso usado código C#, Java ou Python, consulte os exemplos de código da API de envio da Microsoft Store.

Etapa 3: Uso da API de envio da Microsoft Store

Depois que tiver um token de acesso do Azure AD, você poderá chamar métodos na API de envio da Microsoft Store. A API inclui muitos métodos que são agrupados em cenários de aplicativos, complementos e pacotes de pré-lançamento. Para criar ou atualizar os envios, você normalmente chama vários métodos na API de envio da Microsoft Store em uma ordem específica. Para obter informações sobre cada cenário e a sintaxe de cada método, consulte os artigos na tabela a seguir.

Observação

Depois de obter um token de acesso, você tem 60 minutos para chamar métodos na API de envio da Microsoft Store antes que o token expire.

Cenário Descrição
Aplicativos Recupere dados para todos os aplicativos registrados em sua conta do Partner Center e crie envios para aplicativos. Para obter mais informações sobre esses métodos, consulte os seguintes artigos:
Complementos Obtenha, crie ou exclua complementos para seus aplicativos e, em seguida, obtenha, crie ou exclua os envios dos complementos. Para obter mais informações sobre esses métodos, consulte os seguintes artigos:
Pacotes de pré-lançamento Obtenha, crie ou exclua pacotes de pré-lançamento para seus aplicativos e, em seguida, obtenha, crie ou exclua os envios de pacotes de pré-lançamento. Para obter mais informações sobre esses métodos, consulte os seguintes artigos:

Exemplos de código

Os artigos a seguir fornecem exemplos detalhados de código que demonstram como usar a API de envio da Microsoft Store em várias 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.

Solução de problemas

Problema Resolução
Depois de chamar a API de envio da Microsoft Store do PowerShell, os dados de resposta da API ficarão corrompidos se você convertê-la do formato JSON para um objeto do PowerShell usando o cmdlet ConvertFrom-Json e depois voltar para o formato JSON usando o cmdlet ConvertTo Json. Por padrão, o parâmetro -Depth para o cmdlet ConvertTo Json é definido como dois níveis de objetos, que é muito superficial para a maioria dos objetos JSON que são retornados pela API de envio da Microsoft Store. Quando você chamar o cmdlet ConvertTo Json, defina o parâmetro -Depth como um número maior, como 20.

Ajuda adicional

Se você tiver dúvidas sobre a API de envio da Microsoft Store ou precisar de ajuda para gerenciar seus envios com essa API, use os seguintes recursos:

  • Pergunte em nossos fóruns.
  • Visite nossa página de suporte e solicite uma das opções de suporte assistido para o Partner Center. Se você for solicitado a escolher um tipo de problema e categoria, escolha Certificação e envio de aplicativo e Enviando um aplicativo, respectivamente.