Gérer les soumissions de modules complémentaires

  • Article

L’API de soumission du Microsoft Store fournit des méthodes que vous pouvez utiliser pour gérer les soumissions de modules complémentaires (également appelés produits dans l’application ou IAP) pour vos applications. Pour une présentation de l’API de soumission du Microsoft Store, y compris les conditions préalables à l’utilisation de l’API, consultez Créer et gérer des soumissions à l’aide des services du Microsoft Store.

Important

Si vous utilisez l’API de soumission du Microsoft Store pour créer une soumission pour un module complémentaire, veillez à ne modifier la soumission qu’à l’aide de l’API, plutôt que dans l’Espace partenaires. Si vous utilisez l’Espace partenaires pour modifier une soumission que vous avez créée avec l’API, vous ne pourrez plus la modifier ou la valider à l’aide de l’API. Dans certains cas, la soumission peut être laissée dans l’état d’erreur, ce qui empêche le processus de soumission de se poursuivre. Si cela se produit, vous devez supprimer la soumission et en créer une nouvelle.

Méthodes de gestion des soumissions de modules complémentaires

Utilisez les méthodes suivantes pour obtenir, créer, mettre à jour, valider ou supprimer une soumission de module complémentaire. Avant de pouvoir utiliser ces méthodes, le module complémentaire doit déjà exister dans votre compte Espace partenaires. Vous pouvez créer un module complémentaire dans l’Espace partenaires en définissant son type de produit et son ID de produit ou en utilisant les méthodes d’API de soumission du Microsoft Store décrites dans Gérer les modules complémentaires.

Method URI Description
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Obtenir une soumission de module complémentaire existant
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status Obtenir l’état d’une soumission de module complémentaire existant
PUBLICATION https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions Créer une nouvelle soumission de module complémentaire
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Mettre à jour une soumission de module complémentaire existant
PUBLICATION https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit Valider une soumission de module complémentaire nouvelle ou mise à jour
DELETE https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Supprimer une soumission de module complémentaire

Créer une soumission de module complémentaire

Pour créer une soumission de module complémentaire, suivez le processus ci-dessous.

  1. Si vous ne l’avez pas encore fait, remplissez les conditions préalables décrites dans Créer et gérer des soumissions à l’aide des services du Microsoft Store, notamment l’association d’une application Azure AD à votre compte Espace partenaires et l’obtention de votre ID client et de votre clé. Vous devez le faire une seule fois, car ensuite, vous pouvez réutiliser l’ID client et la clé chaque fois que vous devez créer un jeton d’accès Azure AD.

  2. Obtenir un jeton d’accès Azure AD. Vous devez transmettre ce jeton d’accès aux méthodes dans l’API de soumission au Microsoft Store. Une fois que vous avez récupéré le jeton d’accès, vous avez 60 minutes pour l’utiliser avant qu’il n’expire. Une fois le jeton expiré, vous pouvez en obtenir un nouveau.

  3. Exécutez la méthode suivante dans l’API de soumission au Microsoft Store. Cette méthode crée une nouvelle soumission en cours, qui est une copie de votre dernière soumission publiée. Pour plus d’informations, consultez Créer une soumission de module complémentaire.

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

    Le corps de la réponse contient une ressource de soumission de module complémentaire qui comprend l’identifiant de la nouvelle soumission, l’URI de la signature d’accès partagée (SAS) pour le téléchargement d’icônes de module complémentaire pour la soumission dans Azure Blob Storage, et toutes les données de la nouvelle soumission (telles que les listes et les informations sur les prix).

    Remarque

    Un URI SAS permet d’accéder à une ressource sécurisée dans le stockage Azure sans clés de compte. Pour plus d’informations générales sur les URI SAS et leur utilisation avec le Stockage Blob Azure, consultez Signatures d’accès partagé, partie 1 : compréhension du modèle SAS et Signatures d’accès partagé, partie 2 : créer et utiliser une SAS avec le stockage Blob.

  4. Si vous ajoutez de nouvelles icônes pour la soumission, préparez les icônes et ajoutez-les à une archive ZIP.

  5. Mettez à jour les données de la soumission du module complémentaire avec toutes les modifications requises pour la nouvelle soumission, et appliquez la méthode suivante pour mettre à jour la soumission. Pour plus d’informations, consultez Mettre à jour une soumission de module complémentaire.

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

    Remarque

    Si vous ajoutez de nouvelles icônes pour la soumission, veillez à mettre à jour les données de cette dernière afin de faire référence au nom et au chemin d’accès relatif de ces fichiers dans l’archive ZIP.

  6. Si vous ajoutez de nouvelles icônes pour la soumission, téléchargez l’archive ZIP vers le Stockage Blob Azure à l’aide de l’URI SAS fourni dans le corps de la réponse de la méthode POST que vous avez appelée précédemment. Il existe différentes bibliothèques Azure que vous pouvez utiliser pour faire cela sur diverses plateformes, notamment :

    L’exemple de code C# suivant montre comment télécharger une archive ZIP vers le Stockage Blob Azure à l’aide de la classe CloudBlockBlob dans la bibliothèque cliente Stockage Azure pour .NET. Cet exemple présuppose que l’archive ZIP a déjà été écrite dans un objet de flux.

    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. Validez la soumission à l’aide de la méthode suivante. L’Espace partenaires sera ainsi informé que vous avez terminé votre soumission et que vos mises à jour doivent maintenant être appliquées à votre compte. Pour plus d’informations, consultez Valider une soumission de module complémentaire.

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

  8. Vérifiez l’état de validation à l’aide de la méthode suivante. Pour plus d’informations, consultez Obtenir l’état d’une soumission de module complémentaire.

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

    Pour confirmer l’état de la soumission, vérifiez la valeur d’état dans le corps de la réponse. Cette valeur doit passer de CommitStarted à PreProcessing, si la requête réussit, ou CommitFailed en cas d’erreurs dans la requête. En cas d’erreur, le champ statusDetails contient des détails supplémentaires sur cette dernière.

  9. Une fois la validation terminée, la soumission est envoyée au Store pour ingestion. Vous pouvez continuer à suivre le déroulement de la soumission en utilisant la méthode précédente ou en vous rendant dans l’Espace partenaires.

