Mengintegrasikan solusi SaaS Anda dengan Google Cloud Marketplace API menggunakan Producer Portal (Python)

1. Pengantar

Solusi SaaS di Google Cloud Marketplace adalah solusi software yang berjalan di infrastruktur Anda, terlepas dari lokasi, tetapi akan ditagih oleh Google.

Dalam codelab ini, Anda akan menyiapkan solusi SaaS dasar yang terintegrasi dengan Google Cloud Marketplace untuk:

• Menerima notifikasi saat pengguna mendaftar ke solusi contoh.
• Menyetujui pelanggan yang ingin mendaftar, dan menambahkannya ke database Anda.
• Tangani skenario saat pelanggan ingin mengubah atau membatalkan paket penagihan mereka.
• Kirim laporan penggunaan ke Google.

Codelab ini membantu Anda memahami API kontrol layanan dan pengadaan Google Cloud Marketplace. Perhatikan bahwa panduan ini tidak memberikan lingkungan produk lengkap untuk pengujian.

2. Sebelum memulai

• Gunakan Producer Portal untuk mengaktifkan codelab untuk project Anda, jika Anda belum mengaktifkannya.

Link langsung ke Producer Portal adalah:

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

Untuk mengaktifkan codelab, klik Aktifkan di panel Codelab di sisi kanan layar.

• Instal Python 3 di komputer Anda, dengan modul berikut:
• Python Google Client API.
• Library klien google-cloud-pubsub.

Untuk menginstal modul Python, gunakan perintah berikut:

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

• Clone atau download repositori GitHub untuk codelab ini, menggunakan perintah berikut:

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

Download ZIP

• Tetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT ke ID project ini:
• Linux:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

• Windows:

set GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

• Berikan peran Pub/Sub Editor ke akun layanan saas-codelab. Untuk mengetahui langkah-langkah memberikan dan mengelola peran, lihat Memberikan, mengubah, dan mencabut akses ke resource.
• Buat dan download kunci JSON untuk akun layanan. Untuk mengetahui langkah-langkah membuat kunci, lihat Membuat dan mengelola kunci akun layanan.

Perhatian: Jika Anda ingin mengupload kode contoh ke repositori sumber online seperti GitHub atau Cloud Source Repositories, jangan mengupload kunci ini ke repositori Anda.

• Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur lengkap file yang didownload:
• Linux:

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

• Windows:

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

• Untuk melihat contoh solusi di Google Cloud Marketplace, buka Producer Portal dan klik Codelab product di panel Codelabs. Anda juga dapat mengakses solusi secara langsung di https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab
• Di Google Cloud Console, di project baru Anda, aktifkan Partner Procurement API.

Selanjutnya, siapkan backend untuk solusi contoh.

3. Mengintegrasikan dengan Google Cloud Marketplace

Secara umum, Anda mengintegrasikan solusi contoh dengan Google Cloud Marketplace dengan cara berikut:

• Lakukan integrasi dengan Cloud Pub/Sub untuk menerima notifikasi dari Google Cloud Marketplace, seperti saat pengguna mendaftar ke solusi Anda. Partner Engineer Anda membuat topik Cloud Pub/Sub yang harus Anda langgani untuk mendapatkan notifikasi.
• Lakukan integrasi dengan Partner Procurement API untuk membuat akun bagi pelanggan baru. Anda menggunakan Partner Procurement API untuk memperbarui akun saat pengguna memilih, mengubah, atau membatalkan paket langganan mereka. Untuk berintegrasi dengan API, Anda harus membuat library klien sendiri.
• Integrasikan dengan Google Service Control untuk melaporkan informasi penggunaan.

4. Berlangganan topik Cloud Pub/Sub

Saat pengguna memilih paket langganan, Anda akan mendapatkan notifikasi dari Google Cloud Marketplace melalui topik Cloud Pub/Sub.

Untuk memproses pesan pada topik Cloud Pub/Sub, Anda harus membuat langganan terlebih dahulu.

Untuk membuat langganan, gunakan skrip create_subscription.py:

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

Untuk melihat langganan, buka dasbor Cloud Pub/Sub di Konsol Cloud:

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

Mencoba permintaan langganan pengujian

Untuk menguji aplikasi contoh ini sebagai pengguna, buka produk codelab di Marketplace dengan membuka https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab. Pastikan Anda telah memilih project codelab, lalu pilih paket langganan.

Catatan: Harga yang ditampilkan untuk produk demo adalah contoh. Anda tidak dikenai biaya untuk solusi ini, apa pun paket yang Anda pilih.

