Integrowanie rozwiązania SaaS z interfejsem Google Cloud Marketplace API za pomocą portalu producenta (Python)

1. Wprowadzenie

Rozwiązania SaaS w Google Cloud Marketplace to rozwiązania, które korzystają z Twojej infrastruktury (niezależnie od jej lokalizacji), lecz są rozliczane przez Google.

W tym module skonfigurujesz podstawowe rozwiązanie SaaS, które integruje się z Google Cloud Marketplace, aby:

• Otrzymuj powiadomienia, gdy użytkownik zarejestruje się w przykładowym rozwiązaniu.
• Zatwierdzaj klientów, którzy chcą się zarejestrować, i dodawaj ich do bazy danych.
• Obsługa sytuacji, w których klienci chcą zmienić lub anulować plany rozliczeniowe.
• Wysyłaj raporty o użytkowaniu do Google.

Ten przewodnik pomoże Ci zapoznać się z interfejsami API Google Cloud Marketplace do obsługi zakupów i kontroli usług. Pamiętaj, że ten przewodnik nie zawiera pełnego środowiska produktu do testowania.

2. Zanim zaczniesz

• Jeśli nie masz jeszcze włączonych ćwiczeń z programowania, włącz je w Producer Portal.

Bezpośredni link do Producer Portal:

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

Aby włączyć codelab, w panelu Codelabs po prawej stronie ekranu kliknij Włącz.

• Zainstaluj na komputerze Pythona 3 z tymi modułami:
• interfejsy API Google Client w Pythonie.
• Biblioteka klienta google-cloud-pubsub.

Aby zainstalować moduły Pythona, użyj tego polecenia:

pip install --upgrade google-api-python-client google-cloud-pubsub

• Sklonuj lub pobierz repozytorium GitHub dla tego laboratorium, używając tego polecenia:

git clone https://github.com/googlecodelabs/gcp-marketplace-integrated-saas.git
cd gcp-marketplace-integrated-saas

Pobierz plik ZIP

• Ustaw zmienną środowiskową GOOGLE_CLOUD_PROJECT na identyfikator tego projektu:
• Linux:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

• Windows:

set GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

• Przypisz do konta usługi saas-codelab rolę edytującego Pub/Sub. Instrukcje przyznawania ról i zarządzania nimi znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.
• Utwórz i pobierz klucz JSON konta usługi. Instrukcje tworzenia klucza znajdziesz w artykule Tworzenie kluczy kont usługi i zarządzanie nimi.

Uwaga: jeśli chcesz przesłać przykładowy kod do internetowego repozytorium źródłowego, takiego jak GitHub lub Cloud Source Repositories, nie przesyłaj tego klucza do repozytorium.

• Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na pełną ścieżkę do pobranego pliku:
• Linux:

export GOOGLE_APPLICATION_CREDENTIALS="[YOUR_MACHINE]/path/service-account-key.json"

• Windows:

set GOOGLE_APPLICATION_CREDENTIALS=[YOUR_MACHINE]/path/service-account-key.json

• Aby wyświetlić przykładowe rozwiązanie w Google Cloud Marketplace, otwórz Producer Portal i w panelu Codelabs kliknij Codelab product (Produkt Codelab). Możesz też uzyskać bezpośredni dostęp do rozwiązania na stronie https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab
• W konsoli Google Cloud w nowym projekcie włącz Partner Procurement API.

Następnie skonfiguruj backend przykładowego rozwiązania.

3. Integracja z Google Cloud Marketplace

Ogólnie rzecz biorąc, przykładowe rozwiązanie możesz zintegrować z Google Cloud Marketplace w następujący sposób:

