Back-End Ihrer Anwendung einbinden

In diesem Abschnitt werden die Schritte zum Einbinden des Backends Ihrer Anwendung in Google Cloud Marketplace beschrieben. Mit dieser Einbindung können Sie Benutzerkonten und Berechtigungen verwalten, die darauf hinweisen, dass Nutzer Ihr Produkt über Google Cloud Marketplace gekauft haben. Wenn Sie ein nutzungsbasiertes Preismodell ausgewählt haben, binden Sie auch Ihr Back-End ein, um die Nutzung an Google zu melden.

Ein Beispiel für die Einbindung einer Basisanwendung in Google Cloud Marketplace und eine exemplarische Vorgehensweise für den Beispielcode finden Sie im Codelab zum Einbinden eines verwalteten Dienstes.

Den im Codelab verwendeten Beispielcode finden Sie im GitHub-Repository.

Hinweis

  • Richten Sie den Zugriff auf die Cloud Commerce Partner Procurement API ein, wie unter Anwendung einbinden: Einrichtung beschrieben.
  • Wenn Sie ein nutzungsbasiertes Preisschema ausgewählt haben, sorgen Sie dafür, dass Ihr Partnerentwickler einen Dienst erstellt hat, über den Sie die Verwendung melden können.

Nutzerkontoaufgaben

Auf übergeordneter Ebene muss Ihre Anwendung für das folgende Szenario geeignet sein:

  1. Ein Nutzer stellt eine Anfrage oder Änderung im Google Cloud Marketplace, z. B. die Anmeldung für Ihre Lösung.

  2. Google Cloud Marketplace sendet Ihrer Anwendung eine Benachrichtigung über Pub/Sub mit Informationen zur Anfrage im Feld eventType. Wenn ein Nutzer beispielsweise seine Berechtigung ändert, ist eventType ENTITLEMENT_PLAN_CHANGE.

    Siehe die vollständige Liste der möglichen eventType s.

  3. Zum Genehmigen der Anfrage sendet Ihre Anwendung eine HTTP POST-Anfrage an die Partnerbeschaffungs-API.

In den folgenden Abschnitten wird beschrieben, auf welche Arten die Nutzer Anfragen stellen können und was Ihre Anwendung tun muss, um die Anfragen zu bearbeiten.

Verwenden Sie für die in diesem Abschnitt beschriebenen API-Aufrufe diesen Endpunkt:

https://cloudcommerceprocurement.googleapis.com/

Konto für einen neuen Nutzer erstellen

Wenn ein Nutzer Ihre Lösung zum ersten Mal kauft, erstellt Google Cloud Marketplace eine Kontoressource, die die Beziehung des Nutzers zu Ihnen verfolgt. Wenn die Kontoressource erstellt wird, werden Sie über das für Sie erstellte Pub/Sub-Thema benachrichtigt. Die Pub/Sub-Nachricht hat das folgende Format:

{
  "eventId": "...",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

USER_ACCOUNT_ID ist in diesem Fall die vom Google Cloud Marketplace erstellte Konto-ID.

Gleichzeitig wird der Nutzer zu Ihrer Anmeldeseite weitergeleitet, wo er ein Konto in Ihrem System erstellt. Wie Sie die Anmeldeseite erstellen, erfahren Sie unter Front-End Ihrer Anwendung einbinden.

Nach der erfolgreichen Anmeldung des Nutzers muss Ihre Anwendung die Partner-API aufrufen und angeben, dass das Konto genehmigt wurde. Konten werden im Status ACCOUNT_ACTIVE erstellt, haben jedoch einen PENDING-Eintrag im Feld approvals mit dem Namen signup, der angibt, dass der Nutzer noch nicht angemeldet ist. Verwenden Sie zum Genehmigen des Kontos nach der Anmeldung des Nutzers die folgende HTTP POST-Anfrage:

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

YOUR_PARTNER_ID ist in diesem Fall eine ID, die Ihnen zugewiesen wird, wenn Ihr Partnerentwickler den Zugriff auf die Partner Procurement API ermöglicht.

Verwenden Sie zum Prüfen des Status eines verknüpften Kontos die folgende HTTP GET-Anforderung:

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

Die Antwort hat das folgende Format:

{
  "name": "providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID",
  "provider": "acme-services",
  "state": "ACCOUNT_ACTIVE",
  "approvals": [{
    "name": "signup",
    "state": "APPROVED",
    "updateTime": "...",
  }],
  "updateTime": "...",
  "createTime": "..."
}

Eine Liste möglicher Kontostatus finden Sie in der providers.accounts API-Referenz.

Berechtigung erstellen

Wenn Kunden ein Preismodell für Ihre Software auswählen, erstellt Google eine Berechtigung, die angibt, dass der Kunde Ihre Lösung auf dem Google Cloud Marketplace gekauft hat.

Wenn ein Kunde einen Tarif auswählt, wird die folgende Pub/Sub-Nachricht an Ihre Anwendung gesendet:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

ENTITLEMENT_ID ist in diesem Fall eine vom Google Cloud Marketplace erstellte ID.

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

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",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
  },
}

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",
  ...
}

Statusnachricht an Nutzer senden

