Verwalten von Add-On-Übermittlungen

  • Artikel

Die Microsoft Store-Übermittlungs-API bietet Methoden zum Verwalten von Add-On-Übermittlungen (auch als In-App-Produkt oder IAP bezeichnet) für Ihre Apps. Eine Einführung in die Microsoft Store-Übermittlungs-API, einschließlich der Voraussetzungen für die Verwendung der API, finden Sie unter Erstellen und Verwalten von Übermittlungen mithilfe von Microsoft Store-Diensten.

Wichtig

Wenn Sie die Microsoft Store-Übermittlungs-API zum Erstellen einer Übermittlung für ein Add-On verwenden, stellen Sie sicher, dass Sie weitere Änderungen an der Übermittlung nur mithilfe der API vornehmen, anstatt Änderungen im Partner Center vorzunehmen. Wenn Sie Partner Center verwenden, um eine Übermittlung zu ändern, die Sie ursprünglich mithilfe der API erstellt haben, können Sie diese Übermittlung nicht mehr mithilfe der API ändern oder übernehmen. In einigen Fällen kann die Übermittlung in einem Fehlerzustand verbleiben, in dem sie nicht im Übermittlungsprozess fortgesetzt werden kann. In diesem Fall müssen Sie die Übermittlung löschen und eine neue Übermittlung erstellen.

Methoden zum Verwalten von Add-On-Übermittlungen

Verwenden Sie die folgenden Methoden, um eine Add-On-Übermittlung abzurufen, zu erstellen, zu aktualisieren, zu übernehmen oder zu löschen. Bevor Sie diese Methoden verwenden können, muss das Add-On bereits in Ihrem Partner Center-Konto vorhanden sein. Sie können ein Add-On im Partner Center erstellen, indem Sie den Produkttyp und die Produkt-ID definieren oder die Methoden der Microsoft Store-Übermittlungs-API verwenden, die in Add-Ons verwalten beschrieben werden.

Methode URI Beschreibung
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Abrufen einer vorhandenen Add-On-Übermittlung
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status Abrufen des Status einer vorhandenen Add-On-Übermittlung
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions Erstellen einer neuen Add-On-Übermittlung
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Aktualisieren einer vorhandenen Add-On-Übermittlung
POST https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit Commit für eine neue oder aktualisierte Add-On-Übermittlung
DELETE https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId} Löschen einer Add-On-Übermittlung

Erstellen einer Add-On-Übermittlung