• Integracja z Cloud Pub/Sub w celu otrzymywania powiadomień z Google Cloud Marketplace, np. gdy użytkownik zarejestruje się w Twoim rozwiązaniu. Inżynier zespołu partnerskiego tworzy temat Cloud Pub/Sub, który musisz zasubskrybować, aby otrzymywać powiadomienia.
• Skonfiguruj integrację z interfejsem Partner Procurement API, aby tworzyć konta dla nowych klientów. Interfejsu Partner Procurement API używasz do aktualizowania kont, gdy użytkownicy wybierają, zmieniają lub anulują abonamenty. Aby zintegrować się z tym interfejsem API, musisz utworzyć własną bibliotekę klienta.
• Integracja z Google Service Control w celu raportowania informacji o wykorzystaniu.

4. Subskrybowanie tematu Cloud Pub/Sub

Gdy użytkownik wybierze abonament, otrzymasz powiadomienie z Google Cloud Marketplace za pomocą tematu Cloud Pub/Sub.

Aby nasłuchiwać wiadomości w temacie Cloud Pub/Sub, musisz najpierw utworzyć subskrypcję.

Aby utworzyć subskrypcję, użyj skryptu create_subscription.py:

cd gcp-marketplace-integrated-saas/tools
python create_subscription.py

Aby wyświetlić subskrypcję, otwórz panel Cloud Pub/Sub w konsoli Cloud:

https://console.cloud.google.com/cloudpubsub/subscriptions

Wypróbuj prośbę o subskrypcję testową

Aby przetestować tę przykładową aplikację jako użytkownik, otwórz produkt z codelabem w Marketplace, klikając https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab. Sprawdź, czy wybrany jest projekt z codelabu, i wybierz abonament.

Uwaga: ceny wyświetlane w przypadku produktu demonstracyjnego są przykładowe. Nie pobieramy opłat za to rozwiązanie, niezależnie od wybranego planu.

Aby zobaczyć wiadomości Cloud Pub/Sub wysyłane po wybraniu planu, przejdź do katalogu głównego python3 w repozytorium i uruchom to polecenie:

~/gcp-marketplace-integrated-saas/python3$ python -m impl.step_1_pubsub.app

Przykładowy kod, który nasłuchuje wiadomości Cloud Pub/Sub, znajdziesz na stronie https://github.com/googlecodelabs/gcp-marketplace-integrated-saas/blob/master/python3/impl/step_1_pubsub/app.py.

W wiadomości Cloud Pub/Sub pole eventType zawiera informację o przyczynie wysłania wiadomości. Gdy wybierzesz abonament, powinna się pojawić wiadomość o eventType: ENTITLEMENT_CREATION_REQUESTED, która reprezentuje wcześniej wybrany abonament.

Jeśli anulujesz subskrypcję podczas działania tego skryptu, zobaczysz nowy komunikat dotyczący eventType: ENTITLEMENT_CANCELLED.

Pamiętaj, że powyższy przykład nie potwierdza wiadomości. Dzięki temu możesz łatwiej przeprowadzać testy, ponieważ za każdym razem, gdy uruchomisz aplikację, będziesz otrzymywać te same wiadomości.

Aby zamknąć skrypt, naciśnij CTRL + \.

5. Zatwierdź prośbę o konto

Teraz, gdy możesz otrzymywać wiadomości z Google Cloud Marketplace, musisz zacząć obsługiwać zasoby, które usługa zakupów w Google Cloud Marketplace tworzy w imieniu klienta.

Pierwszy to zasób account. Konto reprezentuje połączenie klienta z Twoją usługą. Musisz przechowywać w bazie danych identyfikator konta klienta w usłudze Procurement, aby mapować relację między jego kontem Google a kontem w Twojej usłudze.

Gdy klient wybierze abonament, Google Cloud Marketplace wyśle powiadomienie Cloud Pub/Sub z informacją, że klient prosi o konto. Aplikacja musi zatwierdzić prośbę. W tym samouczku zatwierdzisz prośby o konto po otrzymaniu wiadomości Cloud Pub/Sub.

Uwaga: w ogólnodostępnej integracji Google Cloud Marketplace kieruje klientów do frontendu Twojej usługi, gdzie rejestrują się w Twoim oprogramowaniu, zanim zatwierdzisz ich prośbę o utworzenie konta. W ramach końcowej integracji musisz też skonfigurować stronę rejestracji w interfejsie. Informacje o integracji frontendu aplikacji znajdziesz w dokumentacji Google Cloud Marketplace.