Wenn es nach der Auswahl eines Preismodells durch einen Nutzer einige Stunden oder länger dauern kann, bis die Berechtigung durch das Back-End genehmigt wird, empfiehlt es sich, den Nutzern eine Statusmeldung zu senden. Geben Sie in dieser Nachricht den Fortschritt des Genehmigungsvorgangs an und, falls bekannt, wann dieser voraussichtlich abgeschlossen sein wird.

Stellen Sie zum Bereitstellen einer Statusmeldung die folgende HTTP POST-Anfrage an die Beschaffungs-API:

POST v1/providers/your-partner-id/entitlements/entitlement_id:updateUserMessage

Geben Sie im Anfragetext den Nachrichtentext an, ähnlich dem folgenden Beispiel:

{
  "message": "Approval expected in 2 days"
}

Berechtigungen stornieren

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 cancelled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "cancellationDate": "...",
    "updateTime": "..."
  },
}

Berechtigung löschen

Wenn ein Nutzer diesbezüglich eine direkte Anfrage stellt oder die Google-Plattform verlässt, werden seine Berechtigungen storniert und gelöscht. Außerdem wird sein Konto 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",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "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:

eventTypeBeschreibung
ACCOUNT_CREATION_REQUESTEDVeraltet
ACCOUNT_ACTIVEZeigt an, dass das Kundenkonto erstellt wurde.
ACCOUNT_DELETEDZeigt an, dass das Kundenkonto aus Google Cloud-Systemen gelöscht wurde.
ENTITLEMENT_CREATION_REQUESTEDZeigt an, dass ein Kunde einen Ihrer Preispläne ausgewählt hat.
ENTITLEMENT_ACTIVEZeigt an, dass der von einem Kunden ausgewählte Tarif jetzt aktiv ist.
ENTITLEMENT_PLAN_CHANGE_REQUESTEDZeigt an, dass ein Kunde einen neuen Tarif ausgewählt hat.
ENTITLEMENT_PLAN_CHANGEDZeigt an, dass der Tarifwechsel eines Kunden genehmigt wurde und die Änderungen wirksam wurden.
ENTITLEMENT_PLAN_CHANGE_CANCELLEDZeigt an, dass der Tarifwechsel eines Kunden abgebrochen wurde, entweder weil er nicht genehmigt wurde oder weil er zu seinem alten Tarif zurückgekehrt ist.
ENTITLEMENT_PENDING_CANCELLATIONZeigt an, dass ein Kunde seinen Tarif storniert hat und die Stornierung bis zum Ende des Abrechnungszyklus aussteht.
ENTITLEMENT_CANCELLATION_REVERTEDZeigt an, dass die ausstehende Stornierung eines Kunden zurückgesetzt wurde. Beachten Sie, dass Stornierungen nicht mehr rückgängig gemacht werden können, nachdem sie endgültig sind.
ENTITLEMENT_CANCELLEDZeigt an, dass der Tarif eines Kunden storniert wurde.
ENTITLEMENT_CANCELLINGZeigt an, dass der Tarif eines Kunden gerade storniert wird.
ENTITLEMENT_DELETEDGibt an, dass Daten zum Kundentarif aus dem Google Cloud Marketplace gelöscht wurden.

(Für nutzungsbasierte Preise) Nutzung an Google melden

Wenn Sie für Ihre Lösung nutzungsbasierte Preise wählen, müssen Sie die Nutzung Ihrer Anwendung an die Service Control API melden.

Ihr Partnerentwickler erstellt einen Dienst, der Ihrer Lösung entspricht, und erlaubt Ihrem Dienstkonto, die Nutzung über diesen Dienst zu melden.

Eine Einführung zu Service Control finden Sie im Startleitfaden.

Wenn eine Berechtigung erstellt wird, müssen Sie die Partnerbeschaffungs-API aufrufen, um eine usageReportingId mithilfe der folgenden HTTP GET-Anfrage abzurufen:

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

Die Antwort enthält Informationen zur Berechtigung im folgenden Format:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

Zum Melden der Nutzung müssen Sie zuerst einen services.check-API-Aufruf ausführen, um die Konfiguration des Dienstes zu prüfen. Wenn das Objekt checkErrors[] leer ist, führen Sie in der Antwort einen API-Aufruf services.report aus, um den Nutzungsbericht zu senden.

Der Nutzungsbericht ist ein Operation, der ein MetricValueSet für Ihre Preiskennzahlen enthält. Das Operation enthält auch ein consumerId-Feld, das aus der Berechtigung auf die USAGE_REPORTING_ID gesetzt ist.

Das folgende Beispiel zeigt einen Nutzungsbericht für example-messaging-service, der Informationen über den vom Kunden verwendeten Speicher sendet:

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report

{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }]
  }]
}

Sie müssen die Nutzung Ihrer Anwendung stündlich melden. Stellen Sie sicher, dass die Werte startTime und endTime für die Nutzung korrekt sind. Wenn der Dienst des Nutzers vor dem startTime deaktiviert wurde, sendet die services.check API einen Fehler im checkErrors[]-Objekt, und dem Kunden wird für den Zeitraum keine Gebühr berechnet.

Wenn die services.check-API einen oder mehrere der folgenden Fehler zurückgibt, empfehlen wir, die Bereitstellung Ihres Dienstes für den Kunden einzustellen, bis der Fehler behoben ist:

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED
Zurück
Anwendung einbinden: Einrichtung
Weiter
Front-End Ihrer Anwendung einbinden