Führen Sie diesen Vorgang aus, um eine Übermittlung für ein Add-On zu erstellen.

  1. Wenn Sie dies noch nicht getan haben, füllen Sie die unter Erstellen und Verwalten von Übermittlungen mit Microsoft Store-Diensten beschriebenen Voraussetzungen aus, einschließlich der Zuordnung einer Azure AD-Anwendung zu Ihrem Partner Center-Konto und zum Abrufen Ihrer Client-ID und des Schlüssels. Sie müssen dies nur einmal tun; Nachdem Sie über die Mandanten-ID, die Client-ID und den Schlüssel verfügen, können Sie diese jederzeit wiederverwenden, wenn Sie ein neues Azure AD-Zugriffstoken erstellen müssen.

  2. Abrufen eines Azure AD-Zugriffstokens Sie müssen dieses Zugriffstoken an die Methoden in der Microsoft Store-Übermittlungs-API übergeben. Nachdem Sie ein Zugriffstoken erhalten haben, haben Sie 60 Minuten Zeit, es zu verwenden, bevor es abläuft. Nachdem das Token abgelaufen ist, können Sie eine neue abrufen.

  3. Führen Sie die folgende Methode in der Microsoft Store-Übermittlungs-API aus. Diese Methode erstellt eine neue laufende Übermittlung, bei der es sich um eine Kopie Ihrer letzten veröffentlichten Übermittlung handelt. Weitere Informationen finden Sie unter Erstellen einer Add-On-Übermittlung.

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

    Der Antworttext enthält eine Add-On-Übermittlungsressource, die die ID der neuen Übermittlung, den SAS-URI (Shared Access Signature) zum Hochladen von Add-On-Symbolen für die Übermittlung in Azure Blob Storage und alle Daten für die neue Übermittlung enthält (z. B. Die Auflistungen und Preisinformationen).

    Hinweis

    Ein SAS-URI bietet Zugriff auf eine sichere Ressource im Azure-Speicher, ohne dass Kontoschlüssel erforderlich sind. Hintergrundinformationen zu SAS-URIs und deren Verwendung mit Azure Blob Storage finden Sie unter Shared Access Signatures, Teil 1: Grundlegendes zum SAS-Modell und freigegebenen Zugriffssignaturen, Teil 2: Erstellen und Verwenden eines SAS mit Blob-Speicher.

  4. Wenn Sie neue Symbole für die Übermittlung hinzufügen, bereiten Sie die Symbole vor, und fügen Sie sie einem ZIP-Archiv hinzu.

  5. Aktualisieren Sie die Add-On-Übermittlungsdaten mit allen erforderlichen Änderungen für die neue Übermittlung, und führen Sie die folgende Methode aus, um die Übermittlung zu aktualisieren. Weitere Informationen finden Sie unter Aktualisieren einer Add-On-Übermittlung.

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

    Hinweis

    Wenn Sie neue Symbole für die Übermittlung hinzufügen, müssen Sie die Übermittlungsdaten aktualisieren, um auf den Namen und den relativen Pfad dieser Dateien im ZIP-Archiv zu verweisen.

  6. Wenn Sie neue Symbole für die Übermittlung hinzufügen, laden Sie das ZIP-Archiv mithilfe des SAS-URI in Azure Blob Storage hoch, der im Antworttext der POST-Methode bereitgestellt wurde, die Sie zuvor aufgerufen haben. Es gibt verschiedene Azure-Bibliotheken, mit denen Sie dies auf einer Vielzahl von Plattformen tun können, darunter:

    Im folgenden C#-Codebeispiel wird das Hochladen eines ZIP-Archivs in Azure Blob Storage mithilfe der CloudBlockBlobe-Klasse, in der Azure Storage-Clientbibliothek für .NET veranschaulicht. In diesem Beispiel wird davon ausgegangen, dass das ZIP-Archiv bereits in ein Streamobjekt geschrieben wurde.

    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. Führen Sie die folgende Methode aus, um die Übermittlung zu übernehmen. Dadurch wird Partner Center benachrichtigt, dass Sie mit Ihrer Übermittlung fertig sind und dass Ihre Updates jetzt auf Ihr Konto angewendet werden sollen. Weitere Informationen finden Sie unter Einreichen einer Add-On-Übermittlung.

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

  8. Überprüfen Sie den Commitstatus, indem Sie die folgende Methode ausführen. Weitere Informationen finden Sie unter Abrufen des Status einer Add-On-Übermittlung.

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

    Um den Übermittlungsstatus zu bestätigen, überprüfen Sie den Statuswert im Antworttext. Dieser Wert sollte von CommitStarted in PreProcessing geändert werden, wenn die Anforderung erfolgreich ist oder CommitFailed ausgeführt wird, wenn Fehler in der Anforderung vorhanden sind. Wenn Fehler vorhanden sind, enthält das Feld statusDetails weitere Details zum Fehler.

  9. Nachdem der Commit erfolgreich abgeschlossen wurde, wird die Übermittlung zur Aufnahme an den Store gesendet. Sie können den Übermittlungsfortschritt weiterhin mithilfe der vorherigen Methode oder über das Partner Center überwachen.

Codebeispiele

Die folgenden Artikel enthalten ausführliche Codebeispiele, die veranschaulichen, wie eine Add-On-Übermittlung in verschiedenen Programmiersprachen erstellt wird:

StoreBroker PowerShell-Modul

Als Alternative zum direkten Aufrufen der Microsoft Store-Übermittlungs-API stellen wir auch ein Open-Source-PowerShell-Modul bereit, das eine Befehlszeilenschnittstelle über die API implementiert. Dieses Modul wird als StoreBroker bezeichnet. Sie können dieses Modul verwenden, um Ihre App-, Flight- und Add-On-Übermittlungen über die Befehlszeile zu verwalten, anstatt die Microsoft Store-Übermittlungs-API direkt aufzurufen, oder Sie können einfach die Quelle durchsuchen, um weitere Beispiele für den Aufruf dieser API anzuzeigen. Das StoreBroker-Modul wird in Microsoft aktiv als primäre Art und Weise verwendet, wie viele Erstanbieteranwendungen an den Store übermittelt werden.

Weitere Informationen finden Sie auf unserer StoreBroker-Seite auf GitHub.

Datenressourcen