Tworzenie bazy danych z informacjami o koncie

W tym samouczku używamy prostej bazy danych JSON, która może śledzić konta klientów i zakupy.

Aby przetestować ten przykład, utwórz na stacji roboczej plik z pustym obiektem JSON:

{}

Ustaw zmienną środowiskową PROCUREMENT_CODELAB_DATABASE na pełną ścieżkę do tego pliku:

• Linux:

export PROCUREMENT_CODELAB_DATABASE="YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json"

• Windows:

set PROCUREMENT_CODELAB_DATABASE=YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json

Moduł, który odczytuje i zapisuje dane w bazie danych, znajduje się w python3/impl/database.

Przykładowa implementacja korzysta ze schematu, który można rozszerzyć, jeśli integrujesz z Google Cloud Marketplace więcej niż 1 ofertę produktu. Oto przykładowy wpis w bazie danych użytkownika, który zasubskrybował abonament Very Good w przykładowej aplikacji:

{
   "a2b3c4d5-b3f1-4dea-b134-generated_id":{
      "procurement_account_id":"generated-b3f1-4dea-b134-4a1d100c0335",
      "internal_account_id":"generated-45b7-4f4d-1bcd-2abb114f77de",
      "products":{
         "isaas-codelab":{
            "start_time":"2019-01-04T01:21:16.188Z",
            "plan_id":"very-good",
            "product_id":"isaas-codelab",
            "consumer_id":"project_number:123123345345"
         }
      }
   }
}

W ostatecznej implementacji musisz połączyć aplikację z własnymi bazami danych, aby powiązać konta klientów w Google Cloud Marketplace z własnymi zasobami klientów.

Zatwierdzanie konta

Aby zatwierdzić prośbę o konto, uruchom to polecenie:

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_2_account.app

Przykładowy kod do zatwierdzania konta znajdziesz w pliku impl/step_2_account.

Uwaga: w typowym przypadku integracji zatwierdzenie konta oznacza, że klient zarejestrował się w Twojej aplikacji za pomocą interfejsu. W ostatecznej implementacji musisz zatwierdzać konta tylko w procesie rejestracji.

W katalogu marketplaceui w samouczku znajduje się strona demonstracyjna, na której wyświetlany jest identyfikator konta zakupowego z zweryfikowanego tokena JWT.

Przykładowa implementacja korzysta z klasy Procurement, która obsługuje interakcje z interfejsem Procurement API. Oto metody get_account() i approve_account():

step_2_account/app.py

def _get_account_name(self, account_id):
    return 'providers/DEMO-{}/accounts/{}'.format(PROJECT_ID,
                                                  account_id)

def get_account(self, account_id):
    """Gets an account from the Procurement Service."""
    name = self._get_account_name(account_id)
    request = self.service.providers().accounts().get(name=name)
    try:
        response = request.execute()
        return response
    except HttpError as err:
        if err.resp.status == 404:
            return None

def approve_account(self, account_id):
    """Approves the account in the Procurement Service."""
    name = self._get_account_name(account_id)
    request = self.service.providers().accounts().approve(
        name=name, body={'approvalName': 'signup'})
    request.execute()

W tym module w usłudze Procurement identyfikator dostawcy to DEMO-YOUR_PROJECT_ID, gdzie YOUR_PROJECT_ID to utworzony przez Ciebie projekt. Podczas korzystania z interfejsu Procurement API nazwa konta musi mieć ten format:

providers/DEMO-YOUR_PROJECT_ID/accounts/account-id

Następnie zatwierdzasz uprawnienie, czyli zapis zakupu dokonanego przez klienta.

6. Zatwierdzanie uprawnienia

