دمج حلّ SaaS مع Google Cloud Marketplace API باستخدام Producer Portal (Python)

1. مقدمة

حلول SaaS على Google Cloud Marketplace هي حلول برمجية تعمل على البنية الأساسية بغض النظر عن الموقع الجغرافي، ولكن يتم إصدار فواتيرها من Google.

في هذا الدرس التطبيقي حول الترميز، ستعدّ حلاً أساسيًا لخدمة تأجير البرامج يتكامل مع Google Cloud Marketplace لتنفيذ ما يلي:

  • تلقّي إشعارات عندما يشترك مستخدم في الحلّ النموذجي.
  • وافِق على العملاء الذين يريدون الاشتراك، وأضِفهم إلى قاعدة البيانات.
  • التعامل مع السيناريوهات التي يريد فيها العملاء تغيير خطط الفوترة أو إلغاءها
  • إرسال تقارير الاستخدام إلى Google

يساعدك هذا الدرس العملي في التعرّف على واجهات برمجة التطبيقات الخاصة بالشراء والتحكّم في الخدمات في Google Cloud Marketplace. يُرجى العِلم أنّ هذا الدليل لا يوفّر بيئة منتج كاملة للاختبار.

2. قبل البدء

  • استخدِم Producer Portal لتفعيل جلسة البرمجة في مشروعك، إذا لم يسبق لك تفعيلها.

الرابط المباشر إلى "بوابة المنتج" هو:

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

لتفعيل برنامج التدريب العملي، انقر على تفعيل في لوحة Codelabs على الجانب الأيسر من الشاشة.

لتثبيت وحدات Python، استخدِم الأمر التالي:

pip install --upgrade google-api-python-client google-cloud-pubsub
  • استنسِخ مستودع GitHub الخاص بهذا الدرس النموذجي أو نزِّله باستخدام الأمر التالي:
git clone https://github.com/googlecodelabs/gcp-marketplace-integrated-saas.git
cd gcp-marketplace-integrated-saas

  • اضبط متغيّر البيئة GOOGLE_CLOUD_PROJECT على رقم تعريف هذا المشروع:
  • أجهزة Linux:
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
  • نظام التشغيل Windows:
set GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
  • اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على المسار الكامل للملف الذي تم تنزيله:
  • أجهزة 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، انتقِل إلى Producer Portal وانقر على منتج Codelab في لوحة Codelabs. يمكنك أيضًا الوصول إلى الحلّ مباشرةً على https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab
  • في Google Cloud Console، فعِّل Partner Procurement API في مشروعك الجديد.

بعد ذلك، اضبط الخلفية للحلّ النموذجي.

3- الدمج مع Google Cloud Marketplace

على مستوى عالٍ، يمكنك دمج الحلّ النموذجي مع Google Cloud Marketplace بالطرق التالية:

  • يمكنك الدمج مع Cloud Pub/Sub لتلقّي إشعارات من Google Cloud Marketplace، مثلاً عندما يشترك مستخدم في حلك. ينشئ "مهندس الشريك" موضوعًا على Cloud Pub/Sub يجب الاشتراك فيه لتلقّي الإشعارات.
  • يمكنك الدمج مع واجهة برمجة التطبيقات Partner Procurement API لإنشاء حسابات للعملاء الجدد. يمكنك استخدام Partner Procurement API لتعديل الحسابات عندما يختار المستخدمون خطط اشتراك أو يغيّرونها أو يلغونها. ولدمج واجهة برمجة التطبيقات، عليك إنشاء مكتبة العميل الخاصة بك.
  • التكامل مع "التحكّم في الخدمات على Google" لإعداد تقارير عن معلومات الاستخدام

4. الاشتراك في موضوع Cloud Pub/Sub

عندما يختار المستخدم خطة اشتراك، ستتلقّى إشعارًا من Google Cloud Marketplace من خلال موضوع Cloud Pub/Sub.

للاستماع إلى الرسائل في موضوع Cloud Pub/Sub، يجب أولاً إنشاء اشتراك.

لإنشاء اشتراك، استخدِم النص البرمجي create_subscription.py:

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

للاطّلاع على الاشتراك، افتح لوحة بيانات Cloud Pub/Sub في Cloud Console:

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

تجربة طلب اشتراك اختباري

لاختبار هذا التطبيق النموذجي كمستخدم، افتح منتج Codelab في Marketplace من خلال الانتقال إلى https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab. تأكَّد من اختيار مشروع الدرس العملي واختَر خطة اشتراك.

للاطّلاع على رسائل Cloud Pub/Sub التي يتم إرسالها عند اختيار خطة، انتقِل إلى جذر الدليل python3 في المستودع، ونفِّذ الأمر التالي:

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

للاطّلاع على نموذج الرمز الذي يستمع إلى رسائل Cloud Pub/Sub، يُرجى الانتقال إلى https://github.com/googlecodelabs/gcp-marketplace-integrated-saas/blob/master/python3/impl/step_1_pubsub/app.py.

في رسالة Cloud Pub/Sub، يعرض الحقل eventType سبب إرسال الرسالة. عند اختيار خطة، من المفترض أن تظهر لك رسالة eventType: ENTITLEMENT_CREATION_REQUESTED، وهي تمثّل اختيارك السابق لخطة الاشتراك.

إذا ألغيت خطتك أثناء تنفيذ هذا النص البرمجي، ستظهر لك رسالة جديدة، وهي eventType: ENTITLEMENT_CANCELLED.

يُرجى العِلم أنّ النموذج أعلاه لا يقرّ باستلام الرسائل. يتيح لك ذلك إجراء الاختبار بسهولة أكبر من خلال تلقّي الرسائل نفسها في كل مرة تشغّل فيها تطبيقك.

لإغلاق النص البرمجي، اضغط على CTRL + \.

5- الموافقة على طلب الحساب

بعد أن أصبح بإمكانك تلقّي رسائل من Google Cloud Marketplace، عليك البدء في التعامل مع الموارد التي تنشئها خدمة "الشراء في Google Cloud Marketplace" نيابةً عن العميل.

الأول هو مورد الحساب. يمثّل الحساب ارتباط العميل بمنتجك. يجب تخزين معرّف حساب العميل على Procurement في قاعدة البيانات لربط العلاقة بين حسابه على Google وحسابه على خدمتك.

عندما يختار العميل خطة، يرسل Google Cloud Marketplace إشعارًا من Cloud Pub/Sub بأنّ العميل يطلب إنشاء حساب. يجب أن يوافق تطبيقك على الطلب. في هذا الدرس العملي، ستوافق على طلبات الحساب عند تلقّي رسائل Cloud Pub/Sub.

إنشاء قاعدة بيانات لمعلومات الحساب

في هذا الدرس العملي، نستخدم قاعدة بيانات JSON بسيطة يمكنها تتبُّع حسابات العملاء وعمليات الشراء.

لاختبار هذا النموذج، أنشئ ملفًا يحتوي على عنصر JSON فارغ في أي مكان على محطة العمل:

{}

اضبط متغيّر البيئة PROCUREMENT_CODELAB_DATABASE على المسار الكامل لهذا الملف:

  • أجهزة Linux:
export PROCUREMENT_CODELAB_DATABASE="YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json"
  • نظام التشغيل Windows:
set PROCUREMENT_CODELAB_DATABASE=YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json

الوحدة التي تقرأ قاعدة البيانات وتكتب فيها موجودة في python3/impl/database.

يستخدم نموذج التنفيذ مخططًا يمكن توسيعه في حال دمج أكثر من عرض منتج واحد مع Google Cloud Marketplace. في ما يلي مثال على إدخال قاعدة بيانات لمستخدم اشترك في خطة جيدة جدًا في التطبيق النموذجي:

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

في عملية التنفيذ النهائية، يجب ربط تطبيقك بقواعد البيانات الخاصة بك لربط حسابات العملاء على Google Cloud Marketplace بموارد العملاء الخاصة بك.

الموافقة على الحساب

للموافقة على طلب الحساب، نفِّذ الأمر التالي:

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

يمكنك العثور على الرمز النموذجي للموافقة على حساب في impl/step_2_account.

يستخدم التنفيذ النموذجي الفئة Procurement التي تتعامل مع التفاعلات مع Procurement API. في ما يلي طريقتَي get_account() و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()

في هذا الدرس العملي، يكون معرّف الموفّر في خدمة Procurement هو DEMO-YOUR_PROJECT_ID، حيث YOUR_PROJECT_ID هو المشروع الذي أنشأته. أثناء التفاعل مع Procurement API، يجب أن يستخدم اسم الحساب التنسيق التالي:

providers/DEMO-YOUR_PROJECT_ID/accounts/account-id

بعد ذلك، عليك الموافقة على استحقاق، وهو سجلّ لعملية الشراء التي أجراها العميل.

6. الموافقة على حق الوصول

عندما يختار العميل خطة اشتراك في Google Cloud Marketplace، يتم إنشاء حساب، ثم يتم إنشاء طلب استحقاق جديد على الفور. يمثّل الاستحقاق شراء خدمة. قبل أن يتمكّن العميل من بدء استخدام الخدمة، عليك الموافقة على طلب الحصول على إذن الوصول، ثم إعداد الخدمة ليتمكّن العميل من بدء استخدامها.