Exemples de code

Les articles suivants fournissent des exemples détaillés de code qui démontrent comment créer une soumission de module complémentaire dans plusieurs langages de programmation :

Module PowerShell StoreBroker

Au lieu d’appeler directement l’API de soumission au Microsoft Store, nous fournissons également un module PowerShell open-source qui implémente une interface de ligne de commande parallèlement à l’API. Ce module s’appelle StoreBroker. Vous pouvez l’utiliser pour gérer votre application, la version d’évaluation et des soumissions de modules complémentaires à partir de la ligne de commande au lieu d’appeler directement l’API de soumission au Microsoft Store. Vous pouvez aussi simplement parcourir la source pour voir d’autres exemples sur la façon d’appeler cette API. Le module StoreBroker est fréquemment utilisé au sein de Microsoft comme principal moyen de soumettre des applications internes au Store.

Pour plus d’informations, consultez notre page StoreBroker sur GitHub.

Ressources de données

Les méthodes d’API de soumission au Microsoft Store pour la gestion des soumissions de modules complémentaires utilisent les ressources de données JSON suivantes.

Ressource de soumission de module complémentaire

Cette ressource décrit une soumission de module complémentaire.

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

Cette ressource a les valeurs suivantes.

Valeur Type Description
id string L’ID de la soumission. Cet ID est disponible dans les données de réponse pour les demandes de création d’une soumission de module complémentaire, d’obtention de tous les modules complémentaires et d’obtention d’un module complémentaire. Pour une soumission créée dans l’Espace partenaires, cet ID est également disponible dans l’URL de la page de soumission dans l’Espace partenaires.
contentType string Le type de contenu fourni dans le module complémentaire. Il peut s’agir de l’une des valeurs suivantes :
  • NotSet
  • BookDownload
  • EMagazine
  • ENewspaper
  • MusicDownload
  • MusicStream
  • OnlineDataStorage
  • VideoDownload
  • VideoStream
  • Asp
  • OnlineDownload
mots clés tableau Tableau de chaînes contenant jusqu’à 10 mot clés pour le module complémentaire. Votre application peut rechercher des modules complémentaires à l’aide de ces mot clé.
lifetime string Durée de vie du module complémentaire. Il peut s’agir de l’une des valeurs suivantes :
  • Toujours
  • OneDay
  • ThreeDays
  • FiveDays
  • OneWeek
  • TwoWeeks
  • OneMonth
  • TwoMonths
  • ThreeMonths
  • SixMonths
  • OneYear