Gdy klient wybierze w Google Cloud Marketplace plan subskrypcji, zostanie utworzone konto, a następnie od razu zostanie utworzona nowa prośba o uprawnienie. Upoważnienie reprezentuje zakup usługi. Zanim klient zacznie korzystać z usługi, musisz zatwierdzić prośbę o uprawnienia, a następnie skonfigurować usługę, aby klient mógł z niej korzystać.

Gdy aplikacja przykładowa otrzyma wiadomość Cloud Pub/Sub z parametrem eventType ENTITLEMENT_CREATION_REQUESTED, uprawnienie zostanie zatwierdzone, a aplikacja musi poczekać na wiadomość ENTITLEMENT_ACTIVE, aby zapisać uprawnienie w bazie danych, a następnie skonfigurować zasoby dla klienta.

Sprawdzona metoda: twórz uprawnienia tylko dla kont, które zostały już przez Ciebie zatwierdzone. Jeśli w bazie danych nie ma informacji o koncie, nie twórz nowego uprawnienia.

Aby utworzyć uprawnienie, uruchom to polecenie:

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_3_entitlement_create.app

Kod zatwierdzający uprawnienie znajduje się w przykładowej implementacji.

Następnie zajmij się sytuacjami, w których klient prosi o zmianę abonamentu.

7. Zatwierdzanie zmian w uprawnieniu

Jeśli Twoja usługa ma kilka abonamentów, musisz obsługiwać prośby klientów, którzy chcą przejść na wyższy lub niższy abonament.

Jeśli Twoja usługa ma tylko 1 abonament, przejdź do sekcji Obsługa anulowanych zakupów.

Nie ma technicznej różnicy między aktywowaniem uprawnienia po raz pierwszy a aktywacją po zmianie planu. Z tego powodu przykładowa implementacja ma wspólną metodę handleActiveEntitlement() w obu przypadkach. Ta metoda sprawdza wiadomości przychodzące pod kątem zdarzeń związanych z uprawnieniami:

step_4_entitlement_change/app.py

def handleActiveEntitlement(self, entitlement, customer, accountId):
  """Updates the database to match the active entitlement."""

  product = {
      'product_id': entitlement['product'],
      'plan_id': entitlement['plan'],
  }

  if 'consumerId' in entitlement:
    product['consumer_id'] = entitlement['consumerId']

  customer['products'][entitlement['product']] = product

  self.db.write(accountId, customer)

Ten fragment kodu sprawdza, czy wartość eventType to ENTITLEMENT_PLAN_CHANGE_REQUESTED lub ENTITLEMENT_PLAN_CHANGED:

step_4_entitlement_change/app.py

elif eventType == 'ENTITLEMENT_PLAN_CHANGE_REQUESTED':
  if state == 'ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL':
    # Don't write anything to our database until the entitlement becomes
    # active within the Procurement Service.
    self.approveEntitlementPlanChange(id, entitlement['newPendingPlan'])
    return True

elif eventType == 'ENTITLEMENT_PLAN_CHANGED':
  if state == 'ENTITLEMENT_ACTIVE':
    # Handle an active entitlement after a plan change.
    self.handleActiveEntitlement(entitlement, customer, accountId)
    return True

W ostatecznej implementacji, gdy uprawnienie wróci do stanu ENTITLEMENT_ACTIVE, metoda odbiornika powinna zaktualizować bazę danych, aby odzwierciedlić zmianę, i wykonać niezbędne działania związane z udostępnianiem.

W zależności od tego, jak skonfigurujesz usługę z inżynierem ds. partnerów, może ona nie zezwalać na przejście na niższą wersję ani anulowanie subskrypcji do końca okresu rozliczeniowego. W takich przypadkach zmiana abonamentu będzie nadal oczekiwać na zatwierdzenie nawet po jego uzyskaniu, ale uprawnienia nie wrócą do stanu ENTITLEMENT_ACTIVE, dopóki zmiana abonamentu nie zostanie zakończona.

Kod, który sprawdza i zatwierdza zmiany uprawnień, znajdziesz w przykładowej implementacji.

Następnie zajmij się sytuacjami, w których klienci anulują zakupy.

