Compartilhar via


Gerenciar envios de extensões

A API de envio da Microsoft Store fornece métodos que você pode usar para gerenciar envios de complemento (também conhecido como produto no aplicativo ou IAP) para seus aplicativos. 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 complemento, certifique-se de fazer mais alterações no envio apenas usando a API, em vez de fazer alterações 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 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 complemento

Use os métodos a seguir para obter, criar, atualizar, confirmar ou excluir uma submissão de complemento. Antes de usar esses métodos, o complemento já deve existir em sua conta do Partner Center. Você pode criar um complemento no Partner Center definindo o tipo de produto e a ID do produto ou usando os métodos de API de envio da Microsoft Store descritos em Gerenciar complementos.

Método URI Descrição
OBTER https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Obter uma submissão existente de complemento
OBTER https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status Obter o status de uma submissão de complemento existente
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions Criar uma nova submissão de extensão
COLOCAR https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Atualizar uma submissão existente de complemento
PUBLICAR https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit Confirmar um de envio de complemento novo ou atualizado
EXCLUIR https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Excluir uma submissão de complemento

Criar uma submissão de complemento

Para criar uma submissão para um complemento, siga este procedimento.

  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. Execute 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 seu último envio publicado. Para obter mais informações, consulte Criar uma submissão de complemento.

    POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions
    

    O corpo da resposta contém um recurso de submissão de add-on que inclui a ID da nova submissão, o URI de SAS (Assinatura de Acesso Compartilhado) para fazer upload de quaisquer ícones de add-on para a submissão ao Armazenamento de Blobs do Azure, e todos os dados referentes à nova submissão (como as listagens e informações de preço).

    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 ícones de envio, prepare os ícones e adicione-os a um arquivo ZIP.

  5. Atualize os dados da submissão de complemento com as alterações necessárias para o novo envio e execute o método a seguir para atualizá-lo. Para obter mais informações, consulte Atualizar uma submissão de complemento.

    PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}
    

    Observação

    Se você estiver adicionando novos ícones 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 ícones 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. Confirme o envio 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. Para obter mais informações, consulte Realizar um envio de complemento.

    POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit
    
  8. Verifique o status de confirmação executando o método a seguir. Para mais informações, consulte Verificar o status de uma submissão de complemento.

    GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/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 um envio de complemento em várias linguagens de programação diferentes:

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.

Recursos de dados

Os métodos da API de submissão da Microsoft Store para gerenciar submissões de complementos usam os seguintes recursos de dados JSON.

Recurso para submissão de complemento

Esse recurso descreve um envio de complemento.