Die Methoden der Microsoft Store-Übermittlungs-API zum Verwalten von Add-On-Übermittlungen verwenden die folgenden JSON-Datenressourcen.

Add-On-Übermittlungsressource

Diese Ressource beschreibt eine Add-On-Übermittlung.

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

Diese Ressource weist die folgenden Werte auf:

Wert Typ Beschreibung
id Zeichenfolge Die ID der Übermittlung Diese ID steht in den Antwortdaten für Anforderungen zum Erstellen einer Add-On-Übermittlung, zum Abrufen aller Add-Ons und zum Abrufen eines Add-Ons zur Verfügung. Für eine Übermittlung, die im Partner Center erstellt wurde, ist diese ID auch in der URL für die Übermittlungsseite im Partner Center verfügbar.
contentType Zeichenfolge Der Inhaltstyp, der im Add-On bereitgestellt wird. Dies kann einer der folgenden Werte sein:
  • NotSet
  • BookDownload
  • EMagazine
  • ENewspaper
  • MusicDownload
  • MusicStream
  • OnlineDataStorage
  • VideoDownload
  • VideoStream
  • Asp
  • OnlineDownload
keywords array Ein Array von Zeichenfolgen, die bis zu 10 Schlüsselwörter für das Add-On enthalten. Ihre App kann mithilfe dieser Schlüsselwort (keyword) nach Add-Ons abfragen.
Lebensdauer Zeichenfolge Die Lebensdauer des Add-Ons. Dies kann einer der folgenden Werte sein:
  • Endlos
  • OneDay
  • ThreeDays
  • FiveDays
  • OneWeek
  • TwoWeeks
  • OneMonth
  • TwoMonths
  • ThreeMonths
  • SixMonths
  • OneYear
listings Objekt Ein Wörterbuch mit Schlüssel- und Wertpaaren, wobei jeder Schlüssel ein zweiseitiger ISO 3166-1 Alpha-2-Ländercode ist und jeder Wert eine Eintragsressource ist, die Eintragsinformationen für das Add-On enthält.
Preise Objekt Eine Preisressource, die Preisinformationen für das Add-On enthält.
targetPublishMode Zeichenfolge Der Veröffentlichungsmodus für die Übermittlung. Dies kann einer der folgenden Werte sein:
  • Direkt
  • Manuell
  • SpecificDate
targetPublishDate Zeichenfolge Das Veröffentlichungsdatum für die Übermittlung im ISO 8601-Format, wenn der targetPublishMode auf SpecificDate festgelegt ist.
tag Zeichenfolge Die benutzerdefinierten Entwicklerdaten für das Add-On (diese Informationen wurden zuvor als Tag bezeichnet).
Sichtbarkeit Zeichenfolge Die Sichtbarkeit des Add-Ons. Dies kann einer der folgenden Werte sein:
  • Ausgeblendet
  • Öffentlich
  • Privat
  • NotSet
status Zeichenfolge Der Status der Übermittlung. Dies kann einer der folgenden Werte sein:
  • Keine
  • Storniert
  • PendingCommit
  • CommitStarted
  • CommitFailed
  • PendingPublication
  • Veröffentlichung
  • Veröffentlicht
  • PublishFailed
  • PreProcessing
  • PreProcessingFailed
  • Zertifizierung
  • CertificationFailed
  • Freigabe
  • ReleaseFailed
statusDetails Objekt Eine Statusdetailsesource, die zusätzliche Details zum Status der Übermittlung enthält, einschließlich Informationen zu Fehlern.
fileUploadUrl Zeichenfolge Der SAS-URI (Shared Access Signature) zum Hochladen von Paketen für die Übermittlung. Wenn Sie neue Pakete für die Übermittlung hinzufügen, laden Sie das ZIP-Archiv hoch, das die Pakete enthält, in diesen URI. Weitere Informationen finden Sie unter Erstellen einer Add-On-Übermittlung.
friendlyName Zeichenfolge Der Anzeigename der Übermittlung, wie im Partner Center gezeigt. Dieser Wert wird für Sie generiert, wenn Sie die Übermittlung erstellen.

Auflistungsressource

Diese Ressource enthält Eintragsinformationen für ein Add-On. Diese Ressource weist die folgenden Werte auf:

Wert Typ BESCHREIBUNG
Beschreibung string Die Beschreibung für das Add-On-Listing.
Symbol Objekt Eine Symbolressource, die Daten für das Symbol für das Add-On-Listing enthält.
title Zeichenfolge Der Titel für das Add-On-Listing.

Symbolressource

Diese Ressource enthält Symboldaten für ein Add-On-Listing. Diese Ressource weist die folgenden Werte auf:

Wert Typ Beschreibung
fileName Zeichenfolge Der Name der Symboldatei im ZIP-Archiv, das Sie für die Übermittlung hochgeladen haben. Das Symbol muss eine PNG-Datei sein, die genau 300 x 300 Pixel misst.
fileStatus Zeichenfolge Der Status der Symboldatei. Dies kann einer der folgenden Werte sein:
  • Keine
  • PendingUpload
  • Hochgeladen
  • PendingDelete

Preisressource

Diese Ressource enthält Preisinformationen für das Add-On. Diese Ressource weist die folgenden Werte auf:

Wert Typ Beschreibung
marketSpecificPricings Objekt Ein Wörterbuch mit Schlüssel- und Wertpaaren, wobei jeder Schlüssel ein zweiseitiger ISO 3166-1 Alpha-2-Ländercode ist und jeder Wert ein Preisniveau ist. Diese Artikel stellen die benutzerdefinierten Preise für Ihr Add-On in bestimmten Märkten dar. Alle Elemente in diesem Wörterbuch setzen den Grundpreis außer Kraft, der durch den PriceId-Wert für den angegebenen Markt angegeben wird.
sales array Veraltet. Ein Array von Verkaufsressourcen, die Verkaufsinformationen für das Add-On enthalten.
priceId Zeichenfolge Ein Preisniveau, das den Grundpreis für das Add-On angibt.
isAdvancedPricingModel boolean Wenn zutreffend, hat Ihr Entwicklerkonto Zugriff auf die erweiterte Gruppe von Preisniveaus von 0,99 USD auf 1999,99 USD. Wenn falsch, hat Ihr Entwicklerkonto Zugriff auf die originale Gruppe von Preisniveaus von 0,99 USD auf 999,99 USD. Weitere Informationen zu den verschiedenen Ebenen finden Sie unter Preisniveaus.

Hinweis Dieses Feld ist schreibgeschützt

Verkaufsressource

Diese Ressourcen enthalten Verkaufsinformationen für ein Add-On.

Wichtig

Die Verkaufsressource wird nicht mehr unterstützt, und derzeit können Sie die Verkaufsdaten für eine Add-On-Übermittlung nicht mithilfe der Microsoft Store-Übermittlungs-API abrufen oder ändern. In Zukunft aktualisieren wir die Microsoft Store-Übermittlungs-API, um eine neue Möglichkeit für den programmgesteuerten Zugriff auf Verkaufsinformationen für Add-On-Übermittlungen einzuführen.

Diese Ressource weist die folgenden Werte auf:

Wert Typ BESCHREIBUNG
name Zeichenfolge Der Name des Verkaufs.
basePriceId Zeichenfolge Das Preisniveau, das für den Grundpreis des Verkaufs verwendet werden soll.
startDate Zeichenfolge Das Startdatum für den Verkauf im ISO 8601-Format.
endDate Zeichenfolge Das Enddatum für den Verkauf im ISO 8601-Format.
marketSpecificPricings Objekt Ein Wörterbuch mit Schlüssel- und Wertpaaren, wobei jeder Schlüssel ein zweiseitiger ISO 3166-1 Alpha-2-Ländercode ist und jeder Wert ein Preisniveau ist. Diese Artikel stellen die benutzerdefinierten Preise für Ihr Add-On in bestimmten Märkten dar. Alle Elemente in diesem Wörterbuch setzen den Grundpreis außer Kraft, der durch den basePriceId für den angegebenen Markt angegeben wird.

Statusdetails-Ressource

Diese Ressource enthält zusätzliche Details zum Status einer Übermittlung. Diese Ressource weist die folgenden Werte auf:

Wert Typ Beschreibung
errors Objekt Ein Array von Statusdetailsesourcen, die Fehlerdetails für die Übermittlung enthalten.
warnings Objekt Ein Array von Statusdetailsesourcen, die Warnungsdetails für die Übermittlung enthalten.
certificationReports Objekt Ein Array von Zertifizierungsberichtsressourcen, die Zugriff auf die Zertifizierungsberichtsdaten für die Übermittlung bieten. Sie können diese Berichte auf weitere Informationen überprüfen, wenn die Zertifizierung fehlschlägt.