8. Obsługa anulowanych zakupów

Klienci mogą anulować zakupy. W zależności od tego, jak skonfigurujesz usługę z inżynierem ds. partnerów, anulowanie może nastąpić natychmiast lub na koniec okresu rozliczeniowego.

Gdy klient anuluje zakup, wysyłana jest wiadomość z symbolem eventType ENTITLEMENT_PENDING_CANCELLATION. Jeśli Twój produkt jest skonfigurowany tak, aby natychmiast przetwarzać anulowania, wkrótce po tym zostanie wysłana wiadomość z symbolem eventType ENTITLEMENT_CANCELLED.

step_5_entitlement_cancel/app.py

elif eventType == 'ENTITLEMENT_CANCELLED':
  # Clear out our records of the customer's plan.
  if entitlement['product'] in customer['products']:
    del customer['products'][entitlement['product']]

  ### TODO: Turn off customer's service. ###
  self.db.write(accountId, customer)
  return True

elif eventType == 'ENTITLEMENT_PENDING_CANCELLATION':
  # Do nothing. We want to cancel once it's truly canceled. For now it's
  # just set to not renew at the end of the billing cycle.
  return True

elif eventType == 'ENTITLEMENT_CANCELLATION_REVERTED':
  # Do nothing. The service was already active, but now it's set to renew
  # automatically at the end of the billing cycle.
  return True

Twoja usługa musi poczekać na wiadomość ENTITLEMENT_CANCELLED, a następnie usunąć uprawnienie z bazy danych i wyłączyć usługę dla klienta.

Po anulowaniu uprawnienia jest ono usuwane z systemów Google i wysyłana jest wiadomość z kodem eventType ENTITLEMENT_DELETED:

step_5_entitlement_cancel/app.py

elif eventType == 'ENTITLEMENT_DELETED':
  # Do nothing. Entitlements can only be deleted when they are already
  # cancelled, so our state is already up-to-date.
  return True

Kod, który anuluje uprawnienie, znajdziesz w przykładowej implementacji.

9. Wysyłanie raportów o użytkowaniu

Niektóre usługi mają komponenty oparte na wykorzystaniu, w przypadku których Google musi znać sposób korzystania z usługi przez klientów, aby obciążyć ich odpowiednią kwotą. Usługa musi zgłaszać wykorzystanie za pomocą interfejsu Google Service Control API.

Jeśli Twoja usługa nie ma komponentów opartych na wykorzystaniu, pomiń tę sekcję.

Szczegółowe informacje o wysyłaniu raportów o użytkowaniu znajdziesz w dokumentacji wprowadzającej.

Raporty o wykorzystaniu należy wysyłać do interfejsu Google Service Control API co godzinę. W tym laboratorium kodowania raporty są wysyłane za pomocą skryptu, który możesz zaplanować jako zadanie cron. Skrypt zapisuje w bazie danych czas ostatniego raportu o użyciu i używa go jako czasu rozpoczęcia pomiaru wykorzystania.

Skrypt sprawdza każdego aktywnego klienta usługi i wysyła raport o wykorzystaniu do Google Service Control, używając pola consumer_id uprawnień klienta. Następnie skrypt aktualizuje wpis w bazie danych klienta, ustawiając wartość last_report_time na czas zakończenia właśnie wysłanego raportu o użytkowaniu.

Usługa Google Service Control udostępnia 2 metody: check i report. Pierwsza z nich powinna być zawsze wywoływana bezpośrednio przed wywołaniem drugiej. Jeśli w pierwszym przypadku wystąpią błędy, usługa klienta powinna zostać wyłączona do czasu ich naprawienia.

Całe wykorzystanie danego uprawnienia jest przypisywane do jednego usageReportingId. W przypadku usług SaaS to wykorzystanie jest jednak powiązane z pozycją [Charges not specific to a project] na koncie rozliczeniowym Google Cloud. Jeśli Twoja usługa SaaS może być szeroko udostępniana w organizacji klienta i chcesz obsługiwać przypisywanie kosztów, zalecamy, aby wszystkie Twoje usługi zawierały w raporcie wykorzystania opcjonalne pole userLabels operation.

