Kundenberechtigungen für Ihr SaaS-Produkt verwalten

Wenn Kunden ein Preismodell für Ihre Software auswählen, erstellt Google eine Berechtigung, die angibt, dass der Kunde Ihr Produkt auf dem Cloud Marketplace gekauft hat. In diesem Abschnitt wird beschrieben, wie Sie über die Partner Procurement API Ansprüche für Ihre Kunden erstellen und verwalten können.

Weitere Informationen zum Verwalten von Berechtigungen finden Sie in der Referenzdokumentation.

Hinweise

• Richten Sie den Zugriff auf die Cloud Commerce Partner Procurement API ein, wie unter Anwendung einbinden beschrieben.

Wenn Sie mehrere Bestellungen desselben Produkts aktiviert haben, kann die Partner Procurement API mehrere Ereignisse mit dem Ereignistyp ENTITLEMENT_ACTIVE für denselben Wert ACCOUNT_ID senden, jeweils mit einer eindeutigen ENTITLEMENT_ID, die ein anderes Angebot darstellt. Das bedeutet, dass die Ereignisablauflogik Ihrer App auf ENTITLEMENT_ID reagieren muss, anstatt auf ACCOUNT_ID oder PRODUCT_ID.

Sie müssen dafür sorgen, dass Ihre Frontend-Integration das neue orders-Objekt verarbeiten kann, das in der JWT-Nutzlast enthalten ist. Weitere Informationen finden Sie unter Frontend Ihrer Anwendung einbinden.

Weitere Informationen zum Aktivieren mehrerer Bestellungen desselben Produkts finden Sie unter Mehrere Bestellungen desselben Produkts aktivieren.

Berechtigung genehmigen

Wenn ein Kunde ein Preismodell auswählt, erstellt Cloud Marketplace eine Berechtigung und sendet die folgende Pub/Sub-Nachricht an Ihre Anwendung:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for offer-based entitlements
  },
}

ENTITLEMENT_ID ist in diesem Fall eine vom Cloud Marketplace erstellte ID. Wenn das Angebot eine bestimmte Dauer hat, wird diese in Jahren und Monaten angegeben. Wenn für das Angebot ein Enddatum anstelle einer Dauer angegeben ist, ist das Feld für die Dauer leer.

Aktualisieren Sie in Ihrem System das Konto des Nutzers, um anzuzeigen, dass er ein Abo erworben hat. Senden Sie zum Genehmigen der Berechtigung eine HTTP POST-Anfrage an die Partnerbeschaffungs-API und senden Sie die ENTITLEMENT_ID, die Sie genehmigen:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

Berechtigung ablehnen

Wenn Sie eine Berechtigung ablehnen möchten, senden Sie eine HTTP POST-Anfrage an die Partnerbeschaffungs-API und verwenden Sie in Ihrer Anfrage die Methode reject:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject

Wenn Sie im Anfragetext einen Grund für die Ablehnung der Berechtigung angeben möchten, verwenden Sie das folgende Format:

{
  "reason": "..."
}

Berechtigungsmodell ändern

Je nachdem, wie Sie Ihr Preismodell eingerichtet haben, können Ihre Kunden gegebenenfalls ein anderes Angebot wählen. Wenn ein Kunde einen neuen Preismodell auswählt, erhalten Sie eine Pub/Sub-Nachricht im folgenden Format:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for the new offer, for offer-based entitlements
    "newProduct": "test-product.cloud.goog"
    "newOffer": "projects/1234567/services/test-product.cloud.goog/standardOffers/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  },
}

Wenn das Angebot eine bestimmte Dauer hat, wird diese in Jahren und Monaten angegeben. Wenn für das Angebot ein Enddatum anstelle einer Dauer angegeben ist, ist das Feld für die Dauer leer.

Stellen Sie zum Genehmigen des Tarifwechsels die folgende HTTP POST-Anfrage an die Partner-API:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

Die Antragsstelle muss den Tarif haben, der genehmigt wird:

{
  "pendingPlanName": PLAN_NAME
}

Nachdem der Wechsel genehmigt wurde, erhalten Sie eine weitere Pub/Sub-Nachricht, wenn der Wechsel wirksam wird. In der Nachricht ändert sich das Feld eventType in ENTITLEMENT_PLAN_CHANGED. Stellen Sie zum Prüfen des Status eines Tarifs die folgende HTTP GET-Anfrage an die Partnerbeschaffungs-API.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

Die Antwort ähnelt der folgenden: Das Feld state gibt an, ob der neue Tarif aktiv ist oder ob der Tarifwechsel noch aussteht.

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

Berechtigung widerrufen

Wenn ein Nutzer sich entscheidet, seine Berechtigung zu stornieren, erhalten Sie eine Cloud Pub/Sub-Benachrichtigung. Ähnlich wie bei einem Wechsel des Preismodells kann die tatsächliche Stornierung am Ende des aktuellen Abrechnungszyklus wirksam werden.

Die Benachrichtigung hat folgendes Format:

{
  "eventId": "...",
  // If the entitlement is canceled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "..."
  },
}

Berechtigung löschen

Wenn ein Nutzer diesbezüglich eine direkte Anfrage an den Google-Support stellt oder die Google-Plattform verlässt, werden seine Berechtigungen sofort storniert. Nach einer Kulanzzeitraum von 60 Tagen werden seine Berechtigungen und Konten gelöscht. Sie müssen die Daten von Ihren Servern löschen, sobald Sie benachrichtigt wurden, um die Privatsphäre des Nutzers zu schützen.

Wenn die Berechtigungen storniert und das Konto gelöscht wird, erhalten Sie Benachrichtigungen, die den folgenden ähneln:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

Liste der Ereignistypen für Kontoaufgaben

Das Folgende ist eine Liste der eventType s, die Ihre Anwendung möglicherweise in Pub/Sub-Nachrichten empfängt: