Mengintegrasikan backend aplikasi

Bagian ini menjelaskan langkah-langkah untuk mengintegrasikan backend aplikasi Anda dengan Cloud Marketplace. Dengan integrasi ini, Anda dapat mengelola akun dan hak pengguna, yang menunjukkan bahwa pengguna telah membeli produk Anda dari Cloud Marketplace. Jika memilih model harga berbasis penggunaan, Anda juga mengintegrasikan backend untuk melaporkan penggunaan ke Google.

Untuk contoh mengintegrasikan aplikasi dasar dengan Cloud Marketplace dan panduan kode contoh, lihat codelab untuk mengintegrasikan layanan terkelola.

Untuk kode contoh yang digunakan dalam codelab, lihat repositori GitHub.

Sebelum memulai

• Siapkan akses ke Cloud Commerce Partner Procurement API, seperti yang dijelaskan dalam Mengintegrasikan aplikasi Anda: penyiapan.
• Jika memilih skema harga berbasis penggunaan, pastikan Partner Engineer telah membuat layanan yang dapat Anda gunakan untuk melaporkan penggunaan. Layanan ini ditampilkan di kolom Domain layanan pada bagian Integrasi Penagihan di Produsen Portal.

Membuat akun layanan

Untuk mengintegrasikan produk Anda dengan Google Cloud, Anda harus membuat akun layanan dalam project yang digunakan untuk produk Anda. Aplikasi Anda menggunakan akun layanan ini untuk berinteraksi dengan Cloud Marketplace Partner API dan mendapatkan informasi tentang pembelian pengguna.

Gunakan Portal Produsen untuk membuat dan menautkan akun layanan Anda. Guna mengetahui langkah-langkah mendetail untuk membuat akun layanan, lihat Membuat dan mengelola akun layanan.

Menggunakan Produsen Portal untuk mengintegrasikan backend aplikasi Anda

Untuk mengakses semua informasi yang diperlukan untuk mengintegrasikan backend aplikasi Anda dengan Cloud Marketplace dari satu lokasi, seperti akun layanan dan ID tingkat paket, Anda dapat menggunakan bagian Billing integration di Produsen Portal.

Link langsung ke PD Portal adalah:

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

Catatan: Jika Anda tidak melihat link atau tidak dapat mengakses URL, pastikan Anda telah memilih project yang benar. Jika Anda tetap tidak dapat mengakses URL, gunakan Partner Support Desk untuk meminta bantuan, dan sertakan kata "Marketplace" dalam deskripsi Anda. Untuk mengetahui informasi selengkapnya tentang Partner Support Desk, buka Meminta bantuan terkait Cloud Marketplace.

Untuk mengakses bagian Integrasi penagihan:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Overview produk Anda, buka bagian Technical integration dan klik Billing integration.

Membuat dan menautkan akun layanan di PD Portal

Anda dapat menggunakan bagian Billing integration di Produsen Portal untuk membuat dan menautkan akun layanan yang Anda gunakan untuk berinteraksi dengan Partner API dan mendapatkan informasi tentang pembelian pengguna.

Link langsung ke PD Portal adalah:

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

Catatan: Jika Anda tidak melihat link atau tidak dapat mengakses URL, pastikan Anda telah memilih project yang benar. Jika Anda tetap tidak dapat mengakses URL, gunakan Partner Support Desk untuk meminta bantuan, dan sertakan kata "Marketplace" dalam deskripsi Anda. Untuk mengetahui informasi selengkapnya tentang Partner Support Desk, buka Meminta bantuan terkait Cloud Marketplace.

Pada langkah-langkah berikut, Anda dapat menggunakan akun layanan yang ada, atau membuat akun layanan baru. Jika Anda membuat akun layanan baru, tentukan nama akun layanan di kolom Nama akun layanan dan ID akun layanan di kolom ID akun layanan, lalu klik Buat dan tautkan.

Untuk menautkan akun layanan:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Overview produk Anda, buka bagian Technical integration dan klik Billing integration.