Untuk melihat pesan Cloud Pub/Sub yang dikirim saat Anda memilih paket, buka root direktori python3 di repositori, lalu jalankan perintah berikut:

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

Untuk melihat contoh kode yang memproses pesan Cloud Pub/Sub, lihat https://github.com/googlecodelabs/gcp-marketplace-integrated-saas/blob/master/python3/impl/step_1_pubsub/app.py.

Dalam pesan Cloud Pub/Sub, kolom eventType menunjukkan alasan pesan dikirim. Saat memilih paket, Anda akan melihat pesan untuk eventType: ENTITLEMENT_CREATION_REQUESTED, yang menunjukkan pilihan paket langganan Anda sebelumnya.

Jika Anda membatalkan paket saat skrip ini berjalan, Anda akan melihat pesan baru, untuk eventType: ENTITLEMENT_CANCELLED.

Perhatikan bahwa contoh di atas tidak mengonfirmasi pesan. Dengan begitu, Anda dapat menguji dengan lebih mudah dengan menerima pesan yang sama setiap kali Anda menjalankan aplikasi.

Untuk menutup skrip, tekan CTRL + \.

5. Menyetujui permintaan akun

Setelah dapat menerima pesan dari Google Cloud Marketplace, Anda harus mulai menangani resource yang dibuat oleh layanan Pengadaan Google Cloud Marketplace atas nama pelanggan.

Yang pertama adalah resource account. Akun mewakili koneksi pelanggan ke produk Anda. Anda harus menyimpan ID akun Pengadaan pelanggan di database Anda, untuk memetakan hubungan antara Akun Google mereka dan akun mereka untuk layanan Anda.

Saat pelanggan memilih paket, Google Cloud Marketplace akan mengirimkan notifikasi Cloud Pub/Sub bahwa pelanggan meminta akun. Aplikasi Anda harus menyetujui permintaan. Dalam codelab ini, Anda menyetujui permintaan akun saat pesan Cloud Pub/Sub diterima.

Catatan: Dalam integrasi yang tersedia secara umum, Google Cloud Marketplace mengarahkan pelanggan ke frontend produk Anda, tempat mereka mendaftar ke software Anda sebelum Anda menyetujui permintaan akun mereka. Dalam integrasi akhir, Anda juga harus menyiapkan halaman pendaftaran di frontend. Untuk mengetahui informasi tentang mengintegrasikan frontend aplikasi Anda, buka dokumentasi Google Cloud Marketplace.

Buat database untuk informasi akun

Untuk codelab ini, kita menggunakan database JSON sederhana yang dapat melacak akun dan pembelian pelanggan.

Untuk menguji contoh ini, buat file dengan objek JSON kosong, di mana saja di workstation Anda:

{}

Tetapkan variabel lingkungan PROCUREMENT_CODELAB_DATABASE ke jalur lengkap file ini:

• Linux:

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

• Windows:

set PROCUREMENT_CODELAB_DATABASE=YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json

Modul yang membaca dan menulis database ada di python3/impl/database.

Implementasi contoh menggunakan skema yang dapat diperluas jika Anda mengintegrasikan lebih dari satu penawaran produk dengan Google Cloud Marketplace. Berikut adalah contoh entri database untuk pengguna yang berlangganan paket Sangat Baik di aplikasi contoh:

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

Dalam penerapan akhir, Anda harus menghubungkan aplikasi dengan database Anda sendiri untuk menautkan akun Google Cloud Marketplace pelanggan dengan resource pelanggan Anda sendiri.

Menyetujui akun

Untuk menyetujui permintaan akun, jalankan perintah berikut:

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

Kode contoh untuk menyetujui akun ada di impl/step_2_account.

Catatan: Dalam integrasi umum, menyetujui akun menunjukkan bahwa pelanggan telah mendaftar ke aplikasi Anda melalui frontend Anda. Dalam penerapan akhir, Anda hanya boleh menyetujui akun melalui alur pendaftaran.

Direktori marketplaceui codelab memiliki halaman demo yang menampilkan ID akun pengadaan dari token JWT terverifikasi.

Implementasi contoh menggunakan class Procurement, yang menangani interaksi dengan Procurement API. Berikut metode get_account() dan approve_account()-nya:

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

Untuk codelab ini, di layanan Pengadaan, ID penyedia adalah DEMO-YOUR_PROJECT_ID, dengan YOUR_PROJECT_ID adalah project yang Anda buat. Saat berinteraksi dengan Procurement API, nama akun harus menggunakan format berikut:

providers/DEMO-YOUR_PROJECT_ID/accounts/account-id

Selanjutnya, Anda menyetujui hak, yang merupakan catatan pembelian pelanggan.

6. Menyetujui hak

Saat pelanggan memilih paket langganan di Google Cloud Marketplace, akun akan dibuat, lalu permintaan hak baru akan segera dibuat. Hak mewakili pembelian layanan. Sebelum pelanggan dapat mulai menggunakan layanan, Anda harus menyetujui permintaan hak, lalu menyiapkan layanan agar pelanggan dapat mulai menggunakannya.

Saat aplikasi contoh mendapatkan pesan Cloud Pub/Sub dengan eventType ENTITLEMENT_CREATION_REQUESTED, hak disetujui, dan aplikasi harus menunggu pesan ENTITLEMENT_ACTIVE untuk mencatat hak dalam database, lalu menyiapkan resource untuk pelanggan.

Praktik terbaik: Buat hak hanya untuk akun yang telah Anda setujui. Jika database Anda tidak memiliki catatan akun, jangan buat hak baru.

Untuk membuat hak, jalankan perintah berikut:

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

Kode untuk menyetujui hak ada di contoh penerapan.

Selanjutnya, Anda akan menangani situasi saat pelanggan meminta perubahan pada paket langganannya.

7. Menyetujui perubahan pada hak

Jika layanan Anda memiliki beberapa paket, Anda harus menangani permintaan dari pelanggan yang mungkin ingin mengupgrade atau mendowngrade paket yang ada.

Jika layanan Anda hanya memiliki satu paket, lanjutkan ke Menangani pembelian yang dibatalkan.

Tidak ada perbedaan teknis antara hak yang menjadi aktif untuk pertama kalinya dan hak yang menjadi aktif setelah perubahan paket. Oleh karena itu, contoh implementasi memiliki metode handleActiveEntitlement() bersama untuk kedua kasus. Metode ini memeriksa pesan masuk untuk peristiwa terkait hak:

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)

Cuplikan berikut memeriksa apakah eventType adalah ENTITLEMENT_PLAN_CHANGE_REQUESTED atau 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

Dalam implementasi akhir Anda, saat hak kembali ke status ENTITLEMENT_ACTIVE, metode pemroses Anda harus memperbarui database Anda untuk mencerminkan perubahan dan melakukan penyediaan yang diperlukan.

Bergantung pada cara Anda menyiapkan produk dengan Partner Engineer, layanan Anda mungkin tidak mengizinkan downgrade atau pembatalan hingga akhir siklus penagihan. Dalam kasus tersebut, perubahan paket akan terus menunggu keputusan meskipun setelah persetujuan, tetapi hak tidak akan kembali ke status ENTITLEMENT_ACTIVE hingga perubahan paket selesai.

Untuk kode yang memeriksa dan menyetujui perubahan hak, lihat contoh penerapan.

Selanjutnya, Anda menangani situasi saat pelanggan membatalkan pembelian.

8. Menangani pembelian yang dibatalkan

Pelanggan dapat memilih untuk membatalkan pembelian mereka. Bergantung pada cara Anda menyiapkan produk dengan Partner Engineer, pembatalan dapat berlaku segera, atau di akhir siklus penagihan.

Saat pelanggan membatalkan pembelian, pesan dengan eventType ENTITLEMENT_PENDING_CANCELLATION akan dikirim. Jika Anda telah menyiapkan produk untuk segera memproses pembatalan, pesan dengan eventType ENTITLEMENT_CANCELLED akan dikirim segera setelahnya.

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

Layanan Anda harus menunggu pesan ENTITLEMENT_CANCELLED, lalu menghapus hak dari database Anda, dan menonaktifkan layanan untuk pelanggan.

Setelah hak dibatalkan, hak tersebut akan dihapus dari sistem Google, dan pesan dengan eventType ENTITLEMENT_DELETED akan dikirim:

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

Untuk kode yang membatalkan hak, lihat contoh implementasi.

9. Mengirim laporan penggunaan

Beberapa layanan memiliki komponen berbasis penggunaan, yang mengharuskan Google mengetahui penggunaan layanan oleh pelanggan untuk menagih pelanggan dengan jumlah yang benar. Layanan Anda harus melaporkan penggunaan melalui Google Service Control API.

Jika layanan Anda tidak memiliki komponen berbasis penggunaan, lewati bagian ini.

