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. Dieser Dienst wird im Feld Dienstdomain des Abschnitts „Abrechnungsintegration“ des Producer Portals angezeigt.

Dienstkonto erstellen

Zur Einbindung des Produkts in Google Cloud müssen Sie in dem Projekt, das Sie für Ihr Produkt verwenden, ein Dienstkonto erstellen. Ihre Anwendung verwendet dieses Dienstkonto, um mit den Google Cloud Marketplace Partner APIs zu interagieren und Informationen zu Käufen von Nutzern zu erhalten.

Wir empfehlen, das Producer Portal zum Erstellen und Verknüpfen Ihrer Dienstkonten zu verwenden.

Wenn Sie das Partner-Portal verwenden, erteilt Ihr Partnerentwickler diesem Dienstkonto die Rolle „Pub/Sub-Abonnent“. Ausführliche Schritte zum Erstellen eines Dienstkontos finden Sie unter Dienstkonten erstellen und verwalten.

Back-End Ihrer Anwendung mit Producer Portal integrieren

Wenn Sie auf alle Informationen zugreifen möchten, die Sie benötigen, um das Back-End Ihrer Anwendung von einem Ort aus in Google Cloud Marketplace zu integrieren, z. B. Ihre Dienstkonten und Kennungen auf Planebene, können Sie die ABRECHNUNGSEINBINDUNG des Producer Portals verwenden.

Der Link zum Producer Portal lautet:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

So greifen Sie auf den Abschnitt ABRECHNUNGSEINBINDUNG zu:

  1. Klicken Sie in der Produktliste auf den Namen Ihres Produkts.

  2. Gehen Sie auf der Seite Übersicht des Produkts zum Abschnitt Technische Integration und klicken Sie auf ABRECHNUNG ABRECHNUNG.

Dienstkonten im Producer Portal erstellen und verknüpfen

Im Abschnitt ABRECHNUNGSEINBINDUNG des Producer Portals können Sie die Dienstkonten erstellen und verknüpfen, die Sie für die Interaktion mit den Partner-APIs verwenden, und Informationen zu Käufen von Nutzern abrufen.

Der Link zum Producer Portal lautet:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

In den folgenden Schritten können Sie vorhandene Dienstkonten verwenden oder neue Dienstkonten erstellen. Wenn Sie ein neues Dienstkonto erstellen, geben Sie den Namen des Dienstkontos im Feld Dienstkontoname und die ID des Dienstkontos im Feld Dienstkonto-ID ein. Klicken Sie dann auf Erstellen und verknüpfen.

So verknüpfen Sie Ihre Dienstkonten:

  1. Klicken Sie in der Produktliste auf den Namen Ihres Produkts.

  2. Gehen Sie auf der Seite Übersicht des Produkts zum Abschnitt Technische Integration und klicken Sie auf ABRECHNUNG ABRECHNUNG.

  3. Wenn Sie eine Integration in die Partner Procurement API vornehmen möchten, klicken Sie unter Dienstkonto verknüpfen, um die Procurement API aufzurufen auf Dienstkonto hinzufügen. Sie können ein vorhandenes Dienstkonto in das Feld eingeben oder ein neues Dienstkonto erstellen.

  4. Klicken Sie zur Einbindung in Pub/Sub unter Dienstkonto verknüpfen, um Pub/Sub-Thema zu abonnieren auf Dienstkonto hinzufügen. Sie können ein vorhandenes Dienstkonto in das Feld eingeben oder ein neues Dienstkonto erstellen.

  5. Klicken Sie zur Integration in die Service Control API unter roles/servicemanagement.serviceController einem Dienstkonto hinzufügen auf Dienstkonto hinzufügen. Sie können ein vorhandenes Dienstkonto in das Feld eingeben oder ein neues Dienstkonto erstellen.

Nutzerkontoaufgaben

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

  1. Ein Nutzer stellt eine Anfrage oder Änderung in Google Cloud Marketplace, z. B. die Registrierung für Ihr Produkt.

  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_CHANGED.

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

  3. Zum Genehmigen der Anfrage sendet Ihre Anwendung eine HTTP POST-Anfrage an die Partner Procurement 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 Ihr Produkt zum ersten Mal kauft, erstellt Google Cloud Marketplace eine Kontoressource, in der die Beziehung des Nutzers mit Ihnen verfolgt wird. 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": "...",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

Dabei ist USER_ACCOUNT_ID die von Google Cloud Marketplace erstellte Konto-ID und YOUR_PARTNER_ID eine ID, die Ihnen zugewiesen wird, wenn Ihr Partner Engines Zugriff auf die Partner Procurement API ermöglicht.

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'}

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.

Berechtigungen verwalten

Wenn Kunden ein Preismodell für Ihre Software auswählen, erstellt Google eine Berechtigung, die angibt, dass der Kunde Ihr Produkt von Google 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.

Berechtigung genehmigen oder ablehnen

Wenn ein Kunde ein Preismodell auswählt, erstellt Google 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": "...",
  },
}

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

