Üretici Portalı'nı kullanarak SaaS çözümünüzü Google Cloud Marketplace API'siyle entegre edin (Python)

1. Giriş

Google Cloud Marketplace'teki SaaS çözümleri, konumdan bağımsız olarak altyapınızda çalışan ancak Google tarafından faturalandırılan yazılım çözümleridir.

Bu codelab'de, Google Cloud Marketplace ile entegre olan temel bir SaaS çözümü oluşturarak şunları yapacaksınız:

  • Bir kullanıcı örnek çözüme kaydolduğunda bildirim alın.
  • Kaydolmak isteyen müşterileri onaylayın ve veritabanınıza ekleyin.
  • Müşterilerin faturalandırma planlarını değiştirmek veya iptal etmek istediği durumları ele alın.
  • Kullanım raporlarını Google'a gönderin.

Bu codelab, Google Cloud Marketplace tedarik ve hizmet kontrolü API'lerini tanımanıza yardımcı olur. Bu kılavuzun, test için tam bir ürün ortamı sağlamadığını unutmayın.

2. Başlamadan önce

  • Henüz etkinleştirmediyseniz projeniz için codelab'i etkinleştirmek üzere Üretici Portalı'nı kullanın.

Producer Portal'ın doğrudan bağlantısı:

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

Codelab'i etkinleştirmek için ekranın sağ tarafındaki Codelab'ler panelinde Etkinleştir'i tıklayın.

Python modüllerini yüklemek için aşağıdaki komutu kullanın:

pip install --upgrade google-api-python-client google-cloud-pubsub
  • Bu codelab için GitHub deposunu aşağıdaki komutu kullanarak klonlayın veya indirin:
git clone https://github.com/googlecodelabs/gcp-marketplace-integrated-saas.git
cd gcp-marketplace-integrated-saas

  • GOOGLE_CLOUD_PROJECT ortam değişkenini bu projenin kimliği olarak ayarlayın:
  • Linux:
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
  • Windows:
set GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
  • GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini indirilen dosyanın tam yoluna ayarlayın:
  • Linux:
export GOOGLE_APPLICATION_CREDENTIALS="[YOUR_MACHINE]/path/service-account-key.json"
  • Windows:
set GOOGLE_APPLICATION_CREDENTIALS=[YOUR_MACHINE]/path/service-account-key.json
  • Google Cloud Marketplace'te örnek bir çözümü görüntülemek için Üretici Portalı'nı ziyaret edin ve Codelab'ler panelinde Codelab ürünü'nü tıklayın. Çözüme doğrudan https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab adresinden de erişebilirsiniz.
  • Google Cloud Console'da, yeni projenizde Partner Procurement API'yi etkinleştirin.

Ardından, örnek çözümün arka ucunu ayarlayın.

3. Google Cloud Marketplace ile entegrasyon

Özet olarak, örnek çözümü Google Cloud Marketplace ile aşağıdaki şekillerde entegre edersiniz:

  • Google Cloud Marketplace'ten bildirim almak için Cloud Pub/Sub ile entegre olun. Örneğin, bir kullanıcı çözümünüze kaydolduğunda bildirim alabilirsiniz. İş ortağı mühendisiniz, bildirimler için abone olmanız gereken bir Cloud Pub/Sub konusu oluşturur.
  • Yeni müşteriler için hesap oluşturmak üzere İş Ortağı Tedarik API'si ile entegrasyon sağlayın. Kullanıcılar abonelik planlarını seçtiğinde, değiştirdiğinde veya iptal ettiğinde hesapları güncellemek için Partner Procurement API'yi kullanırsınız. API ile entegrasyon için kendi istemci kitaplığınızı oluşturmanız gerekir.
  • Kullanım bilgilerini bildirmek için Google Service Control ile entegre olun.

4. Cloud Pub/Sub konusuna abone olma

Kullanıcı bir abonelik planı seçtiğinde, Cloud Pub/Sub konusu aracılığıyla Google Cloud Marketplace'ten bildirim alırsınız.

Bir Cloud Pub/Sub konusundaki mesajları dinlemek için önce bir abonelik oluşturmanız gerekir.

Abonelik oluşturmak için create_subscription.py komut dosyasını kullanın:

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

Aboneliği görmek için Cloud Console'da Cloud Pub/Sub kontrol panelini açın:

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

Test aboneliği isteği göndermeyi deneyin