عندما يتلقّى التطبيق النموذجي رسالة Cloud Pub/Sub تتضمّن eventType ENTITLEMENT_CREATION_REQUESTED، تتم الموافقة على حق الوصول، ويجب أن ينتظر التطبيق رسالة ENTITLEMENT_ACTIVE لتسجيل حق الوصول في قاعدة البيانات، ثم إعداد الموارد للعميل.

لإنشاء إذن الوصول، شغِّل الأمر التالي:

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

يمكنك العثور على الرمز اللازم للموافقة على حق الوصول في نموذج التنفيذ.

بعد ذلك، يمكنك التعامل مع الحالات التي يطلب فيها العميل تغيير خطة اشتراكه.

7. الموافقة على التغييرات التي تم إجراؤها على أحد امتيازات الوصول

إذا كانت خدمتك تتضمّن خططًا متعددة، عليك التعامل مع طلبات العملاء الذين قد يريدون ترقية خطتهم الحالية أو خفضها.

إذا كانت خدمتك تتضمّن خطة واحدة فقط، انتقِل إلى قسم "التعامل مع عمليات الشراء الملغاة".

لا يوجد فرق فني بين أن يصبح الاستحقاق نشطًا للمرة الأولى وأن يصبح نشطًا بعد تغيير الخطة. لهذا السبب، يتضمّن نموذج التنفيذ طريقة handleActiveEntitlement() مشتركة لكلتا الحالتين. تتحقّق هذه الطريقة من الرسائل الواردة بحثًا عن الأحداث المتعلّقة بالاستحقاق:

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)

يتحقّق المقتطف التالي ممّا إذا كانت قيمة eventType هي ENTITLEMENT_PLAN_CHANGE_REQUESTED أو 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

في عملية التنفيذ النهائية، عندما تعود حالة الإذن إلى ENTITLEMENT_ACTIVE، يجب أن تعدّل طريقة معالجة البيانات قاعدة البيانات لتعكس التغيير وتوفّر أي خدمات ضرورية.

استنادًا إلى طريقة إعداد منتجك مع "مهندس الشريك"، قد لا تسمح خدمتك بخفض مستوى الخطة أو إلغائها حتى نهاية دورة الفوترة. في هذه الحالات، سيظل تغيير الخطة معلّقًا حتى بعد الموافقة، ولكن لن تعود حالة الاستحقاق إلى ENTITLEMENT_ACTIVE إلا بعد اكتمال تغيير الخطة.

للاطّلاع على الرمز الذي يتحقّق من تغييرات الأهلية ويوافق عليها، يُرجى الاطّلاع على نموذج التنفيذ.

بعد ذلك، عليك التعامل مع الحالات التي يلغي فيها العملاء عمليات الشراء.

8. التعامل مع عمليات الشراء الملغاة

يمكن للعملاء اختيار إلغاء عمليات الشراء. استنادًا إلى طريقة إعداد المنتج مع "مهندس الشريك"، يمكن أن يسري الإلغاء على الفور أو في نهاية دورة الفوترة.

عندما يلغي العميل عملية الشراء، يتم إرسال رسالة تتضمّن eventType ENTITLEMENT_PENDING_CANCELLATION. إذا كنت قد أعددت منتجك لمعالجة عمليات الإلغاء على الفور، سيتم إرسال رسالة تتضمّن 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

يجب أن تنتظر خدمتك تلقّي الرسالة ENTITLEMENT_CANCELLED، ثم تزيل إذن الوصول من قاعدة البيانات وتوقف الخدمة للعميل.

بعد إلغاء حق الوصول، تتم إزالته من أنظمة Google، ويتم إرسال رسالة تتضمّن 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

للاطّلاع على الرمز الذي يلغي حق الوصول، راجِع نموذج التنفيذ.

9- إرسال تقارير الاستخدام

تتضمّن بعض الخدمات عناصر مستندة إلى الاستخدام، حيث تحتاج Google إلى معرفة استخدام العملاء للخدمة من أجل تحصيل المبلغ الصحيح من العميل. يجب أن تبلّغ خدمتك عن الاستخدام من خلال Google Service Control API.

إذا كانت خدمتك لا تتضمّن عناصر مستندة إلى الاستخدام، يمكنك تخطّي هذا القسم.

للحصول على معلومات مفصّلة حول إرسال تقارير الاستخدام، يُرجى الاطّلاع على مستندات الإعداد.