Untuk mengetahui informasi mendetail tentang pengiriman laporan penggunaan, lihat dokumentasi aktivasi.

Laporan penggunaan harus dikirim ke Google Service Control API setiap jam. Dalam codelab ini, laporan dikirim menggunakan skrip yang dapat Anda jadwalkan sebagai cron job. Skrip menyimpan waktu laporan penggunaan terakhir dalam database, dan menggunakannya sebagai waktu mulai untuk mengukur penggunaan.

Skrip memeriksa setiap pelanggan aktif layanan, dan mengirim laporan penggunaan ke Kontrol Layanan Google menggunakan kolom consumer_id hak pelanggan. Kemudian, skrip memperbarui entri database untuk pelanggan agar memiliki last_report_time yang ditetapkan ke waktu berakhir laporan penggunaan yang baru saja dikirim.

Kontrol Layanan Google mengekspos dua metode: check dan report. Yang pertama harus selalu dipanggil tepat sebelum panggilan ke yang kedua. Jika ada error pada yang pertama, layanan pelanggan harus dinonaktifkan hingga error tersebut diperbaiki.

Semua penggunaan untuk hak tertentu diatribusikan ke satu usageReportingId. Namun, untuk produk SaaS, penggunaan ini dikaitkan dengan item baris [Charges not specific to a project] di Penagihan Google Cloud. Jika produk SaaS Anda mungkin dibagikan secara luas dalam organisasi pelanggan, dan Anda ingin mendukung atribusi biaya, sebaiknya semua layanan Anda menyertakan kolom userLabels opsional pada operasi laporan penggunaan.

Google Cloud Marketplace mencadangkan kunci label cloudmarketplace.googleapis.com/resource_name dan cloudmarketplace.googleapis.com/container_name. Label ini dimaksudkan untuk merekam konteks penggunaan dalam hierarki layanan dan resource native Anda. Nama yang ditetapkan pelanggan untuk resource ini akan disertakan sebagai nilai label dalam laporan penggunaan. Sebaiknya sertakan label ini dalam laporan penggunaan Anda secara default.

Kunci Label	Nilai Label	Deskripsi
cloudmarketplace.googleapis.com/resource_name	RESOURCE_NAME	Nama resource yang terkait dengan metrik penggunaan.
cloudmarketplace.googleapis.com/container_name	CONTAINER_NAME	Nama penampung resource.

Cuplikan berikut melaporkan penggunaan untuk aplikasi demo dan mengatribusikan penggunaan untuk produk SaaS ke resource yang ditetapkan pelanggan bernama products_db. Untuk codelab ini, service_name adalah 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)

Lihat contoh penerapan skrip ini untuk kode lengkapnya. Untuk membuat laporan penggunaan contoh, jalankan perintah berikut:

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

10. Selamat!

Anda telah mempelajari cara solusi SaaS Anda dapat terintegrasi dengan Google Cloud Marketplace untuk menangani akun dan hak pelanggan, serta melaporkan penggunaan terhadap layanan. Untuk mengetahui langkah-langkah integrasi lengkap, lihat dokumentasi integrasi backend.

Tips: Jika Anda ingin mencoba alur langganan lagi, reset persetujuan dan hak akun Anda dengan menjalankan skrip reset_account. Sebelum menjalankan skrip, berikan peran Billing Account Administrator kepada akun layanan Anda.

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

ID Akun dapat ditemukan di file EMPTY_JSON_OBJECT.json Anda.

Pembersihan

Jika Anda tidak berencana menggunakannya lagi, hapus resource berikut:

• Langganan Cloud Pub/Sub
• Akun layanan dan kuncinya
• Secara opsional, project yang Anda buat
• Opsional, akun penagihan yang Anda buat

Langkah berikutnya

Mengintegrasikan frontend

Contoh dalam codelab ini secara otomatis menyetujui akun dan hak. Dalam praktiknya, pelanggan Anda harus diarahkan ke halaman pendaftaran yang Anda buat, tempat mereka dapat membuat akun di sistem Anda. Setelah mereka berhasil mendaftar, Anda harus membuat permintaan API untuk menyetujui akun dan hak mereka.

Untuk mengetahui informasi tentang cara mengintegrasikan frontend aplikasi Anda, lihat dokumentasi Google Cloud Marketplace.

Pelajari lebih lanjut cara menawarkan solusi SaaS

Untuk mengetahui ringkasan tentang cara menawarkan solusi SaaS di Google Cloud Marketplace, lihat Menawarkan solusi SaaS.