3. Untuk berintegrasi dengan Partner Procurement API, di bagian Link a service account to call Procurement API, klik Add service account. Anda dapat memasukkan akun layanan yang ada ke kolom ini, atau membuat akun layanan baru.

4. Untuk berintegrasi dengan Pub/Sub, di bagian Link a service account to subscribe to Pub/Sub topic, klik Add service account. Anda dapat memasukkan akun layanan yang ada ke kolom ini, atau membuat akun layanan baru.

5. Untuk berintegrasi dengan Service Control API, di bagian Add roles/servicemanagement.serviceController to a service account, klik Add service account. Anda dapat memasukkan akun layanan yang ada ke kolom tersebut, atau membuat akun layanan baru.

Tugas akun pengguna

Pada level yang tinggi, aplikasi Anda harus menangani skenario berikut:

1. Pengguna membuat permintaan atau perubahan di Cloud Marketplace, misalnya mendaftar ke produk Anda.

2. Cloud Marketplace mengirimkan notifikasi ke aplikasi Anda melalui Pub/Sub, yang berisi informasi tentang permintaan tersebut di kolom eventType. Misalnya, jika pengguna mengubah haknya, eventType adalah ENTITLEMENT_PLAN_CHANGED.

   Lihat daftar lengkap kemungkinan eventType.

3. Untuk menyetujui permintaan tersebut, aplikasi Anda akan mengirimkan permintaan HTTP POST ke Partner Procurement API.

Bagian berikut menjelaskan jenis permintaan yang dapat dibuat pengguna, dan apa yang harus dilakukan aplikasi Anda untuk menangani permintaan tersebut.

Untuk panggilan API yang dijelaskan di bagian ini, gunakan endpoint ini:

https://cloudcommerceprocurement.googleapis.com/

Buat akun untuk pengguna baru

Saat pengguna pertama kali membeli produk Anda, Cloud Marketplace membuat resource akun yang melacak hubungan pengguna dengan Anda. Saat resource akun dibuat, Anda akan menerima notifikasi melalui topik Pub/Sub yang telah dibuat untuk Anda. Pesan Pub/Sub menggunakan format berikut:

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

dengan USER_ACCOUNT_ID adalah ID akun yang dibuat oleh Cloud Marketplace dan YOUR_PARTNER_ID adalah ID yang ditetapkan untuk Anda saat Partner Engineer mengaktifkan akses ke Partner Procurement API.

Kemudian, pengguna akan diarahkan ke halaman pendaftaran Anda, tempat mereka membuat akun di sistem Anda. Untuk informasi tentang cara membuat halaman pendaftaran, lihat Mengintegrasikan frontend aplikasi.

Menyetujui akun pengguna

Setelah pengguna berhasil mendaftar, aplikasi Anda harus memanggil Partner Procurement API dan menunjukkan bahwa akun telah disetujui. Akun dibuat dalam status ACCOUNT_ACTIVE, tetapi memiliki entri PENDING di kolom approvals yang disebut signup, yang menunjukkan bahwa pengguna belum mendaftar. Untuk menyetujui akun setelah pengguna mendaftar, gunakan permintaan HTTP POST berikut:

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

Memeriksa status akun pengguna

Untuk memeriksa status akun tertaut, gunakan permintaan HTTP GET berikut:

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

Respons tersebut dalam format berikut:

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

Untuk daftar kemungkinan status akun, lihat referensi API providers.accounts.

Kelola hak

Saat pelanggan memilih paket harga untuk software Anda, Google akan membuat hak, yang menunjukkan bahwa pelanggan telah membeli produk Anda dari Cloud Marketplace. Bagian ini meninjau cara membuat dan mengelola hak untuk pelanggan Anda yang menggunakan Partner Procurement API.

Untuk mengetahui detail selengkapnya tentang cara mengelola hak, buka dokumentasi referensi.

Menyetujui atau menolak hak

Saat pelanggan memilih paket harga, Cloud Marketplace akan membuat hak dan mengirimkan pesan Pub/Sub berikut ke aplikasi Anda:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for offer-based entitlements
  },
}