référencements object Dictionnaire de paires clé et valeur, où chaque clé est un code de pays ISO 3166-1 alpha-2 à deux lettres et chaque valeur est une ressource de référencement qui contient des informations de référencement pour le module complémentaire.
Prix object Ressource de tarification qui contient des informations de tarification pour le module complémentaire.
targetPublishMode string Mode de publication de la soumission. Il peut s’agir de l’une des valeurs suivantes :
  • Immédiat
  • Manuel
  • SpecificDate
targetPublishDate string Date de publication de la soumission au format ISO 8601, si le targetPublishMode est défini sur SpecificDate.
tag string Données de développeur personnalisées pour le module complémentaire (ces informations étaient précédemment appelées balise).
visibility string Visibilité du module complémentaire. Il peut s’agir de l’une des valeurs suivantes :
  • Masqué(e)
  • Public
  • Privée
  • NotSet
statut string État de la soumission. Il peut s’agir de l’une des valeurs suivantes :
  • Aucun
  • Annulé
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Publication
  • Publiée
  • PublishFailed
  • PreProcessing
  • PreProcessingFailed
  • Certification
  • CertificationFailed
  • Libérer
  • ReleaseFailed
statusDetails object Ressource de détails sur l’état qui contient des détails supplémentaires sur l’état de la soumission, y compris des informations sur les erreurs éventuelles.
fileUploadUrl string URI de signature d’accès partagé (SAS) pour le téléchargement de packages pour la soumission. Si vous ajoutez de nouveaux packages pour la soumission, téléchargez l’archive ZIP qui contient les packages vers cet URI. Pour plus d’informations, consultez Créer une soumission de module complémentaire.
friendlyName string Nom convivial de la soumission tel qu’il apparaît dans l’Espace partenaires. Cette valeur est générée pour vous lorsque vous créez la soumission.

Ressource liste

Cette ressource contient des informations de liste pour un module complémentaire. Cette ressource a les valeurs suivantes.

Valeur Type Description
description string Description pour la liste du module complémentaire.
icône object Ressource d’icône qui contient des données pour l’icône de la liste du module complémentaire.
title string Titre pour la liste du module complémentaire.

Ressource d’icône

Cette ressource contient des données d’icône pour une liste de module complémentaire. Cette ressource a les valeurs suivantes.

Valeur Type Description
fileName string Nom du fichier d’icône dans l’archive ZIP que vous avez téléchargée pour la soumission. L’icône doit être un fichier .png avec les dimensions exactes suivantes : 300 x 300 pixels.
fileStatus string État du fichier d’icône. Il peut s’agir de l’une des valeurs suivantes :
  • Aucun
  • PendingUpload
  • Chargé
  • PendingDelete

Ressource sur la tarification

Cette ressource contient des informations sur la tarification pour le module complémentaire. Cette ressource a les valeurs suivantes.

Valeur Type Description
marketSpecificPricings object Dictionnaire de paires clé et valeur, où chaque clé est un code de pays ISO 3166-1 alpha-2 à deux lettres et chaque valeur est un niveau tarifaire. Ces éléments représentent les prix personnalisés de votre module complémentaire sur des marchés spécifiques. Tous les éléments de ce dictionnaire remplacent le prix de base spécifié par la valeur priceId pour le marché spécifié.
sales tableau Déconseillé. Tableau de ressources de vente qui contiennent des informations de vente pour le module complémentaire.
priceId string Niveau tarifaire qui spécifie le prix de base du module complémentaire.
isAdvancedPricingModel booléen Si la valeur est true, votre compte de développeur a accès à l’ensemble étendu des niveaux tarifaires de 0,99 USD à 1 999,99 USD. Si la valeur est false, votre compte de développeur a accès à l’ensemble des niveaux tarifaires d’origine de 0,99 USD à 999,99 USD. Pour plus d’informations sur les différents niveaux, consultez les niveaux tarifaires.

Remarque Ce champ est en lecture seule.

Ressource de vente

Ces ressources contiennent des informations de vente pour un module complémentaire.

Important

La ressource Vente n’est plus prise en charge et vous ne pouvez pas obtenir ou modifier les données de vente pour une soumission de module complémentaire à l’aide de l’API de soumission au Microsoft Store. Nous mettrons à jour l’API de soumission au Microsoft Store pour introduire une nouvelle façon d’accéder par programmation aux informations de vente pour les soumissions de modules complémentaires.

Cette ressource a les valeurs suivantes.