{
  "id": "1152921504621243680",
  "contentType": "EMagazine",
  "keywords": [
    "books"
  ],
  "lifetime": "FiveDays",
  "listings": {
    "en": {
      "description": "English add-on description",
      "icon": {
        "fileName": "add-on-en-us-listing2.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (English)"
    },
    "ru": {
      "description": "Russian add-on description",
      "icon": {
        "fileName": "add-on-ru-listing.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (Russian)"
    }
  },
  "pricing": {
    "marketSpecificPricings": {
      "RU": "Tier3",
      "US": "Tier4",
    },
    "sales": [],
    "priceId": "Free",
    "isAdvancedPricingModel": true
  },
  "targetPublishDate": "2016-03-15T05:10:58.047Z",
  "targetPublishMode": "Immediate",
  "tag": "SampleTag",
  "visibility": "Public",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [
      {
        "code": "None",
        "details": "string"
      }
    ],
    "warnings": [
      {
        "code": "ListingOptOutWarning",
        "details": "You have removed listing language(s): []"
      }
    ],
    "certificationReports": [
      {
      }
    ]
  },
  "fileUploadUrl": "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",
  "friendlyName": "Submission 2"
}

Esse recurso tem os seguintes valores.

Valor Tipo Descrição
id corda O ID do envio. Este ID está disponível nos dados de resposta para solicitações de criação de envio de complemento, obtenção de todos os complementos, e obtenção de um complemento. Para um envio criado no Partner Center, essa ID também está disponível na URL para a página de envio no Partner Center.
tipo de conteúdo corda O tipo de conteúdo fornecido no complemento. Esse valor pode ser um dos seguintes:
  • Não definido
  • Download de Livro
  • EMagazine
  • E-Jornal
  • Download de Música
  • MusicStream
  • OnlineDataStorage
  • Download de Vídeo
  • VideoStream
  • Naja
  • OnlineDownload
Palavras-chave conjunto Uma matriz de cadeias de caracteres que contêm até 10 palavras-chave para o complemento. Seu aplicativo pode consultar complementos usando essas palavras-chave.
duração da vida corda A vida útil do complemento. Esse valor pode ser um dos seguintes:
  • Eternamente
  • Um Dia
  • ThreeDays
  • FiveDays
  • OneWeek
  • TwoWeeks
  • UmMês
  • Dois Meses
  • TrêsMeses
  • SeisMeses
  • UmAno
Listas objeto Um dicionário de pares chave e valor, em que cada chave é um código de país ISO 3166-1 alfa-2 de duas letras e cada valor é um recurso de listagem que contém informações de listagem para o add-on.
preços objeto Um recurso de precificação que contém informações de preços para o complemento.
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.
etiqueta corda O dados personalizados do desenvolvedor para o complemento (essas informações eram anteriormente chamadas de de marca).
visibilidade corda A visibilidade do complemento. Esse valor pode ser um dos seguintes:
  • Oculto
  • Público
  • Privado
  • Não definido
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.
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 complemento.
nome amigável corda O nome amigável do envio, conforme mostrado no Partner Center. Este valor é gerado para você quando você cria a submissão.

Listagem de recursos

Este recurso contém informações de listagem para um complemento. Esse recurso tem os seguintes valores.

Valor Tipo Descrição
descrição corda A descrição da listagem de complementos.
ícone objeto Um recurso de ícone que contém dados para o ícone para a listagem de complementos.
título corda O título da listagem de complementos.

Recurso de ícone

Esse recurso contém dados de ícone para uma listagem de complementos. Esse recurso tem os seguintes valores.

Valor Tipo Descrição
nome do arquivo corda O nome do arquivo de ícone no arquivo ZIP que você carregou para o envio. O ícone deve ser um arquivo .png que mede exatamente 300 x 300 pixels.
fileStatus corda O status do arquivo de ícone. Esse valor pode ser um dos seguintes:
  • Nenhum
  • Envio Pendente
  • Enviado
  • Deleção Pendente

Recursos de precificação

Esse recurso contém informações de preços para o complemento. Esse recurso tem os seguintes valores.

Valor Tipo Descrição
preçosEspecíficosDeMercado objeto Um dicionário de pares chave e valor, no qual cada chave é um código de país ISO 3166-1 alfa-2 de duas letras e cada valor é uma faixa de preço. Esses itens representam os preços personalizados para seu complemento em mercados específicos. Todos os itens neste dicionário substituem o preço base especificado pelo valor priceId para o mercado especificado.
vendas conjunto Preterido. Uma matriz de recursos de venda que contêm informações de vendas para o complemento.
priceId corda Um tipo de preço que especifica o de preço base para o complemento.
éModeloDePrecificaçãoAvançada booleano Se for verdadeiro, sua conta de desenvolvedor terá acesso ao conjunto expandido de faixas de preço de US$ 0,99 a US$ 1.999,99. Se falso, sua conta de desenvolvedor tem acesso ao conjunto original de tipos de preço de 0,99 USD a 999,99 USD. Para obter mais informações sobre os diferentes níveis, consulte tipos de preço.

Observação Este campo é somente leitura.

Recurso de vendas

Este recurso contém informações de venda para um complemento.

Importante

O recurso Sale não é mais suportado e, atualmente, você não pode obter ou modificar os dados de venda para uma submissão de add-on usando a API de submissão da Microsoft Store. No futuro, atualizaremos a API de envio da Microsoft Store para introduzir uma nova maneira de acessar programaticamente as informações de vendas para envios de complementos.

  • Depois de chamar o método GET para obter uma submissão de complemento, o valor de vendas do estará vazio. Você pode continuar a usar o Partner Center para obter os dados de venda para a submissão do complemento.
  • Ao chamar o método PUT para atualizar a submissãode complemento, as informações no valor de vendas são ignoradas. Você pode continuar a usar o Partner Center para alterar os dados de venda da submissão do complemento.

Esse recurso tem os seguintes valores.

Valor Tipo Descrição
nome corda O nome da venda.
basePriceId corda A faixa de preço para usar como o preço base da venda.
Data de Início corda A data de início da venda no formato ISO 8601.
data de término corda A data de término da venda no formato ISO 8601.
preçosEspecíficosDeMercado objeto Um dicionário de pares chave e valor, no qual cada chave é um código de país ISO 3166-1 alfa-2 de duas letras e cada valor é uma faixa de preço. Esses itens representam os preços personalizados para seu complemento em mercados específicos. Quaisquer itens neste dicionário substituem o preço base especificado pelo basePriceId para o mercado especificado.

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.

Enumerações

Esses métodos usam as enumerações a seguir.

Tipos de preço

Os valores a seguir representam as faixas de preço disponíveis no recurso de precificação do recurso para a submissão de um complemento.

Valor Descrição
Base O tipo de preço não está definido; use o preço base para o complemento.
Não disponível O complemento não está disponível na região especificada.
Grátis O complemento é gratuito.
Camadaxxxx Uma cadeia de caracteres que especifica a faixa de preço do complemento, no formato Camadaxxxx. Atualmente, há suporte para as seguintes faixas de preço:

  • Se o isAdvancedPricingModel valor do recurso de precificação for verdadeiro, os valores de nível de preço disponíveis para sua conta serão Tier1012 - Tier1424.
  • Se o valor de isAdvancedPricingModel do recurso de precificação for falso, os níveis de preço disponíveis para sua conta serão Nível 2 - Nível 96.
Para ver a tabela completa de tipos de preço que estão disponíveis para sua conta de desenvolvedor, incluindo os preços específicos do mercado que estão associados a cada camada, acesse a página Preços e disponibilidade para qualquer um dos envios de aplicativo no Partner Center e clique no link ver tabela na seção Mercados e preços personalizados (para algumas contas de desenvolvedor, este link está na seção Preços).

Código de status de envio

Os valores a seguir representam o código de status de um envio.

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