dengan ENTITLEMENT_ID adalah ID yang dibuat oleh Cloud Marketplace. Jika penawaran memiliki durasi tertentu, durasi tersebut diberikan dalam tahun dan bulan. Jika penawaran memiliki tanggal akhir yang ditentukan, bukan durasi, kolom yang menunjukkan durasi kosong.

Di sistem Anda, update akun pengguna untuk mencerminkan bahwa dia telah membeli paket. Kemudian, untuk menyetujui hak, buat permintaan HTTP POST ke Partner Procurement API, dan kirim ENTITLEMENT_ID yang Anda setujui:

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

Untuk menolak hak, gunakan metode reject dalam permintaan HTTP POST Anda:

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

Untuk memberikan alasan penolakan hak dalam isi permintaan, gunakan format berikut:

{
  "reason": "..."
}

Mengubah paket hak

Bergantung pada cara Anda menyiapkan paket harga, pelanggan Anda mungkin dapat mengubah paket mereka. Jika pelanggan memilih paket harga baru, Anda akan menerima pesan Pub/Sub dalam format berikut:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for the new offer, for offer-based entitlements
  },
}

Jika penawaran memiliki durasi tertentu, durasi tersebut diberikan dalam tahun dan bulan. Jika penawaran memiliki tanggal akhir yang ditentukan, bukan durasi, kolom yang menunjukkan durasi kosong.

Untuk menyetujui perubahan paket, buat permintaan HTTP POST berikut ke Partner Procurement API:

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

Badan permintaan harus memiliki rencana yang sedang disetujui:

{
  "pendingPlanName": PLAN_NAME
}

Setelah perubahan disetujui, Anda akan menerima pesan Pub/Sub lain saat perubahan tersebut diterapkan. Dalam pesan, kolom eventType berubah menjadi ENTITLEMENT_PLAN_CHANGED. Untuk memeriksa status paket, buat permintaan HTTP GET berikut ke Partner Procurement API.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

Responsnya mirip dengan berikut ini, dengan kolom state yang menunjukkan apakah paket baru aktif atau apakah perubahan paket masih tertunda:

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

Mengirim pesan status ke pengguna

Jika waktu antara pengguna memilih paket harga dan backend Anda menyetujui hak adalah beberapa jam atau lebih, sebaiknya berikan pesan status kepada pengguna. Dalam pesan ini, tunjukkan progres persetujuan, dan jika tersedia, kapan Anda memperkirakan persetujuan akan selesai.

Untuk memberikan pesan status, buat permintaan HTTP POST berikut ke Procurement API:

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

Dalam isi permintaan, berikan teks pesan, mirip dengan contoh berikut:

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

Membatalkan hak

Jika pengguna memutuskan untuk membatalkan haknya, Anda akan menerima notifikasi Pub/Sub. Serupa dengan mengubah paket, pembatalan yang sebenarnya mungkin akan berlaku pada akhir siklus penagihan saat ini.

Notifikasi tersebut menggunakan format berikut:

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

Menghapus hak

Jika pengguna membuat permintaan langsung ke dukungan Google, atau jika mereka keluar dari platform Google, hak mereka akan segera dibatalkan, dan hak serta akun mereka dihapus setelah masa tenggang 60 hari. Untuk melindungi privasi pengguna, Anda harus menghapus data mereka dari server saat Anda menerima notifikasi.

Saat hak dibatalkan dan akun dihapus, Anda akan menerima notifikasi yang serupa dengan hal berikut:

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

Daftar jenis peristiwa untuk tugas akun

Berikut adalah daftar eventType yang mungkin diterima aplikasi Anda dalam pesan Pub/Sub:

eventType	Deskripsi
ACCOUNT_CREATION_REQUESTED	Tidak digunakan lagi
ACCOUNT_ACTIVE	Menunjukkan bahwa akun pelanggan telah dibuat.
ACCOUNT_DELETED	Menunjukkan bahwa akun pelanggan telah dihapus dari sistem Google Cloud.
ENTITLEMENT_CREATION_REQUESTED	Menunjukkan bahwa pelanggan telah memilih salah satu paket harga Anda.
ENTITLEMENT_OFFER_ACCEPTED	Menunjukkan bahwa penawaran diterima oleh pelanggan. Termasuk waktu mulai penawaran yang dijadwalkan, jika ada.
ENTITLEMENT_ACTIVE	Menunjukkan bahwa paket yang dipilih pelanggan kini aktif.
ENTITLEMENT_PLAN_CHANGE_REQUESTED	Menunjukkan bahwa pelanggan memilih paket baru.
ENTITLEMENT_PLAN_CHANGED	Menunjukkan bahwa perubahan paket pelanggan disetujui dan perubahan telah diterapkan.
ENTITLEMENT_PLAN_CHANGE_CANCELLED	Menunjukkan bahwa perubahan paket pelanggan dibatalkan karena tidak disetujui, atau karena mereka beralih kembali ke paket lama.
ENTITLEMENT_PENDING_CANCELLATION	Menunjukkan bahwa pelanggan membatalkan paketnya, dan pembatalan tertunda hingga akhir siklus penagihan.
ENTITLEMENT_CANCELLATION_REVERTED	Menunjukkan bahwa pembatalan yang tertunda milik pelanggan telah dikembalikan. Perhatikan bahwa pembatalan tidak dapat dikembalikan setelah final.
ENTITLEMENT_CANCELLED	Menunjukkan bahwa paket pelanggan dibatalkan.
ENTITLEMENT_CANCELLING	Menunjukkan bahwa paket pelanggan sedang dalam proses pembatalan.
ENTITLEMENT_RENEWED	Menunjukkan bahwa hak pelanggan telah diperpanjang untuk satu masa berlaku. Anda tidak perlu melakukan tindakan apa pun untuk menyelesaikan perpanjangan.
ENTITLEMENT_OFFER_ENDED	Menunjukkan bahwa penawaran pribadi pelanggan telah berakhir. Jika hak pelanggan dibatalkan, peristiwa ENTITLEMENT_CANCELLED terpisah akan dipicu. Jika hak pelanggan masih aktif, paket mereka akan kembali ke harga tanpa diskon.
ENTITLEMENT_DELETED	Menunjukkan bahwa informasi tentang paket pelanggan telah dihapus dari Cloud Marketplace.

(Untuk harga berdasarkan penggunaan) Melaporkan penggunaan ke Google

Jika memilih harga berdasarkan penggunaan untuk produk, Anda harus melaporkan penggunaan aplikasi ke Service Control API.

Untuk pengantar Kontrol Layanan, lihat Panduan Memulai.

Sebaiknya gunakan prod Portal untuk membuat akun layanan di prod Portal untuk digunakan dengan Service Control.

Saat hak dibuat, Anda harus memanggil Partner Procurement API untuk mengambil usageReportingId, menggunakan permintaan HTTP GET berikut:

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

Respons berisi informasi tentang hak, dalam format berikut:

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

Untuk melaporkan penggunaan, Anda harus melakukan panggilan API services.check terlebih dahulu untuk memeriksa konfigurasi layanan. Sebagai respons, jika objek checkErrors[] kosong, lakukan panggilan API services.report untuk mengirim laporan penggunaan.

Perhatian: Saat menguji pelaporan berbasis penggunaan, jangan melebihi 92 miliar dari total tagihan per akun penagihan dalam mata uang akun penagihan tersebut. Hal ini menurunkan pengalaman Anda.

Laporan penggunaan adalah Service Control API Operation. Berikut adalah contoh laporan penggunaan untuk example-messaging-service yang mengirimkan informasi tentang penyimpanan yang digunakan oleh pelanggan:

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

dengan:

• operationId adalah string unik yang dihasilkan instance layanan Anda. Anda harus menggunakan operationId yang sama untuk operasi check dan report.

• consumerId sama dengan usageReportingId dari hak.

• startTime dan endTime mewakili waktu mulai dan berakhir dari total interval untuk Operasi report. Pada umumnya, startTime dari Operasi report harus memiliki nilai yang sama dengan endTime dari Operasi report sebelumnya.

  Jika layanan pelanggan dinonaktifkan sebelum startTime dari Operasi report, panggilan API services.check akan mengirimkan error dalam objek checkErrors[], dan pelanggan tidak dikenai biaya untuk interval yang sesuai.

