Gewähren kostenloser Produkte
Verwenden Sie diese Methode in der Microsoft Store-Einkaufs-API, um einem bestimmten Benutzer eine kostenlose App oder ein kostenloses Add-On (auch als In-App-Produkt oder IAP bezeichnet) zu gewähren.
Derzeit können Sie nur kostenlose Produkte gewähren. Wenn Ihr Dienst versucht, diese Methode zu verwenden, um ein produkt zu gewähren, das nicht kostenlos ist, gibt diese Methode einen Fehler zurück.
Voraussetzungen
Um diese Methode zu verwenden, benötigen Sie Folgendes:
- Ein Azure AD-Zugriffstoken mit dem Zielgruppen-URI-Wert
https://onestore.microsoft.com. - Ein Microsoft Store-ID-Schlüssel, der die Identität des Benutzers darstellt, für den Sie ein kostenloses Produkt gewähren möchten.
Weitere Informationen finden Sie unter Verwalten von Produktberechtigungen aus einem Dienst.
Anfordern
Anforderungssyntax
| Methode | Anforderungs-URI |
|---|---|
| POST | https://purchase.mp.microsoft.com/v6.0/purchases/grant |
Anforderungsheader
| Header | Typ | Beschreibung |
|---|---|---|
| Autorisierung | Zeichenfolge | Erforderlich. Das Azure AD-Zugriffstoken im Formular Bearer<-Token>. |
| Host | Zeichenfolge | Muss auf den Wert purchase.mp.microsoft.com festgelegt werden. |
| Inhaltslänge | Zahl | Die Länge des Anforderungstexts. |
| Content-Type | Zeichenfolge | Gibt den Anforderungs- und Antworttyp an. Derzeit ist der einzige unterstützte Wert "application/json". |
Anforderungstext
| Parameter | Typ | Beschreibung | Erforderlich |
|---|---|---|---|
| availabilityId | Zeichenfolge | Die Verfügbarkeits-ID des Produkts, das aus dem Microsoft Store-Katalog gewährt werden soll. | Ja |
| b2bKey | Zeichenfolge | Der Microsoft Store-ID-Schlüssel , der die Identität des Benutzers darstellt, für den Sie ein Produkt gewähren möchten. | Ja |
| devOfferId | Zeichenfolge | Eine vom Entwickler angegebene Angebots-ID, die nach dem Kauf im Sammlungselement angezeigt wird. | |
| language | Zeichenfolge | Die Sprache des Benutzers. | Ja |
| Markt | Zeichenfolge | Der Markt des Benutzers. | Ja |
| orderId | guid | Eine FÜR die Bestellung generierte GUID. Dieser Wert ist für den Benutzer eindeutig, muss jedoch nicht für alle Bestellungen eindeutig sein. | Ja |
| productId | Zeichenfolge | Die Store-ID für das Produkt im Microsoft Store-Katalog. Eine Beispiel-Store-ID für ein Produkt ist 9NBLGGH42CFD. | Ja |
| Menge | int | Die zu kaufende Menge. Derzeit ist der einzige unterstützte Wert 1. Wenn nichts angegeben ist, wird der Standardwert 1 verwendet. | No |
| skuId | Zeichenfolge | Die Store-ID für die SKU des Produkts im Microsoft Store-Katalog. Eine Beispielspeicher-ID für eine SKU ist 0010. | Ja |
Anforderungsbeispiel
POST https://purchase.mp.microsoft.com/v6.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK……
Content-Length: 1863
Content-Type: application/json
{
"b2bKey" : "eyJ0eXAiOiJK……",
"availabilityId" : "9RT7C09D5J3W",
"productId" : "9NBLGGH5WVP6",
"skuId" : "0010",
"language" : "en-us",
"market" : "us",
"orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
}
Antwort
Antworttext
| Parameter | Typ | Beschreibung | Erforderlich |
|---|---|---|---|
| clientContext | ClientContextV6 | Kontextinformationen des Kunden für diese Bestellung. Dies wird dem ClientID-Wert aus dem Azure AD-Token zugewiesen. | Ja |
| createdtime | datetimeoffset | Der Zeitpunkt, zu dem die Bestellung erstellt wurde. | Ja |
| currencyCode | Zeichenfolge | Währungscode für totalAmount und totalTaxAmount. N/A für kostenlose Artikel. | Ja |
| friendlyName | Zeichenfolge | Der Anzeigename für die Bestellung. N/A für Bestellungen, die mit der Microsoft Store-Einkaufs-API getätigt wurden. | Ja |
| isPIRequired | boolean | Gibt an, ob ein Zahlungsmittel (PI) als Teil der Bestellung erforderlich ist. | Ja |
| language | Zeichenfolge | Die Sprach-ID für die Bestellung (z. B. "en"). | Ja |
| Markt | Zeichenfolge | Die Markt-ID für den Auftrag (z. B. "US"). | Ja |
| orderId | Zeichenfolge | Eine ID, die die Reihenfolge für einen bestimmten Benutzer identifiziert. | Ja |
| orderLineItems | OrderLineItemV6 auflisten<> | Die Liste der Positionen für die Bestellung. In der Regel gibt es 1 Position pro Bestellung. | Ja |
| orderState | Zeichenfolge | Der Status der Bestellung. Die gültigen Status sind "Editing", "CheckingOut", "Pending", "Purchased", "Refunded", "ChargedBack" und "Cancelled". | Ja |
| orderValidityEndTime | Zeichenfolge | Das letzte Mal, wenn die Auftragspreise gültig sind, bevor sie übermittelt wird. N/A für kostenlose Apps. | Ja |
| orderValidityStartTime | Zeichenfolge | Das erste Mal, wenn die Auftragspreise gültig sind, bevor sie übermittelt wird. N/A für kostenlose Apps. | Ja |
| Käufer | IdentityV6 | Ein Objekt, das die Identität des Käufers beschreibt. | Ja |
| totalAmount | decimal | Der Gesamtkaufbetrag aller Artikel in der Bestellung einschließlich Steuern. | Ja |
| totalAmountBeforeTax | Decimal | Gesamtkaufbetrag aller Artikel in der Bestellung vor Steuern. | Ja |
| totalChargedToCsvTopOffPI | Decimal | Wenn Sie ein separates Zahlungsmittel und einen gespeicherten Wert (CSV) verwenden, wird der betrag für CSV berechnet. | Ja |
| totalTaxAmount | Decimal | Der Gesamtbetrag der Steuern für alle Positionen. | Ja |
Das ClientContext-Objekt enthält die folgenden Parameter.
| Parameter | Typ | Beschreibung | Erforderlich |
|---|---|---|---|
| client | Zeichenfolge | Die Client-ID, die die Bestellung erstellt hat. | No |
Das OrderLineItemV6 -Objekt enthält die folgenden Parameter.
| Parameter | Typ | Beschreibung | Erforderlich |
|---|---|---|---|
| Agent | IdentityV6 | Der Agent, der die Position zuletzt bearbeitet hat. Weitere Informationen zu diesem Objekt finden Sie in der folgenden Tabelle. | No |
| availabilityId | Zeichenfolge | Die Verfügbarkeits-ID des Produkts, das im Microsoft Store-Katalog erworben werden soll. | Ja |
| Begünstigter | IdentityV6 | Die Identität des Begünstigten des Auftrags. | No |
| billingState | Zeichenfolge | Der Abrechnungsstatus der Bestellung. Dies ist auf "Belastet " festgelegt, wenn der Vorgang abgeschlossen ist. | No |
| campaignId | Zeichenfolge | Die Kampagnen-ID für diese Bestellung. | No |
| currencyCode | Zeichenfolge | Der Währungscode, der für Preisdetails verwendet wird. | Ja |
| description | string | Eine lokalisierte Beschreibung des Zeilenelements. | Ja |
| devofferId | Zeichenfolge | Die Angebots-ID für die jeweilige Bestellung, sofern vorhanden. | No |
| fulfillmentDate | datetimeoffset | Das Datum, an dem die Erfüllung aufgetreten ist. | No |
| fulfillmentState | Zeichenfolge | Der Zustand der Erfüllung dieses Artikels. Dies ist auf "Erfüllt " festgelegt, wenn sie abgeschlossen ist. | No |
| isPIRequired | boolean | Gibt an, ob für diese Position ein Zahlungsmittel erforderlich ist. | Ja |
| isTaxIncluded | boolean | Gibt an, ob die Steuern in den Preisdetails des Artikels enthalten sind. | Ja |
| legacyBillingOrderId | Zeichenfolge | Die ältere Abrechnungs-ID. | No |
| lineItemId | Zeichenfolge | Die Zeilenelement-ID für den Artikel in dieser Reihenfolge. | Ja |
| listPrice | Decimal | Der Listenpreis des Artikels in dieser Reihenfolge. | Ja |
| productId | Zeichenfolge | Die Store-ID für das Produkt , das die Position im Microsoft Store-Katalog darstellt. Eine Beispiel-Store-ID für ein Produkt ist 9NBLGGH42CFD. | Ja |
| productType | Zeichenfolge | Der Typ des Produkts. Die unterstützten Werte sind "Durable", "Application" und "UnmanagedConsumable". | Ja |
| Menge | int | Die Menge des bestellten Artikels. | Ja |
| Einzelhandelspreis | Decimal | Der Verkaufspreis des bestellten Artikels. | Ja |
| revenueRecognitionState | Zeichenfolge | Der Status der Einnahmenerkennung. | Ja |
| skuId | Zeichenfolge | Die Store-ID für die SKU des Zeilenelements im Microsoft Store-Katalog. Eine Beispielspeicher-ID für eine SKU ist 0010. | Ja |
| taxAmount | Decimal | Der Steuerbetrag für die Position. | Ja |
| taxType | Zeichenfolge | Der Steuertyp für die anwendbaren Steuern. | Ja |
| Titel | Zeichenfolge | Der lokalisierte Titel des Zeilenelements. | Ja |
| totalAmount | decimal | Der Gesamtbetrag des Einkaufsbetrags der Position einschließlich Steuern. | Ja |
Das IdentityV6 -Objekt enthält die folgenden Parameter.
| Parameter | Typ | Beschreibung | Erforderlich |
|---|---|---|---|
| identityType | Zeichenfolge | Enthält den Wert "pub". | Ja |
| identityValue | Zeichenfolge | Der Zeichenfolgenwert der publisherUserId aus dem angegebenen Microsoft Store-ID-Schlüssel. | Ja |
Beispielantwort
Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XjfuNWLQlEuxj6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2015 21:21:51 GMT
{
"clientContext": {
"client": "86b78998-d05a-487b-b380-6c738f6553ea"
},
"createdTime": "2015-10-13T21:21:51.1863494+00:00",
"currencyCode": "USD",
"isPIRequired": false,
"language": "en-us",
"market": "us",
"orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
"orderLineItems": [{
"availabilityId": "9RT7C09D5J3W",
"beneficiary": {
"identityType": "pub",
"identityValue": "user1"
},
"billingState": "Charged",
"currencyCode": "USD",
"description": "Jewels, Jewels, Jewels - Consumable 2",
"fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
"fulfillmentState": "Fulfilled",
"isPIRequired": false,
"isTaxIncluded": true,
"lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
"listPrice": 0.0,
"payments": [],
"productId": "9NBLGGH5WVP6",
"productType": "UnmanagedConsumable",
"quantity": 1,
"retailPrice": 0.0,
"revenueRecognitionState": "None",
"skuId": "0010",
"taxAmount": 0.0,
"taxType": "NoApplicableTaxes",
"title": "Jewels, Jewels, Jewels - Consumable 2",
"totalAmount": 0.0
}],
"orderState": "Purchased",
"orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
"orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
"purchaser": {
"identityType": "pub",
"identityValue": "user1"
},
"testScenarios": "None",
"totalAmount": 0.0,
"totalTaxAmount": 0.0
}
Fehlercodes
| Code | Fehler | Interner Fehlercode | Beschreibung |
|---|---|---|---|
| 401 | Nicht autorisiert | AuthenticationTokenInvalid | Das Azure AD-Zugriffstoken ist ungültig. In einigen Fällen enthalten die Details des ServiceError weitere Informationen, z. B. wenn das Token abgelaufen ist oder der Appid-Anspruch fehlt. |
| 401 | Nicht autorisiert | PartnerAadTicketRequired | Ein Azure AD-Zugriffstoken wurde im Autorisierungsheader nicht an den Dienst übergeben. |
| 401 | Nicht autorisiert | InkonsistenteClientId | Der ClientId-Anspruch im Microsoft Store-ID-Schlüssel im Anforderungstext und der Appid-Anspruch im Azure AD-Zugriffstoken im Autorisierungsheader stimmen nicht überein. |
| 400 | BadRequest | InvalidParameter | Die Details enthalten Informationen zum Anforderungstext und zu den Feldern mit einem ungültigen Wert. |