Statusdetailressource

Diese Ressource enthält zusätzliche Informationen zu Fehlern oder Warnungen für eine Übermittlung. Diese Ressource weist die folgenden Werte auf:

Wert Typ BESCHREIBUNG
code Zeichenfolge Ein Übermittlungsstatuscode, der den Typ des Fehlers oder der Warnung beschreibt.
details Zeichenfolge Eine Nachricht mit weiteren Details zum Problem.

Ressource für den Zertifizierungsbericht

Diese Ressource bietet Zugriff auf die Zertifizierungsberichtsdaten für eine Übermittlung. Diese Ressource weist die folgenden Werte auf:

Wert Typ Beschreibung
Datum Zeichenfolge Datum und Uhrzeit der Berichterstellung im ISO 8601-Format.
reportUrl Zeichenfolge Die URL, über die Sie auf den Bericht zugreifen können.

Enumerationen

Diese Methoden verwenden die folgenden Enumerationen.

Preisstufen

Die folgenden Werte stellen die verfügbaren Preisniveaus in der Ressourcenressource für eine Add-On-Übermittlung dar.

Wert Beschreibung
Basis Das Preisniveau ist nicht festgelegt; verwenden Sie den Grundpreis für das Add-On.
NotAvailable Das Add-On ist in der angegebenen Region nicht verfügbar.
Kostenlos Das Add-On ist kostenlos.
Tierxxxx Eine Zeichenfolge, die das Preisniveau für das Add-On im Format Tierxxxx angibt. Derzeit werden die folgenden Preisstufen unterstützt:

  • Wenn der isAdvancedPricingModel-Wert der Preisressourcetrue ist, sind die verfügbaren Preisniveauwerte für Ihr Konto Tier1012 - Tier1424".
  • Wenn der isAdvancedPricingModel-Wert der Preisressourcefalse ist, sind die verfügbaren Preisniveauwerte für Ihr Konto Tier2 - Tier96".
Um die vollständige Tabelle der Preisniveaus anzuzeigen, die für Ihr Entwicklerkonto verfügbar sind, einschließlich der marktspezifischen Preise, die den einzelnen Stufen zugeordnet sind, wechseln Sie zur Seite Preise und Verfügbarkeit für eine Ihrer App-Übermittlungen im Partner Center, und klicken Sie auf den Link Ansichtstabelle im Abschnitt Märkte und benutzerdefinierte Preise (für einige Entwicklerkonten, dieser Link befindet sich im Abschnitt Preise).

Übermittlungsstatuscode

Die folgenden Werte stellen den Statuscode einer Übermittlung dar.

Wert BESCHREIBUNG
Keine Es wurde kein Code angegeben.
InvalidArchive Das ZIP-Archiv, das das Paket enthält, ist ungültig oder weist ein unbekanntes Archivformat auf.
MissingFiles Das ZIP-Archiv verfügt nicht über alle Dateien, die in Ihren Übermittlungsdaten aufgelistet wurden, oder sie befinden sich am falschen Speicherort im Archiv.
PackageValidationFailed Mindestens ein Paket in Ihrer Übermittlung konnte nicht überprüft werden.
InvalidParameterValue Einer der Parameter im Anforderungstext ist ungültig.
InvalidOperation Der von Ihnen versuchte Vorgang ist ungültig.
InvalidState Der von Ihnen versuchte Vorgang ist für den aktuellen Status des Flight-Pakets ungültig.
ResourceNotFound Das angegebene Flight-Paket konnte nicht gefunden werden.
ServiceError Ein interner Dienstfehler verhinderte, dass die Anforderung erfolgreich war. Versuchen Sie die Anforderung erneut.
ListingOptOutWarning Der Entwickler hat eine Auflistung aus einer vorherigen Übermittlung entfernt oder keine Eintragsinformationen enthalten, die vom Paket unterstützt werden.
ListingOptInWarning Der Entwickler hat einen Eintrag hinzugefügt.
UpdateOnlyWarning Der Entwickler versucht, etwas einzufügen, das nur Updateunterstützung enthält.
Andere Die Übermittlung befindet sich in einem nicht erkannten oder nicht kategorisierten Zustand.
PackageValidationWarning Der Paketüberprüfungsprozess führte zu einer Warnung.