• MetricValueSet berisi satu interval waktu atau menengah dan nilai metrik yang diperbarui. Anda menentukan metrik layanan saat memilih dan mengirimkan model harga.

  Anda dapat melihat dan merujuk ID untuk metrik Anda di bagian Integrasi teknis di Produsen Portal.

• userLabels adalah label yang dibuat pengguna, yang ditetapkan sebagai string nilai kunci yang mengikuti persyaratan sintaksis tertentu. Label ini diteruskan ke alat pengelolaan biaya Penagihan Cloud untuk atribusi. Untuk konvensi pelabelan yang direkomendasikan, lihat Praktik terbaik untuk pelabelan penggunaan.

Jika services.check API menampilkan satu atau beberapa error berikut, sebaiknya Anda berhenti menyediakan layanan kepada pelanggan hingga error tersebut diatasi:

• SERVICE_NOT_ACTIVATED
• BILLING_DISABLED
• PROJECT_DELETED

Praktik terbaik untuk pelaporan penggunaan

Saat melaporkan penggunaan, misalnya operasi pengguna atau penggunaan resource, perhatikan informasi berikut untuk memastikan pelanggan Anda ditagih dengan benar.

Melaporkan penggunaan saat kejadian

Penundaan dalam pelaporan penggunaan akan menurunkan pengalaman pengelolaan biaya pelanggan Anda dan mungkin tidak tercermin dalam laporan partner. Penyedia layanan harus melaporkan penggunaan dalam waktu satu jam setelah penggunaan dibuat.

Jika memerlukan tambahan waktu untuk melaporkan penggunaan, hubungi partner engineer Anda.

Melaporkan penggunaan setelah hak dibatalkan

Jika memiliki penggunaan yang tidak dilaporkan setelah hak dibatalkan, Anda tetap dapat melaporkannya dengan stempel waktu yang menunjukkan waktu sebenarnya saat penggunaan tersebut dihasilkan. Stempel waktu harus jatuh sebelum hak dibatalkan. Laporkan penggunaan ini dalam waktu satu jam. Anda tidak boleh melaporkan penggunaan apa pun sebagai penggunaan baru setelah hak berakhir.

Melaporkan penggunaan di akhir bulan

Periode pelaporan satu jam berlaku untuk batas waktu akhir bulan. Untuk memastikan bahwa penggunaan dilaporkan dalam invoice bulan berjalan, laporkan penggunaan sebelum pukul 01.00, Waktu Pasifik AS dan Kanada (UTC-7 atau UTC-8) pada hari berikutnya.

Misalnya, untuk invoice bulan September, laporkan penggunaan paling lambat 1 Oktober pukul 01.00 Waktu Pasifik AS dan Kanada (UTC-7 atau UTC-8).

Jika penggunaan dilaporkan pada akhir hari, penggunaan tersebut mungkin tidak disertakan dalam invoice bulan berjalan.

Perbaikan untuk tindakan pelanggan yang mencegah pelaporan penggunaan pada saat kejadian

Jika Anda tidak dapat melaporkan penggunaan, atau jika layanan atau penagihan dinonaktifkan untuk waktu yang lebih lama, sebaiknya berikan masa tenggang kepada pelanggan untuk memulihkan layanan. Sebaiknya jangan melebihi 30 hari. Selama masa tenggang ini, pertimbangkan untuk melakukan hal berikut:

• Menurunkan kualitas layanan yang disediakan. Misalnya, alihkan pelanggan ke paket gratis atau mulai tolak panggilan.

• Terus kumpulkan log penggunaan saat layanan dinonaktifkan. Sebaiknya kumpulkan penggunaan dengan perincian tagihan menurut, maksimum, jangka waktu satu jam sehingga dapat diputar ulang setelah layanan diaktifkan.