Bu örnek uygulamayı kullanıcı olarak test etmek için https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab adresini ziyaret ederek Marketplace'te codelab ürününü açın. Codelab projenizin seçili olduğundan emin olun ve bir abonelik planı seçin.

Bir plan seçtiğinizde gönderilen Cloud Pub/Sub mesajlarını görmek için depodaki python3 dizininin kök dizinine gidin ve aşağıdaki komutu çalıştırın:

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

Cloud Pub/Sub mesajlarını dinleyen örnek kodu görmek için https://github.com/googlecodelabs/gcp-marketplace-integrated-saas/blob/master/python3/impl/step_1_pubsub/app.py adresini ziyaret edin.

Cloud Pub/Sub mesajında, eventType alanı mesajın neden gönderildiğini gösterir. Bir plan seçtiğinizde, daha önce seçtiğiniz abonelik planını temsil eden eventType: ENTITLEMENT_CREATION_REQUESTED mesajını görürsünüz.

Bu komut dosyası çalışırken planınızı iptal ederseniz eventType: ENTITLEMENT_CANCELLED için yeni bir mesaj görürsünüz.

Yukarıdaki örnekte iletilerin onaylanmadığını unutmayın. Bu sayede, uygulamanızı her çalıştırdığınızda aynı mesajları alarak daha kolay test yapabilirsiniz.

Senaryoyu kapatmak için CTRL + \ tuşuna basın.

5. Hesap isteğini onaylama

Artık Google Cloud Marketplace'ten mesaj alabileceğinize göre, Google Cloud Marketplace Procurement hizmetinin müşteri adına oluşturduğu kaynakları işlemeye başlamanız gerekir.

Birincisi hesap kaynağıdır. Hesap, müşterinin ürününüzle bağlantısını temsil eder. Müşterinin Google Hesabı ile hizmetinizdeki hesabı arasındaki ilişkiyi eşlemek için müşterinin tedarik hesabı kimliğini veritabanınızda saklamanız gerekir.

Bir müşteri plan seçtiğinde Google Cloud Marketplace, müşterinin hesap istediğine dair bir Cloud Pub/Sub bildirimi gönderir. Uygulamanız isteği onaylamalıdır. Bu codelab'de, Cloud Pub/Sub mesajları alındığında hesap isteklerini onaylayacaksınız.

Hesap bilgileri için veritabanı oluşturma

Bu codelab'de, müşteri hesaplarını ve satın alma işlemlerini takip edebilen basit bir JSON veritabanı kullanıyoruz.

Bu örneği test etmek için iş istasyonunuzda herhangi bir yerde boş bir JSON nesnesi içeren bir dosya oluşturun:

{}

PROCUREMENT_CODELAB_DATABASE ortam değişkenini bu dosyanın tam yoluna ayarlayın:

  • Linux:
export PROCUREMENT_CODELAB_DATABASE="YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json"
  • Windows:
set PROCUREMENT_CODELAB_DATABASE=YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json

Veritabanını okuyup yazan modül python3/impl/database'dadır.

Örnek uygulama, Google Cloud Marketplace ile birden fazla ürün teklifi entegre ediyorsanız genişletilebilen bir şema kullanır. Aşağıda, örnek uygulamada Çok İyi planına abone olan bir kullanıcı için örnek veritabanı girişi verilmiştir:

{
   "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"
         }
      }
   }
}

Son uygulamanızda, müşterilerin Google Cloud Marketplace hesaplarını kendi müşteri kaynaklarınızla bağlamak için uygulamanızı kendi veritabanlarınıza bağlamanız gerekir.

Hesabı onaylama

Hesap isteğini onaylamak için aşağıdaki komutu çalıştırın:

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

Bir hesabı onaylamak için kullanılan örnek kod impl/step_2_account içinde yer alır.

Örnek uygulamada, Procurement API ile etkileşimleri işleyen Procurement sınıfı kullanılır. get_account() ve approve_account() yöntemleri şunlardır:

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()

Bu codelab'de, tedarik hizmetinde sağlayıcı kimliği DEMO-YOUR_PROJECT_ID şeklindedir. Burada YOUR_PROJECT_ID, oluşturduğunuz projedir. Procurement API ile etkileşimde bulunurken hesap adı şu biçimde olmalıdır:

providers/DEMO-YOUR_PROJECT_ID/accounts/account-id

Ardından, müşterinin satın alma işleminin kaydı olan bir yararlanma hakkını onaylarsınız.

6. Yetkilendirmeyi onaylama

