Compartilhar via

Gerenciar envios de complemento

  • Artigo

A API de envio da Microsoft Store fornece métodos que você pode usar para gerenciar envios de complementos (também conhecidos como produtos 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 somente 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 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 complementos

Use os seguintes métodos para obter, criar, atualizar, confirmar ou excluir um envio 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 seu tipo de produto e ID do produto ou usando os métodos da API de envio da Microsoft Store descritos em Gerenciar complementos.

Método URI Descrição
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Obter um envio de complemento existente
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status Obter o status de um envio de complemento existente
POSTAR https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions Criar um novo envio de complemento
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Atualizar um envio de complemento existente
POSTAR https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit Confirmar um envio de complemento novo ou atualizado
DELETE https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Excluir um envio de complemento

Criar um envio de complemento

Para criar um envio para um complemento, 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. Execute o seguinte método na API de envio da Microsoft Store. Esse método cria um novo envio em andamento, que é uma cópia do último envio publicado. Para obter mais informações, consulte Criar um envio de complemento.

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

    O corpo da resposta contém um recurso de envio de complemento que inclui a ID do novo envio, o URI de assinatura de acesso compartilhado (SAS) para carregar quaisquer ícones de complemento para o envio ao Armazenamento de Blobs do Azure e todos os dados para o novo envio (como 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 ícones para o envio, prepare os ícones e adicione-os a um arquivo ZIP.

  5. Atualize os dados de envio do complemento com as alterações necessárias para o novo envio e execute o seguinte método para atualizar o envio . Para obter mais informações, consulte Atualizar um envio 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, certifique-se de atualizar os dados de envio para fazer referência 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 no Armazenamento de Blobs do Azure usando o URI SAS fornecido no corpo da resposta do método POST chamado 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 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 Comprometer-se com 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 obter mais informações, consulte Obter o status de um envio de complemento.

    GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/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 complemento 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.

Recursos de dados

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

Recurso de envio de complemento

Este 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"
}

Este recurso possui os seguintes valores.

Valor Type Descrição
id string A ID do envio. Essa ID está disponível nos dados de resposta para solicitações para criar um envio de complemento, obter todos os complementos e obter um complemento. Para um envio criado no Partner Center, essa ID também está disponível na URL da página de envio no Partner Center.
contentType string O tipo de conteúdo fornecido no complemento. Esse valor pode ser um dos seguintes:
  • NotSet
  • BookDownload
  • EMagazine
  • ENewspaper
  • MusicDownload
  • MusicStream
  • OnlineDataStorage
  • VideoDownload
  • VideoStream
  • ASP
  • OnlineDownload
palavras-chave matriz 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.
lifetime string O tempo de vida do complemento. Esse valor pode ser um dos seguintes:
  • Para sempre
  • OneDay
  • ThreeDays
  • FiveDays
  • OneWeek
  • TwoWeeks
  • OneMonth
  • TwoMonths
  • ThreeMonths
  • SixMonths
  • OneYear
listagens objeto Um dicionário de pares de chaves e valores, onde cada chave é um código de país ISO 3166-1 alpha-2 de duas letras e cada valor é um recurso de listagem que contém informações de listagem para o complemento.
preços objeto Um recurso de preços que contém informações de preços para o complemento.
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.
marcação string Os dados personalizados do desenvolvedor para o complemento (essas informações eram anteriormente chamadas de tag).
visibility string A visibilidade do complemento. Esse valor pode ser um dos seguintes:
  • Oculto
  • Setor Público
  • Privados
  • NotSet
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.
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 complemento.
friendlyName string O nome amigável do envio, conforme mostrado no Partner Center. Esse valor é gerado para você quando você cria o envio.

Recurso de listagem

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

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

Ícone de recurso

Este recurso contém dados de ícone para uma listagem de complemento. Este recurso possui os seguintes valores.

Valor Type Descrição
fileName string 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 string O status do arquivo de ícone. Esse valor pode ser um dos seguintes:
  • Nenhum
  • PendingUpload
  • Carregado
  • PendingDelete

Recursos de preço

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

Valor Type Descrição
marketSpecificPricings objeto Um dicionário de pares de chaves e valores, onde cada chave é um código de país ISO 3166-1 alpha-2 de duas letras e cada valor é uma camada 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 matriz Preterido. Uma matriz de recursos de venda que contém informações de vendas para o complemento.
priceId string Uma camada de preço que especifica o preço base para o complemento.
isAdvancedPricingModel boolean Se for verdade, sua conta de desenvolvedor terá acesso ao conjunto expandido de níveis de preço de .99 USD a 1999.99 USD. Se falso, sua conta de desenvolvedor terá acesso ao conjunto original de níveis de preço de 0,99 USD a 999,99 USD. Para obter mais informações sobre as diferentes camadas, consulte Camadas de preço.

Nota Este campo é somente leitura.

Recurso de venda

Esses recursos contêm informações de venda para um complemento.

Importante

O recurso Venda não é mais suportado e, no momento, você não pode obter ou modificar os dados de venda para um envio de complemento usando a API de envio 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 um envio de complemento, o valor de vendas estará vazio. Você pode continuar a usar o Partner Center para obter os dados de venda para o envio do complemento.
  • Ao chamar o método PUT para atualizar um envio de 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 para o envio do complemento.

Este recurso possui os seguintes valores.

Valor Type Descrição
name string O nome da venda.
basePriceId string A camada de preço a ser usada para o preço base da venda.
startDate string A data de início da venda, no formato ISO 8601.
endDate string A data de fim da venda, no formato ISO 8601.
marketSpecificPricings objeto Um dicionário de pares de chaves e valores, onde cada chave é um código de país ISO 3166-1 alpha-2 de duas letras e cada valor é uma camada 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 basePriceId para o mercado especificado.

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.

Enumerações

Esses métodos usam os seguintes enums.

Faixas de preço

Os valores a seguir representam as camadas de preço disponíveis no recurso de recurso de preços para um envio de complemento.

Valor Descrição
Base O nível de preço não está definido; Use o preço base para o complemento.
NotAvailable O complemento não está disponível na região especificada.
Gratuita O complemento é gratuito.
Nívelxxxx Uma cadeia de caracteres que especifica a camada de preço para o complemento, no formato Camadaxxxx. Atualmente, os seguintes intervalos de níveis de preço são suportados:

Para ver a tabela completa de níveis de preços disponíveis para sua conta de desenvolvedor, incluindo os preços específicos do mercado associados a cada camada, vá para a página Preço e disponibilidade de qualquer um dos envios de aplicativos no Partner Center e clique no link da tabela de exibição 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.
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.