Google Cloud Marketplace rezerwuje klucze etykiet cloudmarketplace.googleapis.com/resource_name i cloudmarketplace.googleapis.com/container_name. Te etykiety mają na celu uchwycenie kontekstu użycia w ramach Twojej usługi natywnej i hierarchii zasobów. W raportach o wykorzystaniu zasobów nazwy przypisane przez klienta będą uwzględniane jako wartości etykiet. Zalecamy, aby domyślnie uwzględniać te etykiety w raportach o użyciu.

Klucz etykiety	Wartość etykiety	Opis
cloudmarketplace.googleapis.com/resource_name	RESOURCE_NAME	Nazwa zasobu powiązanego z rodzajem wykorzystania.
cloudmarketplace.googleapis.com/container_name	CONTAINER_NAME	Nazwa kontenera zasobów.

Poniższy fragment kodu raportuje wykorzystanie aplikacji demonstracyjnej i przypisuje wykorzystanie usługi SaaS do zasobu przypisanego przez klienta o nazwie products_db. W tym ćwiczeniu z programowania service_name to isaas-codelab.mp-marketplace-partner-demos.appspot.com.

operation = {
  'operationId': '<UUID>',
  'operationName': 'Codelab Usage Report',
  'consumerId': 'project_number:<Project Number>',
  'startTime': '<Timestamp>',
  'endTime': '<Timestamp>',
  'metricValues': [{
      'int64Value': 100,
  }],
  'userLabels': {
    'cloudmarketplace.googleapis.com/container_name': 'saas-storage-solutions',
    'cloudmarketplace.googleapis.com/resource_name': 'products_db'
  }
}

service.services().report(
    serviceName=service_name, body={
        'operations': [operation]
    }).execute()
product['last_report_time'] = end_time
database.write(customer_id, customer)

Pełny kod znajdziesz w przykładowej implementacji tego skryptu. Aby utworzyć przykładowy raport o użyciu, uruchom to polecenie:

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_6_usage_reporting.report isaas-codelab.mp-marketplace-partner-demos.appspot.com

10. Gratulacje!

Dowiedziałeś się, jak zintegrować usługę SaaS z Google Cloud Marketplace, aby zarządzać kontami klientów i uprawnieniami oraz raportować wykorzystanie usługi. Pełne instrukcje integracji znajdziesz w dokumentacji integracji backendu.

Wskazówka: jeśli chcesz ponownie wypróbować proces subskrypcji, zresetuj zatwierdzenia i uprawnienia konta, uruchamiając skrypt reset_account. Przed uruchomieniem skryptu przyznaj kontu usługi rolę administratora konta rozliczeniowego.

~/gcp-marketplace-integrated-saas$ python3 tools/reset_account.py

Identyfikator konta znajdziesz w pliku EMPTY_JSON_OBJECT.json.

Czyszczenie danych

Jeśli nie planujesz już ich używać, usuń te zasoby:

• Subskrypcja Cloud Pub/Sub
• Konto usługi i jego klucze
• Opcjonalnie utworzony projekt
• opcjonalnie utworzone przez Ciebie konto rozliczeniowe.

Co dalej?

Integracja frontendu

Przykłady w tym laboratorium automatycznie zatwierdzają konta i uprawnienia. W praktyce klienci muszą być kierowani na utworzoną przez Ciebie stronę rejestracji, na której mogą utworzyć konta w Twoim systemie. Po pomyślnej rejestracji musisz wysłać żądania do interfejsu API, aby zatwierdzić ich konta i uprawnienia.

Informacje o integracji frontendu aplikacji znajdziesz w dokumentacji Google Cloud Marketplace.

Więcej informacji o oferowaniu rozwiązań SaaS

Ogólne informacje o oferowaniu rozwiązań SaaS w Google Cloud Marketplace znajdziesz w artykule Oferowanie rozwiązań SaaS.