Valeur Type Description
name chaîne Nom de la vente.
basePriceId string Niveau tarifaire à utiliser pour le prix de base de la vente.
startDate string Date de début de la vente, au format ISO 8601.
endDate string Date de fin de la vente, au format ISO 8601.
marketSpecificPricings object Dictionnaire de paires clé et valeur, où chaque clé est un code de pays ISO 3166-1 alpha-2 à deux lettres et chaque valeur est un niveau tarifaire. Ces éléments représentent les prix personnalisés de votre module complémentaire sur des marchés spécifiques. Tous les éléments de ce dictionnaire remplacent le prix de base spécifié par la valeur basePriceId pour le marché spécifié.

Ressource de détails de l’état

Cette ressource contient des détails supplémentaires sur l’état d’une soumission. Cette ressource a les valeurs suivantes.

Valeur Type Description
erreurs object Tableau de ressources de détails de l’état qui contient des détails d’erreur pour la soumission.
Avertissements object Tableau de ressources de détails de l’état qui contient des détails d’avertissement pour la soumission.
certificationReports object Tableau de ressources du rapport de certification qui donnent accès aux données du rapport de certification pour la soumission. Vous pouvez examiner ces rapports pour plus d’informations si la certification échoue.

Ressource de détails de l’état

Cette ressource contient des informations supplémentaires sur les erreurs ou avertissements associés concernant une soumission. Cette ressource a les valeurs suivantes.

Valeur Type Description
code string Code d’état d’une soumission qui décrit le type d’erreur ou d’avertissement.
details string Message contenant plus de détails sur le problème.

Ressource de rapport de certification

Cette ressource donne accès aux données du rapport de certification pour une soumission. Cette ressource a les valeurs suivantes.

Valeur Type Description
date string La date et l’heure du rapport sont générées au format ISO 8601.
reportUrl string URL permettant d’accéder au rapport.

Énumérations

Ces méthodes utilisent les énumérations suivantes.

Niveaux tarifaires

Les valeurs suivantes représentent les niveaux tarifaires disponibles dans la ressource de tarification pour une soumission de module complémentaire.

Valeur Description
Base Le niveau tarifaire n’est pas défini ; utilisez le prix de base pour le module complémentaire.
NotAvailable Le module complémentaire n’est pas disponible dans la région spécifiée.
Gratuit Le module complémentaire est gratuit.
Niveauxxxx Chaîne qui spécifie le niveau tarifaire du module complémentaire, au format Tierxxxx. Actuellement, les plages tarifaires suivantes sont prises en charge :

  • Si la valeur isAdvancedPricingModel de la ressource tarifaire est true, les valeurs de niveau tarifaire disponibles pour votre compte sont Tier1012 - Tier1424.
  • Si la valeur isAdvancedPricingModel de la ressource tarifaire est false, les valeurs de niveau tarifaire disponibles pour votre compte sont Tier2 - Tier96.
Pour consulter le tableau complet des niveaux tarifaires disponibles pour votre compte de développeur, y compris les prix spécifiques au marché associés à chaque niveau, accédez à la page Tarification et disponibilité de l’une de vos soumissions d’applications dans l’Espace partenaires, puis cliquez sur le lien afficher le tableau dans la section Marchés et prix personnalisés (pour certains comptes de développeur, ce lien se trouve dans la rubrique Tarification).

Code d’état de la soumission

Les valeurs suivantes représentent le code d’état d’une soumission.

Valeur Description
None Aucun code n’a été spécifié.
InvalidArchive L’archive ZIP contenant le package n’est pas valide ou son format d’archive n’est pas reconnu.
MissingFiles L’archive ZIP ne contient pas tous les fichiers répertoriés dans vos données de soumission, ou alors ils se trouvent à un emplacement erroné dans l’archive.
PackageValidationFailed Un ou plusieurs packages de votre soumission n’ont pas pu être validés.
InvalidParameterValue L’un des paramètres du corps de la requête n’est pas valide.
InvalidOperation L’opération tentée n’est pas valide.
InvalidState L’opération tentée n’est pas valide pour l’état actuel de la version d’évaluation de package.
ResourceNotFound Le fichier de la version d’évaluation de package spécifié est introuvable.
ServiceError Une erreur de service interne a empêché le succès de la requête. Essayez à nouveau.
ListingOptOutWarning Le développeur a supprimé une liste d’une soumission précédente ou n’a pas inclus les informations de référencement prises en charge par le package.
ListingOptInWarning Le développeur a ajouté une liste.
UpdateOnlyWarning Le développeur essaie d’insérer quelque chose qui dispose seulement d’une prise en charge des mises à jour.
Autres La soumission est dans un état non reconnu ou non catégorisé.
PackageValidationWarning Le processus de validation du package a donné lieu à un avertissement.