Wenn Sie eine Berechtigung ablehnen möchten, verwenden Sie stattdessen die Methode reject in Ihrer HTTP POST-Anfrage:

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

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

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 aufheben

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",
    "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",
  "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:

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_REQUESTEDGibt an, dass ein Kunde eines Ihrer Preismodelle ausgewählt hat. Außerdem wird alle 24 Stunden ein neues ENTITLEMENT_CREATION_REQUESTED-Ereignis ausgelöst, bis Sie auf Anfrage des Kunden reagiert.
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. Außerdem wird alle 24 Stunden ein neues ENTITLEMENT_PLAN_CHANGE_REQUESTED-Ereignis ausgelöst, bis Sie bei der Auswahl des Kunden eine Aktion ausführen.
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_RENEWEDGibt an, dass die Berechtigung eines Kunden für einen anderen Zeitraum verlängert wurde. Sie müssen nichts unternehmen, um die Verlängerung abzuschließen.
ENTITLEMENT_ANGEBOT_ENDEDGibt an, dass das private Angebot eines Kunden beendet ist. Wenn die Berechtigung des Kunden abgebrochen wurde, wird ein separates ENTITLEMENT_CANCELLED-Ereignis ausgelöst. Wenn die Berechtigung des Kunden noch aktiv ist, gilt für das Abo wieder der ermäßigte Preis.
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 Ihr Produkt nutzungsbasierte Preise auswählen, müssen Sie die Nutzung Ihrer Anwendung an die Service Control API melden.

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

Wenn Sie Zugriff auf Producer Portal haben, empfehlen wir, dass Sie im Producer-Portal ein Dienstkonto verwenden, um es mit Service Control zu verwenden.

Wenn Sie keinen Zugriff auf Producer Portal haben, erstellt Ihr Partnerentwickler einen Dienst, der Ihrer Lösung entspricht, und Ihrem Dienstkonto Zugriff auf die Nutzung wurden.

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 eine Service Control API Operation. 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" }]
    }],
    "userLabels": {
      "cloudmarketplace.googleapis.com/resource_name": "order_history_cache",
      "cloudmarketplace.googleapis.com/container_name": "storefront_prod",
      "environment": "prod",
      "region": "us-west2"
    }
  }]
}

wobei

  • operationId ist ein eindeutiger String, den die Dienstinstanz generiert. Für Ihre check- und report-Vorgänge sollten Sie denselben operationId verwenden.

  • consumerId ist mit dem usageReportingId der Berechtigung identisch.

  • startTime und endTime stellen die Start- und Endzeiten des Gesamtintervalls für den Vorgang report dar. In den meisten Fällen sollte der startTime eines report-Vorgangs denselben Wert wie der endTime des vorherigen report-Vorgangs haben.

    Wenn der Dienst eines Kunden vor dem startTime eines report-Vorgangs deaktiviert wird, sendet der services.check-API-Aufruf einen Fehler im Objekt checkErrors[] und der Kunde wird nicht in Rechnung gestellt. für das entsprechende Intervall.

  • MetricValueSet enthält ein oder Zwischenintervalle und die entsprechenden aktualisierten Messwerte. Sie definieren die Messwerte für Ihren Dienst, wenn Sie Ihr Preismodell auswählen und einreichen.

    Wenn Sie Zugriff auf Producer Portal haben, können Sie die IDs für Ihre Messwerte im Abschnitt Technische Integration des Producer Portals ansehen und darauf verweisen.

  • userLabels sind vom Nutzer erstellte Labels, die als Schlüssel/Wert-Paare definiert sind und bestimmte Syntaxanforderungen erfüllen. Diese Labels werden zur Zuordnung an Cloud Billing-Tools weitergeleitet. Empfohlene Labeling-Konventionen finden Sie unter Best Practices für die Verwendung von Labels.

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

Best Practices für die Verwendung von Labels

Bei einer bestimmten Berechtigung wird die gesamte Nutzung einer einzelnen usageReportingId zugeordnet. In einigen Szenarien wird jedoch ein usageReportingId unter Umständen innerhalb der Organisation eines Kunden gemeinsam verwendet. Zur Unterstützung einer detaillierten Kostenzuordnung empfehlen wir allen Diensten, userLabels an Nutzungsberichte anzuhängen. Labels werden an die Kostenverwaltungstools von Cloud Billing weitergeleitet, darunter Kostenberichte und Abrechnungsexporte.

Wenn Ihr Dienst nativ ein Konzept von Ressourcenlabels unterstützt, empfehlen wir Ihnen, diese Labels in Ihren Nutzungsberichten weiterzuleiten. Beachten Sie, dass Labels den Syntaxanforderungen entsprechen müssen.

Außerdem verwendet Google Cloud Marketplace die folgenden Labelkonventionen. Sie können diese Labels verwenden, um zusätzlichen Kontext für die Verwendung innerhalb Ihrer nativen Dienstplattform zu identifizieren. Wir empfehlen, diese Labels standardmäßig in Ihre Nutzungsberichte aufzunehmen.

LabelschlüsselLabelwertBeschreibung>
cloudmarketplace.googleapis.com/resource_name USER_SUPPLIED Der Name der Ressource, die mit einem Nutzungsmesswert verknüpft ist. Wenn der Messwert beispielsweise Datenbankspeicherbeträge meldet, ist der Wert dieses Labels der Datenbankname.
cloudmarketplace.googleapis.com/container_name USER_SUPPLIED Der Name eines Ressourcencontainers. Wenn beispielsweise eine Datenbankressource einem Clustercontainer übergeordnet ist, hat der Wert dieses Labels den Namen des Clusters.
Zurück
App einbinden: Einrichtung
Weiter
Front-End Ihrer Anwendung einbinden