Müşteri, Google Cloud Marketplace'te bir abonelik planı seçtiğinde bir hesap oluşturulur ve ardından hemen yeni bir yetkilendirme isteği oluşturulur. Yararlanma hakkı, bir hizmetin satın alınmasını ifade eder. Müşteri hizmeti kullanmaya başlamadan önce hak talebini onaylamanız ve ardından hizmeti müşterinin kullanmaya başlaması için ayarlamanız gerekir.

Örnek uygulama, eventType ENTITLEMENT_CREATION_REQUESTED ile bir Cloud Pub/Sub mesajı aldığında hak onaylanır ve uygulamanın, hak veritabanına kaydedilene kadar bir ENTITLEMENT_ACTIVE mesajı beklemesi, ardından müşteri için kaynakları ayarlaması gerekir.

Yetkilendirmeyi oluşturmak için aşağıdaki komutu çalıştırın:

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

Hak kazanmayı onaylama kodu örnek uygulamada yer alır.

Ardından, müşterilerin abonelik planlarında değişiklik yapma isteklerini ele alırsınız.

7. Bir hakta yapılan değişiklikleri onaylama

Hizmetinizde birden fazla plan varsa mevcut planlarını yükseltmek veya düşürmek isteyen müşterilerin isteklerini karşılamanız gerekir.

Hizmetinizde yalnızca bir plan varsa İptal edilen satın alma işlemlerini ele alma bölümüne geçin.

Bir hakka ilk kez erişilmesi ile plan değişikliğinden sonra erişilmesi arasında teknik olarak bir fark yoktur. Bu nedenle, örnek uygulamada her iki durum için de ortak bir handleActiveEntitlement() yöntemi vardır. Bu yöntem, gelen iletilerde hakla ilgili etkinlikleri kontrol eder:

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)

Aşağıdaki snippet, eventType değerinin ENTITLEMENT_PLAN_CHANGE_REQUESTED veya ENTITLEMENT_PLAN_CHANGED olup olmadığını kontrol eder:

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

Son uygulamanızda, hak durumu tekrar ENTITLEMENT_ACTIVE durumuna geçtiğinde dinleyici yönteminiz, değişikliği yansıtmak için veritabanınızı güncellemelidir ve gerekli hazırlıkları yapmalıdır.

Ürününüzü iş ortağı mühendisinizle birlikte nasıl ayarladığınıza bağlı olarak, hizmetiniz faturalandırma döneminin sonuna kadar sürüm düşürmeye veya iptale izin vermeyebilir. Bu gibi durumlarda, onaylandıktan sonra bile plan değişikliği beklemede kalmaya devam eder ancak plan değişikliği tamamlanana kadar hak ENTITLEMENT_ACTIVE durumuna geri dönmez.

Hak değişikliklerini kontrol eden ve onaylayan kod için örnek uygulamaya bakın.

Ardından, müşterilerin satın alma işlemlerini iptal ettiği durumları ele alırsınız.

8. İptal edilen satın alma işlemlerini yönetme

Müşteriler, satın alma işlemlerini iptal etmeyi seçebilir. Ürünü iş ortağı mühendisinizle nasıl ayarladığınıza bağlı olarak iptal işlemi hemen veya faturalandırma döneminin sonunda geçerli olabilir.

Müşteri satın alma işlemini iptal ettiğinde eventType ENTITLEMENT_PENDING_CANCELLATION içeren bir mesaj gönderilir. Ürününüzü iptalleri hemen işleyecek şekilde ayarladıysanız kısa süre sonra eventType ENTITLEMENT_CANCELLED simgesini içeren bir mesaj gönderilir.

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

Hizmetiniz, ENTITLEMENT_CANCELLED mesajını beklemeli, ardından yetkiyi veritabanınızdan kaldırmalı ve müşteri için hizmeti devre dışı bırakmalıdır.

Hak iptal edildikten sonra Google'ın sistemlerinden silinir ve eventType ENTITLEMENT_DELETED ile ilgili bir mesaj gönderilir:

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

Hak iptal eden kod için örnek uygulamaya bakın.

9. Kullanım raporları gönderme

Bazı hizmetlerde, Google'ın müşteriden doğru tutarı tahsil etmek için müşterinin hizmeti kullanımı hakkında bilgi sahibi olması gereken kullanıma dayalı bileşenler bulunur. Hizmetiniz, Google Service Control API aracılığıyla kullanımı bildirmelidir.

Hizmetinizde kullanıma dayalı bileşenler yoksa bu bölümü atlayın.

Kullanım raporları gönderme hakkında ayrıntılı bilgi için ilk katılım belgelerine bakın.