يجب إرسال تقارير الاستخدام إلى Google Service Control API كل ساعة. في هذا الدرس العملي، يتم إرسال التقارير باستخدام نص برمجي يمكنك جدولته كمهمة cron. يخزّن النص البرمجي وقت آخر تقرير استخدام في قاعدة البيانات، ويستخدمه كوقت بدء لقياس الاستخدام.

يفحص النص البرمجي كل عميل نشط للخدمة، ويرسل تقرير استخدام إلى "خدمة التحكّم في Google" باستخدام الحقل consumer_id الخاص بحقوق العميل. بعد ذلك، يعدّل النص البرمجي إدخال قاعدة البيانات الخاص بالعميل ليتم ضبط last_report_time على وقت انتهاء تقرير الاستخدام الذي تم إرساله للتو.

تعرض خدمة "التحكّم في خدمات Google" طريقتَين: check وreport. يجب دائمًا طلب الأول مباشرةً قبل طلب الأخير. إذا كان النموذج السابق يتضمّن أي أخطاء، يجب إيقاف خدمة العميل إلى حين إصلاحها.

يتمّ إسناد كلّ استخدام لأحد الحقوق إلى usageReportingId واحد. ومع ذلك، بالنسبة إلى منتجات SaaS، يرتبط هذا الاستخدام ببند [Charges not specific to a project] في "فوترة Google Cloud". إذا كان من المحتمل أن تتم مشاركة منتجك كبرنامج كخدمة (SaaS) على نطاق واسع داخل مؤسسة أحد العملاء، وكنت تريد إتاحة تحديد مصدر التكلفة، ننصحك بأن تتضمّن جميع خدماتك الحقل الاختياري userLabels في تقرير الاستخدام operation.

يحتفظ Google Cloud Marketplace بمفاتيح التصنيف cloudmarketplace.googleapis.com/resource_name وcloudmarketplace.googleapis.com/container_name. تهدف هذه التصنيفات إلى تسجيل سياق الاستخدام ضمن التسلسل الهرمي للخدمة والموارد الأصلية. سيتم تضمين الأسماء التي يحدّدها العميل لهذه الموارد كقيم تصنيف في تقارير الاستخدام. ننصحك بتضمين هذه التصنيفات في تقارير الاستخدام تلقائيًا.

مفتاح التصنيف

قيمة التصنيف

الوصف

cloudmarketplace.googleapis.com/resource_name

RESOURCE_NAME

اسم المورد المرتبط بمقياس الاستخدام.

cloudmarketplace.googleapis.com/container_name

CONTAINER_NAME

تمثّل هذه السمة اسم حاوية موارد.

يعرض المقتطف التالي معلومات الاستخدام لتطبيق العرض التوضيحي وينسب استخدام منتج SaaS إلى المورد الذي حدّده العميل باسم products_db. في هذا الدرس التطبيقي حول الترميز، قيمة service_name هي 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)

يمكنك الاطّلاع على نموذج التنفيذ لهذا النص البرمجي للحصول على الرمز الكامل. لإنشاء نموذج لتقرير الاستخدام، شغِّل الأمر التالي:

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

10. تهانينا!

تعرّفت على كيفية دمج حل SaaS مع Google Cloud Marketplace للتعامل مع حسابات العملاء وأذوناتهم، ولإعداد تقارير عن الاستخدام مقابل إحدى الخدمات. للاطّلاع على خطوات الدمج الكاملة، يُرجى الرجوع إلى مستندات عملية الدمج في الخلفية.

تَنظيم

إذا لم تعُد تخطّط لاستخدامها، احذف الموارد التالية:

  • الاشتراك في Cloud Pub/Sub
  • حساب الخدمة ومفاتيحه
  • اختياريًا، المشروع الذي أنشأته
  • اختياريًا، حساب الفوترة الذي أنشأته

الخطوات التالية

دمج الواجهة الأمامية

تتم الموافقة تلقائيًا على الحسابات والأذونات في العيّنات الواردة في هذا الدرس العملي. في الواقع، يجب توجيه عملائك إلى صفحة تسجيل تنشئها، حيث يمكنهم إنشاء حسابات في نظامك. بعد أن يكملوا عملية الاشتراك بنجاح، عليك إرسال طلبات إلى واجهة برمجة التطبيقات للموافقة على حساباتهم وأذوناتهم.

للحصول على معلومات حول دمج الواجهة الأمامية لتطبيقك، اطّلِع على مستندات Google Cloud Marketplace.

مزيد من المعلومات حول تقديم حلول SaaS

للحصول على نظرة عامة حول تقديم حلول SaaS على Google Cloud Marketplace، يُرجى الاطّلاع على تقديم حلول SaaS.