Saat layanan diaktifkan, Anda harus melaporkan penggunaan yang dikumpulkan saat layanan dinonaktifkan sebagai penggunaan sebenarnya dengan saat data dikumpulkan. Anda juga harus melanjutkan pelaporan penggunaan normal.

Untuk aplikasi Kubernetes, jika laporan penggunaan gagal selama startup aplikasi, sebaiknya aplikasi berhenti sendiri agar pelanggan mendapatkan masukan segera dan dapat menyelesaikan masalah.

Praktik terbaik untuk pelabelan penggunaan

Untuk produk SaaS berbasis penggunaan, penggunaan diatribusikan ke satu project yang ditentukan oleh kolom usageReportingId. Dalam beberapa skenario, produk SaaS mungkin digunakan secara luas dalam organisasi pelanggan dan digunakan di banyak project pelanggan. Guna mengaktifkan dukungan untuk atribusi biaya yang lebih spesifik, sebaiknya produk SaaS berbasis penggunaan menyertakan kolom userLabels opsional pada operasi laporan penggunaannya.

Jika layanan Anda secara native mendukung konsep label resource, sebaiknya teruskan label tersebut dalam laporan penggunaan. Label harus sesuai dengan persyaratan sintaksis.

Cloud Marketplace mencadangkan label berikut. Anda dapat menggunakan label ini untuk mengidentifikasi konteks tambahan untuk penggunaan dalam platform layanan native. Sebaiknya Anda menyertakan label ini dalam laporan penggunaan secara default.

Kunci Label	Nilai Label	Deskripsi>
cloudmarketplace.googleapis.com/resource_name	USER_SUPPLIED	Nama resource yang terkait dengan metrik penggunaan.
cloudmarketplace.googleapis.com/container_name	USER_SUPPLIED	Nama container resource.

Label diteruskan ke alat pengelolaan biaya Penagihan Cloud, termasuk laporan biaya dan ekspor penagihan.

Contoh pelabelan penggunaan

Untuk contoh ini, bayangkan organisasi Anda menawarkan produk penyimpanan bernama SaaS Storage Solutions.

Seorang pelanggan, Carl, telah membeli penawaran penyimpanan Anda untuk project Google Cloud e-commerce-website, guna menghosting database user_profiles_db dan products_db untuk situs e-commerce-nya:

• user_profiles_db berisi informasi tentang pengguna yang mengunjungi situs Cahya.
• products_db berisi informasi tentang produk yang dijual Carl di situsnya.

Jika ingin memberikan perincian biaya mendetail kepada Carl terkait penggunaannya, Anda dapat menggunakan pasangan nilai kunci userLabels untuk melaporkan biaya penggunaan untuk setiap database secara terpisah.

Misalnya, untuk melaporkan biaya yang diatribusikan ke penggunaan penyimpanan products_db Carl, Anda dapat mengirim laporan berikut, yang menunjukkan bahwa penyimpanan products_db Carl menghabiskan biaya 100 unit:

operation = {
  'operationId': '<UUID>',
  'operationName': 'db-total-storage',
  'consumerId': 'project:carl_website',
  'startTime': '<Timestamp>',
  'endTime': '<Timestamp>',
  'metricValues': [{
      'int64Value': 100,
  }],
  'userLabels': {
    'cloudmarketplace.googleapis.com/container_name': 'e-commerce-website',
    'cloudmarketplace.googleapis.com/resource_name': 'products_db'
  }
}

service.services().report(
  serviceName=service_name, body={
    'operations': [operation]
}).execute()

Dalam contoh ini, service_name adalah Project ID dari project Google Cloud Carl.

Untuk contoh penggunaan userLabels yang lebih terperinci, Anda dapat melihat codelab SaaS.

(Opsional) Mengintegrasikan pelaporan Anda dengan Virtual Private Cloud (VPC)

Jika ingin menggunakan Virtual Private Cloud (VPC) di lingkungan tempat layanan produk Anda berjalan, Anda harus menyelesaikan langkah-langkah berikut untuk mengintegrasikan pelaporan Google Cloud Marketplace dengan VPC. Secara default, VM Compute Engine di VPC Anda hanya dapat berkomunikasi secara internal. Anda harus mengonfigurasi salah satu VM untuk berkomunikasi secara eksternal, sehingga VM lainnya di VPC Anda dapat menggunakannya untuk pelaporan.