Kullanım raporları, Google Service Control API'ye saatte bir gönderilmelidir. Bu codelab'de raporlar, cron işi olarak planlayabileceğiniz bir komut dosyası kullanılarak gönderilir. Komut dosyası, son kullanım raporunun zamanını veritabanında saklar ve kullanımı ölçmek için başlangıç zamanı olarak kullanır.

Komut dosyası, hizmetin her etkin müşterisini kontrol eder ve müşteri yetkisinin consumer_id alanını kullanarak Google Hizmet Denetimi'ne bir kullanım raporu gönderir. Ardından komut dosyası, müşterinin veritabanı girişini, yeni gönderilen kullanım raporunun bitiş zamanına ayarlanmış bir last_report_time ile günceller.

Google Hizmet Denetimi iki yöntem sunar: check ve report. Birincisi, ikincisi çağrılmadan hemen önce her zaman çağrılmalıdır. İlkinde hata varsa düzeltilene kadar müşterinin hizmeti devre dışı bırakılmalıdır.

Belirli bir hakka ilişkin tüm kullanım tek bir usageReportingId ile ilişkilendirilir. Ancak SaaS ürünlerinde bu kullanım, Google Cloud Faturalandırma'daki [Charges not specific to a project] satır öğesiyle ilişkilendirilir. SaaS ürününüz bir müşterinin kuruluşunda geniş çapta paylaşılabilir ve maliyet ilişkilendirmeyi desteklemek istiyorsanız tüm hizmetlerinizin kullanım raporu işleminde isteğe bağlı userLabels alanını içermesini öneririz.

Google Cloud Marketplace, cloudmarketplace.googleapis.com/resource_name ve cloudmarketplace.googleapis.com/container_name etiket anahtarlarını ayırır. Bu etiketler, yerel hizmetinizdeki ve kaynak hiyerarşinizdeki kullanım bağlamını yakalamak için tasarlanmıştır. Bu kaynakların müşteri tarafından atanan adları, kullanım raporlarında etiket değerleri olarak yer alır. Bu etiketleri varsayılan olarak kullanım raporlarınıza eklemenizi öneririz.

Etiket Anahtarı

Etiket Değeri

Açıklama

cloudmarketplace.googleapis.com/resource_name

RESOURCE_NAME

Kullanım metriğiyle ilişkili kaynağın adı.

cloudmarketplace.googleapis.com/container_name

CONTAINER_NAME

Kaynak kapsayıcısının adı.

Aşağıdaki snippet, demo uygulamasının kullanımını bildirir ve SaaS ürününün kullanımını products_db adlı müşteri tarafından atanmış kaynağa atfeder. Bu codelab'de service_name, isaas-codelab.mp-marketplace-partner-demos.appspot.com'dir.

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)

Tam kod için bu komut dosyasının örnek uygulamasına bakın. Örnek bir kullanım raporu oluşturmak için aşağıdaki komutu çalıştırın:

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

10. Tebrikler!

SaaS çözümünüzün, müşteri hesaplarını ve yetkilerini yönetmek, ayrıca hizmet kullanımını bildirmek için Google Cloud Marketplace ile nasıl entegre edilebileceğini öğrendiniz. Tam entegrasyon adımları için arka uç entegrasyonu belgelerine bakın.

Temizleme

Artık kullanmayı planlamıyorsanız aşağıdaki kaynakları silin:

  • Cloud Pub/Sub aboneliği
  • Hizmet hesabı ve anahtarları
  • İsteğe bağlı olarak, oluşturduğunuz proje
  • İsteğe bağlı olarak, oluşturduğunuz faturalandırma hesabı

Sırada ne var?

Ön ucunuzu entegre etme

Bu codelab'deki örnekler, hesapları ve hakları otomatik olarak onaylar. Uygulamada, müşterileriniz oluşturduğunuz bir kayıt sayfasına yönlendirilmeli ve bu sayfada sisteminizde hesap oluşturabilmelidir. Kullanıcılar başarıyla kaydolduktan sonra hesaplarını ve haklarını onaylamak için API istekleri göndermeniz gerekir.

Uygulamanızın ön ucunu entegre etme hakkında bilgi edinmek için Google Cloud Marketplace belgelerini inceleyin.

SaaS çözümleri sunma hakkında daha fazla bilgi edinin

Google Cloud Marketplace'te SaaS çözümleri sunmaya genel bir bakış için SaaS çözümleri sunma başlıklı makaleyi inceleyin.