Sebelum memulai

• Siapkan implementasi VPC pilihan Anda di lingkungan layanan. Untuk mengetahui langkah-langkah penyiapan VPC, baca artikel Membuat dan memodifikasi jaringan Virtual Private Cloud (VPC).

• Pastikan Anda memiliki peran Admin Jaringan Compute (roles/compute.NetworkAdmin) Identity and Access Management (IAM) untuk project Google Cloud Anda.

Siapkan Akses Google Pribadi

Agar virtual machine (VM) Compute Engine produk Anda dapat berkomunikasi secara eksternal untuk tujuan pelaporan, Anda harus menyiapkan Akses Google Pribadi. Untuk mengetahui informasi selengkapnya tentang mengonfigurasi Akses Google Pribadi, lihat Mengonfigurasi Akses Google Pribadi.

1. Aktifkan Akses Google Pribadi untuk lingkungan layanan Anda.

2. Konfigurasikan DNS untuk menyelesaikan permintaan ke private.googleapis.com.

3. Membuat rute kustom untuk Google API:

   • Untuk Nama, tentukan route-google-apis-services.

   • Untuk Network, pilih VPC Anda.

   • Untuk Destination IP range, tentukan 199.36.153.8/30.

   • Untuk Priority, tentukan 0.

   • Untuk Instance tags, tentukan google-apis-services.

   • Untuk Next hop, pilih Default internet gateway.

4. Buat aturan firewall VPC agar produk Anda dapat berkomunikasi dengan Google API:

   • Untuk Nama, tentukan google-apis-services.

   • Untuk Description, tentukan Allow egress traffic to Google APIs and services.

   • Aktifkan logging aturan firewall.

   • Untuk Network, pilih VPC Anda.

   • Untuk Direction of traffic, pilih Traffic keluar.

   • Untuk Tindakan pada pencocokan, pilih Izinkan.

   • Untuk Nama, tentukan google-apis-services.

   • Untuk Targets, pilih Specified target tags, lalu untuk Target tags, tentukan google-apis-services.

   • Untuk Destination filter, pilih IPv4 ranges, dan untuk Destination IPv4 ranges, tentukan 199.36.153.8/30.

   • Untuk Protocols and ports, pilih Allow all.

5. Di Konsol Google Cloud, pilih VM yang ingin Anda gunakan untuk melaporkan penggunaan produk. Di bagian Tag jaringan, tambahkan google-apis-services, lalu klik SIMPAN.

6. Di bagian Network interfaces, cari antarmuka jaringan VPC Anda.

7. Di kolom Subnetwork, klik link subnet. Dari halaman Subnet details, klik EDIT, lalu tetapkan Private Google Access ke On.

8. Klik SAVE.

(Opsional) Mengintegrasikan pelaporan Anda dengan Kontrol Layanan VPC

Jika ingin menggunakan Kontrol Layanan VPC di lingkungan tempat layanan produk Anda berjalan, Anda harus menyelesaikan langkah-langkah berikut untuk mengintegrasikan pelaporan Google Cloud Marketplace dengan Kontrol Layanan VPC:

1. Siapkan implementasi Kontrol Layanan VPC pilihan Anda di lingkungan layanan. Untuk mengetahui informasi lebih lanjut tentang cara menyiapkan Kontrol Layanan VPC, baca artikel Menyiapkan perimeter layanan menggunakan Kontrol Layanan VPC.

2. Pastikan layanan servicecontrol.googleapis.com dalam penerapan Kontrol Layanan VPC Anda tidak dibatasi.

   Perhatian: Jika penerapan Kontrol Layanan VPC Anda membatasi servicecontrol.googleapis.com layanan, pelaporan mungkin tidak berfungsi sebagaimana mestinya, dan pengguna Anda mungkin tidak dikenai biaya dengan benar atas penggunaan mereka.